cheerio-mcp-bridges

Four "narrow tool" MCP servers that allow an orchestrator agent that cannot operate a terminal GUI (e.g., Claude running in Cowork) to drive four locally installed, logged-in coding CLIs:

The four bridges are independent; you don't need to install all four. First run npm run doctor to see which CLIs are available on this machine, then only enable the corresponding bridges.

Each server exposes a single, scoped tool (not a generic run_command) — it can only "send a prompt to that agent." The residual risk lies in what the underlying CLI can do after receiving the prompt, so the default posture is conservative.

Design Points

1. Working directory locked by the server: cwd comes from environment variables (PI_BRIDGE_CWD / AGY_BRIDGE_CWD / CODEX_BRIDGE_CWD / COPILOT_BRIDGE_CWD), the caller's prompt cannot change it.

2. Deterministic session continuation:

   • pi: Server generates a UUID → --session-id (pi supports "create if not exists"), returns the id on the first call; subsequent calls use the same id to continue, avoiding the ambiguous "continue the most recent one" semantics.

   • agy: Cannot pre-specify an id. After the first run, extracts the conversation_id from --output-format stream-json and returns it; subsequent calls use --conversation <id> to continue.

   • codex: After the first run, extracts the thread_id from the thread.started event and returns it; subsequent calls use codex exec resume <id> to continue.

   • copilot: Server generates a UUID → --session-id, returns the id on the first call; subsequent calls use the same id to continue.

3. Zero shell injection: All four use shell:false with direct spawn, the prompt is a single argv element, and no shell special characters are interpreted.

4. Conservative permission flags:

   • Default allows read/write files (matching user choice), but write/dangerous capabilities are still segmented.

   • pi defaults to not using project trust -a (only enabled with approve_project).

   • agy defaults to not using --dangerously-skip-permissions; workspace read/write is allowed automatically, shell commands remain gated unless dangerously_allow_all:true.

   • codex defaults sandbox to read-only (danger-full-access must be explicitly specified).

   • copilot defaults to only --allow-all-tools (necessary for non-interactive), not --allow-all (which includes paths + urls); the latter requires dangerously_allow_all:true.

5. Audit: Each call writes one JSONL line to logs/<pi|agy|codex|copilot>-YYYYMMDD.jsonl (prompt, session/thread id, exit code, duration, usage).

Related MCP server: all-agents-mcp

Pitfalls Encountered (from actual testing)

• stdin must be closed: CLIs treat piped stdin as additional context. Node's default spawn leaves an open stdin pipe, causing the CLI to hang waiting for EOF. Solution: stdio: ['ignore','pipe','pipe'].

• pi extensions disabled by default: Interactive extensions (e.g., auto-annotate/plannotator) hang in headless mode (waiting for a UI that never appears). Therefore, --no-extensions is the default; use enable_extensions:true to re-enable them.

• codex must use --skip-git-repo-check: If cwd is not a git repo (e.g., C:/Cheerio), omitting this flag causes an immediate error and exit.

• copilot non-interactive mode requires --allow-all-tools: The documentation explicitly states that non-interactive mode must include this flag, otherwise it hangs waiting for user permission confirmation. The bridge includes --allow-all-tools by default, but --allow-all (including paths + urls) is only enabled when dangerously_allow_all:true.

• copilot MCP server loads slowly: Even in non-interactive mode, copilot loads all MCP servers (playwright, notion, tavily, etc.), taking 10-30 seconds just to start. Setting the timeout too short will kill it during the MCP loading phase.

• copilot default auto-routing may hit quota limits: When no model is specified, copilot's hydra router automatically selects a model (e.g., gpt-5-mini). If that model's quota is exhausted, it fails immediately. It is recommended that the caller explicitly specify a model.

• Copilot/Codex cannot query remaining quota in non-interactive mode:

  • Copilot: copilot billing / copilot limits are help topics, only useful in the interactive mode UI. The non-interactive CLI has no copilot usage command. The bridge can only get a "snapshot at the time of failure" from the model.call_failure event's quotaSnapshots, it cannot proactively query remaining quota.

  • Codex: codex login status only shows the login method (Logged in using ChatGPT), with no usage/quota query. codex doctor only performs installation diagnostics. The bridge's turn.completed.usage only provides token usage for that call, not remaining quota.

• Enterprise TLS interception proxies may cause npm install to fail: Some organizations use TLS inspection proxies (e.g., security vendor certificate interception solutions) to perform man-in-the-middle decryption of HTTPS traffic. This causes Node.js TLS validation to fail, with npm install reporting errors like UNABLE_TO_GET_ISSUER_CERT_LOCALLY or certificate chain incomplete. Solution: Set the environment variable NODE_EXTRA_CA_CERTS to point to the company's complete certificate chain file (PEM format). Note that this needs to be the CA intermediate certificate, not just the leaf cert.

• Enterprise IP allow list blocking CLI access (bridge handles this by default): If your account's enterprise plan (e.g., GitHub Copilot Enterprise) has an IP allow list enabled, ask_copilot may be blocked by the API (error message similar to "enterprise has an IP allow list enabled, and your IP address is not permitted"). The root cause is usually: The bridge server's parent process environment has HTTP_PROXY/HTTPS_PROXY proxy settings. The child process's CLI tool inherits these proxy variables, causing OAuth requests to go through the enterprise proxy, and the proxy's egress IP is not on the allow list. Starting from v0.2.0, the bridge automatically strips proxy environment variables (HTTP_PROXY/HTTPS_PROXY/ALL_PROXY including case variations) from the child process's env by default, allowing the CLI to connect directly to avoid this issue. If your environment requires the opposite (must go through a proxy to reach the target service), set BRIDGE_BYPASS_PROXY=false to revert to letting the child process inherit proxy settings.

Cross-Machine Installation (From Scratch)

The four bridges are independent. First run npm run doctor to see which CLIs are available on this machine, only register the corresponding bridges in the MCP client configuration, don't add the ones that aren't installed.

Prerequisites

• Node.js ≥ 18 (needs to support node:test and ES modules)

• npm ≥ 9

Step 1: Clone & Install

git clone https://github.com/CheerioCorner/cheerio-mcp-bridges.git
cd cheerio-mcp-bridges
npm install

Step 2: Check Which CLIs Are Available

npm run doctor

This will output a table showing whether each of the 4 CLIs was found, whether they can successfully run --version, and which bridges are recommended for enabling.

Step 3: Install the CLIs You Need (If Not Already Installed)

Below are the installation and login methods for each CLI. Skip the ones you don't need; you don't have to install them all:

pi (earendil-works/pi)

npm install -g @earendil-works/pi-coding-agent
pi   # 首次啟動會引導登入

Verify: pi --version or pi --help

agy (Google Antigravity CLI)

# 請參考官方文件安裝，通常是一個獨立執行檔
# https://github.com/nicholasareed/antigravity
agy   # 首次啟動會引導 Google 帳號授權

Verify: agy --version

codex (OpenAI Codex CLI)

# 請參考 OpenAI 官方文件安裝
# Windows 通常安裝在 %LOCALAPPDATA%/Programs/OpenAI/Codex/
codex login   # 會引導 ChatGPT 帳號授權

Verify: codex --version, codex login status

copilot (GitHub Copilot CLI)

npm install -g @github/copilot-cli
copilot login   # 會引導 GitHub 帳號授權

Verify: copilot --version

Step 4: Optionally Enable Bridges

Copy the bridge configurations you need from mcp-config.example.json into your MCP client configuration (e.g., ~/.mcp.json or .mcp.json).

Don't copy all four. Only copy the blocks corresponding to the CLIs that are installed and logged in on this machine, then adjust the paths and environment variables.

For example, if you only have pi and copilot installed, only add the pi-bridge and copilot-bridge blocks.

Step 5: Verify the Bridge is Working

After starting your MCP client, send a small test prompt using the corresponding tool:

• ask_pi: { "prompt": "Reply only: pong" }

• ask_agy: { "prompt": "Reply only: pong" }

• ask_codex: { "prompt": "Reply only: pong" }

• ask_copilot: { "prompt": "Reply only: pong" }

You should receive a pong reply and a line of bridge metadata. If you receive an error message, check:

• Whether the CLI executable path (environment variable *_BRIDGE_ENTRY) is correct

• Whether the CLI is logged in

• Whether the cwd environment variable (*_BRIDGE_CWD) exists

Quick Start

cd C:/Cheerio/Claude/mcp-bridges   # 或你 clone 的路徑
npm install
npm run doctor        # 檢查哪些 CLI 可用
npm test              # 執行 parser/arg-builder 單元測試（不花 API 額度）

Registering with an MCP Client

See mcp-config.example.json. It is a menu — based on the CLIs actually available on your machine, only copy the corresponding blocks into your MCP client configuration (.mcp.json) and adjust according to the actual paths. You don't need to copy all four.

Tool Interfaces

ask_pi

Returns: pi's final text + one line of pi-bridge metadata (including session_id).

ask_agy

Returns: agy's final response + one line of agy-bridge metadata (including conversation_id, status).

ask_codex

Returns: Codex's final text + one line of codex-bridge metadata (including thread_id, usage).

ask_copilot

Returns: Copilot's final response + one line of copilot-bridge metadata (including session_id, usage, quota_snapshots).

Quota Query Limitation: The Copilot CLI has no non-interactive command to query "remaining total quota." copilot billing / copilot limits are only useful in the interactive mode UI. The bridge can only report "how much was consumed in this call" (usage + the call's quotaSnapshots), it cannot report remaining total quota. Codex is similar; codex login status only shows login status, with no usage query.

Environment Variables

BRIDGE_BYPASS_PROXY: The bridge defaults to stripping HTTP_PROXY/HTTPS_PROXY/ALL_PROXY (including case variations) from the child process's env before calling the underlying CLI, preventing the child process from being affected by enterprise proxy settings inherited from the parent process. The strip behavior is only disabled when explicitly set to the string "false".