实现篇第11章 给外部能力开一扇门——MCP ​

老Z章鱼在小A机器人旁检查来自远程日历服务的工具,并让只读日历卡通过适配与审批台。

本章导读: 实现篇扩展第 3 章。概念篇讲过 MCP 是“能力发现与消息交换的协议”。这一章推演 mini-agent 怎么接一个外部 MCP 服务,代码不进 src,要讲清的是 transport、工具适配、失败语义和信任边界。

小A的 Agent 只能读写自己的工作区。他想要一个“查日历”的能力,但日历在另一个服务里。他问老Z:“能不能让 Agent 直接调那个服务的 API?”

“能,但你别把 HTTP 请求直接写进工具。”老Z说,“你要接的是一个 MCP 服务端,它按协议暴露工具,你的 Agent 按协议调用。先把丑话说在前面:协议解决连通性,不解决信任。”

小A不服:“为什么不直接写个 calendar 工具,里面 fetch 那个 API?比接 MCP 简单多了。”

“现在简单,以后是债。”老Z说,“你直接写 fetch,API 地址、认证、错误处理全焊死在一个工具里,换个服务就得重写。MCP 把这些抽到协议层:服务端自己管认证和错误,你的 Agent 只管调一个叫 calendar_query 的工具。更关键的是,mini-agent 的 Tool.execute 返回 Promise<ToolResult>(见 types.ts),它假设本地同步语义,你把网络请求塞进去,超时、断连、重试都得在工具里处理。MCP 的价值就在这儿:它把‘远端能力’伪装成‘本地工具’,循环不需要知道背后是网络。这一章推演这个伪装层长什么样,不写进 src。”

先分清两个方向 ​

“MCP 有三种原语,先分清你接的是什么。”老Z说:

  • Tool:可调用的动作,这是 Agent 最需要的。
  • Resource:可读取的上下文(文件、文档)。
  • Prompt:可复用的模板。

“mini-agent 的循环只能消费自己的 Tool 接口(spec + execute)。所以 MCP 接入的核心问题是:怎么把一个 MCP 服务端的 Tool 变成 mini-agent 能调用的 Tool。这就是适配缝的位置,你不需要让循环懂 MCP,只需要一个把 MCP 工具翻译成 ToolSpec 的桥。”

把三种原语按“mini-agent 的循环有没有消费点”逐个过一遍:

MCP 原语 是什么 循环里有消费点吗 要接的话怎么接
Tool 可调用的动作 有:options.tools 适配成 Tool,直接可用
Resource 可读取的上下文 无 包成 read_resource 工具
Prompt 可复用的模板 无 改 system 注入逻辑

“这张表前两列是 MCP 的世界,第三、四列是 mini-agent 的世界。”老Z说,“只有 Tool 天然有消费点,Resource 和 Prompt 都要先改造循环才接得进去。改造本身不坏,坏的是没想清楚‘为什么要改’就动手,先把消费点画出来,原语接在哪一目了然。”

小A接着问:“那 Resource 和 Prompt 就不接了?”

“现在不接,循环没有消费它们的地方。”老Z说,“mini-agent 的 runAgent 只认 tools: Tool[](见 agent.ts),模型能调的只有工具。真要接,Resource 得包成一个 read_resource 工具,Prompt 得改 system 注入逻辑,而 mini-agent 现在的 system 是写死的字符串(见 main.ts)。规矩就一条:每接一种原语,先回答‘循环哪一处消费它’;消费点不存在,原语就先别接。”

设计一个最小 McpClient ​

版本与核验边界: 本章沿用原稿所引的 MCP 2026-07-28 外部规范专题,非 pi v1.0.0 实现;相关外部机制未经核验,也未用 pi v1.0.0 快照核验。本章没有补齐直接规范来源。下文及表格中的无状态、无握手/会话、_meta、server/discover、HTTP 重试与请求 ID、协议错误分类、resultType: "input_required" 和 inputResponses 均保留为【待核验】描述,不可当作已确认的规范要求或直接据此实现。先用本章讨论适配器边界;接入真实服务前须另行核对目标版本规范。

老Z沿 ModelClient 的模式推演了一个接口:

ts
// 设计草图:McpClient(未进 src,先确认需求)
export interface McpClient {
  /** 可选 server/discover 确认版本与能力,再 tools/list 拿到工具清单 */
  connect(): Promise<{ tools: McpTool[] }>;
  /** 调用一个工具;signal 请求取消本地等待,不保证远端副作用撤销 */
  call(name: string, input: unknown, signal?: AbortSignal): Promise<{ content: unknown; isError: boolean }>;
  close(): Promise<void>;
}

// 把 MCP 工具翻译成 mini-agent 的 Tool
function mcpToolToTool(mcpTool: McpTool): Tool {
  return {
    spec: { name: mcpTool.name, description: mcpTool.description, inputSchema: mcpTool.inputSchema },
    execute: async (input, signal) => {
      const result = await mcp.call(mcpTool.name, input, signal);
      const content = JSON.stringify(result.content ?? []);
      if (content === undefined) {
        throw new TypeError("MCP tool content is not JSON-serializable");
      }
      return { isError: result.isError, content };
    },
  };
}

“先说 connect 这个名字。”老Z说,“原稿对 MCP 2026-07-28 版的描述是无状态、没有握手和会话,每个请求在 _meta 里带协议版本和客户端能力;这些机制尚待核验。若目标版本确认采用这种机制,这里的 connect 就只是宿主自己的启动步骤:拉起 stdio 子进程,可选地调一次 server/discover 确认对方支持的版本,再调 tools/list。在这个假设下,版本和能力字段由 McpClient 在每次请求时补上,循环和适配器都不用管。”

“signal 要由 McpClient.call 传给底层传输并响应中止;这里只声明接口,尚未实现取消。取消本地等待不证明远端工具没执行,已发生的副作用也不会因此回滚。JSON.stringify 若抛错或返回 undefined,适配器就向上失败,不能把非字符串结果交给循环。”老Z说。

“再看 mcpToolToTool,它把 MCP 工具的形状翻译成 mini-agent 的形状。”老Z说,“循环完全不知道背后是 MCP,它只看到一个普通 Tool。这就是适配器:McpClient 管协议,mcpToolToTool 管形状转换,循环只管调用。三层各管一段。”

三层之间的调用链,和错误各自停在哪一层,画出来是这样:

runAgent(循环)
   │ 只认识 Tool / ToolSpec
   ▼
mcpToolToTool(适配缝:把 McpTool 翻译成 Tool)
   │ 只做形状转换:spec 字段 + execute 里 JSON.stringify
   ▼
McpClient(协议层:connect / call / close)
   │ 只认识 MCP 协议,不认识循环
   ▼
McpTransport(stdin/stdout 或 HTTP)
   │ 只认识字节流,翻译成协议消息
   ▼
远端 MCP 服务端

“图里每一层只跟上下两层说话。”老Z说,“循环问 execute,适配器问 McpClient.call,协议层问 transport.send。哪一层出错,就在哪一层翻译成自己的语言,别一路穿透三层,后面讲的协议错误和工具错误,争的其实就是‘在哪一层定责’。”

小A越看越眼熟:“这个适配器跟 mini-agent 现有的 AnthropicModelClient 是一个套路?”

“一模一样的套路,只是方向相反。”老Z说,“AnthropicModelClient(见 model-client.ts)把 Anthropic 的流式协议翻译成 mini-agent 的 ModelEvent,处理 content_block_start、input_json_delta,吐出 text、tool_call、done。mcpToolToTool 反过来,把 MCP 工具描述翻译成 ToolSpec。两个适配器干的是同一类活,把外部协议接到内部接口上。mini-agent 的测试能用 FakeClient(见 agent.test.ts)跑完整回合,也是同一个原因:循环不关心背后是 Anthropic 还是 MCP。适配器因此成了这个架构里的复用单位。”

小A指着 execute 里那行问:“JSON.stringify(result.content) 是嫌模型读不了对象,先转成字符串?”

“对。mini-agent 的 ToolResult.content 是字符串(见 types.ts),但 MCP 工具返回的 content 可能是结构化对象。”老Z说,“你看 mini-agent 自己的工具,read 返回文件内容,bash 返回 stdout 拼接,内部接口统一用字符串,模型拿来就能读。MCP 返回结构化数据,得 stringify 才能塞进这个形状,有损就损在这儿,换来的是循环不用懂 MCP 的返回格式。”

小A追问:“那 stringify 丢了类型信息,模型解析不了结构化结果怎么办?”

“让模型按文本处理,或者你在适配器里做一层格式化。”老Z说,“这跟 read 的截断是同一个思路:内部接口是字符串,结构化信息要么靠模型自己读文本,要么在适配器里提前格式化成可读文本,选择权在你,不在循环。想让模型看到 { title: '开会', time: '10:00' } 而不是一串 JSON,就在 mcpToolToTool 的 execute 里做格式化,别给循环加‘理解 JSON’的新规则,两端格式都交给适配器一处去懂。”

本章其余小节为付费内容

登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。