FastMCP 装饰器源码探秘：从 tool() 到 prompt() 的注册与转换机制

1. FastMCP装饰器机制概览FastMCP作为MCP协议的Python实现其核心魔力在于三个装饰器tool()、resource()和prompt()。这些装饰器就像魔法棒能将普通Python函数变成MCP生态系统中的标准组件。想象你正在搭建一个天气查询服务只需要几行代码from mcp.server.fastmcp import FastMCP mcp FastMCP(nameweather) mcp.tool() def get_weather(city: str) - str: 获取指定城市的天气信息 return f{city}的天气是晴朗这个简单的tool()背后其实完成了函数签名解析、参数Schema生成、类型转换等复杂操作。装饰器的工作原理就像流水线函数包装捕获被装饰函数的元信息签名解析提取参数类型和返回类型Schema生成创建符合MCP规范的接口描述注册管理将组件添加到对应的管理器2. 装饰器核心实现解析2.1 装饰器工厂模式FastMCP采用装饰器工厂模式这是Python中实现可配置装饰器的经典方式。以tool()为例def tool(self, nameNone, titleNone, descriptionNone) - Callable: # 检查装饰器是否被正确调用 if callable(name): raise TypeError(需使用tool()而非tool) def decorator(fn: Callable) - Callable: self.add_tool(fn, namename, titletitle, descriptiondescription) return fn return decorator这种结构允许装饰器接收配置参数同时保持被装饰函数的原始签名。当看到mcp.tool(nameweather_tool)时先执行tool(nameweather_tool)返回decorator函数再用decorator装饰目标函数2.2 类型系统集成FastMCP深度集成Python类型注解系统通过inspect模块实现智能解析import inspect def process_function(fn): sig inspect.signature(fn) params sig.parameters for name, param in params.items(): print(f参数 {name}: 类型{param.annotation} 默认值{param.default})对于这个天气查询函数mcp.tool() def get_weather(city: str 北京) - str: ...装饰器会提取参数city类型为str默认值北京返回类型为str3. 组件注册全流程3.1 Tool注册机制tool()的完整注册流程包含这些关键步骤元数据提取func_name name or fn.__name__ func_doc description or fn.__doc__ or is_async inspect.iscoroutinefunction(fn)参数模型构建from pydantic import create_model ArgModel create_model( f{func_name}Arguments, __base__BaseModel, **dynamic_fields )工具实例化tool Tool( namefunc_name, descriptionfunc_doc, parametersArgModel.schema(), fnfn )注册到管理器self._tool_manager.add_tool(tool)3.2 类型转换黑科技FastMCP会自动处理类型转换例如将字符串转为Message对象mcp.prompt() def weather_prompt(city: str) - list: # 返回简单字符串也会被自动包装 return f查询{city}天气背后的转换逻辑if isinstance(result, str): return [UserMessage(contentTextContent(textresult))]4. 三大装饰器对比特性tool()resource()prompt()核心用途功能工具数据资源对话模板必需参数无URI字符串无返回类型任意str/bytes/dictList[Message]异步支持是是是管理器ToolManagerResourceManagerPromptManager5. 实战中的坑与技巧5.1 常见问题排查当装饰器不工作时可以这样调试检查函数签名print(inspect.signature(your_function))验证类型注解from typing import get_type_hints print(get_type_hints(your_function))查看生成的Schematool mcp._tool_manager._tools[your_tool] print(tool.parameters)5.2 性能优化建议对于高频调用的工具函数使用functools.lru_cache缓存结果from functools import lru_cache mcp.tool() lru_cache(maxsize100) def cached_query(param: str) - str: ...避免在装饰器参数中做复杂计算# 不推荐 mcp.tool(descriptiongenerate_complex_desc()) # 推荐 DESC generate_complex_desc() mcp.tool(descriptionDESC)6. 深入源码关键类6.1 ToolManager解析ToolManager是工具组件的核心管家主要数据结构class ToolManager: def __init__(self): self._tools: dict[str, Tool] {} self._lock threading.Lock() def add_tool(self, tool: Tool): with self._lock: if tool.name in self._tools: raise ValueError(f工具{tool.name}已存在) self._tools[tool.name] tool关键方法get_tool(name)按名称获取工具list_tools()返回所有工具remove_tool(name)移除指定工具6.2 类型适配系统TypeAdapter负责处理各种参数类型from pydantic import TypeAdapter adapter TypeAdapter(Union[str, int, float]) def validate_input(value): try: return adapter.validate_python(value) except ValidationError as e: print(f类型错误: {e})这套系统支持基础类型str/int/float等复合类型List/Dict/Union等自定义Pydantic模型7. 自定义装饰器进阶7.1 扩展装饰器功能继承FastMCP创建自定义装饰器class CustomMCP(FastMCP): def custom_decorator(self, **kwargs): def decorator(fn): # 前置处理 print(f注册函数: {fn.__name__}) # 调用原始装饰器 tool self.tool(**kwargs)(fn) # 后置处理 self._custom_registry[fn.__name__] fn return tool return decorator7.2 动态参数处理处理带可变参数的函数mcp.tool() def dynamic_args(**kwargs): 接收任意关键字参数 return kwargs # 自动生成的Schema会包含额外属性字段 additional_properties { additionalProperties: True }8. 调试与问题诊断8.1 使用调试工具FastMCP提供了内置调试工具元数据检查器python -m mcp.inspect your_server.py实时日志监控mcp FastMCP(debugTrue) # 启用详细日志8.2 常见错误处理签名解析失败 检查函数是否使用了不支持的参数类型如*args类型转换错误 确保返回类型与声明一致必要时添加显式转换命名冲突 使用name参数显式指定唯一标识符mcp.tool(nameunique_weather) def get_weather(): ...通过源码分析我们发现FastMCP的装饰器设计完美体现了Python的约定优于配置哲学。在实际项目中合理利用这些装饰器可以大幅提升开发效率但也要注意类型系统的严格校验可能带来的学习曲线。