Wiki AI

ZCode MCP 集成

3分钟阅读

MCP（Model Context Protocol）是 ZCode 扩展运行时的一部分，拥有”配置发现/加载”，与 agent-core（如何进入上下文与 turn）分离。

配置来源（三条并入路径）

  1. 插件内：.mcp.json + manifest mcpServers（合并，manifest 优先）——见 plugin-system。
  2. 用户/项目：~/.zcode/cli/config.json 的 mcp.servers、<workspace>/.zcode/config.json 的 mcp.servers。
  3. 导入：设置页从外部 Agent 扫描 12 类来源（Claude ~/.claude/settings.json + .mcp.json、Codex config.toml、OpenCode opencode.json、OpenClaw、Qwen、Qoder/CN、Trae、Kiro、Roo、CodeBuddy、通用 .agents/mcp.json）；同名保留 ZCode 现有配置。
  4. Host 注入：官方插件 hostMcpServerNames（browser-use / computer-use 的 node_repl），不是 manifest 内 server。

配置格式（CLI）

默认用户配置路径 ~/.zcode/cli/config.json，MCP 默认启用（features.mcp 仅在需要显式开关时设置）：

{
  "mcp": {
    "servers": {
      "filesystem": { "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] },
      "docs": { "type": "http", "url": "https://mcp.example.com/mcp" },
      "legacy-sse": { "type": "sse", "url": "https://mcp.example.com/sse", "enabled": false }
    }
  }
}
  • stdio：需 command，可 args/cwd/env/enabled/timeoutMs。
  • http / sse：需 url，可 headers/enabled/timeoutMs。
  • MCP 工具在首次模型请求前注册，暴露为 mcp__<server>__<tool>。
  • 会话内命令：/mcp list、/mcp status、/mcp connect <server>、/mcp disconnect <server>。

插件侧 MCP

adapters/src/plugins/mcp.ts：

  • 来源合并：.mcp.json（插件根）+ manifest mcpServers，后者覆盖前者。
  • server 名命名空间 plugin:<pluginName>:<serverName>；runtime source 归类 builtin / plugin。
  • 传输：stdio / Streamable HTTP / SSE；OAuth 支持 client_credentials 与 authorization_code。
  • 官方鉴权 zcode_official + jwt_token：仅允许 http/stdio，sse 直接禁用；与 oauth 不能共存；静态 header 不得含官方保留头；provenance 由宿主生成，不能伪造。
  • 环境模板 CLAUDE_PROJECT_DIR/ZCODE_PROJECT_DIR、ZCODE_PLUGIN_DATA、ZCODE_PLUGIN_ROOT（含 CLAUDE 别名）；sensitive user_config 只允许展开到敏感 sink（env/header/clientSecret）。

MCP 客户端实现

adapters/src/mcp/：pool.ts、stdio-transport.ts、oauth*.ts、resource-subscriptions.ts、windows-job-object.ts（Windows 进程容器）、timeout.ts、telemetry.ts。

平台边界（docs/mcp-platform-boundary.md）

  • MCP 原生目录管理是平台能力，UI 只经 IPlatformService（loadMcpFromUserDirectory / saveMcpToUserDirectory / migrateLegacyCommonMcp）。
  • 普通 stdio / Streamable HTTP 用 dual-era auto 协商。
  • 内置 node_repl 固定 MCP 2026-07-28、无 Mcp-Session-Id、按 workspaceKey 共享无状态进程（docs/mcp-stateless-node-repl.md）。
  • 手机 /remote 复用 desktop shared-host attachment，不建独立 runtime。
  • 设置页显示本地化 initialize/tools/list 诊断并按 pluginId 归属；官方 Server MCP 单独处理 auth/quota/unavailable。

MCP Apps（插件 UI 页面）

packages/shared/src/mcp-apps/ 是纯 wire contract：

  • contract.ts：沙箱契约类型、PluginSandboxPlatformPort
  • hostContract.ts：ui/download-file、tool-input/result 载荷、titleBar/样式变量
  • toolMeta.ts：_meta 归一化、ui:// resourceUri 优先级
  • sampling.ts、appTools.ts、schemas.ts

CONTRACT.md 规定页面↔宿主的 ui/* 线协议由官方 @modelcontextprotocol/ext-apps 承担；ZCode 扩展放 hostCapabilities.experimental["zcode/…"]；沙箱 origin 由 sandboxId 派生、partition 由 server 身份派生。详见 plugin-system、desktop。

相关设计文档

docs/mcp-dual-era-version-negotiation.md、mcp-stateless-node-repl.md、mcp-oauth-client-auth.md、mcp-oauth-two-phase.md、mcp-tool-output-budget.md、mcp-async-tool-catalog-cache.md、mcp-apps-resource-mime-spec.md、mcp-config-compat-diagnostics.md、mcp-stdio-failure-stderr-diagnostics.md、windows-mcp-job-object-containment.md。

相关页面

关系图谱

反向链接