使用说明

MCP Hello 服务器

一个用Python实现的简单模型上下文协议（MCP）服务器，提供了基本工具用于问候、回显消息、获取时间以及执行算术运算。

什么是MCP？

模型上下文协议（Model Context Protocol，MCP）是一种标准化协议，它使得人工智能模型和客户端能够与外部工具和服务进行通信。可以将其视为一种通用语言，使人工智能助手能够：

发现服务器上有哪些可用工具
打电话 那些具有特定参数的工具
接收结构化的结果返回

这在人工智能系统与外部功能之间搭建了一座桥梁，使得利用自定义工具轻松扩展人工智能能力成为可能。

其工作原理

架构概述

MCP服务器遵循一种简单但强大的架构：

┌─────────────────┐    JSON-RPC     ┌─────────────────┐
│   MCP Client    │ ◄─────────────► │   MCP Server    │
│   (AI Model)    │    Messages     │  (Our Python    │
│                 │                 │   Application)  │
└─────────────────┘                 └─────────────────┘

核心组件

1. 服务器实例

server = Server("mcp-hello-server")

服务器是核心组件，负责管理工具注册、处理客户端连接以及处理工具调用。

2. 工具注册系统

@server.list_tools()
async def list_tools() -> List[Tool]:
    return [
        Tool(
            name="hello",
            description="Say hello to someone",
            inputSchema={...}
        )
    ]

这个装饰器告诉服务器：“当客户端询问您有哪些工具时，返回这个列表。” 每个工具包括：

名字该如何称呼它
描述它的功能
**输入模式（或输入架构）**它期望接收哪些参数（JSON模式）

3. 工具执行系统

@server.call_tool()
async def call_tool(name: str, arguments: Dict[str, Any]) -> List[TextContent]:
    if name == "hello":
        name_arg = arguments.get("name", "World")
        message = f"Hello, {name_arg}! Welcome to the MCP Hello Server!"
        return [TextContent(type="text", text=message)]

这个装饰器处理实际的工具执行：

接收工具名称和参数
执行请求的操作
返回结构化结果

4. 通信协议

服务器使用 stdio 传输（或：标准I/O传输） - 它通过标准输入/输出进行通信：

async with stdio_server() as (read_stream, write_stream):
    await server.run(read_stream, write_stream, ...)

这意味着：

客户端通过标准输入发送JSON-RPC消息
服务器通过标准输出进行响应
无需网络端口 - 仅需进程间通信

消息流示例

当你调用“hello”工具时，会发生以下情况：

第一步：客户问“你们有哪些工具？”

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

步骤2：服务器返回工具列表

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "hello",
        "description": "Say hello to someone",
        "inputSchema": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "The name of the person to greet"
            }
          },
          "required": ["name"]
        }
      }
    ]
  }
}

步骤3：客户端调用hello工具

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "hello",
    "arguments": {
      "name": "Alice"
    }
  }
}

步骤4：服务器执行并响应

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Hello, Alice! Welcome to the MCP Hello Server!"
      }
    ]
  }
}

关键技术特性

异步架构

为了提升性能，一切操作均为异步执行：

async def 函数处理请求
asyncio.run(main()) 启动事件循环
可以同时处理多个请求

错误处理

服务器包含全面的错误处理机制：

except (ValueError, TypeError) as e:
    return [TextContent(type="text", text=f"Error: Invalid numbers provided - {str(e)}")]

日志系统

内置的日志记录有助于调试：

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
logger.info(f"Tool called: {name} with arguments: {arguments}")

类型安全

在整个应用程序中使用 Pydantic 模型进行验证和类型安全控制。

这种架构的优势

标准化使用MCP协议 - 与任何MCP兼容的客户端均可配合工作
可扩展的通过添加更多内容，轻松添加新工具 Tool 定义
类型安全使用 Pydantic 模型进行验证
异步能够高效处理多个请求
简单无需复杂的网络配置，只需通过标准输入/输出进行通信
可调试的全面的日志记录和错误处理

特性/特点

这个MCP服务器提供了以下工具：

你好按名字向某人问好
回声回传您提供的任何信息
获取时间获取当前日期和时间
加数字将两个数相加

安装

先决条件

Python 3.8或更高版本
pip（Python包安装工具）

设置

克隆或下载此仓库
创建一个虚拟环境：
```
py -m venv .venv
```
激活虚拟环境：
- 在Windows上：
```
.venv\Scripts\activate
```
- 在 macOS/Linux 上：
```
source .venv/bin/activate
```
安装所需的依赖项：
```
pip install -r requirements.txt
```

本地测试

快速测试

运行简单的测试脚本来验证一切是否正常工作：

py test_simple.py

这将检查：

✅ 依赖项已正确安装
✅ 服务器模块导入无错误
✅ 服务器启动成功，未发生崩溃

手动测试

方法1：直接运行服务器

启动服务器：

.venv\Scripts\python.exe -m mcp_hello_server.main

服务器将启动并等待在标准输入（stdin）上接收JSON-RPC消息。 你会看到：
```
INFO:mcp_hello_server:Starting MCP Hello Server...
```

使用JSON-RPC消息进行测试 （你可以复制粘贴这些）：

初始化服务器：

{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}

发送初始化通知：

{"jsonrpc": "2.0", "method": "notifications/initialized"}

列出可用工具：

{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}

调用hello工具：

{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "hello", "arguments": {"name": "Test User"}}}

调用回声工具：

{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "echo", "arguments": {"message": "Hello, MCP!"}}}

停止服务器： 新闻界 Ctrl+C

方法2：使用MCP客户端进行测试

配置MCP客户端 （如Claude Desktop）并配置在 mcp_config.json:

{
  "mcpServers": {
    "mcp-hello-server": {
      "command": ".venv\\Scripts\\python.exe",
      "args": ["-m", "mcp_hello_server.main"],
      "env": {}
    }
  }
}

客户端将自动：
- 启动服务器进程
- 发送初始化消息
- 发现可用工具
- 允许您通过客户端界面调用工具

方法三：交互式测试

为了获得更互动的体验，您可以使用测试脚本：

py test_interactive.py

这直接测试服务器功能，而不使用stdio传输。

预期回复

在手动测试时，你应该看到类似这样的响应：

工具列表响应：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "hello",
        "description": "Say hello to someone",
        "inputSchema": {...}
      },
      {
        "name": "echo", 
        "description": "Echo back the provided message",
        "inputSchema": {...}
      }
    ]
  }
}

你好，工具响应：

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Hello, Test User! Welcome to the MCP Hello Server!"
      }
    ]
  }
}

故障排除

服务器立即退出：

这是正常的！MCP服务器在标准输入上等待JSON-RPC消息
如果你看到了启动日志信息，说明服务器正在运行

导入错误：

确保你已经激活了虚拟环境： .venv\Scripts\activate
验证依赖项是否已安装： pip list | grep mcp

权限错误：

在Windows上，请确保您使用的是 .venv\Scripts\python.exe 而不是仅仅 python
检查虚拟环境是否成功创建

使用方法

运行服务器

您可以直接运行MCP服务器：

py -m mcp_hello_server.main

或者使用已安装的包：

mcp-hello-server

MCP 客户端配置

要在MCP客户端中使用此服务器，请将以下配置添加到您的MCP客户端配置文件中：

{
  "mcpServers": {
    "mcp-hello-server": {
      "command": "py",
      "args": ["-m", "mcp_hello_server.main"],
      "env": {}
    }
  }
}

确保调整好 command 并且 args 基于您的Python安装和虚拟环境设置。

可用工具

你好

按名字问候某人。

参数：

name （字符串，必填）：要问候的人的名字

示例：

{
  "name": "hello",
  "arguments": {
    "name": "Alice"
  }
}

回复：

Hello, Alice! Welcome to the MCP Hello Server!

echo（回声）

回传提供的信息。

参数：

message （字符串，必填）：要回显的消息

示例：

{
  "name": "echo",
  "arguments": {
    "message": "Hello, MCP!"
  }
}

回答：

Echo: Hello, MCP!

获取时间

返回当前的日期和时间。

参数： 无

示例：

{
  "name": "get_time",
  "arguments": {}
}

回应：

Current time: 2024-01-15 14:30:25

加数字

将两个数相加。

参数：

a （数字，必填）：第一个数字
b （数字，必填）：第二个数字

示例：

{
  "name": "add_numbers",
  "arguments": {
    "a": 5,
    "b": 3
  }
}

回复：

5 + 3 = 8

发展

项目结构

MCP-Server/
├── mcp_hello_server/
│   ├── __init__.py      # Main server implementation
│   └── main.py          # Entry point
├── requirements.txt     # Python dependencies
├── pyproject.toml       # Project configuration
├── mcp_config.json     # MCP client configuration example
└── README.md           # This file

添加新工具

向服务器添加新工具：

将工具定义添加到 list_tools() 函数 in mcp_hello_server/__init__.py
将工具实现添加到 call_tool() 同一文件中的函数
用新工具的文档更新此README文件

测试

你可以通过运行服务器并使用MCP客户端与它进行交互来测试服务器。服务器使用stdio传输方式，因此它通过标准输入/输出进行通信。

故障排除

常见问题

导入错误确保你已安装所有依赖项，使用 pip install -r requirements.txt
权限错误确保您拥有运行Python脚本的必要权限
虚拟环境在运行服务器之前，请确保已激活您的虚拟环境

记录（日志）

服务器记录重要事件以辅助调试。日志包括：

服务器启动信息
工具调用请求和响应
错误信息

许可证

这个项目采用MIT许可证授权。

做出贡献

请随时提交问题、功能请求或拉取请求，以改进这个MCP服务器的实现。

使用说明

MCP Hello 服务器

什么是MCP？

其工作原理

架构概述

核心组件

1. 服务器实例

2. 工具注册系统

3. 工具执行系统

4. 通信协议

消息流示例

关键技术特性

异步架构

错误处理

日志系统

类型安全

这种架构的优势

特性/特点

安装

先决条件

设置

本地测试

快速测试

手动测试

方法1：直接运行服务器

方法2：使用MCP客户端进行测试

方法三：交互式测试

预期回复

故障排除

使用方法

运行服务器

MCP 客户端配置

可用工具

你好

echo（回声）

获取时间

加数字

发展

项目结构

添加新工具

测试

故障排除

常见问题

记录（日志）

许可证

做出贡献

相关 MCP

ChatGPT交互工具

Loki日志查询服务

Genkit MCP 集成插件

网页搜索协议服务

WHOIS查询服务

ChatGPT MCP服务器