codemode-mcp

把本地多个 stdio MCP server 聚合成 一个 Cloudflare Code Mode code 工具。

Agent 不再面对一堆工具定义，只见一个 code 工具；模型在隔离 sandbox 里写代码，以 codemode.<prefix>_<tool>(...) 编排各 MCP server 的工具，中间结果留在 sandbox，不进入对话上下文。

Agent ── 只见 1 个 code 工具 ──> http://localhost:8787/mcp
                                      │ sandbox: codemode.<prefix>_<tool>()
                                      ▼
                    桥 :9230（官方 MCP SDK，stdio ↔ Streamable HTTP）
                                      │  按 mcp.jsonc 拉起各 stdio server
                                      ▼
                     chrome-devtools-mcp ──> 你的 Chrome（--auto-connect）
                     @modelcontextprotocol/server-filesystem ──> 文件系统
                     ...任何 stdio MCP server

快速开始

要求：Bun 1.3+；连接本机 Chrome 需 Chrome 144+ 并在 chrome://inspect/#remote-debugging 开启远程调试。

bun install
bun run dev

bun run dev 会依次：读取 mcp.jsonc（首次运行自动从 mcp.jsonc.example 生成）→ 拉起各 stdio MCP server → 启动桥（:9230）→ 启动 wrangler dev（:8787）。Ctrl+C 一次清理全部子进程。

Agent / MCP 客户端接入：

{
  "mcpServers": {
    "codemode": { "url": "http://localhost:8787/mcp" }
  }
}

也可用 MCP Inspector 图形化验证：npx @modelcontextprotocol/inspector@latest，Streamable HTTP 连接 http://localhost:8787/mcp，List Tools 应只见一个 code，其描述中包含各 server 的 <prefix>_<tool> 方法。

Related MCP server: MCP Hub

配置：mcp.jsonc

唯一需要编辑的文件（JSONC，支持注释；已被 .gitignore 忽略，可放心写个人配置）：

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "bun",
      "args": ["x", "chrome-devtools-mcp", "--auto-connect"]
    },
    "filesystem": {
      "command": "bun",
      "args": ["x", "@modelcontextprotocol/server-filesystem", "/data"]
      // "prefix": "fs"   // 可选，默认取名字首段：chrome-devtools -> chrome
    }
  }
}

• command / args / env：MCP 生态通用格式，与 Claude Desktop、opencode 等一致；

• prefix：sandbox 方法前缀（可选，默认取名字首段，前缀冲突会在启动时报错）；

• 新增 server 无需改任何代码，重启 bun run dev 生效；

• 单个 server 启动失败只降级跳过（日志标明），不影响其余 server。

工作原理

几个设计要点：

• 为什么需要桥：codeMcpServer() 只接受进程内 McpServer 实例，而 stdio MCP server（如 chrome-devtools-mcp）无法在 workerd 里 spawn。桥用官方 @modelcontextprotocol/sdk 做 stdio ↔ HTTP 协议转换，工具定义与执行全程走 MCP 协议。

• 动态发现：Worker 不读配置文件，每次请求经桥的 /servers 端点获取列表再 listTools 注册——上游 server 升级新增工具后无需改动本项目。

• JSON Schema → zod：Worker（workerd）禁止 eval，故选用运行时直接构造 zod 对象的 @dmitryrechkin/json-schema-to-zod（Cloudflare Workers 兼容）。

• 运行时分工：bun 跑桥与编排（Node 环境），wrangler（workerd）跑 Worker；两者在 9230 端口以 HTTP 对话。

说明与限制

• 本项目是本地链路：wrangler deploy 部署到 Cloudflare 后，线上 Worker 无法访问 127.0.0.1:9230 的桥与本机 Chrome；如需远程部署，把桥跑在 Worker 可达的主机上并修改 wrangler.jsonc 的 vars.MCP_BRIDGE_URL。

• chrome-devtools 的 --auto-connect 依赖 Chrome 144+ 的远程调试开关（chrome://inspect/#remote-debugging）；也可用 --browserUrl 指向传统 CDP 端口（--remote-debugging-port，Chrome 136+ 需配合非默认 --user-data-dir）。

• 在 TUN 透明代理环境下若 bunx 下载依赖失败（DNS 返回 IPv6 而 TUN 只接管 IPv4），给桥进程设置 HTTPS_PROXY 指向本地代理端口即可（scripts/bridge.ts 已默认注入 http://127.0.0.1:7890，可按需修改）。

依赖

• Cloudflare Code Mode（@cloudflare/codemode）— 单 code 工具与隔离执行

• chrome-devtools-mcp — 浏览器自动化

• Model Context Protocol TypeScript SDK — MCP 协议实现

• jsonc-parser — JSONC 解析

• Wrangler — workerd 本地运行时