ZCode MCP Bridge(ZCode MCP 桥接)

把 ZCode 作为完整的智能体(agent)暴露给任意 MCP 客户端 —— 在 Claude Code、Codex、Cursor 或 ZCode 自身里,通过两个工具把复杂编码任务委托给一个独立的 ZCode 智能体去执行。

[!WARNING] 当前默认权限模式是 yolo。 如果调用时没有显式传入 mode 或 sandbox,ZCode 会自动批准工具调用,包括修改文件和执行 shell 命令。处理不可信提示词、重要仓库或生产环境时,请显式使用 mode: "plan" 或 sandbox: "read-only";确认方案后再按需切换到 build / workspace-write。只有在明确接受完全访问风险时才使用 yolo / danger-full-access。

本实现对齐 Codex 官方 mcp-server(codex mcp-server 会暴露 codex / codex-reply 两个工具),本项目提供与之等价的:

Codex mcp-server	ZCode MCP Bridge	作用
codex	zcode	运行一个新会话
codex-reply	zcode-reply	用会话 ID(threadId)继续已有会话

工作原理

MCP 客户端(Codex / Claude Code / Cursor / ZCode)
        │  MCP 标准输入输出协议(JSON-RPC 2.0)
        ▼
server.py  ── 提供工具:zcode、zcode-reply
        │  启动子进程并设置 ELECTRON_RUN_AS_NODE=1
        ▼
ZCode 安装包内置 CLI 包(glm/zcode.cjs,无界面 headless 模式)
        │  参数 --prompt / --resume <sess_...> --json
        ▼
ZCode 智能体会话(包含全部已启用插件:技能、Bash、MCP 工具等)

• 零额外运行时依赖:直接驱动 ZCode 安装包内置的 CLI 包(通过 Electron 的 node 模式运行),无需另行安装 Node.js 或任何 Python 包。
• 会话连续性:zcode-reply 通过 --resume <sessionId> 续接,上下文跨调用保持(依赖 ZCode 的持久化会话)。
• 能力继承:无界面会话与桌面端共享同一套插件 / 技能 / MCP 配置。例如启用 ios-simulator 插件后,通过桥接的会话可以直接使用 mcp__plugin_ios-simulator_ios-simulator__* 这 20 个 iOS 工具(已实测可用)。

能力与实测结果

• 完整 MCP 握手(initialize / ping / tools/list / tools/call),标准输入输出传输
• 新建会话 + 会话续接,支持多轮对话(实测单会话连续续接 5 轮正常)
• 复杂任务可用:文件读写、Bash 工具、多步任务、中文回复
• 并发:通过 ZCODE_MCP_MAX_CONCURRENCY 限流,实测 6 路并行正常
• 稳定性:连续 / 并行压测 0 失败(详见测试)
• 错误处理:参数校验、超时、CLI 异常均以结构化 isError 返回,不会导致服务器崩溃

平台支持范围

操作系统	CPU 架构	支持状态	默认发现路径	备注
macOS	Apple Silicon(arm64)	支持	/Applications/ZCode.app、~/Applications/ZCode.app	使用标准 .app/Contents/... 布局
macOS	Intel(x64)	支持	/Applications/ZCode.app、~/Applications/ZCode.app	与 Apple Silicon 使用相同的应用布局
Linux	ARM64(aarch64)	支持,已验证	/opt/ZCode、~/.local/opt/ZCode	已在 Ubuntu 24.04 ARM64 + ZCode 3.6.5 验证完整 MCP 链路
Linux	x64	支持	/opt/ZCode、~/.local/opt/ZCode	使用官方 .deb 安装或将运行时解包至受支持路径
Windows	x64 / ARM64	支持	—	已验证完整 MCP 链路

macOS、Linux 与 Windows 均直接运行 ZCode 内置 CLI,不启动桌面窗口;Linux 不依赖 X11、Wayland 或 Xvfb。Windows 已完成端到端 MCP 链路验证,并包含 UTF-8 stdio、日志编码及 Electron 空输出流兼容处理。桥接本身仅使用 Python 标准库,CPU 架构兼容性取决于所安装的官方 ZCode 包。

如果 ZCode 没有安装在默认位置,可设置 ZCODE_APP_PATH;也可以分别用 ZCODE_BINARY 和 ZCODE_CLI_BUNDLE 指定 Electron 可执行文件与 zcode.cjs。Linux AppImage 用户应先解包或挂载 AppImage,再把这些变量指向对应文件。

目录结构

zcode-mcp-plugin/
├── plugin.json          # ZCode 插件清单(贡献 MCP 服务器)
├── server.py            # MCP 服务器实现(自包含,仅用 Python 标准库)
├── README.md
└── tests/
    ├── test_mcp.py      # 功能测试:握手/工具/新会话/续接/复杂任务/错误/并发/稳定性
    ├── test_stress.py   # 压测:高并发/长稳定循环/多轮对话
    └── test_windows_streams.py # Windows UTF-8 stdio、日志与空输出流回归测试

环境要求

• ZCode 已安装于上述支持平台的默认路径,或已通过环境变量指定运行时位置
• ~/.zcode/cli/config.json 已配置模型提供方(model provider) —— CLI 需要它才能运行无界面会话。若桌面端 ZCode 已在用某个提供方,可一键导入:

python3 server.py --ensure-config

它会从桌面配置 ~/.zcode/v2/config.json 复制已启用的提供方 + 模型到 CLI 配置(优先选择带静态 API 密钥的提供方;只保留该提供方,已有配置会先备份为 .bak)。提供方 ID 会规范化为字母数字形式,因为 CLI 的模型目标解析器会拒绝桌面端的 UUID / builtin: 前缀 ID。

注意:若提供方来自官方 OAuth 登录(无 API 密钥),--ensure-config 会跳过它;当没有可用提供方时,需在 CLI 侧登录或配置(zcode login)。

快速开始

# 1. 检查环境
python3 server.py --probe

# 2. 一键配置 CLI 模型提供方(首次)
python3 server.py --ensure-config

# 3. 冒烟测试(可选)
python3 tests/test_mcp.py --fast

# 4. 以 MCP 服务器方式运行(配合任一客户端注册,见下)
python3 /path/to/zcode-mcp-plugin/server.py

运行方式

1. 作为 ZCode 插件(自动贡献 MCP 服务器)

把本目录放进 ZCode 插件根目录,或在插件市场添加本目录,启用 zcode-mcp-bridge 后 ZCode 会自动启动 zcode-agent MCP 服务器,会话里直接出现 mcp__zcode-agent__zcode 与 mcp__zcode-agent__zcode-reply 工具。

2. 作为独立 MCP 服务器(任意 MCP 客户端)

python3 /path/to/zcode-mcp-plugin/server.py

Codex(~/.codex/config.toml)