GrokBot ↔ Hermes Bridge

Ein selbst gehostetes MCP-Gateway und Agent-Plugin-Template, das es Grok Bot ermöglicht, mit Ihrem bestehenden Hermes Agent zu sprechen. Grok Bot bleibt die Chat-Oberfläche; Hermes läuft auf Ihrem Rechner und erzeugt die Antwort.

Das Repository ist betreiberunabhängig: Es enthält keinen Live-Endpunkt, kein Token, keinen Hostnamen, keine private Adresse, keinen Benutzerpfad, keinen Account-Handle und kein Gespräch.

Schnellstart

Linux oder macOS, in einem einzigen überprüfbaren Befehl:

git clone https://github.com/iamsupersocks/grokbot-hermes-bridge.git && cd grokbot-hermes-bridge && ./scripts/install.sh

Bereits geklont:

./scripts/install.sh
python3 scripts/doctor.py

Das Installationsprogramm ist lokal und überprüfbar. Es lädt keine Remote-Shell herunter, verwendet kein sudo, startet das Gateway nicht und schreibt keinen echten öffentlichen Hostnamen, es sei denn, Sie übergeben einen. Nicht-interaktive und Dry-Run-Modi sind zur Überprüfung und für Tests verfügbar:

./scripts/install.sh --dry-run --non-interactive
./scripts/install.sh --non-interactive --endpoint https://mcp.example.com/mcp

Füllen Sie dann die verbleibenden lokalen Pfade in .env.local aus (Modus 600, niemals committen). Der Owner-Code wird auf der Festplatte generiert; fügen Sie ihn nicht in den Chat ein. Siehe docs/TUTORIAL.md für den illustrierten Rundgang. Doctor bleibt absichtlich rot, solange der Beispiel-Hostname oder die Hermes-Pfade noch Platzhalter sind.

Related MCP server: lighthouse-mcp-oauth

So funktioniert es

1. Das Gateway läuft neben Ihrer Hermes-Installation und stellt genau zwei MCP-Tools bereit: hermes_ask und hermes_status.

2. Ein HTTPS-Reverse-Proxy oder Tunnel macht /mcp von Grok Bot aus erreichbar.

3. Grok Bot entdeckt den OAuth-Flow des Gateways. Sie genehmigen die Verbindung in einem Browser mit einem privaten Owner-Code, der nur in der Serverumgebung gespeichert ist.

4. Das Plugin sendet Benutzeranfragen an Hermes und gibt die begrenzte Antwort zurück.

Es gibt keinen SSH-Endpunkt, kein generisches Shell-Tool, keinen Umgebungsdump und keine committeten Anmeldedaten. Der Owner-Code wird nicht als MCP-Bearer-Token akzeptiert.

Anforderungen

• Python 3.11+

• Eine funktionierende hermes-CLI und ein Hermes-Home-Verzeichnis auf der Gateway-Maschine

• Ein öffentlicher HTTPS-Hostname oder Tunnel, der an 127.0.0.1:8099 weiterleitet

• Grok Bot, Codex, Cursor oder ein anderer Streamable-HTTP-MCP-Client mit OAuth

Gateway ausführen

Nach dem Installationsprogramm (oder dem entsprechenden lokalen venv + .env.local-Setup):

. .venv/bin/activate
set -a
. ./.env.local
set +a
python -m hermes_gateway.mcp --host 127.0.0.1 --port 8099

Mindestens muss .env.local enthalten:

HERMES_BRIDGE_SECRET=<64-random-hex-characters>
HERMES_BRIDGE_PUBLIC_BASE_URL=https://mcp.example.com
HERMES_BRIDGE_ALLOWED_HOSTS=localhost,127.0.0.1,mcp.example.com
HERMES_BRIDGE_HERMES_BIN=/absolute/path/to/hermes
HERMES_BRIDGE_HERMES_HOME=/absolute/path/to/hermes-home

GET /health sollte {"status":"ok"} zurückgeben. Setzen Sie HTTPS vor den Dienst; setzen Sie Port 8099 nicht direkt aus. Siehe deploy/ für generische Beispiele.

Plugin konfigurieren

Das Installationsprogramm ruft scripts/configure_plugin.py für Sie auf. Um es zu wiederholen:

python scripts/configure_plugin.py https://mcp.example.com/mcp

Die generierte Konfiguration enthält nur die URL. Fügen Sie keinen Authorization-Header hinzu: Grok Bot verwendet OAuth-Discovery und PKCE, um sein eigenes Zugriffstoken zu erhalten.

Installieren oder packen Sie diesen Ordner als Plugin, starten Sie Grok Bot neu und aktivieren Sie dann den Connector. Die erste Verbindung öffnet die Genehmigungsseite. Geben Sie denselben Owner-Code ein, der in HERMES_BRIDGE_SECRET gespeichert ist.

Composio neben dieser Bridge hinzufügen

Corey Ganims Grok-Bot-Tipp verwendet Composio Connect, um über den nativen Connector-Katalog eines Clients hinauszugehen. Composio beschreibt Connect als einen gehosteten MCP-Endpunkt für über 1000 Apps über 7 Meta-Tools. Es ist nicht buchstäblich jeder MCP-Server und nicht in diesem Repository gebündelt.

Halten Sie die beiden Verbindungen getrennt:

Die .grok-plugin, .cursor-plugin und .codex-plugin-Manifeste hier installieren nur die Hermes-Bridge. Composio-Datenverkehr läuft nicht über Hermes und Composio ersetzt diese Bridge nicht. Siehe das Tutorial für das vollständige Setup-Modell und die Sicherheitsgrenzen.

Grok Bots Einschränkung bei sichtbaren Nachrichten

Grok Bot gibt derzeit vor jedem Tool-Aufruf eine kurze sichtbare Nachricht aus, z. B. „Ich leite das an Hermes weiter.“ Das Plugin kann diesen Host-Level-Schritt nicht ausblenden oder entfernen. Die gebündelte Fähigkeit hält ihn kurz und verhindert, dass Grok Bot Hermes imitiert.

Sicherheitsmodell

• feste Hermes-Ausführungsdatei; keine Shell-Aufrufe

• begrenzte Eingabeaufforderung, Ausgabe, Runden, Timeout, Nutzlast, Rate und Parallelität

• minimale Child-Process-Umgebung

• OAuth-Discovery, dynamische Client-Registrierung, Autorisierungscode + PKCE, signierte Zugriffstokens und Refresh-Tokens

• Owner-Genehmigung erforderlich; Owner-Code funktioniert nie als Bearer-Token

• Host-/Origin-Prüfungen, DNS-Rebinding-Schutz, Localhost-only-Bindung, Log-Redaktion und gefilterte Statusausgabe

• Fail-Closed-Start, wenn Endpunkt, Owner-Code, Hermes-Binärdatei oder Hermes-Home ungültig sind

Der OAuth-Anbieter ist absichtlich Single-Owner. Registrierte Clients werden lokal in einer JSON-Datei mit Modus 0600 gespeichert; ausstehende Genehmigungen und Autorisierungscodes befinden sich im Speicher. Das Rotieren von HERMES_BRIDGE_SECRET macht ausgestellte Tokens ungültig.

Testen und Prüfen

python -m pip install -e '.[dev]'
python -m unittest discover -s tests -v
python src/privacy_scan.py --root .
python scripts/audit_git_history.py
python3 scripts/doctor.py

Lesen Sie außerdem SECURITY.md, bevor Sie den Endpunkt freigeben. Dieses Repository begann mit einer frischen öffentlichen Git-Historie; es erbt nicht die private Implementierungshistorie.

Lizenz

MIT. Siehe LICENSE.