cheerio-mcp-bridges

4つの「狭いツール」MCPサーバー。ターミナルGUIを操作できないオーケストレーターエージェント（例：Cowork内で動作するClaude）が、このマシンにインストール・ログイン済みの4つのコーディングCLIを駆動できるようにします。

4つのブリッジは独立しており、すべてをインストールする必要はありません。 まず npm run doctor を実行して、このマシンで利用可能なCLIを確認し、対応するブリッジのみを有効にしてください。

4つのサーバーはそれぞれ単一で範囲が限定されたツール（汎用の run_command ではありません）を公開します。できるのは「プロンプトをそのエージェントに送る」ことだけです。残りのリスクは、基盤となるCLIがプロンプトを受け取った後に何ができるかに依存するため、デフォルトの姿勢はやや保守的です。

設計のポイント

1. 作業ディレクトリはサーバーが固定：cwd は環境変数（PI_BRIDGE_CWD / AGY_BRIDGE_CWD / CODEX_BRIDGE_CWD / COPILOT_BRIDGE_CWD）から取得し、呼び出し側のプロンプトでは変更できません。

2. 確定的なセッション継続：

   • pi：サーバーがUUIDを生成 → --session-id（piは「存在しなければ作成」をサポート）、初回呼び出しでIDを返却。以降は同じIDで継続。「直近のものを続ける」という曖昧な意味に依存しません。

   • agy：事前にIDを指定できません。初回実行後に --output-format stream-json の conversation_id から取得して返却。以降は --conversation <id> で継続。

   • codex：初回実行後に thread.started イベントの thread_id から取得して返却。以降は codex exec resume <id> で継続。

   • copilot：サーバーがUUIDを生成 → --session-id、初回呼び出しでIDを返却。以降は同じIDで継続。

3. ゼロシェルインジェクション：4つとも shell:false で直接spawnし、プロンプトは単一のargv要素として渡すため、シェルの特殊文字は一切解釈されません。

4. 保守的な権限フラグ：

   • デフォルトでファイルの読み書きを許可（ユーザーの選択に従う）が、書き込み/危険な能力は段階的に制御。

   • pi はデフォルトでプロジェクト信頼 -a（approve_project で有効化）を付けない。

   • agy はデフォルトで --dangerously-skip-permissions を付けない。ワークスペースの読み書きは自動許可、シェルコマンドはゲート付きのまま。dangerously_allow_all:true の場合のみ全許可。

   • codex はデフォルトのサンドボックスが read-only（danger-full-access は明示的に指定が必要）。

   • copilot はデフォルトで --allow-all-tools のみ（非対話に必須）、--allow-all（paths + urls含む）は付けない。後者は dangerously_allow_all:true の場合のみ。

5. 監査：呼び出しごとに1行のJSONLを logs/<pi|agy|codex|copilot>-YYYYMMDD.jsonl に書き込み（プロンプト、セッション/スレッドID、終了コード、所要時間、使用量）。

ハマったポイント（実測による）

• stdinは閉じなければならない：CLIはパイプされたstdinを追加のコンテキストとして扱うため、Nodeのspawnで開いたstdinパイプを残すとCLIがEOFを待ってハングします。解決策：stdio: ['ignore','pipe','pipe']。

• piの拡張機能はデフォルトで無効：対話型拡張機能（例：auto-annotate/plannotator）はヘッドレスモードでハングします（決して表示されないUIを待つ）。そのためデフォルトで --no-extensions を付け、必要な場合のみ enable_extensions:true で有効化。

• codexは --skip-git-repo-check 必須：cwdがgitリポジトリでない場合（例：C:/Cheerio）、このフラグがないとエラーで終了します。

• copilotの非対話モードでは必ず --allow-all-tools：ドキュメントに明記されている通り、非対話モードではこれが必須で、付けないとユーザーの権限確認を待ってハングします。ブリッジはデフォルトで --allow-all-tools を付けますが、--allow-all（paths + urls含む）は dangerously_allow_all:true の場合のみ有効。

• copilotのMCPサーバー読み込みは遅い：非対話モードでもcopilotはすべてのMCPサーバー（playwright、notion、tavilyなど）を読み込むため、起動だけで10〜30秒かかります。タイムアウトを短く設定すると、MCP読み込み中に強制終了されます。

• copilotのデフォルトauto-routingはクォータに抵触する可能性あり：モデルを指定しない場合、copilotのhydraルーターが自動でモデルを選択します（例：gpt-5-mini）。そのモデルの割り当てが尽きていると、直接失敗します。呼び出し側でモデルを明示的に指定することを推奨。

• Copilot/Codexは非対話で残り総クォータを照会できない：

  • Copilot：copilot billing / copilot limits はヘルプトピックであり、対話モードのUIでのみ有効。非対話CLIには copilot usage のようなコマンドはありません。ブリッジは model.call_failure イベント内の quotaSnapshots から「今回失敗した時点のスナップショット」を取得できるのみで、残りを能動的に照会することはできません。

  • Codex：codex login status はログイン方法のみ表示（Logged in using ChatGPT）。使用量/クォータ照会は不可。codex doctor はインストール診断のみ。ブリッジの turn.completed.usage はそのターンのトークン使用量のみで、残りクォータは不明。

• エンタープライズ級TLSインターセプトプロキシで npm install が失敗する可能性：一部の組織ではTLS検査プロキシ（例：セキュリティベンダーの証明書インターセプトソリューション）を使用してHTTPSトラフィックを中間者復号しています。これによりNode.jsのTLS検証が失敗し、npm install が UNABLE_TO_GET_ISSUER_CERT_LOCALLY や certificate chain incomplete などのエラーを報告します。解決策：環境変数 NODE_EXTRA_CA_CERTS に会社の完全な証明書チェーンファイル（PEM形式）を設定します。必要なのはCA中間証明書（intermediate cert）であり、リーフ証明書だけでは不十分なことに注意。

• GitHub Copilot EnterpriseのIP許可リストがCLIアクセスをブロックする可能性：GitHub Copilot EnterpriseアカウントでIP許可リストが有効になっている場合、ask_copilot がAPIで直接ブロックされる可能性があります（エラーメッセージは "enterprise has an IP allow list enabled, and your IP address is not permitted" など）。これはブリッジやMCPの設定とは無関係で、GitHub Enterprise管理者に現在の出口IPが許可リストに含まれているか、特定のVPNや社内ネットワークを経由する必要があるかを確認する必要があります。

クロスマシンインストール（ゼロから）

4つのブリッジは独立しています。まず npm run doctor を実行して、このマシンで利用可能なCLIを確認し、対応するブリッジのみをMCPクライアント設定に登録してください。インストールされていないものは追加しないでください。

前提条件

• Node.js ≥ 18（node:test とESモジュールをサポート）

• npm ≥ 9

Step 1：Clone & インストール

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

Step 2：利用可能なCLIを確認

npm run doctor

テーブルが出力され、4つのCLIそれぞれが見つかったか、--version が正常に実行できるか、どのブリッジを有効にするのが推奨されるかが表示されます。

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

Step 4：ブリッジを選択的に有効化

必要なブリッジの設定を mcp-config.example.json からコピーして、MCPクライアント設定（例：~/.mcp.json または .mcp.json）に貼り付けます。

4つすべてをコピーしないでください。 このマシンにインストール・ログイン済みのCLIに対応するブロックのみをコピーし、パスと環境変数を調整してください。

例えば、piとcopilotのみインストールしている場合は、pi-bridge と copilot-bridge の2つのブロックのみを追加します。

Step 5：ブリッジが正常に動作することを確認

MCPクライアントを起動したら、対応するツールを使って小さなプロンプトを送信してテストします。

• 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 の応答と1行のブリッジメタデータが返ってくるはずです。エラーが返ってきた場合は、以下を確認してください。

• CLI実行ファイルのパス（環境変数 *_BRIDGE_ENTRY）が正しいか

• CLIがログイン済みか

• cwd環境変数（*_BRIDGE_CWD）が存在するか

クイックスタート

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

MCPクライアントへの登録

mcp-config.example.json を参照してください。これはメニューです。このマシンに実際に存在するCLIに基づいて、対応するブロックのみをコピーしてMCPクライアント設定（.mcp.json）に貼り付け、実際のパスに合わせて調整してください。4つすべてをコピーする必要はありません。

ツールインターフェース

ask_pi

戻り値：piの最終テキスト + 1行の pi-bridge metadata（session_id を含む）。

ask_agy

戻り値：agyの最終応答 + 1行の agy-bridge metadata（conversation_id、status を含む）。

ask_codex

戻り値：Codexの最終テキスト + 1行の codex-bridge metadata（thread_id、usage を含む）。

ask_copilot

戻り値：Copilotの最終応答 + 1行の copilot-bridge metadata（session_id、usage、quota_snapshots を含む）。

クォータ照会の制限：Copilot CLIには非対話モードで「残り総クォータ」を照会するコマンドはありません。copilot billing / copilot limits は対話モードのUIでのみ有効です。ブリッジは「今回の呼び出しで消費した量」（usage + 今回の quotaSnapshots）を報告できるのみで、残り総クォータは報告できません。Codexも同様で、codex login status はログイン状態のみ表示し、使用量照会はできません。

環境変数