[智能体-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对外工具标识add2. 传 name 参数自定义工具名与原函数名解耦python运行mcp.tool(namemath_sum) def add(a: float, b: float) - float: return a b对外工具标识math_sum内部仍执行add函数逻辑3. 补充参数互不干扰description、deprecated 仅做备注标记不改变工具检索名称python运行mcp.tool(namesubtract_calc, description数值减法) def sub(a: float, b: float) - float: return a - b对外调用名subtract_calc2. 基础语法结构python运行from mcp.server.fastmcp import FastMCP # 1. 创建服务实例 mcp FastMCP(服务名) # 2. 工具注册装饰器 mcp.tool(可选参数) def 函数名(形参: 类型注解) - 返回类型: 工具描述文档 # 业务逻辑 return 数据3. 装饰器可选参数3.1 name 自定义工具名python运行mcp.tool(namecalc_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(deprecatedTrue)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(namemath_add, description浮点加法运算) def add(a: float, b: float) - dict: 两数相加 return {sum: a b} if __name__ __main__: mcp.run(transportstdio)9. 常见报错踩点无类型注解→ 注册失败环境没装 mcp→ 找不到mcp.server.fastmcp参数写法不规范→ 客户端调用校验失败函数内部异常→ MCP 返回调用错误报文