Agent Gateway

Ein produktionsorientierter lokaler Agent-Gateway, der ChatGPT Web (GPT-5.6 Sol) deterministischen Zugriff auf deine lokale Maschine über das Model Context Protocol (MCP) über Streamable HTTP gewährt.

Der direkte Modus ist die Standardarchitektur. Der Gateway stellt präzise, deterministische MCP-Tools (Dateisystem, Suche, Prozess, Git) bereit, die in vom Betreiber autorisierten Verzeichnissen ausgeführt werden. GPT-5.6 Sol ist der einzige Reasoning-Agent: Er besitzt die Planungs- und Entscheidungsschleife, und der Gateway führt seine Tool-Aufrufe aus — der Gateway ruft niemals ein zweites LLM auf. Der Gateway funktioniert ohne OpenCode-Server und ohne konfiguriertes Modell/Provider.

Optionaler OpenCode-Agent-Modus (standardmäßig deaktiviert) delegiert zusätzlich ganze Aufgaben an einen lokalen OpenCode-Agenten für längere, autonome Arbeiten.

ChatGPT Web (GPT-5.6 Sol)  <-- the reasoning agent
        │
        │  MCP over HTTPS (Streamable HTTP)
        ▼
Cloudflare Quick Tunnel
        │
        ▼
Agent Gateway  http://127.0.0.1:8000/mcp
        │
        ├── Direct mode (default): deterministic tools
        │       workspace_open / file_* / code_search / process_run / git_*
        │       (filesystem, search, process, git — no OpenCode, no LLM)
        │
        └── OpenCode agent mode (optional, ENABLE_OPENCODE_AGENT=true)
                agent_start_task / agent_status / agent_messages / agent_diff
                → OpenCode  http://127.0.0.1:4096  (localhost only)
        │
        ▼
Local system / repositories / tools

Dieses Projekt ersetzt den früheren chatgpt-local-repo-mcp-Prototyp durch eine saubere, getestete, erweiterbare Grundlage. Es ist keine Kopie dieses Prototyps.

Warum ein Gateway

• ChatGPT kann deinen Localhost nicht erreichen. Ein getunnelter MCP-Endpunkt ist die verifizierte Brücke.

• Direkte deterministische Tools schlagen einen zweiten Agenten. Für die meisten Datei-, Such-, Prozess- und Git-Arbeiten sind die Gateway-Primitive exakt, schnell und benötigen kein zusätzliches Modell. GPT-5.6 Sol behält das Reasoning; der Gateway behält die Maschine.

• Du kannst wachsen. OpenCode (oder ein zukünftiger Codex/Claude-Code-Adapter) kann hinter derselben stabilen MCP-Schnittstelle für autonome Aufgaben-Delegation aktiviert werden.

Related MCP server: chatgpt-codex-tools-mcp

Vertrauensgrenzen

Der /mcp-Endpunkt des Gateways ist die einzige öffentliche Schnittstelle. Remote-Aufrufer können nicht:

• auf Verzeichnisse außerhalb der konfigurierten erlaubten Wurzeln zugreifen,

• uneingeschränkte Shell-Befehle ausführen (Befehle sind über AGENT_ENABLE_COMMANDS optional und zeitlich begrenzt),

• Aufgaben an OpenCode delegieren, es sei denn, der Betreiber hat diesen Modus aktiviert,

• ihre eigenen Berechtigungsanfragen automatisch genehmigen (nie implementiert),

• den Gateway ohne das Bearer-Token erreichen, wenn AGENT_GATEWAY_TOKEN gesetzt ist.

Architektur

tools/  (MCP tools)            thin, callable by GPT-5.6 Sol
   │
   ├── tools/direct.py         deterministic primitives (default mode)
   │       workspace_open → workspace_tree / file_read / file_stat /
   │       file_find / code_search / file_write / file_replace /
   │       file_apply_patch / process_run / git_status / git_diff /
   │       git_log / git_show
   │
   ├── workspaces/             WorkspaceManager: opaque ws_ IDs bound to
   │                           allowed roots; every path re-validated
   │
   └── services/delegation.py  OpenCode mode: session lifecycle + registry
           │
           ▼
       executors/base.py       Executor interface (health, sessions, prompts,
           │                   status, messages, diffs, abort, permissions)
           ▼
       executors/opencode/     OpenCodeExecutor → OpenCodeClient → HTTP API

Jedes Modul hängt von der darunterliegenden Schicht ab; die MCP-Tools berühren httpx nie direkt.

MCP-Tools — Direkter Modus (Standard, kein OpenCode, kein Modell)

Die direkten Tools sind verfügbar, sobald der Gateway läuft. Sie arbeiten nur innerhalb von Arbeitsbereichen, die über workspace_open geöffnet wurden (was voraussetzt, dass das Verzeichnis innerhalb von AGENT_ALLOWED_ROOTS liegt).

Alle direkten Tools: validierte Pfade (keine absoluten Pfade, kein .., keine Symlink-Ausbrüche), Größenlimits bei Lesevorgängen, Eintragslimits bei Auflistungen, strikte relative Pfadargumente innerhalb des gebundenen Arbeitsbereichs.

Schleife im direkten Modus (wie ChatGPT sie verwendet)

workspace_open("C:\...\project")
   → ws_abc123
file_read(ws_abc123, "src/main.py")          → current content
file_apply_patch(ws_abc123, "src/main.py", <<<diff>>>)   → patch applied
process_run(ws_abc123, executable="pytest", args=["-q"], timeout_seconds=60) → verification
git_diff(ws_abc123)                           → review the change set

MCP-Tools — OpenCode-Agent-Modus (optional)

Nur mit ENABLE_OPENCODE_AGENT=true aktiviert. Fügt den generischen Delegationslebenszyklus sowie OpenCode-Diagnosen hinzu:

Delegationslebenszyklus

agent_start_task(executor, task, directory)
      │
      ▼  returns session ID immediately (async dispatch)
agent_status(session_id)
      │
      ├── busy / retry   → wait and poll again
      │
      └── idle + completed
            ├── agent_messages(session_id)   → read what the agent did
            ├── agent_diff(session_id)        → review file changes
            ├── agent_continue(session_id, followup)  → keep going
            └── agent_abort(session_id)       → stop runaway work

Langlaufende Agentenarbeiten nutzen die asynchrone Prompt-API von OpenCode (POST /session/{id}/prompt_async). Der Gateway kehrt sofort zurück und hält, während der Agent arbeitet, niemals eine MCP-Anfrage offen. Der Abschluss wird nur gemeldet, wenn die Sitzung im Leerlauf ist und die letzte Assistentenrunde mit finish="stop" endete.

Jeder Vorgang an einer bestehenden Sitzung überprüft erneut, dass sich das tatsächliche Verzeichnis der Sitzung noch innerhalb von AGENT_ALLOWED_ROOTS befindet (fail closed).

Berechtigungsworkflow

Der Gateway genehmigt nie automatisch. Wenn der Agent eine Genehmigung benötigt, erzeugt er eine Berechtigungsanfrage; der Supervisor sieht sie über agent_status / agent_pending_permissions, und ein Mensch entscheidet über agent_reply_permission. Erlaubte Antworten: once, always, reject.

Sicherheitsmodell

• Transportauthentifizierung: Wenn AGENT_GATEWAY_TOKEN gesetzt ist, muss jede Anfrage an /mcp Authorization: Bearer <token> enthalten (Vergleich in konstanter Zeit). Anfragen ohne gültiges Token erhalten 401. Ein Token ist auch erforderlich, wenn MCP_HOST eine Nicht-Loopback-Adresse ist (z. B. 0.0.0.0, LAN-IP), um eine versehentliche öffentliche Offenlegung zu verhindern.

• Verzeichnissicherheit: AGENT_ALLOWED_ROOTS ist eine durch Semikolon getrennte Liste absoluter Pfade. Wenn nicht gesetzt, wird jedes Verzeichnis abgelehnt (fail closed). Jeder Kandidat wird kanonisiert, muss vorhanden sein (für Aufgabenwurzeln), darf keine Dateisystemwurzel sein und muss innerhalb einer erlaubten Wurzel liegen. Traversierung, Symlink-Ausbrüche und Prefix-Spoofing auf Geschwisterebene (sample vs. sample-evil) werden abgelehnt; Vergleiche sind unter Windows ohne Beachtung der Groß-/Kleinschreibung.

• Keine uneingeschränkte Shell standardmäßig: process_run erfordert AGENT_ENABLE_COMMANDS=true und erzwingt ein Timeout (Standard 300 s).

• Begrenzte Ein-/Ausgabe: Lesegröße, Baumeinträge, Suchergebnisse und Prozessausgabe sind begrenzt; große Nutzlasten werden abgeschnitten statt unbegrenzt gestreamt.

• Der OpenCode-Modus ist optional (ENABLE_OPENCODE_AGENT=true); ohne ihn werden die agent_*-Tools nicht registriert und kein Backend kontaktiert.

• Berechtigungen werden im OpenCode-Modus nie automatisch genehmigt.

• Netzwerk: OpenCode bleibt nur auf Localhost beschränkt. Nur /mcp wird getunnelt. PUBLIC_MCP_HOST erlaubt den Tunnelhost, während der DNS-Rebinding-Schutz aktiviert bleibt.

• Geheimnisse: Passwörter und Authorization-Header werden nie protokolliert; die Konfigurationsübersicht maskiert das Passwort; Modellanbieterlisten schließen Schlüssel aus.

Installation

Voraussetzungen: Python 3.11+ (getestet unter 3.14), git. Die OpenCode-CLI wird nur für den optionalen OpenCode-Modus benötigt.

cd C:\Users\dev\Desktop\chatgpt-like\chatgpt-agent-gateway
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

Konfiguration

Kopiere .env.example nach .env und bearbeite es, oder setze die Umgebungsvariablen direkt:

$env:MCP_PORT = "8000"
$env:PUBLIC_MCP_HOST = "your-tunnel.trycloudflare.com"   # optional
$env:AGENT_ALLOWED_ROOTS = "C:\Users\dev\Desktop\sample-repo;C:\Users\dev\Desktop\projects"
$env:AGENT_GATEWAY_TOKEN = "generate-a-long-random-token"   # recommended
$env:AGENT_ENABLE_COMMANDS = "true"   # allow process_run
$env:LOG_LEVEL = "INFO"

Gateway ausführen

agent-gateway
# or
python -m agent_gateway.server

Lokaler MCP-Endpunkt: http://127.0.0.1:8000/mcp

Bereitstellung über Cloudflare

Die Transportsicherheit des Gateways hält den DNS-Rebinding-Schutz aktiviert und erlaubt localhost sowie den Hostnamen, den du in PUBLIC_MCP_HOST festlegst. Starte einen Quick Tunnel, der auf http://127.0.0.1:8000 zeigt:

cloudflared tunnel --url http://127.0.0.1:8000

Übernimm die ausgegebene https://<id>.trycloudflare.com-Adresse, setze sie als PUBLIC_MCP_HOST und starte das Gateway anschließend neu. Setze AGENT_GATEWAY_TOKEN – das Gateway weigert sich, ein tokenloses /mcp öffentlich bereitzustellen, es sei denn, du setzt explizit AGENT_INSECURE_NO_TOKEN_OPT_OUT=true. Sicherheitsprüfungen werden niemals deaktiviert, um den Tunnel zum Laufen zu bringen; der öffentliche Host wird stattdessen explizit auf die Zulassungsliste gesetzt.

Ausführen von OpenCode (optionaler Agentenmodus)

opencode serve --port 4096 --hostname 127.0.0.1

Überprüfen: Invoke-RestMethod http://127.0.0.1:4096/global/health

Testen

pytest                     # default suite: direct mode only (150 passed, 9 skipped)
pytest tests/unit          # unit tests — no services needed
$env:ENABLE_OPENCODE_AGENT = "true"
pytest                     # full suite incl. OpenCode mode (158 passed, 1 skipped)

Die E2E-Suite startet einen echten Gateway-Prozess auf einem temporären Port und steuert ihn über MCP-over-HTTP mit dem exakten Protokoll, das ChatGPT verwendet. Zwei Varianten:

• tests/e2e/test_direct_e2e.py – Direkter Modus ohne OpenCode und ohne Modell: 401 ohne Token, Tool-Liste, Arbeitsbereich → lesen → patchen → schreiben → Prozess → git diff sowie die Ablehnung nicht autorisierter Verzeichnisse. Läuft in der Standard-Suite.

• tests/e2e/test_opencode_e2e.py – OpenCode-Modus (gesteuert über ENABLE_OPENCODE_AGENT=true und einen laufenden Server): schreibgeschützte delegierte Aufgabe (Repository byte-für-byte unverändert verifiziert) plus der vollständige MCP-Protokoll- Ablauf einschließlich Fehlerfällen.

Repository-Struktur

src/agent_gateway/
├── config.py            typed configuration (env-driven, validated)
├── errors.py            gateway error taxonomy
├── logging.py           redacted logging
├── security/
│   ├── paths.py         allowed-roots enforcement
│   └── auth.py          bearer-token middleware (constant-time compare)
├── workspaces/          WorkspaceManager: ws_ IDs, per-workspace validation
├── direct/              deterministic primitives (filesystem, search,
│   │                    process, git) shared by the direct tools
├── executors/
│   ├── base.py          Executor interface
│   └── opencode/        OpenCode client, models, errors, executor
├── services/delegation.py  OpenCode orchestration + session registry
├── tools/               MCP tool registration (direct, gateway, delegation,
│   │                    permissions, opencode)
└── server.py            MCP server assembly + entry point

Zukünftige Executor-Architektur

Füge ein neues Backend hinzu, indem du executors/base.py implementierst, es in executors/__init__.py registrierst und backend-spezifische Diagnosewerkzeuge in tools/ ergänzt. Die generischen agent_*-Werkzeuge und der Delegierungsdienst benötigen keine Änderungen. Es werden keine gefälschten Codex/Claude-Adapter mitgeliefert.

Einschränkungen

• Die OpenCode-Sitzungsregistrierung ist im Arbeitsspeicher; ein Gateway-Neustart vergisst, aus welchen Verzeichnissen Sitzungen stammten (OpenCode selbst speichert Sitzungen über die ID).

• Direktmodus-Arbeitsbereiche (ws_...) laufen ebenfalls nach einem Gateway-Neustart ab; öffne sie erneut mit workspace_open.

• file_apply_patch erfordert exakte Kontextübereinstimmungen; es gibt keine unscharfe Anwendung.

• Die OpenCode-API wird als Obermenge der v1-OpenAPI-Pfade konsumiert; zukünftige Backend-Versionen sollten erneut gegen ihre eigene /doc-Dokumentation geprüft werden.

• Die Antwort always für Berechtigungen wird auf Protokollebene unterstützt; Betreiber möchten sie möglicherweise global deaktivieren, um eine Genehmigung pro Ausführung durchzusetzen.