cheerio-mcp-bridges

Four "narrow-tool" MCP servers that allow an orchestrator agent (e.g., Claude running in Cowork) that cannot operate a terminal GUI 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 enable only the corresponding bridge.

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 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 first call; subsequent calls use the same id to continue, without relying on the fuzzy semantics of "continue the most recent one."

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

   • codex: on first run, extracts 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 first call; subsequent calls use the same id to continue.

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

4. Conservative permission flags:

   • Default allows read/write files (as the user chooses), but write/dangerous capabilities are still compartmentalized.

   • pi defaults without project trust -a (only enabled with approve_project).

   • agy defaults without --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 (required for non-interactive), not --allow-all (which includes paths + urls); the latter requires dangerously_allow_all:true.

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

Pitfalls Encountered (from actual testing)

• stdin must be closed: CLIs treat piped stdin as extra context; Node spawn leaves an open stdin pipe by default, 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) will hang in headless mode (waiting for a UI that never appears). Therefore, default is --no-extensions, enable with enable_extensions:true when needed.

• codex must include --skip-git-repo-check: if cwd is not a git repo (e.g., C:/Cheerio), without this flag it will immediately error and exit.

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

• copilot MCP server loads very slowly: in non-interactive mode, copilot still loads all MCP servers (playwright, notion, tavily, etc.), startup alone takes 10~30 seconds. Setting timeout too short will kill it during MCP loading.

• copilot default auto-routing may hit quota: 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 will fail directly. It is recommended that the caller explicitly specify a model.

• Copilot/Codex cannot query remaining total quota non-interactively:

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

  • Codex: codex login status only shows login method (e.g., Logged in using ChatGPT), no usage/quota query. codex doctor only does installation diagnostics. The bridge's turn.completed.usage only contains token usage for that turn, no remaining quota.

• Enterprise TLS intercepting proxy may cause npm install failure: some organizations use TLS-inspecting proxies (e.g., certificate interception solutions from security vendors) to perform man-in-the-middle decryption on 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 environment variable NODE_EXTRA_CA_CERTS to point to the company's complete certificate chain file (PEM format); note that you need the CA intermediate certificate, not just the leaf cert.

• GitHub Copilot Enterprise IP allow list may block CLI access: if your GitHub Copilot Enterprise account has an IP allow list enabled, ask_copilot may be directly blocked by the API (error message similar to "enterprise has an IP allow list enabled, and your IP address is not permitted"). This is completely unrelated to bridge / MCP configuration; you need to contact your GitHub Enterprise administrator to confirm whether the current egress IP is on the allow list, or whether you need to use a specific VPN / corporate network.

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 into the MCP client configuration, do not add the ones not 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 which of the 4 CLIs were found, whether they can run --version, and which bridges are recommended to enable.

Step 3: Install the CLIs you need (if not already installed)

Below are the installation and login methods for each CLI, skip the ones not installed, you don't need to install 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 configuration you need from mcp-config.example.json into your MCP client configuration (e.g., ~/.mcp.json or .mcp.json).

Do not copy all four. Only copy the blocks corresponding to the CLIs that are installed and logged in on this machine, then adjust 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 bridge works correctly

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 get an error, 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 MCP Client

See mcp-config.example.json. It's 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 actual paths. Not all four need to be copied.

Tool Interface

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 final text + one line of codex-bridge metadata (including thread_id, usage).

ask_copilot

Returns: Copilot 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 interactive mode UI. The bridge can only report "how much this call consumed" (usage + quotaSnapshots for that call), cannot report remaining total quota. Codex is similar: codex login status only shows login status, no usage query.

Environment Variables