AI Helper 文档中心

主题

MCP 与技能 API ​

本文引用的源码文件

本文引用的文件

目录 ​

  1. 引言
  2. 项目结构与协议边界
  3. 核心组件总览
  4. 架构总览
  5. MCP 工具管理 API
  6. Skill 技能管理 API
  7. MCP 协议自动发现机制
  8. Skill 定义格式与模板引擎
  9. 技能执行框架、权限控制与沙箱隔离
  10. 依赖关系分析
  11. 性能与稳定性特性
  12. 故障排查指南
  13. 结论

引言 ​

本文面向 MCP 协议扩展与 Skill 技能系统的 API 使用者与维护者，说明 Agent 本地代理端暴露的 HTTP 接口契约、MCP 工具注册与调用流程、Skill 类型与执行模型，以及权限与安全策略。文档以仓库中 agent/src/server.js 为路由入口，结合 MCP 注册表、MCP 客户端、Skill 注册表、Skill 执行器与加载器进行代码级分析，并给出可操作的 API 使用示例和实现约束。

本项目采用双进程架构：Chrome 扩展端通过本地 HTTP/WebSocket 调用 Agent；Agent 源码修改后必须重启进程，新接口才生效。

项目结构与协议边界 ​

Agent 端是 MCP 与 Skill 能力的运行时载体，对外暴露统一 HTTP 路由；扩展端通过 local-agent-client.js 封装 /api/mcp/* 与 /api/skill/* 调用。

graph TB
Extension["Chrome 扩展<br/>src/background/local-agent-client.js"] --> AgentServer["Agent HTTP 服务器<br/>agent/src/server.js"]
AgentServer --> McpRegistry["MCP 注册表<br/>agent/src/mcp/registry.js"]
McpRegistry --> McpClient["MCP 客户端<br/>agent/src/mcp/client.js"]
AgentServer --> SkillRegistry["Skill 注册表<br/>agent/src/skill/registry.js"]
SkillRegistry --> SkillExecutor["Skill 执行器<br/>agent/src/skill/executor.js"]
SkillRegistry --> SkillLoader["Skill 加载器<br/>agent/src/skill/loader.js"]

图表来源

章节来源

核心组件总览 ​

  • HTTP 路由层：server.js 负责认证、CORS、请求体解析、日志、安全校验，并将请求分发到 MCP 与 Skill 子系统。
  • MCP 子系统：mcp/registry.js 维护已连接 MCP Server 实例，提供状态查询、工具列表、工具调用、连接/断开、启用/禁用等能力；mcp/client.js 基于官方 SDK 实现 stdio/SSE/streamableHttp/websocket 传输。
  • Skill 子系统：skill/registry.js 管理 Workflow 与 Agent 两类技能的生命周期；skill/executor.js 按 DAG 拓扑并行执行步骤；skill/loader.js 从文件系统加载 JSON/YAML Workflow 与 SKILL.md Agent 技能。
  • 扩展端客户端：local-agent-client.js 封装 Skill/MCP 相关 API 调用，供 side panel 与 options 页面使用。

章节来源

架构总览 ​

Agent 启动时初始化搜索工具、RAG 检测、MCP 注册表与 Skill 注册表；每次请求根据 Accept-Language 同步各子模块语言；所有需要写操作或敏感能力的接口均要求 Bearer Token 认证。

sequenceDiagram
participant Client as "扩展端"
participant Server as "Agent 服务器"
participant McpReg as "MCP 注册表"
participant McpCli as "MCP 客户端"
participant SkillReg as "Skill 注册表"
participant SkillExec as "Skill 执行器"
Client->>Server : "POST /api/mcp/call"
Server->>Server : "验证 Bearer Token"
Server->>McpReg : "callMcpTool(serverId, toolName, args)"
McpReg->>McpCli : "callTool(toolName, args)"
McpCli-->>McpReg : "{success, content, raw}"
McpReg-->>Server : "{success, ...}"
Server-->>Client : "JSON 响应"
Client->>Server : "POST /api/skill/run"
Server->>SkillReg : "runSkill(name, params)"
SkillReg->>SkillExec : "executeSkill(skill, params)"
SkillExec-->>SkillReg : "{success, execId, results}"
SkillReg-->>Server : "{success, ...}"
Server-->>Client : "JSON 响应"

图表来源

MCP 工具管理 API ​

通用约定 ​

  • 基础路径：/api/mcp/*
  • 认证：除 GET 列表类接口外，其余通常需要 Bearer Token；GET 列表接口在认证区，但部分实现仍会走认证逻辑。
  • 响应格式：统一 { success, ... }，失败时附带 error。
  • 错误码：常见为 400（参数缺失）、401/403（认证失败）、500（内部错误）。

接口清单 ​

接口方法路径用途关键参数返回字段
MCP 服务器状态GET/api/mcp/servers获取所有 MCP Server 配置及连接状态无servers[]，含 id/name/connected/toolCount/tools/serverInfo
MCP 工具列表GET/api/mcp/tools扁平化列出已连接 MCP Server 的工具可选 serverIdtools[]，含 serverId/serverName/name/description/inputSchema
MCP 工具调用POST/api/mcp/call调用指定 MCP Server 的工具serverId、toolName、argssuccess/content/raw/error
MCP 服务器连接POST/api/mcp/servers/connect连接指定 MCP Serveridsuccess/toolCount/error
MCP 服务器断开POST/api/mcp/servers/disconnect断开指定 MCP Serveridsuccess/error
MCP 服务器增删改POST/DELETE/api/mcp/servers添加/删除 MCP Serverid/command/url/transport/headers/envsuccess/error
MCP 服务器启用/停用POST/api/mcp/servers/toggle切换 MCP Server 启用状态id/enabledsuccess/error

注意：需求中提到的 /api/mcp/status 在当前路由实现中对应的是 /api/mcp/servers，用于获取 MCP 服务器状态；若前端期望 /api/mcp/status，应改为 /api/mcp/servers。

GET /api/mcp/servers ​

  • 作用：返回所有 MCP Server 的配置、连接状态、工具数量与工具元数据。
  • 典型响应结构：
    • success: true
    • servers: 数组，每项包含 id、name、enabled、connected、toolCount、tools、serverInfo。
  • 未连接时 tools 为空数组，toolCount 为 0。

章节来源

GET /api/mcp/tools ​

  • 作用：返回所有已连接 MCP Server 的工具列表，支持按 serverId 过滤。
  • 典型响应结构：
    • success: true
    • tools: 数组，每项包含 serverId、serverName、name、description、inputSchema。
  • 未连接 Server 的工具不会出现在列表中。

章节来源

POST /api/mcp/call ​

  • 作用：调用指定 MCP Server 的工具。
  • 请求体：
    • serverId: 必填，MCP Server ID。
    • toolName: 必填，工具名称。
    • args: 可选，工具参数对象。
  • 响应：
    • success: 布尔值。
    • content: 文本内容（来自 MCP 返回的 text 类型 content）。
    • raw: 原始 MCP 返回对象。
    • error: 失败原因。

章节来源

POST /api/mcp/servers/connect ​

  • 作用：连接指定 MCP Server。
  • 请求体：id。
  • 行为：先断开已有连接，再创建新 McpClient 并连接；成功后返回工具数量。

章节来源

POST /api/mcp/servers/disconnect ​

  • 作用：断开指定 MCP Server。
  • 请求体：id。
  • 行为：关闭底层 client 与 transport，并从内存映射中移除。

章节来源

POST/DELETE /api/mcp/servers ​

  • 作用：添加或删除 MCP Server。
  • 添加请求体关键字段：
    • id：必填。
    • transport：stdio、sse、streamableHttp、websocket。
    • command：stdio 模式必填。
    • url：HTTP 类传输必填。
    • headers：HTTP 类传输可选。
    • env、cwd、args：按需配置。
  • 安全校验：stdio 模式下会对 command + args 执行命令安全检查，可能返回 confirm 级别需用户确认。

章节来源

POST /api/mcp/servers/toggle ​

  • 作用：启用或停用 MCP Server。
  • 请求体：id、enabled。
  • 行为：禁用时会先断开连接，确保工具立即不可用。

章节来源

API 使用示例 ​

查询 MCP 服务器状态 ​

http
GET /api/mcp/servers
Authorization: Bearer <token>

预期响应：

json
{
  "success": true,
  "servers": [
    {
      "id": "example-mcp",
      "name": "Example MCP",
      "enabled": true,
      "connected": true,
      "toolCount": 2,
      "tools": [
        {
          "name": "read_file",
          "description": "读取文件内容",
          "inputSchema": {
            "type": "object",
            "properties": {
              "path": {"type": "string"}
            }
          }
        }
      ],
      "serverInfo": null
    }
  ]
}

获取 MCP 工具列表 ​

http
GET /api/mcp/tools?serverId=example-mcp
Authorization: Bearer <token>

预期响应：

json
{
  "success": true,
  "tools": [
    {
      "serverId": "example-mcp",
      "serverName": "Example MCP",
      "name": "read_file",
      "description": "读取文件内容",
      "inputSchema": {
        "type": "object",
        "properties": {
          "path": {"type": "string"}
        }
      }
    }
  ]
}

调用 MCP 工具 ​

http
POST /api/mcp/call
Authorization: Bearer <token>
Content-Type: application/json

{
  "serverId": "example-mcp",
  "toolName": "read_file",
  "args": {
    "path": "/tmp/test.txt"
  }
}

预期响应：

json
{
  "success": true,
  "content": "Hello MCP",
  "raw": {
    "content": [{"type": "text", "text": "Hello MCP"}]
  }
}

连接 MCP 服务器 ​

http
POST /api/mcp/servers/connect
Authorization: Bearer <token>
Content-Type: application/json

{
  "id": "example-mcp"
}

断开 MCP 服务器 ​

http
POST /api/mcp/servers/disconnect
Authorization: Bearer <token>
Content-Type: application/json

{
  "id": "example-mcp"
}

章节来源

Skill 技能管理 API ​

通用约定 ​

  • 基础路径：/api/skill/*
  • 认证：Skill 管理接口位于认证区，需要 Bearer Token。
  • 响应格式：统一 { success, ... }，失败时附带 error。
  • Skill 类型：
    • workflow：确定性自动化流程，由 JSON/YAML 定义 steps DAG。
    • agent：AI 能力扩展，由 SKILL.md 描述，适合由 AI 在对话中按需加载与调用。

接口清单 ​

接口方法路径用途关键参数返回字段
技能列表GET/api/skill/list获取所有已注册 Skill可选 typeskills[]，含 name/type/description/version/enabled/builtin/editable/deletable
技能详情GET/api/skill/detail获取单个 Skill 完整定义nameskill 对象
执行技能POST/api/skill/run执行 Workflow Skillname、paramssuccess/execId/results/partial/message
导入技能POST/api/skill/import导入 Workflow Skillname/steps/description/version/parameterssuccess/name/type
删除技能DELETE/api/skill/delete删除 Skillnamesuccess/error
切换启用/停用POST/api/skill/toggle切换 Skill 启用状态namesuccess/enabled
重新加载技能POST/api/skill/reload重新扫描 skills 目录无success/count
Agent 技能 MarkdownGET/api/skill/markdown获取 Agent Skill 的 SKILL.md 与 frontmatternamemarkdown/frontmatter/resources/dirPath
Agent 技能资源GET/api/skill/resource获取 Agent Skill 关联资源文件name、resourcecontent/size
Agent 技能提示词GET/api/skill/agent-prompts注入 AI System Prompt 的轻量列表无prompts
按需加载 Agent 技能GET/api/skill/agent-prompt按需加载单个 Agent Skill 完整 promptnameskill/prompt

注意：需求中提到的 /api/skill/get 在当前路由实现中对应的是 /api/skill/detail；需求中的 /api/skill/remove 对应的是 /api/skill/delete。

GET /api/skill/list ​

  • 作用：返回所有已注册 Skill 的轻量信息。
  • 可选参数：type=workflow|agent。
  • 返回字段：
    • name：技能名称。
    • type：workflow 或 agent。
    • enabled：是否启用。
    • builtin：是否为内置技能。
    • editable、deletable：是否可编辑/删除。
    • Workflow 额外字段：stepCount、parameters。
    • Agent 额外字段：resourceCount、resources、dirName。

章节来源

GET /api/skill/detail ​

  • 作用：获取单个 Skill 的完整定义。
  • 参数：name。
  • 返回：skill 对象，包含 type、steps、prompt、resources 等。

章节来源

POST /api/skill/run ​

  • 作用：执行 Workflow Skill。
  • 参数：
    • name：必填。
    • params：可选，参数对象。
  • 行为：
    • 仅支持 workflow 类型；Agent Skill 直接拒绝。
    • 执行器按 DAG 拓扑并行执行步骤，支持条件跳过、变量注入、超时保护。
  • 返回：
    • success：整体成功标志。
    • execId：执行 ID。
    • results：步骤结果映射。
    • partial：部分成功时存在。
    • message：执行摘要。

章节来源

POST /api/skill/import ​

  • 作用：导入 Workflow Skill。
  • 参数：
    • name：必填。
    • steps：必填，步骤数组。
    • description、version、parameters：可选。
  • 行为：保存到 ~/.ai-helper-agent/skills/<name>.json，并立即注册到内存。

章节来源

DELETE /api/skill/delete ​

  • 作用：删除 Skill。
  • 参数：name。
  • 行为：
    • Agent Skill：删除整个目录。
    • Workflow Skill：删除 JSON 文件。
    • 内置技能不可删除。

章节来源

POST /api/skill/toggle ​

  • 作用：切换 Skill 启用/停用。
  • 参数：name。
  • 行为：
    • 持久化到 disabled_skills.json。
    • 内置技能额外持久化到 builtin_skills_state.json。
    • 尝试更新源文件，失败不影响状态。

章节来源

POST /api/skill/reload ​

  • 作用：重新扫描并加载 Skills。
  • 返回：count，表示重新注册的 Skill 数量。

章节来源

GET /api/skill/markdown ​

  • 作用：获取 Agent Skill 的 SKILL.md 内容与 frontmatter。
  • 参数：name。
  • 返回：markdown、frontmatter、resources、dirPath。

章节来源

GET /api/skill/resource ​

  • 作用：获取 Agent Skill 关联的资源文件内容。
  • 参数：name、resource。
  • 返回：content、size。

章节来源

GET /api/skill/agent-prompts ​

  • 作用：生成注入 AI System Prompt 的轻量 Agent Skill 列表。
  • 返回：prompts，字符串形式，包含可用 Agent Skill 的名称、描述与资源提示。

章节来源

GET /api/skill/agent-prompt ​

  • 作用：按需加载单个 Agent Skill 的完整 prompt。
  • 参数：name。
  • 返回：skill、prompt。

章节来源

API 使用示例 ​

获取 Skill 列表 ​

http
GET /api/skill/list?type=workflow
Authorization: Bearer <token>

预期响应：

json
{
  "success": true,
  "skills": [
    {
      "name": "code-review",
      "type": "workflow",
      "description": "代码风格检查",
      "version": "1.0",
      "enabled": true,
      "builtin": false,
      "editable": true,
      "deletable": true,
      "stepCount": 2,
      "parameters": {}
    }
  ]
}

获取 Skill 详情 ​

http
GET /api/skill/detail?name=code-review
Authorization: Bearer <token>

执行 Skill ​

http
POST /api/skill/run
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "code-review",
  "params": {
    "targetDir": "./src"
  }
}

预期响应：

json
{
  "success": true,
  "execId": "skill_1",
  "results": {
    "step_1": {"success": true, "content": "..."},
    "step_2": {"success": true, "content": "..."}
  },
  "message": "技能 code-review 执行完成，共 2 个步骤"
}

导入 Skill ​

http
POST /api/skill/import
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "my-workflow",
  "description": "自定义工作流",
  "version": "1.0",
  "parameters": {},
  "steps": [
    {
      "id": "step_1",
      "tool": "agent_read_file",
      "args": {
        "path": "{{targetFile}}",
        "action": "read"
      }
    }
  ]
}

删除 Skill ​

http
DELETE /api/skill/delete
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "my-workflow"
}

切换 Skill 启用/停用 ​

http
POST /api/skill/toggle
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "my-workflow"
}

章节来源

MCP 协议自动发现机制 ​

MCP 自动发现基于官方 SDK 的 listTools 与 callTool 能力：

  • 连接成功后调用 client.listTools({})，将返回的 tools 缓存到 McpClient.tools。
  • 注册表聚合所有已连接 Client 的工具，提供扁平化工具列表。
  • 工具调用通过 client.callTool({ name, arguments }) 转发到远端 MCP Server。
sequenceDiagram
participant Registry as "MCP 注册表"
participant Client as "MCP 客户端"
participant Sdk as "MCP SDK"
participant Server as "远端 MCP Server"
Registry->>Client : "connect()"
Client->>Sdk : "connect(transport)"
Sdk->>Server : "建立连接"
Client->>Sdk : "listTools({})"
Sdk->>Server : "请求工具列表"
Server-->>Sdk : "tools[]"
Sdk-->>Client : "tools[]"
Client->>Client : "缓存 tools"
Registry->>Registry : "getMcpTools() 聚合"

图表来源

章节来源

Skill 定义格式与模板引擎 ​

Workflow Skill 定义 ​

Workflow Skill 以 JSON 或 YAML 文件保存在 ~/.ai-helper-agent/skills/<name>.json。

关键字段：

  • name：必填，技能名称。
  • description：必填，技能描述。
  • version：可选，默认 1.0。
  • enabled：可选，默认启用。
  • parameters：可选，参数定义，支持 JSON Schema 风格。
  • steps：必填，步骤数组，每个 step 包含：
    • id：步骤 ID。
    • tool：工具名，如 agent_read_file、agent_exec、agent_search_files。
    • args 或 params：步骤参数，支持模板变量。
    • dependsOn：可选，依赖步骤 ID 数组。
    • when：可选，条件表达式，支持模板渲染。

模板引擎：

  • 使用 template.js 的 render 函数对字符串参数进行变量替换。
  • 变量来源包括：
    • 用户传入的 params。
    • Skill 定义的 parameters.default。
    • 前面步骤的结果，如 step.<stepId>、step.<stepId>.success、step.<stepId>.content。

章节来源

Agent Skill 定义 ​

Agent Skill 以目录形式保存，目录内包含 SKILL.md，支持 frontmatter 与资源文件。

关键字段：

  • name：frontmatter 中的名称。
  • description：frontmatter 中的描述。
  • version：frontmatter 中的版本。
  • enabled：frontmatter 中的启用状态。
  • fullPrompt 或 prompt：SKILL.md 内容。
  • resources：资源文件列表，包含 name、type、size、path。
  • dirPath：技能目录路径。

模板引擎：

  • Agent Skill 不直接执行步骤，而是由 AI 在对话中按需加载完整 prompt。
  • 系统会注入工作目录信息，帮助 AI 解析相对路径。

章节来源

技能执行框架、权限控制与沙箱隔离 ​

执行框架 ​

  • Skill 执行器构建步骤依赖 DAG，按拓扑排序并行执行就绪步骤。
  • 支持条件跳过（when）、变量注入、步骤结果引用。
  • 执行过程有超时保护（默认 5 分钟），并记录活跃执行状态。
  • 返回 partial 表示部分步骤失败，但仍可继续后续步骤。
flowchart TD
Start["开始执行 Skill"] --> Validate["校验参数与类型"]
Validate --> BuildDag["构建步骤依赖 DAG"]
BuildDag --> Ready["收集就绪步骤"]
Ready --> Batch["并行执行批次步骤"]
Batch --> Condition{"是否满足 when 条件?"}
Condition --> |否| Skip["标记步骤跳过"]
Condition --> |是| Render["渲染步骤参数"]
Render --> ToolCall["执行工具调用"]
ToolCall --> Result{"工具调用成功?"}
Result --> |是| Success["标记步骤成功"]
Result --> |否| Error["标记步骤错误"]
Skip --> NextReady["查找新的就绪步骤"]
Success --> NextReady
Error --> NextReady
NextReady --> Done{"是否还有未完成步骤?"}
Done --> |是| Ready
Done --> |否| Finalize["汇总结果并返回"]

图表来源

章节来源

权限控制 ​

  • 所有需要认证的接口均要求 Authorization: Bearer <token>。
  • 文件路径通过 checkPath 校验，防止路径穿越与越权访问。
  • 命令执行通过 checkCommand 校验，灰名单命令在 Workflow Skill 中直接拒绝，白名单命令允许自动执行。
  • MCP stdio 模式新增服务器时对 command + args 做命令安全检查，可能返回 confirm 级别需用户确认。

章节来源

沙箱隔离 ​

  • Skill 执行器不直接暴露任意命令执行给外部；仅允许预定义工具：
    • 文件操作：agent_read_file、agent_write_file、agent_list_dir、agent_delete_file、agent_download_file。
    • 命令执行：agent_exec，受命令白名单/灰名单控制。
    • 搜索：agent_search_files、agent_search_content。
  • 文件路径经过规范化与安全检查，避免路径穿越。
  • 命令执行通过统一执行器，支持 Git Bash 等环境下的 Bash 特性。

章节来源

依赖关系分析 ​

graph TB
Server["server.js"] --> McpRegistry["mcp/registry.js"]
Server --> SkillRegistry["skill/registry.js"]
McpRegistry --> McpClient["mcp/client.js"]
SkillRegistry --> SkillExecutor["skill/executor.js"]
SkillRegistry --> SkillLoader["skill/loader.js"]
LocalClient["background/local-agent-client.js"] --> Server
OptionsSkills["options/toolbox-skills.js"] --> LocalClient

图表来源

章节来源

性能与稳定性特性 ​

  • 并发限制：活跃 Skill 执行最多 100 个，超过上限清理最旧的已完成记录。
  • 超时保护：Skill 执行默认 5 分钟超时，防止长时间阻塞。
  • 清理策略：执行完成后 10 分钟清理执行记录，避免内存泄漏。
  • MCP 连接复用：已连接 MCP Server 的 Client 实例缓存于内存，避免重复连接开销。
  • 工具列表缓存：MCP 工具列表在连接后缓存，减少频繁探测开销。

章节来源

故障排查指南 ​

常见问题 ​

  • MCP 工具列表为空：
    • 检查 MCP Server 是否已连接。
    • 检查 transport 配置是否正确（stdio/SSE/streamableHttp/websocket）。
    • 查看 MCP Server 是否支持 listTools。
  • Skill 执行失败：
    • 检查 Skill 名称是否存在且启用。
    • 检查步骤依赖是否形成环或缺失前置步骤。
    • 检查命令是否被安全策略拒绝。
  • 认证失败：
    • 检查 Authorization: Bearer <token> 是否正确。
    • 检查 Token 是否有效。

调试建议 ​

  • 查看 Agent 日志，关注 skill_run、mcp_tool_call、auth_missing、auth_invalid 等日志类别。
  • 使用 /api/skill/agent-prompts 与 /api/skill/agent-prompt 验证 Agent Skill 是否被正确加载。
  • 使用 /api/mcp/servers 与 /api/mcp/tools 验证 MCP Server 状态与工具发现。

章节来源

结论 ​

本文详细说明了 MCP 工具管理与 Skill 技能管理的 API 契约、自动发现机制、定义格式、执行框架与安全策略。实际使用中，请优先使用 /api/mcp/servers 替代 /api/mcp/status，使用 /api/skill/detail 替代 /api/skill/get，使用 /api/skill/delete 替代 /api/skill/remove。所有敏感操作均需携带 Bearer Token，且 Agent 源码修改后必须重启进程。