[智能体-59]：@mcp.tool () 语法完整详解
基于FastMCP标准工具注册装饰器
1. 作用
@mcp.tool()将普通 Python 函数注册为 MCP 协议可远程调用工具。
注册后，客户端通过 MCP 报文就能MCP Server自动调用该函数，无需程序员手动路由。
@mcp.tool () 命名映射规则
1. 无参写法：默认以函数名作为对外工具名
python
运行
@mcp.tool() def add(a: float, b: float) -> float: return a + b对外工具标识：add
2. 传 name 参数：自定义工具名，与原函数名解耦
python
运行
@mcp.tool(name="math_sum") def add(a: float, b: float) -> float: return a + b对外工具标识：math_sum，内部仍执行add函数逻辑
3. 补充参数互不干扰
description、deprecated 仅做备注标记，不改变工具检索名称
python
运行
@mcp.tool(name="subtract_calc", description="数值减法") def sub(a: float, b: float) -> float: return a - b对外调用名：subtract_calc
2. 基础语法结构
python
运行
from mcp.server.fastmcp import FastMCP # 1. 创建服务实例 mcp = FastMCP("服务名") # 2. 工具注册装饰器 @mcp.tool(可选参数) def 函数名(形参: 类型注解) -> 返回类型: """工具描述文档""" # 业务逻辑 return 数据3. 装饰器可选参数
3.1 name 自定义工具名
python
运行
@mcp.tool(name="calc_add") def add(a: float, b: float) -> float: return a + b客户端调用时用calc_add匹配函数。
3.2 description 强制描述
python
运行
@mcp.tool(description="两个浮点数求和计算")3.3 deprecated 标记废弃
python
运行
@mcp.tool(deprecated=True)4. 函数参数规范（强制要求）
- 必须写类型注解：
int/float/str/bool/dict/list - 支持默认参数
- 不支持动态不定参
*args/**kwargs
示例合法参数
python
运行
@mcp.tool() def user_info(name: str, age: int = 18) -> dict: return {"name": name, "age": age}5. 返回值规范
支持返回类型：
- 基础类型：
int, float, str, bool - 复合类型：
dict, list框架自动序列化为 MCP JSON 协议报文
python
运行
# 合法 return 100 return {"code":0, "data":"ok"} return [1,2,3]6. 文档字符串作用（必填建议）
函数内三引号注释，会自动同步给客户端大模型用于 AI 自动理解工具用途、自动填参。
python
运行
@mcp.tool() def add(a: float, b: float) -> float: """ 实现两个数字相加 :param a: 加数1 :param b: 加数2 :return: 相加结果 """ return a + b7. 底层运行机制
- 代码加载时，装饰器自动扫描函数签名、参数、注释
- 存入 MCP 内部工具注册表
- 客户端发起
call_tool请求 - 框架按函数名匹配、校验参数、自动执行
- 结果封装成标准 MCP 响应返回
8. 完整可运行样板
python
运行
from mcp.server.fastmcp import FastMCP mcp = FastMCP("ToolDemo") @mcp.tool(name="math_add", description="浮点加法运算") def add(a: float, b: float) -> dict: """两数相加""" return {"sum": a + b} if __name__ == "__main__": mcp.run(transport="stdio")9. 常见报错踩点
- 无类型注解→ 注册失败
- 环境没装 mcp→ 找不到
mcp.server.fastmcp - 参数写法不规范→ 客户端调用校验失败
- 函数内部异常→ MCP 返回调用错误报文