fastmcp 学习

https://github.com/jlowin/fastmcp

这篇文章是我学习 FastMCP 的一次系统整理：从 MCP 到 FastMCP 的组件设计，再到 Provider、Transform、Context、任务与部署方式。目标是把零散笔记变成一条能走通的理解路径。

1. 我先把 MCP 讲清楚：它解决的到底是什么问题？

很多时候 AI “会想”，但它不会“做”。

• 想查数据库
• 想调用内部 API
• 想发邮件或写文件

如果没有一套标准的协议，AI 客户端（Claude、Cursor 等）就很难稳定、安全、可扩展地调用你提供的能力。

MCP（Model Context Protocol）就是这套标准协议：

• 客户端用统一的方式发起调用请求
• 服务器用统一的方式暴露工具、资源和提示词
• 中间靠 JSON-RPC 通信

┌─────────────────┐         JSON-RPC          ┌─────────────────┐
│   AI 客户端      │ ◄─────────────────────► │   MCP 服务器     │
│ (Claude/Cursor) │                           │  (你写的代码)    │
└─────────────────┘                           └─────────────────┘

我更愿意把它理解成：“AI 时代的工具接口规范”。

2. FastMCP 最舒服的点：几乎零配置，把函数变成工具

FastMCP 让我觉得设计很顺的地方在于：它会自动读取函数的 docstring 作为工具描述，AI 在 list_tools() 里看到的就是这段说明。

@mcp.tool
def search_database(query: str) -> str:
	"""搜索数据库"""
	return f"搜索结果: {query}"

这背后意味着：

• 你只需要把 Python 函数写好
• 类型注解负责生成 schema
• docstring 负责给 AI “看懂”这个工具

2.1 description 的优先级

如果你在装饰器里手动写了 description，它会覆盖 docstring：

@mcp.tool(description="手动描述，会覆盖 docstring")
def search_database(query: str) -> str:
	"""这个 docstring 不会被用"""
	return f"搜索结果: {query}"

我自己的习惯是：

• 大多数时候只写 docstring
• 需要更强的提示效果时再加 description

3. 三类组件：Tool / Resource / Prompt

FastMCP 把“暴露给 AI 的东西”拆成了三类，我按最常用到最少用排序：

3.1 Tool：需要执行动作（最常用）

Tool = AI 要“干活”。典型是有副作用的事情。

@mcp.tool
def send_email(to: str, body: str) -> str:
	"""发送邮件"""
	return "已发送"

3.2 Resource：只读上下文

Resource = AI 要“看资料”，不执行动作。

@mcp.resource("docs://api-guide")
def api_guide() -> str:
	"""API 使用指南"""
	return open("api_guide.md").read()

3.3 Prompt：预设工作模板

Prompt = 给 AI 的指令模板，单体使用频率不高，但在多 agent、规范化工作流时可能更有价值。

4. 从“写一个 @mcp.tool”到“AI 真正调用成功”：调用链怎么走？

理解调用链能帮我定位很多问题，比如：为什么工具没被注册？为什么参数 schema 不对？为什么调用返回异常？

我用一句话概括：

装饰器阶段把函数注册成组件；运行时根据 name 查组件并执行原始函数；最后把结果包装成 MCP 返回格式。

4.1 装饰器阶段（服务启动时）

@mcp.tool
def add(a: int, b: int) -> int:
	"""加法计算"""
	return a + b

发生的事大致是：

1. 解析函数名、docstring、类型注解
2. 生成 schema
3. 注册进 LocalProvider 的组件容器（类似字典）

4.2 AI 调用阶段（运行时）

• AI 发起 tools/call
• server 路由到 call_tool
• provider 根据 name 找到 tool
• 执行原始函数
• 包装返回

5. Provider：工具不一定要手写

我之前以为 “工具 = 我写的 @mcp.tool”，后来发现 Provider 的设计把工具来源打开了。

• LocalProvider：你手写函数（默认）
• OpenAPIProvider：把 REST API 直接变成工具
• ProxyProvider：代理另一个 MCP 服务，复用对方工具集

这个抽象很关键：工具是一种“能力描述”，能力可以来自不同系统。

6. Transform：在暴露给 AI 前做“加工”

Transform 的感觉有点像中间件，但它作用在“组件层”。我常见的用法是：

• 加命名空间：避免命名冲突（例如 api_search vs local_search）
• 过滤工具：只暴露符合 tag 的工具
• 鉴权/可见性控制：按用户权限隐藏敏感能力

7. Context：让工具执行过程“可解释、可追踪”

工具不是只能返回一个结果。执行过程中如果能告诉 AI 当前在做什么，交互体验会好很多。

@mcp.tool
async def search(query: str, ctx: Context) -> str:
	await ctx.info("正在连接数据库...")
	await ctx.report_progress(50, 100)
	return "结果"

我的理解：

• Context 是工具与系统对话的接口
• 它让工具“边做边说”，而不是沉默地等最终结果

8. 依赖注入：把敏感依赖藏在工具后面

把数据库连接、鉴权、API key 这些东西放进工具参数里是危险的。

FastMCP 的 Depends 注入让我觉得很舒服：

def get_db():
	return Database(os.environ["DATABASE_URL"])

@mcp.tool
def query(sql: str, db = Depends(get_db)) -> str:
	return db.execute(sql)

AI 调用时只需要提供 sql，db 由系统注入。

9. 后台任务（Tasks）：长耗时操作不要阻塞

如果某个工具要跑 1-5 分钟（生成报告、视频渲染、批处理），同步等结果会让体验变差。

@mcp.tool(task=True)
async def generate_report(data: str) -> str:
	"""生成报告"""
	return "报告完成"

工具元信息会告诉 AI：这个工具支持后台模式，客户端可以选择异步调用并轮询状态。

10. Transport：怎么部署、怎么连

我目前最常用的选择是：

• stdio：本地集成（Claude Desktop、Cursor 常用）
• http：远程部署（服务器上跑）

协议本质是 JSON-RPC，只是“跑在哪条管道上”的区别。

11. 这次学习我留下的结论

如果只用一句话总结 FastMCP：

它把“写 Python 函数”升级成“给 AI 暴露可调用的能力”，并且把元信息、通信、组织方式都标准化了。

我自己做 MCP 工具/Agent 项目时，会优先用：

• Tool + docstring（先跑通）
• Depends（把依赖收进去）
• Provider/Transform（再扩展到复用与治理）
• task=True（长任务体验优化）