cheerio-mcp-bridges

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

Die vier Bridges sind unabhängig voneinander; es müssen nicht alle vier installiert sein. 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 einzelnes, eingeschränktes Werkzeug (kein generisches run_command) bereit – es kann nur „eine Eingabeaufforderung an diesen Agenten senden“. Das verbleibende Risiko liegt darin, was das zugrundeliegende CLI nach Erhalt der Eingabeaufforderung selbst tun kann. Daher ist die Standardhaltung eher konservativ.

Design-Grundsätze

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

2. Deterministische Sitzungsfortsetzung:

   • pi: Der Server erzeugt selbst eine UUID → --session-id (pi unterstützt „erstellen, falls nicht vorhanden“), gibt die ID beim ersten Aufruf zurück; danach mit derselben ID fortsetzen, ohne die vage Semantik von „Letzte fortsetzen“.

   • agy: Keine vorherige ID-Angabe möglich; beim ersten Durchlauf wird conversation_id aus --output-format stream-json extrahiert und zurückgegeben; danach mit --conversation <id> fortsetzen.

   • codex: Beim ersten Durchlauf wird thread_id aus dem Ereignis thread.started extrahiert und zurückgegeben; danach mit codex exec resume <id> fortsetzen.

   • copilot: Der Server erzeugt selbst eine UUID → --session-id, gibt die ID beim ersten Aufruf zurück; danach mit derselben ID fortsetzen.

3. Keine Shell-Injection: Alle vier verwenden shell:false direkt spawn, die Eingabe wird als einzelnes argv-Element übergeben, sodass keine Shell-Sonderzeichen interpretiert werden.

4. Konservative Berechtigungsflags:

   • Standardmäßig Lese-/Schreibzugriff auf Dateien erlaubt (entsprechend der Benutzerwahl), aber Schreib-/Gefahrenfähigkeiten sind dennoch gestaffelt.

   • pi: Standardmäßig kein Projekttrauen -a (erst mit approve_project aktivieren).

   • agy: Standardmäßig kein --dangerously-skip-permissions; Workspace-Lese-/Schreibzugriff automatisch erlaubt, Shell-Befehle bleiben geschützt, es sei denn dangerously_allow_all:true.

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

   • copilot: Standardmäßig nur --allow-all-tools (für interaktionsfreien Betrieb notwendig), kein --allow-all (einschließlich paths + urls). Letzteres erfordert dangerously_allow_all:true.

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

Stolpersteine (durch Tests gewonnen)

• stdin muss geschlossen werden: CLIs behandeln gepipedes stdin als zusätzlichen Kontext; Node spawn hinterlässt standardmäßig eine offene stdin-Pipe, was das CLI blockiert, bis EOF eintrifft. 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 setzen; bei Bedarf mit enable_extensions:true wieder einschalten.

• 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 Fehler und sofortigem Abbruch.

• copilot im nicht-interaktiven Modus benötigt zwingend --allow-all-tools: Die Dokumentation stellt klar, dass der nicht-interaktive Modus dieses Flag benötigt, da er sonst blockiert und auf Benutzerbestätigung der Berechtigungen wartet. Die Bridge setzt standardmäßig --allow-all-tools, aber --allow-all (einschließlich paths + urls) wird nur bei dangerously_allow_all:true aktiviert.

• copilot MCP-Server lädt langsam: Auch im nicht-interaktiven Modus lädt copilot alle MCP-Server (playwright, notion, tavily usw.). Allein der Start kann 10–30 Sekunden dauern. Ein zu kurzes Timeout führt dazu, dass der Vorgang bereits während der MCP-Ladephase abgebrochen wird.

• Standardmäßiges Auto-Routing von copilot kann Kontingent erschöpfen: Wenn kein Modell angegeben wird, wählt copilots Hydra-Router automatisch ein Modell (z. B. gpt-5-mini). Wenn das Kontingent dieses Modells aufgebraucht ist, schlägt der Vorgang direkt fehl. Empfehlung: Der Aufrufer sollte das Modell explizit angeben.

• Copilot/Codex können nicht interaktionsfrei das verbleibende Gesamtkontingent abfragen:

  • Copilot: copilot billing / copilot limits sind Hilfethemen, die nur in der interaktiven UI nützlich sind. Der nicht-interaktive CLI hat keinen Befehl wie copilot usage. Die Bridge kann nur aus dem Ereignis model.call_failure die quotaSnapshots „zu diesem Zeitpunkt des Fehlschlags“ abrufen, nicht aktiv das verbleibende Kontingent abfragen.

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

• Unternehmensweite TLS-Intercepting-Proxys können npm install zum Scheitern bringen: Einige Organisationen verwenden TLS-Inspektions-Proxys (z. B. Zertifikatsabfanglösungen von Sicherheitsanbietern), um HTTPS-Datenverkehr mit einem Man-in-the-Middle zu entschlüsseln. Dies führt zu TLS-Überprüfungsfehlern in Node.js; npm install meldet Fehler wie UNABLE_TO_GET_ISSUER_CERT_LOCALLY oder certificate chain incomplete. Lösung: Umgebungsvariable NODE_EXTRA_CA_CERTS auf die vollständige Zertifikatskettendatei des Unternehmens (PEM-Format) setzen. Achtung: Es wird das CA-Zwischenzertifikat (intermediate cert) benötigt, nicht nur das Blattzertifikat.

• IP-Allow-List von GitHub Copilot Enterprise kann CLI-Zugriff blockieren: Wenn Ihr GitHub Copilot Enterprise-Konto eine IP-Allow-List aktiviert hat, kann ask_copilot direkt von der API blockiert werden (Fehlermeldung ähnlich „enterprise has an IP allow list enabled, and your IP address is not permitted“). Dies hat nichts mit der Bridge-/MCP-Konfiguration zu tun; wenden Sie sich an den GitHub Enterprise-Administrator, um zu prüfen, ob die aktuelle Ausgangs-IP auf der Whitelist steht oder ob die Nutzung über ein bestimmtes VPN/Unternehmensnetzwerk erfolgen muss.

Installation auf mehreren Maschinen (von Grund auf)

Die vier Bridges sind unabhängig voneinander. Führen Sie zuerst npm run doctor aus, um zu sehen, welche CLIs auf diesem Rechner verfügbar sind, registrieren Sie nur die entsprechende Bridge in der MCP-Client-Konfiguration. Andere, die nicht installiert sind, nicht hinzufügen.

Voraussetzungen

• Node.js ≥ 18 (Unterstützung für node:test und ES-Module erforderlich)

• npm ≥ 9

Schritt 1: Klonen & Installieren

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

Gibt eine Tabelle aus, die anzeigt, ob die 4 CLIs jeweils gefunden wurden, ob --version korrekt ausgeführt werden kann, und welche Bridges empfohlen werden.

Schritt 3: Die benötigten CLIs installieren (falls noch nicht geschehen)

Im Folgenden werden die Installations- und Anmeldeverfahren für die einzelnen CLIs beschrieben. Überspringen Sie nicht installierte CLIs; Sie müssen nicht alle installieren:

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 Copilot CLI)

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

Überprüfung: copilot --version

Schritt 4: Bridge optional aktivieren

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

Nicht alle vier übernehmen. Kopieren Sie nur die Abschnitte, die den auf diesem Rechner installierten und angemeldeten CLIs entsprechen, und passen Sie die Pfade und Umgebungsvariablen an.

Wenn Sie z. B. nur pi und copilot installiert haben, fügen Sie nur die Abschnitte pi-bridge und copilot-bridge hinzu.

Schritt 5: Überprüfen, ob die Bridge ordnungsgemäß funktioniert

Starten Sie Ihren MCP-Client und senden Sie mit dem entsprechenden Werkzeug eine sehr kleine Eingabeaufforderung zum Testen:

• ask_pi: { "prompt": "Antworte nur: pong" }

• ask_agy: { "prompt": "Antworte nur: pong" }

• ask_codex: { "prompt": "Antworte nur: pong" }

• ask_copilot: { "prompt": "Antworte nur: pong" }

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

• Den Pfad zur CLI-Ausführungsdatei (Umgebungsvariable *_BRIDGE_ENTRY)

• Ob das CLI angemeldet ist

• Ob die cwd-Umgebungsvariable (*_BRIDGE_CWD) vorhanden ist

Schnellstart

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

Registrierung im MCP-Client

Siehe mcp-config.example.json. Dies ist ein Menü – wählen Sie je nach den tatsächlich auf Ihrem Rechner vorhandenen CLIs nur die entsprechenden Abschnitte aus und kopieren Sie diese in Ihre MCP-Client-Konfiguration (.mcp.json). Passen Sie die Pfade an. Nicht alle vier müssen übernommen werden.

Werkzeugschnittstellen

ask_pi

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

ask_agy

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

ask_codex

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

ask_copilot

Rückgabe: Letzte Antwort von Copilot + eine Zeile copilot-bridge metadata (mit session_id, usage, quota_snapshots).

Einschränkung bei der Kontingentabfrage: Der Copilot-CLI hat keinen nicht-interaktiven Befehl, um das „verbleibende Gesamtkontingent“ abzufragen. copilot billing / copilot limits sind nur in der interaktiven UI nützlich. Die Bridge kann nur melden, „wie viel dieser Aufruf verbraucht hat“ (usage + aktuelle quotaSnapshots), nicht das verbleibende Gesamtkontingent. Gleiches gilt für Codex: codex login status zeigt nur den Anmeldestatus an, keine Nutzungsabfrage.

Umgebungsvariablen