用代码插拔感官：基于官方 SDK 手搓底层 MCP Client

(第 60 篇：Agent 动力学之 MCP 实战)

如果你深刻理解了上一篇 MCP 宣扬的“即插即用”哲学，那么作为一名立志写出工业级 Agent Runner 的开发者，你必须要知道：如何在自己的 Agent 代码中徒手初始化一个 MCP Client，去“白嫖”全世界庞大的工具生态。

本篇将深入剖析底层连接线的真实细节，揭秘 Agent 是如何通过标准协议接管外部感官的。

1. 物理运输层：Stdio vs SSE

MCP 并不是一个锁死在 HTTP 的网络协议。在极客开发中，我们通常采用最高效也是最隐秘的传输管道：进程间标准流 (Stdio Transport)。

1.1 Stdio 的隐秘通讯

想象一下：你的主 Agent (Node.js) 为了具备查库功能，它在底层直接 spawn 拉起了一个子进程去跑别人写好的二进制文件（或是 Python 脚本的 MCP Server）。它们两者的通信甚至不走任何本地网卡端口，而是通过极其隐密的 stdin/stdout 进行 JSON-RPC 交互。

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

async function bootMcpSensors() {
    // 实例化：这就相当于你在主板上拉出一根数据线
    const transport = new StdioClientTransport({
       command: "npx",
       args: ["-y", "@modelcontextprotocol/server-postgres"], 
       env: { "DATABASE_URL": "postgresql://..." }
    });

    // 创建客户端实例，指明我的身份与能力边界
    const mcpClient = new Client(
       { name: "ZeroBug-Universal-Agent", version: "2.0.0" },
       { capabilities: { tools: {}, resources: {}, logging: {} } }
    );

    // 插上线！强行连通并进行 Initialize 手约
    await mcpClient.connect(transport);
    console.log("【MCP连线成功】该节点的雷达已激活");
    
    return mcpClient;
}

2. 嗅探可用武库：Capability Discovery

接通以后，你的 Agent 并不预先知道对面这个“USB 设备”里装的是显卡还是打印机。因此，真正的底层 Agent 会立刻发起一次协议级扫表 (Discovery)。

2.1 动态工具发现

这是 Agent 得以逃离“硬编码”苦海的核心逻辑：

async function fetchAndMountTools(mcpClient: Client) {
    // 协议规定必定存在的 `listTools()` 方法
    const toolsResponse = await mcpClient.listTools();
    
    // 这里的 inputSchema 是 Server 返回的完美的 JSON Schema
    const formattedTools = toolsResponse.tools.map(t => ({
        name: t.name,
        description: t.description,
        schema: t.inputSchema 
    }));
    
    // 接下来，将 formattedTools 直接喂给大模型作为可用工具列表
    return formattedTools;
}

3. 按下核按钮：调用 (CallTool) 的无缝桥接

当大模型的大脑深处输出 {"name": "query_db", "args": {"sql": "..."}} 后。在 MCP 架构中，你不需要写任何数据库驱动代码，你只需要把这个 Payload 像踢皮球一样跨进程传导过去。

// 在 Agent 执行循环的末端：
async function handleActionFromLLM(mcpClient: Client, toolName: string, args: any) {
    try {
        // 直接将炸弹踢给 MCP Server，不管它逻辑怎么跑
        const executionResult = await mcpClient.callTool({
            name: toolName,
            arguments: args
        });
        
        // 拿回由 MCP 统一协议规范返回的内容 (text/image)
        if (executionResult.isError) {
             throw new Error(executionResult.content[0].text);
        }
        return executionResult.content[0].text;
    } catch (err) {
        return `[物理执行失败] ${err.message}`;
    }
}

4. 深度挑战：多 Server 聚合 (The MCP Hub)

如果你同时连接了 5 个 MCP Server（Google 搜索、本地 SQL、Github 操作、Jira、邮件），你的 Client 必须处理以下复杂情况：

1. 命名冲突：如果 Server A 和 Server B 都有 read_file 工具，Client 必须在分发给大模型前进行重命名空间处理（如 github_read_file vs local_read_file）。
2. 鉴权透传：Client 负责持有所有的 Secret，并确保这些 Secret 不会被 LLM 偷窥到。
3. 连接治理：实时监测子进程的心跳。如果某个 Server 崩溃（如查询数据量过载），Client 应立刻触发“虚拟下线”并通知大脑，而不是让整个 Agent 进程卡死。

5. 协议底层：MCP = JSON-RPC 2.0（不要把它当成“某个 SDK”）

MCP 的关键不是某个语言的 SDK，而是协议：

1. 所有消息遵循 JSON-RPC 2.0（request/response/notification）。 citeturn0search2
2. transport 可以是 stdio，也可以是基于 HTTP 的形式（不同版本/实现会有差异）。 citeturn0search0

这意味着： 你的 Client 需要具备“协议级事实能力”，而不是只会调用某个 npm 包。 当 SDK 版本漂移、server 行为不一致时，你仍然能通过 raw JSON-RPC 抓包定位问题。

6. 生命周期与可靠性：连接不是一次性事件，是长期会话

一个工程可用的 MCP Client 必须处理：

1. 启动失败：server 缺依赖、权限不足、环境变量不完整。
2. 运行中崩溃：server panic / OOM / 连接断开。
3. 延迟与超时：工具调用可能卡住（DB 锁、网络抖动），需要预算与断路器。
4. 输出治理：工具返回可能很大，需要截断与结构化摘要。

最小治理策略：

1. 心跳/健康检查（定期发轻量请求或监测子进程状态）。
2. 超时：每个 tool call 必须有 deadline，超时后进入 shadow mode（只读工具）。
3. 断路器：连续失败 N 次就将该 server 标记为不可用，避免拖垮全局。

7. 安全边界：MCP Server 返回的数据也可能是“投毒载荷”

不要把 MCP 当成“可信插件系统”。 它是一个把外部数据和工具接进模型上下文的通道， 因此同样面临提示词注入与工具投毒的风险。

Client 层至少需要两条硬约束：

1. 数据与指令隔离：resources/logs 的内容必须标记为不可信数据区块，禁止被当作工具指令执行。
2. 能力最小化：默认只开放只读工具，写入型工具必须显式授权 + 审计。

安全问题在 MCP 语境下已经被研究与讨论为“架构性风险”，不是“某个实现写错”。 citeturn0academia15

8. 把 MCP 接进 Agent 主循环：把“工具世界”做成可插拔模块

MCP Client 的位置非常明确：它位于“LLM 推理”和“外部副作用”之间。 一个推荐的主循环分层：

1. Planner：LLM 产出下一步意图（可能是工具调用、也可能是继续思考）。
2. Router：根据工具名把调用路由到某个 MCP server（处理命名空间与冲突）。
3. Executor：执行 callTool，带 timeout、截断、审计。
4. Observer：把结果转换成“可推理观测”（结构化 + 摘要 + 不可信标记）。
5. Verifier：必要时跑二次校验（schema、权限、幂等、回滚可用性）。

这里最大的工程坑在于： 不要让“工具返回的文本”直接进入模型的 system 语境。 你必须把它放在明确的数据区块里，并附带来源元数据， 否则工具返回可以反向污染你的策略。

9. 最小可测：用一个假 server 做协议回归

MCP Client 的测试不应该依赖真实数据库或第三方服务。 你需要一个最小假 server：

1. 固定返回一组 tools（含 inputSchema）。
2. 固定返回一组 resources。
3. 对 callTool 返回可控的 text/error。

断言点：

1. listTools/listResources 的解析与映射稳定。
2. tool call 超时会触发断路器或降级（而不是卡死）。
3. 输出截断与“已截断标记”存在，避免模型误判。
4. 审计记录包含 server identity、tool name、参数 hash、deadline。

真理的顿悟

学习并手推一份 MCP 的实现，你的思维将瞬间脱胎换骨。现代 AI 工程学正在走向极致的原子化：

• 大脑 (LLM Orchestrator)：仅负责最纯粹的推理。
• 感官躯干 (MCP Server)：封装所有的物理副作用（读写 DB、发请求）。
• 连接器 (MCP Client)：承担起那一层穿针引线的安全审计与路由。

这种分层让你的代码像乐高一样可以任意组合。下一章，我们将讨论如何利用 MCP 给 Agent 装上眼睛——【浏览器自动化与 Playwright：如何让 Agent 真正“看见”网页并像人一样点击？】。我们要开始视觉感知了。

(本文完 - 深度解析系列 60 / 全文约 1600 字) (注：建议通过 npm install @modelcontextprotocol/sdk 开始你的第一个实验。)

参考与延伸（写作核验）

• MCP 规范：消息必须遵循 JSON-RPC 2.0。 citeturn0search2
• MCP transport 概览（stdio/HTTP 等）。 citeturn0search0
• MCP 安全分析研究（提示词注入与工具集成漏洞）。 citeturn0academia15