HostGate MCP

Eine Windows-orientierte lokale Kontrollebene für MCP-Clients.

HostGate MCP gewährt einem MCP-Client ausdrücklich autorisierten Zugriff auf ausgewählte lokale Dateien und vertrauenswürdige Befehlszeilenprogramme, mit einem Desktop-Control-Center für Richtlinien, Audit, Rollback, Diagnose und Service-Lebenszyklusverwaltung.

Das Ausführungsmodell ist bewusst enger gefasst als ein allgemeines Terminal: Top-Level-cmd.exe, Windows PowerShell und pwsh werden nicht als vertrauenswürdige Ausführungswerkzeuge bereitgestellt. Zugelassene ausführbare Dateien werden auf feste Pfade aufgelöst und direkt gestartet.

Warum HostGate existiert

Das Lesen lokaler Dateien über MCP ist unkompliziert. Das sichere Bereitstellen von Schreib- und Prozessausführungs-Fähigkeiten für einen entfernten KI-Client ist schwieriger.

HostGate konzentriert sich auf diese Kontrollebene:

• explizite Lese-/Schreib-/Verweigerungs-Roots;

• transaktionale Richtlinienbearbeitung mit Diff-Überprüfung und Rollback;

• Hot-Reload von Berechtigungen ohne Neustart des MCP-Dienstes;

• Zulassungsliste für vertrauenswürdige ausführbare Dateien mit exakter Pfadauflösung;

• geprüfte direkte Prozessausführung ohne allgemeine Shell;

• Windows-Job-Object-Prozessbaum-Eindämmung;

• lokaler Audit-Verlauf, Konfigurationsrevisionen, Richtliniensimulation und Diagnose;

• ein zweisprachiges Windows-Control-Center (zh-CN / en-US);

• Scheduled-Task-Lebenszyklusverwaltung;

• lokale stdio- und OAuth-geschützte Streamable-HTTP-Modi;

• PyInstaller-onedir- und portable onefile-Control-Center-Builds.

Related MCP server: MCP Local Filesystem Server

Sicherheitsmodell

MCP client
    |
    | OAuth / stdio
    v
HostGate MCP
    |
    +-- Filesystem policy
    |     read roots
    |     write roots
    |     deny paths
    |
    +-- Direct execution policy
    |     trusted executable allowlist
    |     exact path resolution
    |     no general-purpose shell
    |     stdin disabled / bounded output
    |     Windows Job Object lifetime
    |
    +-- Control plane
          GUI / audit / revisions
          diagnostics / rollback

Wichtige Grenze

HostGate MCP ist keine Betriebssystem-Dateisystem-Sandbox.

Die Dateisystemrichtlinie steuert die eigenen Dateiwerkzeuge von HostGate und das von exec_command akzeptierte Arbeitsverzeichnis. Sobald eine autorisierte ausführbare Datei gestartet wird, laufen dieses Programm und seine Nachfolgeprozesse mit den Betriebssystemrechten des MCP-Dienstkontos und können auf Ressourcen zugreifen, auf die dieses Konto zugreifen kann.

Die Zulassungsliste für ausführbare Dateien beschränkt den Top-Level-Prozess. Sie sandboxt keine Nachfolgeprozesse, die von einem autorisierten Programm erzeugt werden.

Lesen Sie SECURITY.md und docs/THREAT_MODEL.md, bevor Sie den Dienst über localhost hinaus verfügbar machen.

Control Center

Das Windows-Control-Center bietet sechs Seiten:

• Dienst — Status, PID, Scheduled-Task-Start/Stopp/Neustart.

• Berechtigungen — Lese-/Schreib-/Verweigerungs-Roots durchsuchen und verwalten.

• Ausführung — vertrauenswürdige CLI-Programme verwalten.

• Richtlinie — effektive Berechtigungen simulieren und Konfigurationsrevisionen wiederherstellen.

• Diagnose — Dienst-/Konfigurations-/Audit-/Revisionsstatus validieren und einen geschwärzten Bericht exportieren.

• Audit — aktuelle Dateiänderungs- und Prozessausführungsereignisse überprüfen.

Richtlinienänderungen verwenden einen Transaktionsablauf anstatt TOML direkt zu bearbeiten:

candidate
  -> validate
  -> review diff
  -> stale SHA256 check
  -> save previous revision
  -> atomic replace
  -> hot reload or controlled restart
  -> health check / rollback

Sichere öffentliche Standardwerte

Das Repository startet fail-closed:

• keine Lese-Roots;

• keine Schreib-Roots;

• keine benutzerdefinierten Verweigerungspfade (Kontrollebenen-Pfade werden automatisch verweigert);

• nur das Windows-Dienstprogramm where.exe ist anfänglich vertrauenswürdig;

• OAuth-URLs zeigen auf 127.0.0.1:8000;

• kein echtes Passwort-Hash, keine Token-Datenbank, keine Audit-Daten und keine Benutzerrichtlinie sind enthalten.

Gewähren Sie nur die Verzeichnisse und ausführbaren Dateien, die Sie tatsächlich benötigen, über das Control Center.

Installation

Anforderungen:

• Windows 10/11;

• Python 3.10+;

• uv empfohlen.

Kernserver + GUI-Installation:

cd C:\path\to\hostgate-mcp
uv sync --no-dev
Copy-Item config\secrets.example.toml config\secrets.toml

Die Standardinstallation umfasst Dateisystem-/Text-/CSV-/Mutations-/Ausführungswerkzeuge, OAuth-HTTP-Unterstützung und das Control Center. Formatspezifische Leser sind optional:

uv sync --extra excel      # Excel tools
uv sync --extra pdf        # PDF tools
uv sync --extra image      # image tools
uv sync --extra pytorch    # PyTorch checkpoint tools
uv sync --extra all        # all optional tool families

Für Entwicklung und die vollständige Testsuite:

uv sync --all-extras
.venv\Scripts\python.exe -m pytest -q

Legen Sie einen echten Argon2id-Besitzer-Passwort-Hash in config\secrets.toml fest und konfigurieren Sie dann Roots und vertrauenswürdige ausführbare Dateien, bevor Sie den HTTP-Dienst verfügbar machen.

Führen Sie das Control Center aus:

scripts\start_control_center.ps1

Installieren Sie die Windows-Scheduled-Task, wenn Sie bereit sind, HostGate bei der Anmeldung auszuführen:

scripts\install_server_task.ps1

Windows-Control-Center-Builds

Empfohlener onedir-Build:

scripts\build_control_center.ps1

Portabler onefile-Build:

scripts\build_control_center.ps1 -OneFile

Build-Artefakte sind absichtlich von der Quellcodeverwaltung ausgeschlossen.

Optionale Tool-Familien

Mit jedem installierten optionalen Extra stellt HostGate den vollständigen Leser-Satz bereit, der für die private 1.4-Linie entwickelt wurde, einschließlich Excel-, PDF-, Bild- und PyTorch-Inspektionswerkzeugen. Ohne ein Extra wird diese Tool-Familie einfach nicht registriert; der Rest des MCP-Servers bleibt nutzbar.

Dadurch bleibt die Standardinstallation auf den RWX-/Kontrollebenen-Anwendungsfall fokussiert, anstatt jeden Benutzer zu zwingen, große wissenschaftliche Abhängigkeiten wie PyTorch zu installieren.

Projektstatus

Aktuelle öffentliche Vorbereitungsversion: 1.4.0rc1.

Das öffentliche Repository wird aus einem sauberen Export ohne Historie der getesteten privaten Entwicklungslinie erstellt. Private Git-Historie, Produktionsrichtlinie, OAuth-Zustand, Protokolle, Geheimnisse und Build-Ausgabe sind absichtlich ausgeschlossen.

Nicht-Ziele

HostGate versucht nicht, Folgendes zu werden:

• ein vollständiger Terminal-Emulator;

• ein Shell-Orchestrierungs-Framework;

• ein MCP-Marktplatz oder -Router;

• ein plattformübergreifender Coding-Agent-Ersatz;

• eine vollständige Betriebssystem-Sandbox.

Neue Fähigkeiten sollten nur hinzugefügt werden, wenn sie ein nachgewiesenes betriebliches oder sicherheitsrelevantes Problem lösen.

Dokumentation

• SECURITY.md — Sicherheitsgrenzen und Meldung von Schwachstellen.

• docs/THREAT_MODEL.md — Annahmen, Schutzgüter und nicht abgedeckte Garantien.

• docs/control_center.md — Control-Center-Architektur und Richtlinientransaktionen.

• docs/architecture.md — Serverarchitektur.

• docs/tools.md — MCP-Tool-Referenz.

• CHANGELOG.md — Versionshistorie.

Lizenz

Lizenziert unter der Apache License 2.0. Siehe NOTICE für Zuschreibungsinformationen.