服务注册与分布式协调 / 系统课时
验证转换后的工具契约
验证转换后的工具契约
转换完成并不代表工具就适合模型调用。这一节用真实 MCP 客户端读取工具列表、检查参数 Schema、执行一次成功调用和一次失败调用,再把结果与后端行为对齐,确认工具描述、参数约束、返回内容和错误语义都能稳定工作。
学习目标
- 用 MCP 客户端读取工具定义并检查名称、描述和输入 Schema
- 调用目标工具,核对返回内容是否与原业务接口语义一致
- 用非法参数验证错误契约,并判断问题发生在参数校验、网关转换还是后端
先定义验收口径
工具契约至少要同时满足四件事:name 稳定且可区分,description 能说明动作和对象,inputSchema 能约束必填项与类型,调用结果既适合模型理解又不丢失业务关键字段。只验证“能调用成功”是不够的,因为模型选错工具、参数类型过宽或异常信息泄露内部实现,同样会让上线后的 Agent 不稳定。

用客户端读取并调用工具
下面使用 MCP Python SDK 的高层 Client。当前 SDK 的 Client(URL) 会使用 Remote HTTP 连接,并提供 list_tools()、call_tool()、protocol_version 等高层接口;工具对象暴露 input_schema,调用结果暴露 content、structured_content 与 is_error。([MCP Python SDK][2]) 运行前在环境中提供 MCP_ENDPOINT、MCP_TOOL_NAME、MCP_TOOL_ARGS 和 MCP_BAD_TOOL_ARGS;后两个值必须是 JSON 对象字符串。MCP_BAD_TOOL_ARGS 应故意违反当前 inputSchema 的一个明确约束,例如缺少必填字段或提供错误类型。
import json
import os
import anyio
from mcp import Client
async def list_all_tools(client: Client):
tools = []
cursor = None
while True:
page = await client.list_tools(cursor=cursor)
tools.extend(page.tools)
if page.next_cursor is None:
return tools
cursor = page.next_cursor
async def main() -> None:
endpoint = os.environ["MCP_ENDPOINT"]
tool_name = os.environ["MCP_TOOL_NAME"]
good_args = json.loads(os.environ["MCP_TOOL_ARGS"])
bad_args = json.loads(os.environ["MCP_BAD_TOOL_ARGS"])
async with Client(endpoint) as client:
tools = await list_all_tools(client)
tool = next((item for item in tools if item.name == tool_name), None)
if tool is None:
raise SystemExit(f"tool not found: {tool_name}")
# 先打印模型实际看到的契约,再执行正向调用。
print("protocol=", client.protocol_version)
print("tool=", tool.name)
print("description=", tool.description)
print("inputSchema=", json.dumps(tool.input_schema, ensure_ascii=False))
result = await client.call_tool(tool_name, good_args)
print("good.is_error=", result.is_error)
print("good.content=", [block.model_dump() for block in result.content])
print("good.structured_content=", result.structured_content)
# 负向用例应返回稳定错误,而不是执行出一条错误业务数据。
try:
bad = await client.call_tool(tool_name, bad_args)
print("bad.is_error=", bad.is_error)
print("bad.content=", [block.model_dump() for block in bad.content])
except Exception as exc:
print("bad.exception=", type(exc).__name__, str(exc))
if __name__ == "__main__":
anyio.run(main)预期输出
protocol= <PROTOCOL_VERSION>
tool= <TOOL_NAME>
description= <TOOL_DESCRIPTION>
inputSchema= {"type":"object",...}
good.is_error= False
good.content= <CONTENT_BLOCKS>
good.structured_content= <STRUCTURED_CONTENT_OR_NONE>
bad.is_error= True
bad.content= <VALIDATION_ERROR_CONTENT>如果目标网关把非法请求作为协议级错误返回,最后两行也可能表现为 bad.exception=<ERROR>;实际文案允许不同,但必须明确指出哪一项参数不合法,且不得包含数据库口令、内部堆栈、Token 等敏感信息。
核对 Schema 是否真的能指导模型
读取 inputSchema 后,重点看必填项、类型、枚举和字段说明是否与后端真实约束一致。后端要求正整数而 Schema 只写 number,或者接口只接受固定状态值却没有 enum,都会扩大模型生成无效参数的空间。工具描述也要能区分相似能力,例如“查询订单详情”和“搜索订单列表”不能只写成模糊的“查询订单”。
如果转换器把路径参数、查询参数和请求体合并到一个对象中,要确认同名字段没有覆盖,默认值没有改变业务含义,敏感字段也没有被错误暴露为模型可填写参数。Schema 的目标不是复制 OpenAPI 的全部细节,而是保留模型正确调用所需要的约束。
对齐返回内容与后端执行
正向调用通过后,不只看 is_error=False。还要核对 content 是否包含模型需要理解的信息,structured_content 若存在,其字段应与业务结果一致;同时在后端日志或链路追踪中用 <ID> 关联这次调用,确认请求方法、路径和参数都落到了预期接口。
对有副作用的工具,验收时还要确认一次 tools/call 只产生一次预期业务效果。若网关或后端启用了自动重试,应使用幂等键或关闭不安全重试,再测试超时和断连场景。
让错误也成为契约的一部分
负向用例至少覆盖一个必填字段缺失或类型错误。理想结果是错误指出“哪个字段、违反什么约束”,而不是只返回“调用失败”。如果非法参数已经到达后端才报错,说明网关侧 Schema 校验没有生效;如果 Schema 正确但正常参数仍被拒绝,则回查转换后的参数映射和后端实际接口定义。
当工具列表稳定、参数约束足够精确、成功结果可被模型理解、失败结果可定位且不泄露内部信息时,这个转换后的工具才算具备可供 Agent 长期调用的契约,而不只是一次偶然成功的接口包装。