cheerio-mcp-bridges

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

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

各サーバーは、単一で範囲が限定されたツール（汎用的な 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、終了コード、所要時間、使用量）。

Related MCP server: mcacp

遭遇した問題（実測による）

• 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のデフォルトの自動ルーティングでクォータに達する可能性がある：モデルを指定しない場合、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）であり、リーフ証明書だけではないことに注意してください。

• エンタープライズレベルのIP許可リストがCLIアクセスをブロックする（ブリッジはデフォルトで対応済み）：お使いのアカウントが所属するエンタープライズプラン（例：GitHub Copilot Enterprise）でIP許可リストが有効になっている場合、ask_copilot がAPIによってブロックされる可能性があります（エラーメッセージは "enterprise has an IP allow list enabled, and your IP address is not permitted" のようになります）。根本的な原因は通常、ブリッジサーバーの親プロセス環境に HTTP_PROXY/HTTPS_PROXY などのプロキシ設定があり、子プロセスのCLIツールがこれらのプロキシ変数を継承し、OAuthリクエストがエンタープライズプロキシを経由して送信され、プロキシの送信元IPが相手の許可リストに含まれていないことです。ブリッジはv0.2.0から、デフォルトで子プロセスのenvからプロキシ環境変数を自動的に削除します（HTTP_PROXY/HTTPS_PROXY/ALL_PROXY の大文字小文字のバリエーションを含む）。これにより、CLIが直接外部に接続してこの問題を回避します。環境が逆の状況（ターゲットサービスに接続するためにプロキシを経由する必要がある）の場合は、BRIDGE_BYPASS_PROXY=false を設定して、子プロセスがプロキシ設定を継承するように戻すことができます。

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

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

前提条件

• Node.js ≥ 18（node:test とESモジュールをサポートしている必要があります）

• npm ≥ 9

ステップ1：Clone & インストール

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

ステップ2：利用可能なCLIを確認する

npm run doctor

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

ステップ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

ステップ4：ブリッジを選択的に有効にする

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

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

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

ステップ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 はログイン状態のみを表示し、使用量の照会はできません。

環境変数

BRIDGE_BYPASS_PROXY：ブリッジはデフォルトで、基盤となるCLIを呼び出す前に、子プロセスのenvから HTTP_PROXY/HTTPS_PROXY/ALL_PROXY（大文字小文字のバリエーションを含む）を削除します。これにより、子プロセスが親プロセスから継承したエンタープライズプロキシ設定の影響を受けるのを防ぎます。明示的に文字列 "false" に設定された場合のみ、削除動作が無効になります。