cheerio-mcp-bridges

Vier „schmale Werkzeug“-MCP-Server, die es einem Orchestrator-Agenten (z. B. Claude in Cowork), der keine GUI auf dem Terminal bedienen kann, ermöglichen, vier lokal installierte, bereits angemeldete Coding-CLIs zu steuern:

Die vier Bridges sind voneinander unabhängig, es müssen nicht alle vier installiert werden. Führen Sie zuerst npm run doctor aus, um zu sehen, welche CLIs auf diesem Rechner verfügbar sind, und aktivieren Sie nur die entsprechende Bridge.

Jeder Server stellt ein einziges, eingeschränktes Werkzeug zur Verfügung (kein allgemeines run_command) – es kann nur „einen Prompt an diesen Agenten senden“. Das verbleibende Risiko besteht darin, was die zugrunde liegende CLI nach Erhalt des Prompts selbst tun kann. Daher ist die Standardhaltung eher konservativ.

Design-Punkte

1. Arbeitsverzeichnis vom Server festgelegt: Das cwd stammt aus einer Umgebungsvariablen (PI_BRIDGE_CWD / AGY_BRIDGE_CWD / CODEX_BRIDGE_CWD / COPILOT_BRIDGE_CWD), der Prompt des Aufrufers kann es nicht ändern.

2. Deterministische Sitzungsfortsetzung:

   • pi: Server generiert eigene UUID → --session-id (pi unterstützt „existiert nicht, wird erstellt“), die ID wird beim ersten Aufruf zurückgegeben; später mit gleicher ID fortsetzen, ohne Abhängigkeit von der vagen Semantik „letzten fortsetzen“.

   • agy: Keine Vorab-ID möglich, nach erstem Lauf aus conversation_id von --output-format stream-json extrahieren und zurückgeben; später mit --conversation <id> fortsetzen.

   • codex: Nach erstem Lauf aus dem thread_id des thread.started-Ereignisses extrahieren und zurückgeben; später mit codex exec resume <id> fortsetzen.

   • copilot: Server generiert eigene UUID → --session-id, die ID wird beim ersten Aufruf zurückgegeben; später mit gleicher ID fortsetzen.

3. Kein Shell-Injection: Alle vier mit shell:false direkt spawnen, der Prompt als einzelnes argv-Element, keinerlei Shell-Sonderzeichen werden interpretiert.

4. Konservative Berichtigungsflagg:

   • Standardmäßig Lese-/Schreibzugriff auf Dateien erlaubt (entsprechend Benutzerwahl), aber Schreib-/Gefährdungsfähigkeiten bleiben segmentiert kontrolliert.

   • pi Standardmäßig kein Projektvertrauen -a (nur mit approve_project öffnen).

   • agy Standardmäßig kein --dangergously-skip-permissions; Workspace-Lese-/Schreibzugriff automatisch erlaubt, Shell-Befehe bleiben gesperrt, außer bei dangergously_allow_all:true.

   • codex Standardmäßig Sandbox read-only (dang-full-access muss explizit angegeben werden).

   • copilot Standardmäßig nur --allow-all-tools (für nicht-interaktiven Modus notwendig), kein --allow-all (enthält pathways + urls), letzteres nur mit dangergously_allow_all:true.

5. Audit: Jeder Aufruf schreibt eine Zeile JSONL in logs/<pi|agy|codex|copilot>-YYYYMMDD.jsonl (Prompt, Session/Thread-ID, Exitcode, Dauer, Nutzung).

Related MCP server: mcacp

Aufgetretene Fallstricke (aus der Praxis)

• stdin muss gesclossen werden: Die CLIs behandeln gepipedes stdin als zusätzlichen Kontext. Node spawn hinterlässt standardmäßig eine offene stdin-Pipe, was die CLI zum Warten auf EOF bringen kann. Lösung: stdio: ['ignore','pipe','pipe'].

• pi-Erweiterungen standardmäßig deaktiviert: Interaktive Erweiterungen (wie auto-annotate/plannotator) hängen im headless-Modus (warten auf eine nie erscheinende UI). Daher standardmäßig --no-extensions, bei Bedarf mit enable_extensions:true wieder aktivieren.

• codex muss --skip-git-repo-check haben: Wenn das cwd kein Git-Repo ist (z. B. C:/Cheerio), führt das Fehlen dieses Flags zu einem sofortigen Fehler und Beenden.

• copilot muss im nicht-interaktiven Modus zwingend --allow-all-tools haben: Die Dokumentation schreibt klar vor, dass der nicht-interaktive Modus dieses Flag benötigt, sonst bleibt er hängen und wartet auf Benutzerbestätigung der Berechtigungen. Die Bridge fügt standardmäßig --allow-all-tools hinzu, aber --allow-all (enthält pathways + urls) wird nur bei dangergously_allow_all:true gesetzt.

• copilot MCP Server laden sehr langsam: Im nicht-interaktiven Modus laden trotzdem alle MCP-Server (playwright, notion, tavily usw.), allein der Start dauert 10–30 Sekunden. Ein zu kurzes Timeout führt dazu, dass der Prozess während der MCP-Ladephase abgebrochen wird.

• copilot Standardmäßiges automatisches Routing kann Kontingentgrenzen treffen: Wenn kein Modell angegeben wird, wählt copilot's hydra-Router automatisch ein Modell aus (z. B. gpt-5-mini). Wenn das Kontingent dieses Modells erschöpft ist, schlägt der Aufruf sofort fehl. Der Aufrufer sollte daher explizit ein Modell angeben.

• Copilot/Codex können im nicht-interaktiven Modus kein Restkontingent abfragen:

  • Copilot: copilot billing / copilot limits sind Hilfethemen, die nur in der interaktiven Modus-Oberfläche nützlich sind. Die nicht-interaktive CLI hat keinen Befehl wie copilot usage. Die Bridge kann nur aus dem model.call_failure-Ereignis das quotaSnapshots erhalten – eine Momentaufnahme des Fehlschlags –, aber nicht aktiv das Restkontingent abfragen.

  • Codex: codex login status zeigt nur die Anmeldemethode (Logged in using ChatGPT), keine Nutzungs-/Kontingentabfrage. codex doctor führt nur Installationsdiagnosen durch. Die Bridge's turn.completed.usage enthält nur den Tokenverbrauch des aktuellen Aufrufs, kein Restkontingent.

• Unternehmens-TLS-Abfangproxy können npm install fehlschlagen lassen: Manche Organisationen verwenden TLS-Prüfproxy (z. B. Zertifikatabfanglösungen von Sicherheitsanbietern), um HTTPS-Datenverkehr mit einem Man-in-the-Middle zu entschlüsseln. Dadurch schlägt die TLS-Überprüfung von Node.js fehl, npm install meldet Fehler wie UNABLE_TO_GET_ISSUER_CERT_LOCALLY oder certificate chain incomplete. Lösung: Setzen Sie die Umgebungsvariable NODE_EXTRA_CA_CERTS auf die vollständige Zertifikatskettendatei des Unternehmens (PEM-Format). Beachten Sie, dass das CA-Zwischenzertifikat (intermediate cert) benötigt wird, nicht nur das Leaf-Zertifikat.

• Unternehmens-IP-Allow-List blockiert CLI-Zugriff (Bridge standardmäßig behandelt): Wenn Ihr Konto zu einem Unternehmensplan (z. B. GitHub Copilot Enterprisse) mit aktivierter IP-Allow-List gehört, kann ask_copilot von der API blockiert werden (Fehlermeldung ähnlich "enterprisse has an IP allow list enabled, and your IP address is not permitted"). Die Grundursache ist oft: Die Umgebung des übergeordneten Prozesses der Bridge enthält Proxy-Einstellungen wie HTTP_PROXY/HTTPS_PROXY, die vom untergeordneten CLI-Prozess geerbt werden. Dadurch werden OAuth-Anfragen über den Unternehmensproxy geleitet, dessen Ausgangs-IP nicht in der Allow-List steht. Die Bridge entfernt ab v0.2.0 standardmäßig autmatisch die Proxy-Umgebungsvariablen (HTTP_PROXY/HTTPS_PROXY/ALL_PROXY einschließlich Groß-/Kleinschreibungsvarianten) aus der Umgebung des untergeordneten Prozesses, sodass die CLI direkt nach außen verbindet, um diese Problem zu umgehen. Wenn Ihre Umgebung umgekehrt ist (Sie müssen den Proxy verwenden, um den Zieldienst zu erreichen), setzen Sie BRIDGE_BYPASS_PROXY=false, um die Vererbung der Proxy-Einstellungen an den untergeordneten Prozess wiedeherzustellen.**

Maschinenübergreifende Insallation (von Null aus)

Die vier Bridgges sind unabhängig. Führen Sie zuaerst npm run doctor aus, um zu sehen, welche CLIs auf diser Maschine verfügbar sind, und registrieren Sie nur die entsprechenden Bridgges in der MCP-Clint-Einstellung, nicht die anderen, die nicht insalliert sind.

Voraussetzungen

• Node.js ≥ 18 (muss node:test und ES-Module unterstützen)

• npm ≥ 9

Schritt 1: Klonen & Insallieren

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

Schritt 2: Prüfen, welche CLIs verfügbar sind

npm run doctor

Es wird eine Tabelle ausgegeben, die anzeigt, ob die 4 CLIs jeweils gefunden wurden, ob sie --version normal ausführen können, und welche Bridges aktiviert werden sollten.

Schritt 3: Insallieren Sie die benötigten CLIs (falls noch nicht geschehen)

Im Folgendem sind die Insallations- und Anmeldeverfahren für jede CLI. Überspringen Sie nicht insallierte, insallieren Sie nicht alle:

pi (earendil-works/pi)

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

Überprüfung: pi --version oder pi --help

agy (Google Antigravity CLI)

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

Überprüfung: agy --version

codex (OpenAI Codex CLI)

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

Überprüfung: codex --version、codex login status

copilot (GitHub Coplot CLI)

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

Überprüfung: copilot --version

Schritt 4: Bridges optional aktivieren

Kopieren Sie die benötigten Bridge-Konfigurationen aus mcp-config.example.json in Ihre MCP-Client-Einstellung (z. B. ~/.mcp.json oder .mcp.json).

Kopieren Sie nicht alle vier. Kopieren Sie nur die Abschnitte, die den auf disem Rechner insallierten und angemeldeten CLIs entsprechen, und passen Sie die Pfade und Umgebungsvariablen an.

Wenn Sie zum Beispliel nur pi und copilot insalliert haben, fügen Sie nur die beiden Abschnitte pi-bridge und copilot-bridge hinzu.

Schritt 5: Üverprüfen Sie, ob die Bridges normal funktionieren

Starten Sie Ihren MCP-Client und senden Sie mit dem entsprechenden Werkzeug einen ganz kleinen Prompt zum Testen:

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

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

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

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

Sie sollten eine pong-Antwort und eine Zeile Bridge-Metadaten erhalten. Bei einer Fehlermeldung prüfen Sie:

• Ist der Pfad zur CLI-Datei (Umgebungsvariable *_*_BRIDGE_ENTRY) korrekt?

• Ist die CLI angemeldet?

• Existiert die cwd-Umgebungsvariable (*_*_BRIDGE_CWD)?

Schnellstart

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

Im MCP-Clint registrieren

Siehe mcp-config.example.json. Dies ist ein Menü – wählen Sie entsprechend der auf diesem Rechner tatsächlich vorhandenem CLIs nur die ensprechenden Abschnitte aus, kopieren Sie sie in Ihre MCP-Client-Einstellung (.mcp.json) und passen Sie die Pfade an. Es müssen nicht alle vier kopiert werden.

Werkzeugschnittstelle

ask_pi

Rückgabe: Endtext von pi + eine Zeile pi-bridge metadata (mit session_id).

ask_agy

Rückgabe: Endantwort von agy + eine Zeile agy-bridge metadata (mit conversation_id, status).

ask_codex

Rückgabe: Endtext von Codex + eine Zeile codex-bridge metadata (mit thread_id, usage).

ask_copilot

Rückgabe: Endantwort von Coplot + eine Zeile coplot-bridge metadata (mit session_id, usage, quota_snapshots).

Kontingentabfrageeinschränkung: Die Copilot CLI hat keinen nicht-interaktiven Befehl, um „Restkontingent“ abzufragen. copilot billing / copilot limits sind nur im interaktiven Modus der Oberfläche nützlich. Die Bridge kann nur melden, „wie viel dieser Aufruf verbraucht hat“ (usage + die aktuellen quotaSnapshots), kann aber kein Restkontingent melden. Ebenso bei Codex: codex login status zeigt nur den Anmeldestatus, keine Nutzungsabfrage.

Umgebungsvariablen

BRIDGE_BYPASS_PROXY: Die Bridge entfernt standardmäßig vor dem Aufruf der untergeordneten CLI aus der Umgebung des Unterprozesses die Proxy-Umgebungsvariablen HTTP_PROXY/HTTPS_PROXY/ALL_PROXY (einschließßlich Groß-/Kleinschreibungsvarianten), um zu verhindern, dass der untergeordnete Prozess von den geerbten Unternehmensproxy-Einstellungen des übergeordneten Prozesses betroffen wird. Nur wenn explizit auf den String "fals" gesetzt ist, wird das Entfernen unterbunden.