Hello World MCP Server 实现总结

📄 Hello World MCP Server 实现总结

一句话总结：本文记录了基于 Python mcp 官方库构建 Hello World MCP Server 的完整过程，涵盖代码架构、部署安装与测试验证三部分。

流程图

创建 mcp_server.py 主程序
定义两个工具：hello_world + hello_json
配置依赖 requirements.txt
pip install mcp 安装依赖
创建 .mcp.json 注册 Server
stdio 方式验证调用
重启 Claude Code 自动加载

内容梳理

一、代码架构

mcp_server.py 是一个标准的 MCP（Model Context Protocol - 模型上下文协议）Server，基于 Python 官方 mcp 库实现，通过 stdio 与 MCP 客户端（如 Claude Code）通信。

核心组成：

Server 实例化 ：Server("hello-world-server") 创建服务实例
日志隔离 ：所有日志通过 logging.basicConfig(stream=sys.stderr) 输出到 stderr，不污染 stdio 通信通道
工具注册 ：通过 @server.list_tools() 装饰器声明可用工具列表
调用路由 ：通过 @server.call_tool() 装饰器根据 name 参数分发到具体工具逻辑
启动入口 ：stdio_server() 上下文管理器创建读写流，server.run() 进入事件循环

两个工具：

工具名	参数	功能
`hello_world`	`name`（可选，默认 "World"）	返回问候语 `"Hello {name}!"`
`hello_json`	`folder_path`（必填）	扫描目录中 `.json` 文件，输出文件数量及每个文件的键数量摘要

二、关键设计决策

stdio 传输 ：选择 stdio_server() 而非 HTTP/SSE，因为 stdio 是 MCP 最基础、零配置的传输方式，适合本地工具集成
错误隔离 ：call_tool 中 try/except 捕获所有异常，即使工具执行失败也返回标准化的 TextContent，不会导致 Server 崩溃
文件数量限制 ：hello_json 中 json_files[:10] 限制最多读取 10 个文件，防止大目录导致响应膨胀
中文 JSON 支持 ：json.dumps(result, ensure_ascii=False) 确保中文内容不被转义

三、文件结构

复制代码

mcp_hello/
├── mcp_server.py          # MCP Server 主程序（约 100 行）
├── requirements.txt        # Python 依赖声明
└── mcp_server_summary.md   # 本文档

项目根目录配置：

复制代码

.mcp.json                   # MCP Server 注册配置

部署与安装

前置条件

Python 3.10+
pip 可用

步骤 1：安装依赖

bash 复制代码

pip install mcp

mcp 包会自动安装所有依赖（starlette、uvicorn、pydantic、jsonschema 等）。

步骤 2：注册到 Claude Code

在项目根目录创建或编辑 .mcp.json：

json 复制代码

{
  "mcpServers": {
    "hello-world": {
      "command": "python",
      "args": ["<项目绝对路径>/mcp_hello/mcp_server.py"]
    }
  }
}

注意：MCP Server 注册必须放在 .mcp.json，不能放在 .claude/settings.json（settings.json 不支持 mcpServers 字段）。

步骤 3：配置权限（可选）

如果 .claude/settings.json 的权限模式为 defaultMode: acceptEdits 以外的严格模式，需要添加 Bash(python *) 允许启动 MCP Server。

步骤 4：重载 Claude Code

重启 Claude Code（关闭并重新打开会话），MCP Server 会自动加载。加载后 Agent 的工具列表中将出现 hello_world 和 hello_json。

测试验证

方法 1：Linux/Bash 手动测试

启动 Server 并通过管道发送 JSON-RPC 请求：

bash 复制代码

cd <项目目录>
printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"hello_world","arguments":{"name":"Claude Code"}}}\n' | timeout 5 python mcp_hello/mcp_server.py 2>/dev/null

预期输出（第二行）：

json 复制代码

{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"{\"message\": \"Hello Claude Code!\", \"status\": \"success\"}"}],"isError":false}}

方法 2：交互式验证

重启 Claude Code 后，在对话中直接让 Agent 调用：

"用 hello_world 工具向我打招呼，name 参数用 '世界'"

Agent 会调用 MCP Server 并返回 Hello 世界!。

方法 3：验证 hello_json 工具

"用 hello_json 工具扫描 XXXX 目录下的 JSON 文件"

Agent 会返回该目录中 JSON 文件的数量和每个文件的键数量。

总结与展望

总结

MCP Server 核心要素只有三个：Server 实例化、list_tools 工具声明、call_tool 调用路由
日志走 stderr、数据走 stdout 的隔离模式是 MCP stdio 通信的关键纪律
MCP Server 必须注册在 .mcp.json，不能在 settings.json
工具内部是 100% 确定性代码，Agent 只有调用权、无法干预逻辑------这是 MCP 对比 Function Call 的核心优势

展望

可按 tools/xxx.py 模块化模式扩展更多工具，只需三步：新建工具文件 → list_tools 追加定义 → call_tool 追加分支
如需远程 MCP Server，可将 stdio 替换为 SSE/HTTP 传输，代码改动很小（仅替换 stdio_server() 为对应的传输层）
此模板可作为"工具工厂"，后续任何需要 AI 与外部系统交互的场景（数据库查询、API 调用、文件处理）均可快速复制