装饰器 · mcp.tool

发表于 | 分类于 ，
将 Python 函数注册为 MCP 服务工具，供 LLM 客户端调用。

0. 一句话定位

维度 内容
作用对象 函数
使用场景 服务注册
来源 第三方 mcp（FastMCP）
语法形式 @mcp.tool() / @mcp.tool(name=..., description=...)

段末注释：MCP（Model Context Protocol，MCP） 是 LLM 与外部工具/资源交互的开放协议。

1. 做什么

把普通 Python 函数注册到 MCP 服务端；函数 docstring 与类型注解会暴露给客户端作为工具 schema；服务启动后 LLM 可发现并调用该工具。

2. 重点参数

参数 类型 默认值 作用 配置建议
name str 函数名 工具对外名称 与函数名不一致时显式指定
description str docstring 工具说明 写清用途与边界，供模型选型
（函数签名） — — 参数类型与返回值 用类型注解 + Google/NumPy 风格 docstring

具体可选参数以所用 FastMCP 版本文档为准；无参 @mcp.tool() 最常见。

3. 最小可运行示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("My_Mcp_Server")

@mcp.tool()
def sum(a: int, b: int) -> int:
    """两个整数相加。

    Args:
        a: 整数 a
        b: 整数 b
    Returns:
        两数之和
    """
    return a + b

if __name__ == "__main__":
    mcp.run(transport="stdio")

4. 常见变体

  • 多个工具挂在同一 FastMCP 实例上，各自 @mcp.tool()
  • HTTP 传输：mcp.settings.host / port + mcp.run(transport="sse") 等（依版本）

5. 适用 / 不适用

适用

  • 将现有 Python 能力暴露给 Cursor、Claude Desktop 等 MCP 客户端
  • 工具逻辑短、输入输出可结构化

不适用

  • 长时任务无进度反馈（需配合 Tasks/Resources 等 MCP 能力）
  • 无类型注解且 docstring 缺失时，模型难以正确填参

6. 易踩坑

  • 函数 docstring 过简会导致 LLM 误用工具；Args/Returns 建议完整
  • 启动方式（stdio / sse）须与客户端配置一致
  • 敏感操作需在本服务层做鉴权，装饰器本身不提供安全边界

7. 参考

-------------本文结束感谢您的阅读-------------