MCP Server 开发指南
项目结构
mcp-server-demo/
├── server_fastmcp.py # FastMCP 方式（推荐，简洁）
├── server_raw.py # 原生 SDK 方式（底层，灵活）
├── test_server.py # 测试脚本
└── README.md # 本文件
快速开始
# 1. 初始化环境（创建 venv + 安装依赖）
bash setup.sh
# 2. 运行测试
.venv/bin/python test_server.py # 测试 FastMCP 版本
.venv/bin/python test_server.py raw # 测试原生 SDK 版本
# 或者先激活 venv，之后直接用 python
source .venv/bin/activate
python test_server.py
两种开发方式对比
FastMCP（推荐入门）
- 用装饰器
@mcp.tool()自动从函数签名生成 JSON Schema - 参数类型从 type hints 自动推断
- docstring 自动变成工具描述
- 启动一行代码：
mcp.run()
原生 SDK（底层）
- 手动定义
inputSchema（JSON Schema 格式） - 手动实现
list_tools()和call_tool()两个处理函数 - 更接近协议本身，适合需要精细控制的场景
如何接入 Hermes
在 ~/.hermes/config.yaml 中添加：
mcp_servers:
demo:
command: "/home/ubuntu/mcp-server-demo/.venv/bin/python"
args: ["/home/ubuntu/mcp-server-demo/server_fastmcp.py"]
重启 Hermes 后，会自动发现并注册两个工具：
mcp_demo_calculate— 计算数学表达式mcp_demo_get_weather— 查询天气
MCP 协议通信流程
客户端 (Hermes) Server (你的代码)
| |
|-- initialize 请求 ------------->|
|<-- initialize 响应 -------------| (serverInfo, capabilities)
| |
|-- tools/list 请求 ------------->|
|<-- tools/list 响应 -------------| (工具名称 + inputSchema)
| |
|-- tools/call 请求 ------------->|
| (name + arguments) |
|<-- tools/call 响应 -------------| (TextContent 结果)
| |
核心概念
Tool 定义
每个工具需要：
- name: 唯一名称
- description: 描述（LLM 会读这个来决定什么时候用）
- inputSchema: JSON Schema 格式的参数定义
传输方式
- stdio: 通过 stdin/stdout 通信，Hermes 默认用这个
- HTTP/StreamableHTTP: 监听端口，适合远程调用
安全注意事项
- 不要在 tool 实现里做危险操作（直接执行用户输入的代码等）
- 使用参数校验（FastMCP 的 type hints 会自动校验）
- 敏感信息通过
env配置传入，不要硬编码
进阶话题
- Resources: 暴露可读取的数据源（文件、数据库等）
- Prompts: 预定义的提示词模板
- Sampling: Server 主动请求 LLM 做推理（需要客户端支持）
- 错误处理: 返回
isError: true的结果 - 进度通知: 长时间运行的工具可以发送进度更新
