AI Helper 文档中心

主题

MCP 协议扩展 ​

本文引用的源码文件

本文引用的文件

目录 ​

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与容量特性
  8. 故障排查指南
  9. 结论
  10. 附录：协议与配置参考

引言 ​

本文件面向“MCP（Model Context Protocol）协议扩展”的完整技术文档，覆盖以下目标：

  • 详细说明 MCP 客户端实现：连接管理、传输层选择、消息传递、工具自动发现与远程工具调用。
  • 说明 MCP 注册表工作原理：多服务器管理、工具扁平化聚合、动态连接/断开、错误处理与日志。
  • 解释 MCP 配置系统：配置文件位置与格式、读写并发控制、启用状态切换、语言国际化注入。
  • 描述 Skill 技能系统架构：Workflow 与 Agent 两类技能、Markdown 定义、模板引擎、执行框架与生命周期。
  • 提供 MCP 协议规范参考：消息语义、工具定义语法、事件类型与错误码。
  • 给出实际 MCP 服务器集成示例与技能开发指南，涵盖认证、日志记录与性能监控。

本项目为双进程架构：Chrome 扩展端（Manifest V3）+ 独立本地代理端 Agent（Node.js）。两端版本号保持同步，当前以 2.3.1 为准；Agent 源码修改后必须重启进程，新接口才生效。

项目结构 ​

围绕 MCP 与 Skill 的核心代码主要位于 agent 子项目：

  • MCP 子系统：client.js、mcp-config.js、registry.js
  • Skill 子系统：loader.js、markdown-loader.js、executor.js、registry.js、template.js
  • 服务入口与路由：server.js
  • 安全与配置：security.js、config.js、auth.js、logger.js
  • 扩展端工具注入：src/background/tool-executor.js
graph TB
subgraph "扩展端"
BG["Background<br/>tool-executor.js"]
end
subgraph "Agent 端"
SRV["HTTP 服务器<br/>server.js"]
MCP_REG["MCP 注册表<br/>registry.js"]
MCP_CLI["MCP 客户端<br/>client.js"]
MCP_CFG["MCP 配置<br/>mcp-config.js"]
SKL_REG["Skill 注册表<br/>registry.js"]
SKL_LDR["Skill 加载器<br/>loader.js / markdown-loader.js"]
SKL_EXEC["Skill 执行器<br/>executor.js"]
TPL["模板引擎<br/>template.js"]
SEC["安全管控<br/>security.js"]
CFG["配置管理<br/>config.js"]
AUTH["认证模块<br/>auth.js"]
LOG["审计日志<br/>logger.js"]
end
BG --> SRV
SRV --> MCP_REG
SRV --> SKL_REG
MCP_REG --> MCP_CLI
MCP_REG --> MCP_CFG
SKL_REG --> SKL_LDR
SKL_REG --> SKL_EXEC
SKL_EXEC --> TPL
SRV --> SEC
SRV --> CFG
SRV --> AUTH
SRV --> LOG

图示来源

章节来源

核心组件 ​

  • MCP 客户端（McpClient）：封装 Model Context Protocol SDK 客户端，支持 stdio、SSE、Streamable HTTP、WebSocket 四种传输；负责建立连接、拉取工具列表、调用工具并返回统一结果。
  • MCP 配置（mcp-config.js）：管理 ~/.ai-helper-agent/mcp_servers.json，提供缓存、写锁、增删改查与启用状态切换。
  • MCP 注册表（registry.js）：维护已连接客户端 Map，启动时连接所有启用的 MCP Server，暴露工具扁平化查询与工具调用转发。
  • Skill 加载器（loader.js + markdown-loader.js）：扫描 skills 目录，加载 Workflow JSON/YAML 与 Agent SKILL.md，支持 ZIP/URL 导入与安全校验。
  • Skill 执行器（executor.js）：解析步骤 DAG、拓扑排序并行执行、条件跳过、参数模板渲染、超时与部分成功处理。
  • Skill 注册表（registry.js）：内存注册、模糊查找、启用/停用持久化、内置技能保护、Agent Prompt 注入。
  • 模板引擎（template.js）：支持 {{var}} 替换与 {{#if}} 条件渲染。
  • 安全与配置（security.js、config.js）：路径白名单、硬阻止、命令分级、配置加密落盘、配对与认证。
  • 审计日志（logger.js）：JSON Lines 日志、按日轮转、清理策略、分类标签。

章节来源

架构总览 ​

下图展示从扩展端发起请求到 Agent 端执行 MCP 工具或 Skill 的整体流程。

sequenceDiagram
participant Ext as "扩展端 Background"
participant API as "Agent HTTP 服务器"
participant Reg as "MCP 注册表"
participant Cli as "MCP 客户端"
participant Srv as "外部 MCP 服务器"
Ext->>API : "GET /api/mcp/tools"
API->>Reg : "getMcpTools()"
Reg-->>API : "扁平化工具列表"
API-->>Ext : "{success, tools}"
Ext->>API : "POST /api/mcp/call {serverId, toolName, args}"
API->>Reg : "callMcpTool(serverId, toolName, args)"
Reg->>Cli : "callTool(toolName, args)"
Cli->>Srv : "MCP callTool"
Srv-->>Cli : "result"
Cli-->>Reg : "{success, content, raw}"
Reg-->>API : "统一结果"
API-->>Ext : "响应"

图示来源

章节来源

详细组件分析 ​

MCP 客户端与连接管理 ​

  • 传输层选择：根据 serverConfig.transport 创建 Stdio/SSE/Streamable HTTP/WebSocket 传输实例；缺失必要字段时抛出翻译后的错误。
  • 连接流程：构造 Client，connect 成功后获取 serverInfo、capabilities，并调用 listTools 拉取工具列表；失败则 disconnect 并返回错误信息。
  • 工具调用：封装 callTool，将 result.error 与 content.text 聚合为统一返回体；未连接直接返回“未连接”错误。
  • 生命周期：disconnect 关闭 client 与 transport；getStatus 返回连接状态与工具数量。
classDiagram
class McpClient {
+string serverId
+string serverName
+object serverConfig
-object client
-object transport
+boolean connected
+array tools
+object serverInfo
+connect() Promise~object~
+callTool(toolName, args) Promise~object~
+disconnect() Promise~void~
+getStatus() object
-_createTransport() object
}

图示来源

章节来源

MCP 配置系统 ​

  • 配置文件：~/.ai-helper-agent/mcp_servers.json，包含 servers 数组。
  • 缓存与写锁：loadMcpConfig 使用 mtime 缓存；saveMcpConfig 通过 withWriteLock 串行写入，避免并发覆盖。
  • 操作接口：addMcpServer、removeMcpServer、toggleMcpServer 均先 load 再 save，保证一致性。
  • 默认行为：不存在文件时创建空 servers 数组。
flowchart TD
Start(["读取配置"]) --> CheckFile{"文件存在?"}
CheckFile --> |否| CreateDefault["创建默认配置"]
CheckFile --> |是| ReadFile["读取并解析 JSON"]
CreateDefault --> Cache["写入内存缓存"]
ReadFile --> Validate{"servers 存在?"}
Validate --> |否| InitServers["初始化 servers 为空数组"]
Validate --> |是| UseServers["使用已有 servers"]
InitServers --> Cache
UseServers --> Cache
Cache --> End(["返回配置"])

图示来源

章节来源

MCP 注册表与工作流 ​

  • 初始化：initializeMcpRegistry 遍历 config.servers，仅连接 enabled=true 的服务器，统计 connected/failed 并输出日志。
  • 工具发现：getMcpTools 将所有已连接服务器的 tools 扁平化为统一结构，支持按 serverId 过滤。
  • 工具调用：callMcpTool 校验 serverId 与连接状态，转发至对应 McpClient.callTool。
  • 连接管理：connectMcpServer/disconnectMcpServer 支持重连与清理；shutdownMcpRegistry 在 Agent 关闭时释放资源。
sequenceDiagram
participant API as "HTTP 服务器"
participant Reg as "MCP 注册表"
participant Cfg as "MCP 配置"
participant Cli as "MCP 客户端"
API->>Cfg : "loadMcpConfig()"
Cfg-->>API : "servers[]"
loop 遍历启用的服务器
API->>Reg : "initializeMcpRegistry()"
Reg->>Cli : "new McpClient(server)"
Reg->>Cli : "connect()"
alt 连接成功
Cli-->>Reg : "{success, toolCount}"
Reg->>Reg : "clients.set(id, client)"
else 连接失败
Cli-->>Reg : "{success : false, error}"
Reg->>Reg : "failedServers.push(...)"
end
end

图示来源

章节来源

Skill 技能系统架构 ​

  • 加载器（loader.js + markdown-loader.js）：
    • Workflow Skill：扫描 .json/.yaml/.yml，校验 name/description/steps，默认 enabled=true。
    • Agent Skill：扫描子目录中的 SKILL.md，解析 frontmatter 与正文，收集 resources（scripts/templates/assets/references），支持 ZIP/URL 导入与安全校验（DNS 解析、私有 IP 判断、ZIP 解压安全）。
  • 执行器（executor.js）：
    • 构建步骤 DAG，拓扑排序并行执行；支持 when 条件、dependsOn 依赖、变量上下文 step.id.*。
    • 内部工具映射：agent_file、agent_exec、agent_search 等，结合 security.checkPath/checkCommand 进行安全校验。
    • 超时控制（EXECUTION_TIMEOUT）、活跃执行上限（MAX_ACTIVE_EXECUTIONS）、部分成功（partial）与错误处理。
  • 注册表（registry.js）：
    • 初始化时种子写入 skill-creator，合并文件系统与内置技能，恢复启用状态（builtin_skills_state.json、disabled_skills.json）。
    • 提供 getSkillList/getSkill/runSkill/getAgentSkillPrompts/getAgentSkillPrompt/importSkill/removeSkill/toggleSkill/reloadSkills。
  • 模板引擎（template.js）：
    • renderTemplate/renderConditional/render 支持 {{var}} 与 {{#if var}}...{{/if}}，点号路径解析 a.b.c。
flowchart TD
A["加载 Skill 定义"] --> B{"类型?"}
B --> |Workflow| C["校验 steps/parameters/name"]
B --> |Agent| D["解析 SKILL.md frontmatter 与正文"]
C --> E["注册到内存 Map"]
D --> E
E --> F["恢复启用状态内置/用户停用"]
F --> G["生成 Agent Prompt 列表"]

图示来源

章节来源

安全与权限控制 ​

  • 路径沙箱：checkPath 支持 ~ 展开、工作目录放行、allowedPaths 前缀匹配、realpath 防符号链接绕过、硬阻止敏感文件/目录。
  • 命令分级：checkCommand 对黑名单绝对禁止、灰名单需确认；支持链式命令拆分、包装器剥壳、内联载荷提取、命令替换特征检测。
  • 配置安全：memoryEmbedding.apiKey 落盘前编码，读取时解码；pairings.token 同样编码落盘。
  • 认证：verifyToken 基于 pairings.json；handlePairRequest 支持失败锁定、一次性配对码轮换。
flowchart TD
Start(["输入路径/命令"]) --> PathCheck{"路径检查"}
PathCheck --> |允许| ExecCheck{"命令检查"}
PathCheck --> |拒绝| Deny["拒绝访问"]
ExecCheck --> |deny| Block["黑名单阻断"]
ExecCheck --> |confirm| Confirm["需要用户确认"]
ExecCheck --> |allow| Allow["允许执行"]

图示来源

章节来源

扩展端工具注入 ​

  • 扩展端 Background 在每次推理前拉取最新 MCP 工具列表，并动态注入 RAW_TOOLS 与 TOOL_HANDLERS。
  • 若 Agent 未连通或不支持 MCP，自动跳过；同时可忽略已禁用服务器的工具。

章节来源

依赖关系分析 ​

  • 低耦合高内聚：MCP 客户端仅依赖 SDK 传输层；注册表依赖配置与客户端；Skill 执行器依赖安全与搜索模块；注册表依赖加载器与执行器。
  • 外部依赖：@modelcontextprotocol/sdk（MCP 通信）、archiver（ZIP 打包）、ws（WebSocket）、fs/path/os/crypto 等 Node 标准库。
  • 潜在循环依赖：server.js 作为入口集中引入各模块，但模块间通过函数导出解耦，未见直接循环 import。
graph LR
Server["server.js"] --> McpReg["mcp/registry.js"]
Server --> SkillReg["skill/registry.js"]
McpReg --> McpCli["mcp/client.js"]
McpReg --> McpCfg["mcp/mcp-config.js"]
SkillReg --> SkillLdr["skill/loader.js"]
SkillReg --> SkillExec["skill/executor.js"]
SkillLdr --> MdLdr["skill/markdown-loader.js"]
SkillExec --> Sec["security.js"]
SkillExec --> Search["search.js"]
Server --> Sec
Server --> Cfg["config.js"]
Server --> Auth["auth.js"]
Server --> Log["logger.js"]

图示来源

章节来源

性能与容量特性 ​

  • MCP 客户端：
    • 连接复用：clients Map 缓存已连接客户端，避免重复连接。
    • 工具发现：listTools 仅在 connect 时调用一次，后续复用 tools 数组。
  • MCP 配置：
    • mtime 缓存减少磁盘 IO；withWriteLock 串行写入避免竞争。
  • Skill 执行：
    • 并行执行：同一批就绪步骤 Promise.all 并行执行。
    • 活跃执行上限：MAX_ACTIVE_EXECUTIONS=100，定期清理已完成/错误记录。
    • 超时保护：EXECUTION_TIMEOUT=300s，防止长时间阻塞。
  • 日志：
    • JSON Lines 追加写入，按日轮转，保留最近 MAX_LOG_FILES=30 个文件，单文件超过 MAX_LOG_SIZE=10MB 清理。

章节来源

故障排查指南 ​

  • MCP 连接失败：
    • 检查 serverConfig.transport 与必填字段（url/command/env/cwd）。
    • 查看 initializeMcpRegistry 日志中 failedServers 列表与错误信息。
  • 工具调用失败：
    • 确认 serverId 与 toolName 正确；检查 McpClient.callTool 返回的 error 与 raw。
  • Skill 执行异常：
    • 检查 parameters 必填项与类型转换；查看步骤回调 onStepUpdate 的状态与消息。
    • 注意 when 条件与 dependsOn 依赖是否形成死循环或缺失前置步骤。
  • 安全拦截：
    • checkPath 返回 forbiddenAgentFile/pathNotInAllowedDir/pathOutOfRange 时，调整 allowedPaths 或 workdir。
    • checkCommand 返回 deny/confirm 时，确认命令是否符合黑名单/灰名单规则。
  • 配置保存失败：
    • 检查 withWriteLock 是否被其他写入阻塞；确认文件权限与磁盘空间。
  • 认证问题：
    • verifyToken 失败时检查 pairings.json 与 token 是否过期或被轮换。

章节来源

结论 ​

本实现以 MCP 协议扩展第三方工具能力为核心，通过标准化客户端与注册表抽象，屏蔽底层传输差异，提供统一的工具发现与调用接口。Skill 系统兼顾确定性工作流与 AI 自主调用，配合模板引擎与安全管控，形成完整的自动化与知识沉淀体系。配置与认证机制确保数据与访问安全，日志系统提供可观测性。整体架构清晰、可扩展性强，适合在生产环境中稳定运行。

附录：协议与配置参考 ​

MCP 协议规范参考 ​

  • 消息语义：
    • listTools：拉取服务端提供的工具列表。
    • callTool：调用指定工具，传入 name 与 arguments。
  • 工具定义语法：
    • 每个工具包含 name、description、inputSchema（JSON Schema 风格）。
  • 事件类型：
    • 连接状态：connected/disconnected。
    • 工具发现：tools 列表变更。
  • 错误码与错误对象：
    • 客户端返回 {success, error, content, raw}；error.message 用于提示。

章节来源

MCP 服务器配置格式 ​

  • 配置文件路径：~/.ai-helper-agent/mcp_servers.json
  • 字段说明：
    • id：服务器唯一标识。
    • name：显示名称（可选）。
    • transport：stdio/sse/streamableHttp/websocket。
    • url：网络传输必填。
    • command/args/env/cwd：stdio 传输必填。
    • headers：SSE/Streamable HTTP 可选请求头。
    • enabled：是否启用。

章节来源

Skill 定义格式 ​

  • Workflow Skill（JSON/YAML）：
    • name、description、version、parameters、steps[]。
    • steps 元素：id、tool、args/params、dependsOn[]、when。
  • Agent Skill（SKILL.md）：
    • frontmatter：name、description、version、enabled。
    • 正文：When to Use、Core Capabilities、Usage、Examples、Source。
    • 资源目录：scripts、templates、assets、references。

章节来源

认证与日志 ​

  • 认证：
    • handlePairRequest：配对码验证、失败锁定、一次性轮换。
    • verifyToken：基于 pairings.json 校验扩展令牌。
  • 日志：
    • logAuth/logFs/logExec/logSecurity/logSystem/logError：分类写入 JSON Lines。
    • queryLogs：分页查询，按时间倒序。

章节来源