FastMCP 简介

FastMCP 是 Python 生态中流行的 MCP Server 框架，基于 mcp 包，提供简洁的装饰器 API。通过 pip install mcp fastmcp 即可开始开发。

基础结构

from fastmcp import FastMCP
mcp = FastMCP("my-server")
@mcp.tool()
def search(query: str) -> str:
    """根据关键词搜索文档"""
    return do_search(query)
@mcp.resource("doc://readme")
def readme() -> str:
    """返回项目 README 内容"""
    return open("README.md").read()

• FastMCP(name) 创建 Server 实例
• @mcp.tool() 注册工具，函数签名自动转为参数 schema
• @mcp.resource(uri) 注册资源，支持动态 URI 模板

装饰器详解

@mcp.tool()

• 支持 name、description 覆盖默认
• 参数可用类型注解（str、int、bool、list 等）或 Pydantic 模型
• 返回值会序列化为 JSON 传给客户端

@mcp.resource(uri_template)

• URI 可含参数，如 "doc://{filename}"
• 对应函数接收 URI 参数，返回文本或二进制内容

@mcp.prompt()

• 注册可复用提示模板
• 支持参数化，客户端传入变量后获取最终 Prompt

传输配置

# stdio（默认，用于 Claude Desktop 等）
mcp.run(transport="stdio")
或作为 HTTP/SSE 服务
mcp.run(transport="sse", host="0.0.0.0", port=8000)

错误处理

• 在工具内 raise ValueError("清晰错误信息")，会转为 MCP 标准错误响应
• 避免暴露内部实现细节，对用户展示友好提示

测试策略

单元测试：直接调用被 @mcp.tool() 装饰的函数，传入 Mock 依赖

协议测试：用 mcp 包的 Client 连接 Server，发送 List/Call 请求，断言响应

E2E 测试：在测试中启动 Server 子进程，通过 stdio 发送完整请求序列

最佳实践

• 工具与资源命名清晰，描述完整，便于模型正确选择
• 参数使用 Pydantic 做严格校验
• 对耗时操作做超时与取消支持
• 敏感操作加权限校验，避免越权调用

小结

FastMCP 通过装饰器大幅简化 Python MCP Server 开发。掌握 tool、resource、prompt 的注册方式与传输配置，再结合单元测试与协议测试，可快速构建稳定可用的 MCP 服务。