cheerio-mcp-bridges
cheerio-mcp-bridges
四個「窄工具」MCP server,讓一個沒辦法操作終端機 GUI 的 orchestrator agent(例如跑在 Cowork 裡的 Claude)能夠驅動本機已安裝、已登入的四個 coding CLI:
Server | 內部呼叫 | 對外工具 | 語言 |
|
|
| Node.js |
|
|
| Node.js |
|
|
| Node.js |
|
|
| Node.js |
五個 bridge 彼此獨立,不需要五個都裝。 先跑 npm run doctor 看這台機器有哪些 CLI 可用,只啟用對應的 bridge 就好。
四個 server 各自暴露單一、範圍受限的工具(不是通用 run_command)——只能「把一段 prompt 送給那個 agent」。殘餘風險在於底層 CLI 收到 prompt 後自己能做什麼,因此預設姿態偏保守。
設計要點
工作目錄由 server 鎖定:cwd 來自環境變數(
PI_BRIDGE_CWD/AGY_BRIDGE_CWD/CODEX_BRIDGE_CWD/COPILOT_BRIDGE_CWD),呼叫端的 prompt 無法變更。確定性的 session 續接:
pi:server 自己產生 UUID →
--session-id(pi 支援「不存在就建立」),第一次呼叫就把 id 回傳;之後帶同一個 id 續接,不依賴「continue 最近一個」的模糊語意。agy:無法預指定 id,第一次跑完從
--output-format stream-json的conversation_id撈出來回傳;之後用--conversation <id>續接。codex:第一次跑完從
thread.started事件的thread_id撈出來回傳;之後用codex exec resume <id>續接。copilot:server 自己產生 UUID →
--session-id,第一次呼叫就把 id 回傳;之後帶同一個 id 續接。
零 shell 注入:全部都
shell:false直接 spawn,prompt 當作單一 argv 元素,任何 shell 特殊字元都不會被解讀。 Windows 上的.cmd/.batshim(codex.cmd、copilot.cmd)不能直接 CreateProcess,走lib/win-args.mjs自己組cmd.exe /d /s /c命令列並逐一跳脫,不用shell:true—— Node 在shell:true下不會替 argv 加引號(DEP0190),prompt 會被 cmd.exe 拆成好幾個參數, 而且帶&的 prompt 等於命令注入。保守的權限旗標:
預設允許讀寫檔案(符合使用者選擇),但寫入/危險能力仍分段控制。
pi 預設不帶專案信任
-a(approve_project才開)。agy 預設不帶
--dangerously-skip-permissions;workspace 讀寫自動放行、shell 指令維持 gated,除非dangerously_allow_all:true。codex 預設 sandbox 為
read-only(danger-full-access要明確指定)。copilot 預設只帶
--allow-all-tools(非互動必要),不帶--allow-all(含 paths + urls),後者要dangerously_allow_all:true。
稽核:每次呼叫寫一行 JSONL 到
logs/<pi|agy|codex|copilot>-YYYYMMDD.jsonl(prompt、session/thread id、exit code、耗時、usage)。可用性登記表(避免對已知被限流的 model/host 白打):四個 bridge 呼叫 CLI 前都會先查
state/availability.json,命中封鎖中就直接回傳清楚錯誤、不 spawn CLI 浪費呼叫;呼叫後若偵測到限流訊號(429/quota/rate limit 等)會自動記錄封鎖時間。也支援人類手動回報「某 model 被鎖到幾點」。完整格式、三種 confidence(exact/estimated/human-reported)行為與手動回報做法,見state/README.md。
Related MCP server: mcacp
踩過的坑(實測得出)
stdin 必須關閉:CLI 都會把 piped stdin 當額外 context,Node spawn 預設留一個開著的 stdin pipe 會讓 CLI 卡住等 EOF。解法:
stdio: ['ignore','pipe','pipe']。pi extensions 預設關閉:互動型 extension(如
auto-annotate/plannotator)會在 headless 模式掛住(等一個永遠不出現的 UI)。因此預設帶--no-extensions,需要時用enable_extensions:true開回來。codex 必須帶
--skip-git-repo-check:如果 cwd 不是 git repo(例如C:/Cheerio),不帶這個 flag 會直接報錯退出。copilot 非互動模式一定要
--allow-all-tools:文件明確寫了 non-interactive mode 必須帶這個,否則會卡住等使用者確認權限。bridge 預設就帶--allow-all-tools,但--allow-all(含 paths + urls)只在dangerously_allow_all:true時才開。copilot MCP server 載入很慢:非互動模式下 copilot 仍然會載入所有 MCP server(playwright、notion、tavily 等),光是啟動就要 10~30 秒。timeout 設太短會在 MCP 載入階段就被 kill。
copilot 預設 auto-routing 可能撞 quota:不指定 model 時,copilot 的 hydra router 會自動選模型(例如
gpt-5-mini),如果該模型的配額用完就會直接失敗。建議呼叫端明確指定 model。Copilot/Codex 都無法非互動查詢剩餘總額度:
Copilot:
copilot billing/copilot limits是 help topic,只在互動模式 UI 裡有用。非互動 CLI 沒有copilot usage之類的指令。bridge 只能從model.call_failure事件裡的quotaSnapshots拿到「這次失敗時的快照」,無法主動查詢剩餘。Codex:
codex login status只顯示登入方式(Logged in using ChatGPT),沒有用量/配額查詢。codex doctor只做安裝診斷。bridge 的turn.completed.usage只有當次 token 用量,無剩餘額度。
claude 的
-p是布林旗標,prompt 是位置參數:跟 pi/agy/copilot 不同(那三支的-p吃 prompt 當值)。所以 prompt 必須放在最後、而且前面要有一個裸的--,否則--version is not a question這種開頭是 dash 的 prompt 會被當成旗標解析。claude 的 stdin 會等 3 秒:實測 stderr 會印
Warning: no stdin data received in 3s, proceeding without it。bridge 用stdio:['ignore',...](關閉的 stdin)正好避開,但這也是上面「stdin 必須關閉」那條的另一個例子。claude 的
subtype不能當錯誤訊號:unknown model 打回 404 時,is_error是true、api_error_status是404,但subtype還是"success"。要看is_error和api_error_status。claude 的 rate limit 是結構化事件:
rate_limit_event帶status和精確的resetsAt,不用像其他四支那樣比對錯誤字串。但同一個事件裡status:"allowed"可以跟overageStatus:"rejected"並存 —— 只能看status,寬鬆比對"rejected"會把健康的帳號鎖掉。企業級 TLS 攔截 Proxy 可能導致
npm install失敗:某些組織會使用 TLS 檢查型 Proxy(例如資安廠商的憑證攔截方案)對 HTTPS 流量做中間人解密。這會讓 Node.js 的 TLS 驗證失敗,npm install報UNABLE_TO_GET_ISSUER_CERT_LOCALLY或certificate chain incomplete之類的錯誤。解法:設定環境變數NODE_EXTRA_CA_CERTS指向公司的完整憑證鏈檔案(PEM 格式),注意需要的是 CA 中繼憑證(intermediate cert),不是只有 leaf cert。企業級 IP allow list 擋 CLI 存取(bridge 預設已處理):如果你的帳號所屬的企業級方案(例如 GitHub Copilot Enterprise)啟用了 IP allow list,
ask_copilot可能會被 API 擋下(錯誤訊息類似 "enterprise has an IP allow list enabled, and your IP address is not permitted")。根本原因通常是:bridge server 的父進程環境帶有HTTP_PROXY/HTTPS_PROXY之類的 proxy 設定,子進程的 CLI 工具繼承了這些 proxy 變數,導致 OAuth 請求繞經企業 proxy 出去,而 proxy 的出口 IP 不在對方的 allow list 內。bridge 從 v0.2.0 開始預設會自動 strip 掉子進程 env 裡的 proxy 環境變數(HTTP_PROXY/HTTPS_PROXY/ALL_PROXY含大小寫變體),讓 CLI 直接對外連線來避開這個問題。如果你的環境情況相反(必須經過 proxy 才連得到目標服務),可以設BRIDGE_BYPASS_PROXY=false切回讓子進程繼承 proxy 設定。
跨機器安裝(從零開始)
五個 bridge 彼此獨立。先跑
npm run doctor看這台機器有哪些 CLI 可用,只把對應的 bridge 註冊進 MCP client 設定就好,其他沒裝的不要加。
前置需求
Node.js ≥ 18(需要支援
node:test和 ES module)npm ≥ 9
Step 1:Clone & 安裝
git clone https://github.com/CheerioCorner/cheerio-mcp-bridges.git
cd cheerio-mcp-bridges
npm installStep 2:檢查哪些 CLI 可用
npm run doctor # 完整檢查(含 smoke test)
npm run doctor -- --no-smoke # 只解析入口與 --version,完全不花額度會輸出一個表格,告訴你 5 支 CLI 各自:
入口從哪裡解析出來的 —
*_BRIDGE_ENTRY環境變數、套件package.json的bin欄位、 還是 PATH。doctor 不會猜路徑,三個來源都沒有就明確報「找不到」。--version過不過smoke test 過不過 — 真的送一個極短 prompt 跑完整條路徑,確認 exit code 是 0 而且有非空輸出。
第 3 項是重點:--version 在某些 CLI 上會在載入完整相依之前就先印版本退出,所以
「--version 過了」不等於「這支 CLI 能用」。2026-09-05 pi 全面失效那次就是這樣 ——
入口檔一 import 就 ERR_MODULE_NOT_FOUND,但 --version 照樣過。smoke test 每支 CLI
只送一個 prompt,成本可忽略;真的不想花就加 --no-smoke。
有任何 bridge 檢查失敗時 doctor 會以 exit code 1 結束,方便掛進 CI 或啟動前檢查。
Step 3:安裝你需要的 CLI(如果還沒裝)
以下是各 CLI 的安裝與登入方式,沒裝的跳過就好,不用全部裝:
pi(earendil-works/pi)
npm install -g @earendil-works/pi-coding-agent
pi # 首次啟動會引導登入驗證:pi --version 或 pi --help
agy(Google Antigravity CLI)
# 請參考官方文件安裝,通常是一個獨立執行檔
# https://github.com/nicholasareed/antigravity
agy # 首次啟動會引導 Google 帳號授權驗證:agy --version
codex(OpenAI Codex CLI)
# 請參考 OpenAI 官方文件安裝
# Windows 通常安裝在 %LOCALAPPDATA%/Programs/OpenAI/Codex/
codex login # 會引導 ChatGPT 帳號授權驗證:codex --version、codex login status
copilot(GitHub Copilot CLI)
npm install -g @github/copilot-cli
copilot login # 會引導 GitHub 帳號授權驗證:copilot --version
claude(Anthropic Claude Code CLI)
npm install -g @anthropic-ai/claude-code
claude # 首次啟動會引導登入(訂閱制走 OAuth)驗證:claude --version
claude是原生執行檔(npm 套件的bin指向bin/claude.exe,各平台的二進位放在optionalDependencies)。CLAUDE_BRIDGE_ENTRY直接填那個執行檔的絕對路徑,前面不要加node。 官方安裝腳本會裝到%USERPROFILE%\.local\bin\claude.exe。
Step 4:選擇性啟用 bridge
把你需要的 bridge 設定從 mcp-config.example.json 複製進你的 MCP client 設定(例如 ~/.mcp.json 或 .mcp.json)。
不要四個全抄。 只複製你這台機器有裝且有登入的 CLI 對應的區塊,然後調整路徑與環境變數。
例如你只裝了 pi 和 copilot,就只加 pi-bridge 和 copilot-bridge 兩個區塊。
Step 5:驗證 bridge 正常運作
啟動你的 MCP client 後,用對應的工具送一個很小的 prompt 測試:
ask_pi:{ "prompt": "Reply only: pong" }ask_agy:{ "prompt": "Reply only: pong" }ask_codex:{ "prompt": "Reply only: pong" }ask_copilot:{ "prompt": "Reply only: pong" }
應該要收到 pong 回覆和一行 bridge metadata。如果收到錯誤訊息,檢查:
CLI 執行檔路徑(環境變數
*_BRIDGE_ENTRY)是否正確CLI 是否已登入
cwd 環境變數(
*_BRIDGE_CWD)是否存在
快速開始
cd C:/Cheerio/CheerioCorner/mcp-bridges # 或你 clone 的路徑
npm install
npm run doctor # 檢查哪些 CLI 可用(含 smoke test;--no-smoke 可跳過)
npm test # 執行 parser/arg-builder 單元測試(不花 API 額度)註冊到 MCP client
見 mcp-config.example.json。那是一份菜單——照你這台機器實際有的 CLI,只挑對應的區塊複製進你的 MCP client 設定(.mcp.json),並依實際路徑調整。不是四個都要抄。
工具介面
ask_pi
參數 | 型別 | 預設 | 說明 |
| string | — | 要送給 pi 的指令(必填) |
| string | 自動產生 | 帶上一次回傳的值即可續接同一對話 |
| boolean | false | true 時只給 |
| string | — | 覆寫 model |
| boolean | false | 是否信任專案本地資源(pi -a) |
| boolean | false | 是否載入 extensions(有掛住風險) |
| number | 300000 | 硬性逾時 |
回傳:pi 的最終文字 + 一行 pi-bridge metadata(含 session_id)。
ask_agy
參數 | 型別 | 預設 | 說明 |
| string | — | 要送給 agy 的指令(必填) |
| string | 自動擷取 | 帶上一次回傳的值即可續接 |
| string | — | model slug(見 |
| low|medium|high | — | 推理強度 |
| boolean | false | 開終端沙箱限制(--sandbox) |
| boolean | false | 危險:自動批准所有工具權限(含 shell) |
| number | 300000 | 硬性逾時(同步作為 agy --print-timeout) |
回傳:agy 的最終回應 + 一行 agy-bridge metadata(含 conversation_id、status)。
ask_codex
參數 | 型別 | 預設 | 說明 |
| string | — | 要送給 Codex 的指令(必填) |
| string | 自動產生 | 帶上一次回傳的 thread_id 即可續接 |
| string | — | 覆寫 model(如 |
| read-only|workspace-write|danger-full-access | read-only | 沙箱策略 |
| number | 300000 | 硬性逾時 |
回傳:Codex 的最終文字 + 一行 codex-bridge metadata(含 thread_id、usage)。
ask_copilot
參數 | 型別 | 預設 | 說明 |
| string | — | 要送給 Copilot 的指令(必填) |
| string | 自動產生 | 帶上一次回傳的值即可續接同一對話 |
| string | — | 覆寫 model(如 |
| none|minimal|low|medium|high|xhigh|max | — | 推理強度 |
| number | — | 單次呼叫的花費上限(安全閥) |
| boolean | false | 危險:加 |
| number | 300000 | 硬性逾時 |
回傳:Copilot 的最終回應 + 一行 copilot-bridge metadata(含 session_id、usage、quota_snapshots)。
ask_claude
參數 | 型別 | 預設 | 說明 |
| string | — | 要送給 Claude 的指令(必填) |
| string | 自動產生 | 帶上一次回傳的值即可續接同一對話 |
| boolean | false | 加 |
| boolean | false | 自動核准檔案編輯( |
| boolean | false | 危險: |
| string | — |
|
| low|medium|high|xhigh|max | — | 推理強度 |
| number | — | 單次呼叫的花費上限( |
| number | 300000 | 硬性逾時 |
回傳:Claude 的最終回應 + 一行 claude-bridge metadata(含 session_id、tools_used、
permission_denials、num_turns、cost_usd、usage、rate_limit_status)。
預設是唯讀的:不帶任何 flag 時 Claude 讀得到檔案,但任何寫入/執行都會被自動拒絕 (
--permission-mode manual+--permission-prompts none)。要它真的動手改檔案, 必須明確帶allow_edits:true。
旗標會依 CLI 版本自動降級:Claude Code 的旗標名稱會在小版號之間變動 —— 2.1.263 有
--permission-prompts,2.1.258 沒有,送過去就是unknown option,整支 bridge 全掛。所以 bridge 啟動時會跑一次claude --help(不花額度、不用登入),只送這個版本認得的旗標;被拿掉或替換掉的每一個都會寫一行[claude-bridge] …到 stderr,也放在回傳的flagWarnings裡。權限旗標被拔掉是會改變 這次執行能做什麼的事,不能安靜地發生。npm run doctor用同一套機制,並在報表裡列出 「版本差異(已自動降級)」。
被拒絕的工具呼叫會講出來:Claude 被擋下寫入時,
is_error是false、exit code 是0、 回應裡還是會很有自信地說「我改好了」。bridge 會把permission_denials同時放進 metadata 和回應本文,避免呼叫端相信一件沒有發生的事。這是這個 repo 最在意的那種靜默失敗。
不會載入你的 MCP 設定:bridge 固定帶
--strict-mcp-config和--safe-mode,所以你的 hooks、plugins、CLAUDE.md 和 MCP servers 都不會載入。這是必要的 —— 否則ask_claude呼叫出去的 claude 會把.mcp.json裡的五個 bridge 全部再載一遍。 用的是--safe-mode而不是--bare:--bare的認證只吃ANTHROPIC_API_KEY/apiKeyHelper, 完全不讀 OAuth 和 keychain,訂閱制登入會直接失敗。
額度查詢限制:Copilot CLI 沒有非互動模式的指令能查詢「剩餘總額度」。
copilot billing/copilot limits只在互動模式的 UI 裡有用。bridge 只能回報「這次呼叫消耗多少」(usage+ 當次quotaSnapshots),無法回報剩餘總額度。Codex 同理,codex login status只顯示登入狀態,無用量查詢。
環境變數
變數 | 必填 | 預設 | 說明 |
| ✅ | 無 | bridge 釘死的工作目錄,絕對路徑。沒設會在啟動時直接報錯 |
| ✅ | 無 | pi 的入口。必須是 pi 套件 |
| ✅ | 無 |
|
| ✅ | 無 |
|
| ✅ | 無 |
|
| ✅ | 無 |
|
|
| 硬性逾時 | |
|
| 稽核 log 目錄 | |
|
| 見下方說明 | |
|
|
|
所有 *_BRIDGE_CWD / *_BRIDGE_ENTRY 都沒有內建預設值:這些是各機器不同的路徑,
埋一個 fallback 只會讓設錯的人以為自己設對了,然後跑到別人的目錄或不存在的執行檔上。
沒設就在啟動時報錯,錯誤會直接出現在 MCP 連線狀態裡。
PI_BRIDGE_ENTRY 為什麼特別容易設錯
pi 的 dist/ 底下同時有兩個入口:
dist/cli.js— 未打包,會import沒有安裝的@earendil-works/pi-server, 一啟動就ERR_MODULE_NOT_FOUND(2026-09-05 的 3 小時全面失效就是這樣來的)dist/bundle/cli.js— 相依已打包,這才是package.json的bin真正指向的檔案
規則很簡單:入口以套件自己的 package.json bin 欄位為準,不要看 dist/ 底下
有什麼就填什麼。npm run doctor 會替你動態解析出正確路徑,並實際送一個 prompt
驗證它真的跑得起來。
BRIDGE_BYPASS_PROXY:bridge 預設會在呼叫底層 CLI 前 strip 掉子進程 env 裡的 HTTP_PROXY/HTTPS_PROXY/ALL_PROXY(含大小寫變體),避免子進程被父進程繼承到的企業 proxy 設定牽連。只有明確設成字串 "false" 時才關閉 strip 行為。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Email inboxes, webhook URLs, mock APIs and 170+ tools for coding agents over one MCP connection.
Hosted MCP server and Agent Skills for specs, engineering threads, and project memory.
Secure Linux sandboxes for AI agents, as MCP tools.
Governed AI agent skills — one library, distributed to devs and exposed to remote agents over MCP.
Related MCP Servers
- AlicenseBqualityFmaintenanceEnables orchestrating multiple AI CLI agents (Claude Code, Codex, Gemini CLI, Copilot CLI) through a unified MCP interface for task delegation, cross-agent comparison, and specialized tools like code review and debugging.1411 npm13MIT
- AlicenseAqualityDmaintenanceBridges any MCP client (like Claude Code, Zed, VS Code) to any ACP coding agent, enabling multi-agent orchestration from a single chat interface.24627 npm12Apache 2.0
- AlicenseNot gradedqualityDmaintenanceMCP bridge for calling local coding-agent CLIs (Codex, Claude) from another agent, enabling bounded tasks like code review, verification, and bug hunting.MIT
- AlicenseAqualityBmaintenanceBridges multiple CLI coding agents (Codex, Cursor, OpenCode, Claude, Antigravity) into any MCP client, enabling delegation of prompts, parallel execution, and code review workflows.671 npmMozilla Public 2.0