主题
协议概述与版本兼容
本文引用的源码文件
本文引用的文件
目录
- 引言
- 项目结构中的 MCP 位置
- MCP 核心理念与设计目标
- 协议基本概念
- AI Helper 架构中的 MCP 角色
- 扩展端与 Agent 端的通信机制
- 协议版本演进与兼容性策略
- v2024.11.5 的定位与当前实现状态
- 核心组件分析
- 数据流与调用序列
- 错误处理与可观测性
- 性能与资源管理
- 故障排查指南
- 结论与建议
引言
本文面向开发者与维护者，系统性说明 AI Helper 中 MCP（Model Context Protocol）协议的定位、设计理念、版本兼容策略以及在整体架构中的作用。文档重点解释：
- MCP 作为标准化工具协议的价值；
- v2024.11.5 在协议演进时间线中的位置；
- 当前代码对 Legacy 模式的实现；
- 扩展端与 Agent 端通过 MCP 连接外部工具服务的方式；
- 多传输协议、多服务器、工具自动发现与调用的整体流程。
项目结构中的 MCP 位置
在 AI Helper 仓库中，MCP 相关逻辑集中在 Agent 端的 agent/src/mcp 目录，由三个核心文件组成：
client.js：封装 MCP Client 的连接、传输层选择、工具列表获取与工具调用；mcp-config.js：管理~/.ai-helper-agent/mcp_servers.json配置，提供加载、保存、增删改查能力；registry.js：维护已连接的 MCP Server 实例映射，统一暴露工具查询、连接管理、工具调用路由等接口。
graph TB subgraph "Agent 进程" Registry["registry.js<br/>MCP 注册表"] Config["mcp-config.js<br/>MCP 配置管理"] Client["client.js<br/>MCP Client 封装"] end subgraph "外部 MCP Server" StdioServer["stdio 子进程 Server"] SseServer["SSE Server"] HttpServer["Streamable HTTP Server"] WsServer["WebSocket Server"] end Registry --> Config Registry --> Client Client --> StdioServer Client --> SseServer Client --> HttpServer Client --> WsServer
图表来源
章节来源
MCP 核心理念与设计目标
MCP 的核心目标是把“AI 能调用的工具”从内置能力扩展到任意实现了 MCP 协议的外部服务。其设计要点包括：
- 标准化工具契约：定义 AI 如何发现工具、如何调用工具、如何接收结构化结果；
- 传输无关：支持 stdio、SSE、Streamable HTTP、WebSocket 等多种传输方式；
- 多服务器聚合：允许同时连接多个 MCP Server，并将工具扁平化注入到可用工具集合；
- 低侵入集成：用户只需配置 Server ID、名称、传输方式和启动命令或 URL，即可让 AI 使用外部能力；
- 可扩展边界：内置工具覆盖通用场景，MCP 负责长尾需求，如数据库、GitHub、内部 API 等。
这些理念在推广文章中以“AI 的 USB 接口”进行类比，强调任何实现 MCP 的服务都能被 AI 直接调用，无需为每个服务单独编写集成代码。
章节来源
协议基本概念
本节从实现角度归纳 MCP 在 AI Helper 中的关键概念：
| 概念 | 含义 | 在代码中的体现 |
|---|---|---|
| MCP Server | 提供工具的外部服务，可以是本地子进程或远程服务 | mcp_servers.json 中的 servers 数组 |
| MCP Client | Agent 侧用于连接和调用 MCP Server 的客户端封装 | McpClient 类 |
| 传输协议 | 客户端与服务端之间的通信通道 | stdio、SSE、Streamable HTTP、WebSocket |
| 工具定义 | Server 暴露的工具名称、描述、输入参数 Schema | listTools 返回的 tools |
| 工具调用 | 按工具名和参数执行远端能力 | callTool |
| 工具注册表 | 管理所有已连接 Server 及其工具的统一入口 | registry.js |
| 配置缓存 | 避免频繁读写磁盘，提升读取性能 | loadMcpConfig 内存缓存 + mtime 校验 |
| 语言上下文 | 错误消息、日志文案使用当前语言 | setMcpClientLang、setMcpRegistryLang |
章节来源
- agent/src/mcp/client.js#L35-L184
- agent/src/mcp/mcp-config.js#L14-L79
- agent/src/mcp/registry.js#L19-L181
AI Helper 架构中的 MCP 角色
AI Helper 采用双进程架构：Chrome 扩展端（Manifest V3）与独立本地 Agent 进程。MCP 位于 Agent 侧，承担以下职责：
- 作为 Agent 与外部 MCP Server 之间的桥梁；
- 将外部工具转换为 Agent 可识别的工具定义；
- 与 Agent 内部的 ReAct 执行循环、工具预筛选、Skill 系统协同工作；
- 为扩展端提供统一的 MCP 管理能力，例如查看连接状态、启停 Server、刷新工具列表。
推广文章指出，MCP 工具会自动注入 AI 的可用工具列表，并按 Server 名称分组，ID 格式类似 mcp_{serverId}_{toolName}，描述前缀为 [MCP:服务器名]。这使得 MCP 工具与内置工具在工具预筛选阶段一视同仁。
章节来源
扩展端与 Agent 端的通信机制
根据项目作者指南，扩展端与 Agent 端的通信契约是架构核心：扩展端经本地 HTTP/WebSocket 端点调用 Agent 的文件读写、命令执行、长期记忆与 RAG 能力。MCP 属于 Agent 侧对外部工具的扩展能力，因此其调用路径通常如下：
- 用户在扩展端选项页或侧边面板配置 MCP Server；
- 配置写入 Agent 的
mcp_servers.json； - Agent 启动时加载配置并连接启用的 MCP Server；
- Agent 将 MCP 工具合并到可用工具集合；
- 扩展端触发 Agent 执行任务时，Agent 推理后调用 MCP 工具；
- MCP Client 通过所选传输协议调用外部 MCP Server；
- 外部 Server 返回工具结果，Agent 将其回传给扩展端展示。
sequenceDiagram participant User as "用户" participant Extension as "Chrome 扩展端" participant Agent as "Agent 进程" participant Registry as "MCP 注册表" participant Client as "MCP Client" participant Server as "外部 MCP Server" User->>Extension : 配置 MCP Server Extension->>Agent : 写入 mcp_servers.json Agent->>Registry : initializeMcpRegistry() Registry->>Client : connect() Client->>Server : 建立传输连接 Server-->>Client : 返回工具列表 Client-->>Registry : 记录已连接 Server 与工具 Extension->>Agent : 发起任务 Agent->>Registry : callMcpTool(serverId, toolName, args) Registry->>Client : callTool(toolName, args) Client->>Server : 调用工具 Server-->>Client : 返回结果 Client-->>Registry : 返回成功或错误 Registry-->>Agent : 返回工具执行结果 Agent-->>Extension : 渲染结果
图表来源
- agent/src/mcp/registry.js#L26-L55
- agent/src/mcp/registry.js#L116-L128
- agent/src/mcp/client.js#L96-L158
章节来源
协议版本演进与兼容性策略
根据升级分析报告，MCP 协议版本演进时间线如下：
- 2024-11-05：初始版本，HTTP+SSE 传输；
- 2025-03-26：引入 Streamable HTTP 传输；
- 2025-06-18：Elicitation、结构化工具输出；
- 2025-11-25：Tasks、Progress、Resource 订阅、OAuth 2.0；
- 2026-07-28：无状态化 MCP 2.0，移除 session/handshake。
当前实现仍基于 Legacy 模式，SDK 版本为 @modelcontextprotocol/sdk@^1.29.0，通过 SDK 内部 connect() 完成握手与版本协商。官方兼容矩阵表明：
- Modern 客户端只能与现代服务端兼容；
- Dual-era 客户端可同时兼容 Modern 与 Legacy；
- Legacy 客户端无法与现代服务端兼容。
因此，若未来需要同时兼容新旧 MCP Server，必须实现 Dual-era 探测机制，先尝试现代请求，失败后降级到 Legacy 握手。
章节来源
v2024.11.5 的定位与当前实现状态
v2024.11.5 对应协议时间线中的 2024-11-05 初始版本，核心特征是 HTTP+SSE 传输。在当前仓库中：
- 代码未显式声明协议版本字符串；
- 实际依赖的是 SDK 的 Legacy 模式；
- 传输层支持 stdio、SSE、Streamable HTTP、WebSocket；
- 工具发现与调用走 SDK 提供的
listTools与callTool； - 版本协商由 SDK 内部处理，而非业务代码直接解析协议版本号。
这意味着 v2024.11.5 在协议演进中属于早期版本，而当前实现更关注“能否连接现有 MCP Server”，而不是“是否严格绑定某个协议版本字符串”。对于使用者而言，只要外部 MCP Server 能被 SDK 连接，就能被 AI Helper 使用。
章节来源
- agent/docs/MCP-UPGRADE-ANALYSIS.md#L9-L23
- agent/docs/MCP-UPGRADE-ANALYSIS.md#L78-L109
- agent/src/mcp/client.js#L96-L127
核心组件分析
McpClient：传输与工具调用封装
McpClient 是 MCP 能力的直接实现者，负责：
- 根据配置创建传输层实例；
- 建立与 MCP Server 的连接；
- 获取服务端版本与能力；
- 拉取工具列表；
- 调用工具并解析文本内容；
- 断开连接并释放资源。
classDiagram
class McpClient {
+string serverId
+string serverName
+object serverConfig
+object client
+object transport
+boolean connected
+array tools
+object serverInfo
+connect() Promise
+callTool(toolName, args) Promise
+disconnect() Promise
+getStatus() object
-_createTransport() object
}
图表来源
章节来源
MCP 配置管理：持久化与并发安全
mcp-config.js 负责 MCP Server 配置的持久化，关键特性包括：
- 配置文件路径固定为用户主目录下的
.ai-helper-agent/mcp_servers.json； - 内存缓存 + mtime 校验，避免每次读取都读盘；
- 写入互斥锁，防止并发写导致配置损坏；
- 提供添加、删除、启用/禁用 Server 的接口；
- 解析失败时降级为空服务器列表，保证 Agent 不崩溃。
flowchart TD
Start(["调用 loadMcpConfig"]) --> CheckCache["检查内存缓存与 mtime"]
CheckCache --> CacheHit{"缓存命中?"}
CacheHit --> |是| ReturnCache["返回缓存配置"]
CacheHit --> |否| CheckFile{"配置文件存在?"}
CheckFile --> |否| CreateDefault["创建默认空配置"]
CreateDefault --> SaveDefault["写入默认文件"]
SaveDefault --> ReturnDefault["返回默认配置"]
CheckFile --> |是| ReadFile["读取并解析 JSON"]
ReadFile --> ParseOk{"解析成功?"}
ParseOk --> |是| UpdateCache["更新缓存与 mtime"]
UpdateCache --> ReturnParsed["返回解析结果"]
ParseOk --> |否| Fallback["降级为空服务器列表"]
Fallback --> ReturnFallback["返回降级配置"]
图表来源
章节来源
MCP 注册表：多 Server 管理与工具路由
registry.js 是 MCP 子系统对外暴露的统一入口，主要职责包括：
- 启动时加载配置并连接启用的 MCP Server；
- 维护
serverId → McpClient映射； - 查询所有 Server 状态与工具列表；
- 调用指定 Server 的工具；
- 动态连接/断开单个 Server；
- 关闭时清理所有连接。
classDiagram
class Registry {
+Map clients
+initializeMcpRegistry() Promise
+getMcpServersStatus() object
+getMcpTools(serverId) object
+callMcpTool(serverId, toolName, args) Promise
+connectMcpServer(serverId) Promise
+disconnectMcpServer(serverId) Promise
+shutdownMcpRegistry() Promise
}
class McpClient {
+connect() Promise
+callTool(toolName, args) Promise
+disconnect() Promise
+getStatus() object
}
Registry --> McpClient : "管理多个实例"
图表来源
章节来源
数据流与调用序列
工具发现流程
sequenceDiagram participant Registry as "MCP 注册表" participant Config as "配置管理" participant Client as "MCP Client" participant Server as "MCP Server" Registry->>Config : loadMcpConfig() Config-->>Registry : servers 列表 loop 遍历启用的 Server Registry->>Client : new McpClient(server) Client->>Server : connect() Server-->>Client : 返回版本与能力 Client->>Server : listTools() Server-->>Client : 返回工具列表 Client-->>Registry : 记录工具数量 end
图表来源
工具调用流程
sequenceDiagram participant Caller as "调用方" participant Registry as "MCP 注册表" participant Client as "MCP Client" participant Server as "MCP Server" Caller->>Registry : callMcpTool(serverId, toolName, args) Registry->>Registry : 查找 client Registry->>Client : callTool(toolName, args) Client->>Server : 调用工具 Server-->>Client : 返回 result Client->>Client : 过滤 text 内容 Client-->>Registry : 返回 success/content/raw Registry-->>Caller : 返回工具执行结果
图表来源
错误处理与可观测性
MCP 的错误处理分为三层：
- 配置层：配置文件解析失败时降级为空服务器列表，并打印错误日志；
- 连接层：连接失败时断开资源，返回包含错误信息的对象；
- 调用层：工具调用失败时返回
success: false与错误消息，同时保留原始结果供调试。
此外，注册表在初始化时会统计成功连接数与失败数，并在有失败时输出警告信息，便于运维排查。
章节来源
- agent/src/mcp/mcp-config.js#L52-L63
- agent/src/mcp/client.js#L96-L127
- agent/src/mcp/client.js#L129-L158
- agent/src/mcp/registry.js#L26-L55
性能与资源管理
MCP 子系统在性能方面做了以下优化：
- 配置读取使用内存缓存与 mtime 校验，减少磁盘 IO；
- 写入操作使用 Promise 链式锁，避免并发写冲突；
- 工具列表在连接成功后缓存到
McpClient.tools； - 注册表维护已连接 Client 映射，避免重复连接；
- 关闭时统一断开所有连接，释放 SDK 与传输层资源。
需要注意的风险包括：
- 多 Server 并行连接可能增加子进程或网络连接数；
- SSE 与 WebSocket 长连接需要关注生命周期；
- 工具列表较大时，扁平化注入可能影响工具预筛选的性能。
章节来源
- agent/src/mcp/mcp-config.js#L14-L79
- agent/src/mcp/registry.js#L19-L83
- agent/src/mcp/client.js#L160-L184
故障排查指南
常见问题与排查建议：
| 问题现象 | 可能原因 | 排查步骤 |
|---|---|---|
| MCP Server 未连接 | 配置缺失 command/url、环境变量未设置、传输协议错误 | 检查 mcp_servers.json、确认传输类型、查看连接日志 |
| 工具列表为空 | Server 未实现 listTools、连接失败、Server 未启用 | 检查 Server 是否 enabled、查看 getMcpServersStatus |
| 工具调用失败 | Server 返回 error、参数不匹配、网络超时 | 查看 callTool 返回的 raw 与 error 字段 |
| 配置写入失败 | 权限不足、磁盘不可写、并发写冲突 | 检查文件权限、重试写入、查看控制台错误 |
| 多 Server 连接不稳定 | 子进程退出、网络中断、SDK 行为差异 | 重启 Agent、检查 Server 进程、观察连接状态 |
章节来源
- agent/src/mcp/mcp-config.js#L69-L79
- agent/src/mcp/registry.js#L116-L167
- agent/src/mcp/client.js#L129-L158
结论与建议
AI Helper 的 MCP 实现以 Agent 为中心，通过 client.js、mcp-config.js、registry.js 三件套完成外部工具接入。当前实现聚焦于稳定连接现有 MCP Server，并使用 Legacy 模式与多传输协议适配不同部署场景。
针对协议版本兼容，建议在未来满足以下条件时推进升级：
- SDK v2.x 发布稳定版且社区反馈稳定；
- 需要对接仅支持 Modern 协议的 MCP Server；
- 需要使用 Tasks、MRTR、subscriptions/listen 等新特性；
- 官方将 2025-11-25 从 current 降级为 deprecated。
在升级前，应保持当前配置与调用链路不变，优先实现 Dual-era 探测，确保新老 Server 共存。对于使用者而言，只要外部 MCP Server 能被 SDK 连接，就能继续被 AI Helper 使用，短期内无需主动迁移。