WorkspaceGuard MCP

WorkspaceGuard MCP ist ein lokaler, plattformübergreifender MCP-Server, der es ChatGPT oder MCP-Clients ermöglicht, in einem festgelegten Arbeitsbereich zu arbeiten. Das Projekt wurde nach der Untersuchung von FileMCP neu aufgebaut, behält die nützlichen Sicherheitsprinzipien bei und reduziert Teile, die für die erste Version noch nicht benötigt werden.

Wofür wird es verwendet?

• Dateien auflisten, nach Datei oder nach Zeilen lesen, nach Namen und nach Inhalt suchen.

• Dateien atomar schreiben, mit Unterstützung für dry_run und expected_sha256, um das Überschreiben neuerer Änderungen zu vermeiden.

• „Löschen“ durch Verschieben in .workspaceguard/trash, manuell wiederherstellbar.

• Git-Status, Log und Diff lesen, ohne eine Shell zu aktivieren.

• Optional Terminal mit program + args ausführen, ohne Zeichenketten über die Shell zu verketten, und nur ausführbare Dateien aus der Allowlist zulassen.

• Nutzung über stdio oder MCP Streamable HTTP auf 127.0.0.1 mit Token.

• Audit-JSONL schreiben, ohne Dateiinhalte oder vollständige Befehlsargumente zu speichern.

Related MCP server: Kastor

Wichtigste Verbesserungen

Die Anwendung verfügt über eine Electron-Desktop-Oberfläche zum Auswählen des Arbeitsbereichs, zum Auswählen des Modus, zum Auswählen der Befehls-Allowlist, zum Starten/Stoppen des Servers, zum Testen von MCP direkt in der App und zum Verbinden mit Secure MCP Tunnel. In Anlehnung an FileMCP erstellt die App pro Sitzung ein neues Loopback-Token, hält den Server auf 127.0.0.1, verwaltet den Lebenszyklus von tunnel-client und speichert den Runtime-API-Schlüssel mit einem Betriebssystem-Verschlüsselungsmechanismus (Keychain auf macOS, wenn verfügbar). Die Binary tunnel-client wird weiterhin vom Benutzer von OpenAI heruntergeladen; das Projekt bündelt diese Binary nicht. Lokale Runtime und Tunnel rufen keine Codex- oder OpenAI-Modelle/APIs auf: Die App wird mit ChatGPT Web über den Developer-Mode verwendet, daher wird kein Codex-Kontingent verbraucht. Die Konversation unterliegt weiterhin den Limits des verwendeten ChatGPT-Plans.

Anforderungen

• Node.js 20 oder höher (mit Node.js 24 getestet).

• Git, wenn die git_*-Tools verwendet werden.

• Für ChatGPT: ein Arbeitsbereich, der benutzerdefinierte MCP-Apps unterstützt, ein Secure MCP Tunnel und ein Runtime-API-Schlüssel mit entsprechenden Tunnel-Berechtigungen. Siehe OpenAI Secure MCP Tunnel.

Schrittweise Ausführung

Schritt 1 — Abhängigkeiten installieren

cd "/Users/danhpham/Documents/ChatGPT/MCP"
npm install

Keinen API-Schlüssel in .env ablegen oder in Git committen.

Schritt 2 — Gesamtes Projekt testen

npm run verify

Dieser Befehl führt Typecheck, Unit-/Integrationstests, Production-Build und semantischen Smoke-Test über MCP stdio aus.

Schritt 3 — Desktop-Oberfläche ausführen (einfachster Weg)

npm run desktop

Im Fenster WorkspaceGuard:

1. Ordner auswählen… klicken und einen Test-Arbeitsbereich auswählen.

2. Beim ersten Mal Nur lesen beibehalten.

3. MCP starten klicken. Wenn der Status Läuft anzeigt, ist der HTTP-Server auf 127.0.0.1:<Port> bereit.

4. Stoppen klicken, wenn fertig. Das Schließen der Anwendung stoppt auch Server und Tunnel.

Die Oberfläche zeigt oder speichert keine HTTP-Tokens; das Token wird bei jedem Start neu im Main-Process erstellt.

Vollständigen MCP-Test direkt in der Oberfläche

Nachdem der Server Läuft anzeigt, MCP-Test ausführen klicken. Dies ist ein echter MCP-Client im Electron-Main-Process, kein Scheintest über die Oberfläche.

• Bei Nur lesen testet die App den MCP-HTTP-Handshake, die Tool-Erkennung, workspace_info und list_files.

• Bei Lesen und Schreiben testet die App zusätzlich write_file → read_file → trash_path. Sie müssen die Bestätigung anhaken, da eine Testdatei mit zufälligem Namen in .workspaceguard/trash verschoben wird.

• Bei Befehl ausführen bleibt node in der Allowlist angehakt, damit die App zusätzlich run_command mit node --version testet.

Wählen Sie für die letzten beiden Modi einen separaten Testordner. Die Ergebnisse jedes Schritts werden sofort im Testbereich der Oberfläche angezeigt.

Schritt 4 — Kern über Terminal bauen (optional)

npm run build

Der Production-Entry-Point ist:

/Users/danhpham/Documents/ChatGPT/MCP/dist/index.js

Schritt 5 — Arbeitsbereich und Modus über Terminal auswählen (optional)

Am besten mit einem kleinen Testordner beginnen:

mkdir -p /tmp/workspaceguard-demo
printf 'Xin chào MCP\n' > /tmp/workspaceguard-demo/hello.txt

Drei Modi:

• read-only: nur Datei-Lese- und Git-Lese-Tools. Dies ist die Standardeinstellung.

• workspace-write: fügt write_file und trash_path hinzu.

• command: fügt Schreibrechte und run_command hinzu.

Hinweis: Der Server schreibt in allen drei Modi weiterhin interne Audits in .workspaceguard/audit.jsonl. „Read-only“ beschreibt die öffentlichen Tools, nicht die Dateisystem-Sandbox des Server-Prozesses selbst.

Schritt 6A — Über stdio ausführen (empfohlen)

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport stdio \
  --mode read-only

Das Terminal wartet darauf, dass der MCP-Client Requests über stdin sendet. Dies ist korrektes Verhalten, kein Hängen.

Schritt 6B — Schreibrechte aktivieren

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport stdio \
  --mode workspace-write

trash_path hat standardmäßig dry_run=true. Nur wenn der Aufrufer dry_run=false sendet, wird der Pfad in den Papierkorb verschoben.

Schritt 6C — Eigene Terminal-Befehlsausführung erlauben

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport stdio \
  --mode command \
  --allow-command git,node,npm,npx

Beispiel für Tool-Input:

{
  "program": "npm",
  "args": ["test"],
  "cwd": "",
  "timeout_seconds": 120
}

run_command verwendet keine Shell, ist aber keine OS-Sandbox. node, npm, Python oder eine erlaubte ausführbare Datei kann weiterhin außerhalb des Arbeitsbereichs lesen/schreiben, das Netzwerk nutzen und andere Prozesse mit den Rechten des aktuellen Kontos ausführen. Verwenden Sie den Befehlsmodus nur mit vertrauenswürdigen Arbeitsbereichen und Workflows.

Schritt 7 — ChatGPT über die Secure-MCP-Tunnel-Oberfläche verbinden

Erstellen Sie auf der OpenAI Platform einen Secure MCP Tunnel und einen Runtime-API-Schlüssel mit Berechtigung zur Tunnel-Nutzung. Laden Sie das passende tunnel-client für Ihr Betriebssystem herunter. Senden Sie den Runtime-API-Schlüssel nicht an Codex und schreiben Sie ihn nicht in .env, Quellcode oder Git.

In der App, nachdem MCP Läuft anzeigt:

1. Tunnel-ID im Format tunnel_... einfügen.

2. Runtime-API-Schlüssel einfügen. Beim nächsten Mal kann das Feld leer bleiben, um den verschlüsselt gespeicherten Schlüssel zu verwenden.

3. tunnel-client eingeben, wenn die Binary bereits im PATH liegt, oder Datei auswählen… klicken, um die heruntergeladene Binary auszuwählen.

4. Standardprofil beibehalten, Tunnel verbinden klicken und auf die Meldung „bereit für ChatGPT“ warten.

5. Die grüne Zeile „bereit für ChatGPT“ bestätigt, dass der lokale Teil verbunden ist. ChatGPT Web öffnen klicken; diese App öffnet oder ruft Codex nicht auf.

6. Tunnel trennen klicken, wenn nur ChatGPT getrennt werden soll; Stoppen klicken, um Tunnel und MCP-Server zu stoppen.

Die App führt das Äquivalent der Sequenz tunnel-client init --sample sample_mcp_remote_no_auth → doctor --explain → run aus, mit MCP-Endpunkt http://127.0.0.1:<Port>/mcp, lokalem Health-Endpunkt und Token-Header, der über Umgebungsvariablen übergeben wird. Die Tunnel-Profile befinden sich in den App-eigenen Daten, nicht im Arbeitsbereich.

Aktivieren Sie in ChatGPT Web den Developer-Mode/benutzerdefinierte MCP-App gemäß der Workspace-Policy, erstellen Sie eine neue App, wählen Sie die Verbindung Tunnel, wählen Sie den erstellten Tunnel, führen Sie Scan Tools aus und testen Sie dann workspace_info, list_files und read_file, bevor Sie Schreib-Tools aktivieren. Wenn die Tunnel-Auswahl nicht sichtbar ist, prüfen Sie, ob der Arbeitsbereich Lese- und Tunnel-Berechtigungen erhalten hat.

Schritt 8 — HTTP-Loopback (optional)

export WORKSPACE_MCP_TOKEN="$(openssl rand -hex 32)"

node dist/index.js \
  --root /tmp/workspaceguard-demo \
  --transport http \
  --mode read-only \
  --port 7331

Health-Check:

curl --fail http://127.0.0.1:7331/healthz

MCP-Requests müssen den Header senden:

X-Workspace-MCP-Token: <WORKSPACE_MCP_TOKEN>

Der HTTP-Server bindet nur 127.0.0.1, prüft Host, Origin, Token, grundlegendes Framing und Body-Limits. Verwenden Sie stdio, wenn kein spezifischer HTTP-Bedarf besteht.

Verfügbare Tools

Immer verfügbar

• workspace_info

• list_files

• read_file

• read_file_range

• search_filenames

• search_content

• git_status

• git_log

• git_diff

Modus workspace-write oder command

• write_file

• trash_path

Nur Modus command

• run_command

Wiederherstellen von in den Papierkorb verschobenen Dateien

Das Tool gibt trashPath zurück. Wiederherstellung über einen lokalen Befehl, zum Beispiel:

mv "/tmp/workspaceguard-demo/.workspaceguard/trash/<id>/remove-me.txt" \
  "/tmp/workspaceguard-demo/remove-me.txt"

WorkspaceGuard räumt den Papierkorb in dieser Version nicht automatisch auf, um unbeabsichtigtes Löschen von Daten zu vermeiden.

Struktur

src/
├── config.ts                 # CLI/env và mode
├── security/path-policy.ts   # containment + sensitive-path policy
├── services/files.ts         # file/search/write/trash
├── services/git.ts           # Git read-only
├── services/process.ts       # process limits + tree cleanup
├── tools.ts                  # MCP schemas, annotations, audit
├── server.ts                 # stdio + HTTP loopback
├── desktop/                  # Electron main/preload + renderer an toàn
└── index.ts                  # CLI entry
tests/                        # unit, integration, MCP semantic smoke
docs/                         # phân tích source và lộ trình

Zusätzliche Dokumentation

• Analyse des ursprünglichen FileMCP-Projekts

• Projektaufbau-Schritte und Roadmap

• Sicherheitsmodell

Lizenz und Referenzquellen

Das Projekt verwendet die Apache License 2.0. FileMCP verwendet ebenfalls Apache-2.0; siehe NOTICE für die Referenz-Designquellen. Die Binary tunnel-client ist nicht enthalten; der Betreiber lädt die passende Version von der offiziellen OpenAI-Quelle herunter.