ai-tools/private-proxy-mcp
Watch
2
0
Fork
You've already forked private-proxy-mcp
 0
Code Issues 2 Pull requests 1 Projects Releases 5 Packages 2 Wiki Activity Actions
Page: Architecture
Pages
ADR-Browser-Backend ADR-Browser-Identity-Playwright ADR-MCP-Go-SDK ADR-Rust-Proxy-Tauri ADR-Tunnel-Protocol Architecture CLI Compatibility Configuration Deployment Desktop-Proxy Development Home MVP-Acceptance Releases Security-MCP-Exposure Security-Network-Policy Shared-Key Troubleshooting
9 Architecture
Forgeagent edited this page 2026-07-20 18:52:20 +02:00
Table of contents

Architektur und Datenfluss

Datenfluss

flowchart LR
  subgraph U[Vertrauensbereich: MCP-Aufrufer]
    C[MCP-Client]
  end
  subgraph P[Öffentliche oder vorgeschaltete Infrastruktur]
    E[Reverse Proxy / TLS / MCP-Authentisierung]
    M["mcp-server<br/>Streamable HTTP :9334"]
    L["Reverse Connector<br/>HTTP/1.1 Upgrade :9335"]
  end
  subgraph R[Vertrauensbereich: privates Netz]
    PP["private-proxy<br/>ausgehende Verbindung"]
    X[HTTP-, Media-, Search- und Browser-Executor]
    T[freigegebenes Ziel]
  end

  C -->|MCP POST /mcp| E
  E -->|nur geprüfte Origin/Identität| M
  M -->|binäres Request-Frame| L
  PP -->|TLS + Bearer-Key + Upgrade /connector| L
  L -->|multiplexierter Tunnel| PP
  PP --> X
  X -->|DNS-Auflösung und Policy-Prüfung; HTTP(S)| T
  T -->|begrenzte Antwort| X
  X -->|Response-/Error-Frame| M
  M -->|MCP-Tool-Ergebnis| C

Die Pfeile vom privaten Proxy zum Ziel sind entscheidend: Webrequests werden nicht auf dem MCP-Server, sondern ausschließlich im Prozess private-proxy im privaten Netz ausgeführt. Der öffentliche Prozess übermittelt validierte, begrenzte Aufträge. Der private Prozess prüft Methode, Header, Ziel, jede aufgelöste IP und jeden Redirect erneut gegen seine lokale Policy.

Die Standardports sind:

  • 9334: MCP Streamable HTTP, standardmäßig nur 127.0.0.1, Pfad /mcp.
  • 9335: Reverse Connector, standardmäßig 0.0.0.0, Pfad /connector.

Vertrauensgrenzen

  1. MCP-Client → MCP-Exposure: Der Server implementiert keine eigene Benutzeranmeldung. Loopback ist der sichere Default. Bei externer Exposition muss ein authentisierender TLS-Reverse-Proxy vorgeschaltet sein; exakte Origins sind zusätzlich erforderlich.
  2. MCP-Server → privater Proxy: Der private Proxy baut die Verbindung nach außen auf. TLS schützt Transport und Serveridentität, ein gemeinsamer Bearer-Key authentisiert den Connector. Nur eine Verbindung ist aktiv; eine neue ersetzt die alte mit goaway(replaced).
  3. Privater Proxy → Zielnetz: Dies ist die einzige Grenze, über die Zieltraffic läuft. Nicht öffentliche IP-Bereiche sind standardmäßig gesperrt und nur über explizite CIDRs freischaltbar.

Der Shared Key autorisiert den gesamten Connector und ist kein MCP-Client- Credential. Die nicht geheime private_proxy.identity dient nur der Log-Korrelation und ist keine Autorisierungsgrenze.

Komponenten und Pakete

Pfad Verantwortung
cmd/private-proxy-mcp gemeinsamer Prozesseinstieg
internal/cli Cobra-Befehle, Signale, Prozess-Lifecycle
internal/config Defaults, Datei/Environment/Flags, Validierung
internal/mcpserver MCP Streamable HTTP, Tools, Health-Endpunkte
internal/mcpsecurity Origin- und Trusted-Proxy-Auswertung
internal/connector öffentlicher HTTP/1.1-Upgrade-Endpunkt und Gateway
internal/tunnel binäres Framing und Zustandsmaschine v1.1 (Legacy 1.0)
internal/toolcatalog Proxy-autorisierte MCP-Tool-Schemas für tools_announce
internal/privateproxy ausgehender Connector, TLS, Reconnect, Ausführung
internal/httpexec HTTP-Ausführung, Header-/Profil- und Netzwerk-Policy
internal/mediaexec optionale yt-dlp/ffmpeg-Jobs plus InnerTube-Transcript-Fallback (PATH-Auto-Discovery, optionaler Versions-Pin)
internal/searchexec optionale DuckDuckGo-HTML-Websuche (web_search) über httpexec
internal/browserexec optionale isolierte Chromium-Sessions (chromedp oder Playwright-Sidecar)
internal/observability strukturierte, redigierte Logs und interne Metriken

connector.Gateway übersetzt MCP-Tool-Aufträge in Tunnelrequests. privateproxy.Client demultiplexiert sie und delegiert anhand des Payloads an HTTP-, Media-, Search- oder Browser-Executor. Capability-abhängige MCP-Tools erscheinen nur während eine aktive, authentisierte Verbindung die Capability ankündigt.

Lifecycle und Fehlergrenzen

  • GET /health/live meldet reine Prozess-Liveness.
  • GET /health/ready liefert erst mit aktivem Proxy HTTP 200, sonst 503.
  • Connect-/Authentisierungsfehler verwenden begrenzten exponentiellen Backoff mit Jitter; nach erfolgreichem Upgrade wird er zurückgesetzt.
  • Ping/Pong erkennt tote Verbindungen. SIGINT/SIGTERM löst Goaway, Drain, Abbruch verbleibender Requests und sauberes Schließen aus.
  • Request-/Response-Größen, Dekompressionsgröße, Parallelität, Deadlines und Framegröße sind unabhängig begrenzt. HTTP 4xx/5xx sind normale Tool-Ergebnisse; Policy-, Transport-, Timeout- und Kapazitätsfehler sind Tool-Fehler.