吉安微信网站河南省网站

引言：装饰器遇见类方法的“陷阱”

FastMCP的装饰器（如@tool、@resource、@prompt）是定义MCP组件（工具、资源、提示）的核心方式，但当它们与类中的方法（实例方法、类方法、静态方法）结合时，直接使用往往会出现意外行为——LLM可能看到self或cls等无关参数，甚至方法变得不可调用。本文将系统解析这一问题的根源，提供三种方法类型的正确使用姿势，帮助开发者在保持面向对象设计的同时，无缝集成MCP组件。

一、问题根源：装饰器与方法绑定的冲突

FastMCP装饰器的工作原理是在“装饰时”捕获函数并将其转换为MCP组件（如Tool、Resource对象）。但类中的方法在定义时处于“未绑定”状态：

• 实例方法：装饰时self参数尚未绑定到具体实例，LLM会将其视为必填参数；
• 类方法：装饰时cls参数未绑定到类，同样会被LLM误判为需要传入的参数；
• 装饰器返回值：装饰器返回的是MCP组件对象（如Tool），而非原始函数，直接装饰会导致方法失去可调用性。

典型错误示例：

from fastmcp import FastMCP
mcp = FastMCP()class Calculator:@mcp.tool  # 错误：直接装饰实例方法def add(self, x: int, y: int) -> int:return x + yobj = Calculator()
obj.add(1, 2)  # 报错：add已被转换为Tool对象，不再是可调用方法

二、实例方法：先实例化，再注册绑定后的方法

实例方法依赖self参数绑定具体实例，直接装饰会导致self被暴露给LLM。正确的做法是：先创建实例，再注册绑定后的方法（此时self已自动关联实例，LLM看不到该参数）。

错误做法：直接装饰实例方法

class Calculator:@mcp.tool  # 错误：装饰未绑定的实例方法def multiply(self, x: int, y: int) -> int:return x * y# 问题1：LLM会看到self参数，无法调用
# 问题2：方法已被转换为Tool对象，实例调用失败
calc = Calculator()
calc.multiply(3, 4)  # AttributeError: 'Tool' object is not callable

正确做法：实例化后注册绑定方法

class Calculator:def multiply(self, x: int, y: int) -> int:  # 不直接装饰return x * y# 步骤1：创建实例（self绑定到该实例）
calc = Calculator()
# 步骤2：注册绑定后的方法（self已隐含，LLM仅见x和y）
mcp.tool(calc.multiply)# 验证：LLM调用正常，Python调用也正常
calc.multiply(3, 4)  # 正常返回12
await mcp._mcp_call_tool("multiply", {"x": 3, "y": 4})  # 正常返回12

原理：通过实例访问方法时（calc.multiply），Python会创建“绑定方法”，self已自动关联实例，注册时MCP只会暴露x和y参数，避免LLM混淆。

三、类方法：类定义后注册，避免装饰器顺序错误

类方法依赖cls参数绑定类本身，直接装饰会导致cls被暴露。更关键的是，装饰器与@classmethod的顺序会引发错误——正确的做法是先定义类方法，再在类外注册。

错误做法：装饰器与@classmethod顺序冲突

class Parser:# 错误1：@classmethod在前，@mcp.tool在后——不报错但LLM会看到cls参数@[e-mail] from_string_v1(cls, s: str):return cls(data=s)# 错误2：@mcp.tool在前，@classmethod在后——直接报错@mcp.tool@classmethoddef from_string_v2(cls, s: str):return cls(data=s)
# 运行时会抛出ValueError：Cannot decorate classmethod with @tool...

正确做法：类定义后注册类方法

class Parser:@classmethod  # 仅使用@classmethod装饰def from_string(cls, s: str):return cls(data=s)# 类定义后注册类方法（cls已绑定到Parser类）
mcp.tool(Parser.from_string)# 验证：LLM调用时仅需传入s，无需关注cls
await mcp._mcp_call_tool("from_string", {"s": "test data"})  # 正常返回Parser实例

原理：类方法通过Parser.from_string访问时，cls已自动绑定到Parser类，注册后MCP会隐藏cls，仅暴露业务参数（如s）。

四、静态方法：推荐事后注册，而非直接装饰

静态方法不依赖self或cls，直接装饰看似可行，但装饰器会将其转换为MCP组件对象，导致方法失去可调用性。因此，推荐与实例方法、类方法保持一致：事后注册。

不推荐做法：直接装饰静态方法

class Utils:@mcp.tool  # 不推荐：装饰后方法变为Tool对象，失去可调用性@staticmethoddef sum(x: int, y: int) -> int:return x + yUtils.sum(1, 2)  # 报错：'Tool' object is not callable

推荐做法：静态方法事后注册

class Utils:@staticmethod  # 仅用@staticmethod装饰def sum(x: int, y: int) -> int:return x + y# 类定义后注册静态方法
mcp.tool(Utils.sum)# 验证：Python调用和LLM调用均正常
Utils.sum(1, 2)  # 正常返回3
await mcp._mcp_call_tool("sum", {"x": 1, "y": 2})  # 正常返回3

五、进阶模式：类初始化时自动注册组件

为避免手动注册的繁琐，可在类的__init__方法中自动注册实例方法，实现“实例化即注册”：

from fastmcp import FastMCP
mcp = FastMCP()class DataProcessor:def __init__(self, mcp_instance):# 初始化时自动注册实例方法mcp_instance.tool(self.clean_data)mcp_instance.resource("resource://processed")(self.get_processed_data)def clean_data(self, raw: str) -> str:"""清洗原始数据"""return raw.strip().lower()def get_processed_data(self) -> str:"""返回处理后的资源数据"""return "processed_data"# 实例化时自动注册组件
processor = DataProcessor(mcp)# 验证：组件已可用
await mcp._mcp_call_tool("clean_data", {"raw": "  Hello World  "})  # 返回"hello world"

适用场景：

• 封装多个关联组件（工具+资源），确保注册逻辑内聚；
• 动态创建组件实例（如多租户场景，每个实例注册专属组件）。

六、总结：三种方法的正确处理方式

方法类型	错误做法	正确做法	核心原理
实例方法	直接用@mcp.tool装饰	实例化后注册：mcp.tool(obj.method)	绑定self，隐藏实例参数
类方法	装饰器与@classmethod顺序错误	类定义后注册：mcp.tool(Cls.method)	绑定cls，隐藏类参数
静态方法	直接用@mcp.tool装饰	类定义后注册：mcp.tool(Cls.method)	避免方法变为不可调用的组件对象

通过“事后注册”而非“直接装饰”，既能保留面向对象设计的封装性，又能确保MCP组件被LLM正确识别和调用。这一模式让类方法与FastMCP装饰器无缝协作，为复杂业务场景提供了灵活且可靠的组件管理方案。

立即实践：将你的类方法按本文模式改造，体验面向对象与MCP组件结合的最佳实践！