课程大纲 第 139 课,共 250 课 · 结构化输出与函数/工具调用
结构化输出与函数/工具调用

通过 MCP(模型上下文协议)使用工具

一旦你的应用有了不止一个工具,每家模型厂商都会为调用它们发明自己的 JSON 形状,于是你最终要为每个提供商写一个适配器。模型上下文协议(MCP)就是解决这个问题的开放标准。它是一个 JSON-RPC 2.0 线路协议,用来向任何模型客户端暴露工具(模型可以调用的函数)、资源(它可以读取的数据)和提示词。写一次 MCP 服务器,任何支持 MCP 的客户端(IDE 助手、桌面应用、智能体)都能使用它。

每条消息都是 JSON-RPC 2.0,这是一个很小的、固定的信封。一个请求总是带着四个键:

{"jsonrpc": "2.0", "id": 1, "method": "tools/call",
 "params": {"name": "add", "arguments": {"a": 2, "b": 3}}}

id 把一个回复和它的请求联系起来。服务器用一个响应来回答,它回传同一个 id,并且带着要么一个 result、要么一个 error 对象,永远不会两者都有:

{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "5"}], "isError": false}}
{"jsonrpc": "2.0", "id": 1, "error": {"code": -32601, "message": "Method not found"}}

负数代码是标准的 JSON-RPC:-32601 是 "method not found",-32602 是 "invalid params",依此类推。tools/call 的结果总是那个形状:一个由块(文本、图片等等)组成的 content 列表加上 isError。一个运行了但失败了的工具(比如城市名错了)会在一个正常的结果里用 isError: true 回答,这样模型能读到失败;JSON-RPC 的 error 对象是用于协议问题的,比如一个未知的方法。

一次会话以握手开始:客户端发送一个 initialize 请求(它的协议版本、它的能力和它的名字),服务器用自己的能力回答,然后客户端用一个 notifications/initialized 通知确认(一条没有 id 的消息,因为没人回复它)。只有这之后,客户端才会通过用空的 params 调用 tools/list 来发现工具;服务器返回工具描述的列表。

一个真正的 MCP 服务器运行在 stdio 或 HTTP 上,并把这些接进 SDK;这里我们用标准库的 json 模块构建和解析这些消息,让线路格式变得具体。你要写三个函数。

  • build_request(id, method, params) -> 信封 {"jsonrpc": "2.0", "id": id, "method": method, "params": params} 的 JSON 字符串。用 json.dumps。
  • parse_response(text) -> 用 json.loads 解析文本,要求 jsonrpc == "2.0"(否则抛出 ValueError)。如果它有 result,就返回 {"id": ..., "ok": True, "result": ...}。如果它有 error,就返回 {"id": ..., "ok": False, "error": {"code": ..., "message": ...}}。如果两者都没有,就抛出 ValueError。
  • list_tools_request(id) -> 发现工具的请求:一个方法为 "tools/list"、params 为空 {} 的 build_request。

因为 build_request 返回的是字符串,测试会用 json.loads 把它解析回来再比较字典,所以键的顺序无关紧要。确保结果和错误都能往返,发现请求的方法正确,而缺少 jsonrpc 或者既没有 result 也没有 error 的消息会抛出异常。

轮到你了

用 json 模块构建和解析 MCP 风格的 JSON-RPC 2.0 消息。build_request(id, method, params) 返回 {"jsonrpc": "2.0", "id", "method", "params"} 的 JSON 字符串。parse_response(text) 加载文本,要求 jsonrpc == "2.0"(否则抛出 ValueError),对结果返回 {"id", "ok": True, "result"},对错误返回 {"id", "ok": False, "error": {"code", "message"}},两者都没有时抛出异常。list_tools_request(id) 返回 params 为空的 tools/list 发现请求(在握手之后发送)。

发现这节课有问题?报告它 · 就这节课提问

这个练习即将开放

完成它前面的那一课,这一课就会解锁。整门课程免费,无需账号,而且你现在就可以阅读这节课。