AI Agent / 系统课时

暴露 MCP 工具

暴露 MCP 工具

本节把一个普通 Python 函数变成 MCP 工具,并让客户端能够发现它的名称、参数结构和用途,再通过统一的工具调用完成参数校验与执行。完成后,你会知道工具定义中哪些信息会直接影响 Agent 是否能正确选择和调用它。

学习目标

  • 使用 MCPServer 把本地函数注册为可发现工具
  • 区分结构校验、业务校验与函数执行
  • 通过工具清单和调用结果验证暴露是否正确

工具暴露的核心链路

MCP 工具不是“把函数名发给模型”这么简单。服务端需要公开工具元数据,客户端先获取工具清单,再把名称、描述和输入结构提供给 Agent;Agent 决定调用后,客户端把参数送回 MCP 服务端,由服务端完成校验并执行本地函数。

MCP 工具从发现到调用的时序

工具的输入结构通常由函数签名和类型标注派生。类型不匹配属于结构问题,应尽量在进入业务逻辑前被拒绝;例如“数量必须大于 0”这类跨字段或业务规则,仍应在函数内部显式检查。

注册一个可调用工具

把下面的服务保存为 orders_server.py,放在上一课 probe.py 所在目录。沿用 Python SDK 2.3.0。金额用整数分保存,避免二进制浮点舍入。

python
from typing import Annotated
from mcp.server.mcpserver import MCPServer
from pydantic import Field

server = MCPServer("order-tools")

@server.tool()
def order_total(
    unit_cents: Annotated[int, Field(strict=True, ge=0, le=10_000_000)],
    quantity: Annotated[int, Field(strict=True, gt=0, le=10_000)],
) -> int:
    """计算单价与数量的乘积,输入和输出金额都以分计。"""
    return unit_cents * quantity

if __name__ == "__main__":
    server.run(transport="stdio")
bash
python probe.py orders_server.py --tool order_total --arguments '{"unit_cents":1990,"quantity":3}'

列表应包含 order_total,调用输出 tool_error: False 和 text: 5970。把数量改成 0,客户端应看到工具失败。参数类型、范围和单位同时写进工具定义,函数仍应依据实际业务校验请求人是否可以访问或修改相应订单。

让工具容易被正确调用

工具能注册成功,不代表 Agent 就会用对。名称应表达动作,描述应说明适用场景,参数名要避免缩写;不要把多个完全不同的业务动作塞进一个“万能工具”,否则模型很难稳定选择参数和调用时机。

参数校验最好分两层:JSON Schema 或 SDK 负责检查类型、必填字段等结构约束,函数内部负责库存不能为负、用户是否有权限、订单状态能否迁移等业务约束。即使调用来自模型,也不能跳过后端原本需要的权限和一致性检查。

验证发现与执行

验证时不要只看“服务能启动”。先确认客户端能够列出工具及参数结构,再用一组合法参数发起调用,最后补一组非法参数检查失败是否可控。对本例而言,1990 分乘以 3 得到 5970 分。数量 0、浮点数或字符串都应作为不合法参数处理。

真正可用的 MCP 工具需要同时满足三个条件:客户端找得到、Agent 看得懂、服务端执行得安全。把这三个条件分别验证,比只测试本地函数本身更接近真实 Agent 运行环境。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

暴露 MCP 工具

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通