safe-workspace-mcp

Ein minimaler, sicherheitsfokussierter MCP-Server, der strukturierten Lese-/Schreibzugriff auf genau einen lokalen Arbeitsbereich bietet, mit integrierten lokalen Git-Checkpoints und Rollback.

Entwickelt, damit ein Chat-Modell (z. B. ChatGPT mit MCP-Unterstützung) sicher Dateien in einem Projektordner bearbeiten kann – und sonst nichts.

Windows-Portabler Schnellstart (kein Python, kein Git, kein Node)

1. Laden Sie das Windows-Release-ZIP von Releases herunter und entpacken Sie es.

2. Bereiten Sie ein Arbeitsverzeichnis vor (den einen Ordner, den der Server berühren darf).

3. Besorgen Sie sich eine OpenAI-Secure-MCP-Tunnel-ID (hier erstellen) und einen Runtime-API-Schlüssel (hier erstellen).

4. Führen Sie im entpackten Ordner aus:

.\Start-SafeWorkspaceMCP.ps1 -Workspace "D:\ChatGPT_Workspace\demo" -TunnelId "tunnel_..."

5. Geben Sie den Runtime-API-Schlüssel ein, wenn Sie dazu aufgefordert werden (verdeckte Eingabe, wird nie gespeichert).

6. Lassen Sie das Terminal geöffnet; Ctrl+C beendet alles.

7. Verbinden Sie den vorhandenen Tunnel über den ChatGPT-Entwicklermodus – den konto-seitigen Schritt führen Sie selbst durch.

Der Launcher lädt beim ersten Start den offiziellen OpenAI-Tunnel-Client (festgelegt auf v0.0.11, SHA-256 verifiziert) herunter und speichert ihn unter %LOCALAPPDATA%\SafeWorkspaceMCP\. No admin rights, keine PATH-/Registry-Änderungen. Vollständige Details finden Sie in README-PORTABLE.md` im ZIP.

Präzise Aussage: Portable lokale Bereitstellung ohne erforderliche Python-/Git-/Node-Installation; der Launcher bootstrapt den getesteten OpenAI-Tunnel-Client automatisch. Es ist keine „Null-Konfiguration“ – Sie bringen den Arbeitsbereich, die Tunnel-ID, den Runtime-Schlüssel und das ChatGPT-Konto-Setup mit.

Related MCP server: git-mcp-server

Was es ist

• Ein Prozess = eine Konfiguration = ein fester Arbeitsbereich (beim Start gewählt, zur Laufzeit unveränderlich)

• Strukturiertes CRUD für Textdateien mit atomaren Multi-Datei-Transaktionen

• Optimistische Nebenläufigkeit: Jede Änderung einer vorhandenen Datei erfordert deren aktuellen sha256

• Verwaltete lokale Git-Historie (über Dulwich, nie git.exe): Checkpoints vor/nach Änderungen, Diff, Historie, Wiederherstellung

• Stdio-MCP-Server, insgesamt 9 Tools

Nicht-Ziele (bewusst nicht enthalten)

Keine Shell, kein Terminal, kein Unterprozess, keine Codeausführung, kein Compiler/Testrunner/Paketmanager, keine beliebigen HTTP- oder Netzwerk-Tools, kein entferntes Git, kein Wechsel des Arbeitsbereichs, keine Binär-/Bildbearbeitung, keine Behauptungen über ein OS-Sandboxing.

Wenn eine Fähigkeit unten nicht aufgeführt ist, verfügt dieser Server nicht darüber.

Architektur

ChatGPT / any MCP client
        │
OpenAI Secure MCP Tunnel (account-side, outbound-only)
        │
tunnel-client.exe            <- external deployment layer (official OpenAI binary,
        │                       pinned + SHA-256 verified by the launcher)
        │ MCP over stdio (child process)
        ▼
Safe Workspace MCP           <- this project (9 tools, no network, no exec)
        │
   fixed single workspace
        │
   ┌────┴─────────────┐
   │                   │
structured file CRUD   managed local Git checkpoints

• Websuche / URL-Abruf übernimmt der Chat-Host selbst; dieser Server hat von Natur aus keine Netzwerkfähigkeit.

• Der Tunnel-Client ist eine externe Bereitstellungskomponente, nicht Teil dieses Servers: Der Serverprozess selbst öffnet nie Sockets, und die einzige Netzwerkaktivität des Launchers ist das Herunterladen des festgelegten, prüfsummenverifizierten offiziellen Tunnel-Clients.

Die neun Tools

Alle apply_changes-Operationen validieren zuerst (Pfade, Hashes, Richtlinie, Plankonflikte); wenn etwas fehlschlägt, wird nichts angewendet. Bei einem Fehler während der Ausführung wird alles zurückgerollt.

Installation

Zwei unterstützte Wege:

• Endbenutzer (Windows): Laden Sie das portable Release-ZIP herunter – kein Python/Git/Node erforderlich (siehe Schnellstart oben).

• Entwickler / Linux: Quellcode-Checkout mit Python 3.12+:

git clone https://github.com/Xs-trek/safe-workspace-mcp.git
cd safe-workspace-mcp
py -3.12 -m venv .venv
.venv\Scripts\pip install -e .

Laufzeitabhängigkeiten: mcp==2.0.0 (offizielles SDK), dulwich==1.2.6, Python-Standardbibliothek. Sonst nichts. Die Endbenutzer-Voraussetzungen für die portable Version sind nur: Windows 10/11, PowerShell, Internet für den Tunnel, ein Arbeitsordner, Tunnel-ID + Runtime-API-Schlüssel und ein eigenes ChatGPT-Konto-Setup.

Konfiguration

TOML-Datei, einmal beim Start geladen, danach unveränderlich. Es gibt kein Tool (und keinen Codepfad), das/der die Konfiguration, das Arbeitsverzeichnis oder ein Limit zur Laufzeit ändern kann.

[workspace]
root = "D:/ChatGPT_Workspace/demo"
max_file_bytes = 2097152        # largest file the server will write/track
max_read_bytes = 1048576        # largest read returned / searched per file
max_transaction_bytes = 10485760
max_search_results = 200
excluded = ["node_modules", "build", "dist", ".venv"]  # plus built-ins

[paths]
reject_reparse_points = true    # symlinks/junctions/mounts: always recommended
reject_hardlinks = true
require_same_filesystem = true

[write]
allow_create_file = true
allow_modify_file = true
allow_delete_file = true
allow_move = true
allow_create_directory = true
allow_delete_empty_directory = true
require_expected_hash = true

[git]
mode = "managed"                # only mode in v0.1.0
author_name = "Safe Workspace MCP"
author_email = "safe-workspace-mcp@local"

[search]
include_hidden = false

[server]
transport = "stdio"             # only transport in v0.1.0

Siehe examples/ für Varianten mit minimaler / vorhandener Quelle / großer Quelle.

Verwalteter Arbeitsbereich

Beim ersten Start mit einem leeren oder einfachen Quellverzeichnis (kein .git) führt der Server Folgendes aus:

1. scannt das Verzeichnis (nur reguläre Textdateien werden verfolgt),

2. initialisiert ein verwaltetes Repository unter <root>/.git,

3. erstellt den Checkpoint initial snapshot.

Wenn der Arbeitsbereich bereits .git enthält, schlägt der Start mit EXISTING_GIT_REPOSITORY_NOT_SUPPORTED fehl. Die Übernahme vorhandener Repositories, Worktrees, Submodule und Remotes ist für v0.1.0 nicht vorgesehen.

Bearbeitbar ⇒ Wiederherstellbar: Jede reguläre Datei, die das MCP ändern oder löschen kann, wird im verwalteten Repository verfolgt, sodass sie immer aus einem Checkpoint wiederhergestellt werden kann. Ausgeschlossene Verzeichnisse (node_modules, Build-Artefakte, Virtualenvs, …) sind für jedes Tool unsichtbar – nicht lesbar, nicht beschreibbar, nicht durchsuchbar, nicht checkpointet.

Ausführen

.venv\Scripts\safe-workspace-mcp path\to\config.toml

Der Server spricht MCP über stdio und protokolliert auf stderr. Er weigert sich zu starten, wenn das Arbeitsverzeichnis nicht existiert oder unsicher ist.

Mehrere Projekte

Ein Prozess bedient genau einen Arbeitsbereich. Führen Sie mehrere Prozesse mit mehreren Konfigurationen aus:

safe-workspace-mcp project-a.toml
safe-workspace-mcp project-b.toml

Importieren vorhandener Quelle

Richten Sie workspace.root auf ein vorhandenes Quellverzeichnis ohne .git. Der erste Snapshot übernimmt den aktuellen Zustand als Basislinie; danach wird das Verzeichnis verwaltet. Große generierte Verzeichnisse sollten zu excluded hinzugefügt werden.

Portable Nutzungsszenarien (Windows)

• Erster Start auf einem neuen PC: ZIP entpacken, Arbeitsbereich erstellen/auswählen, Launcher ausführen, Tunnel-Anmeldedaten angeben. Der Launcher lädt den festgelegten Tunnel-Client automatisch herunter und verifiziert ihn.

• Zweiter Start: Derselbe Launcher; der zwischengespeicherte Tunnel-Client wird wiederverwendet – kein erneutes Herunterladen, keine Neuinstallation.

• Projektwechsel: Gleiches Release, anderer -Workspace-Pfad. Jeder MCP-Prozess bedient weiterhin genau einen festen Arbeitsbereich (kein Wechsel zur Laufzeit).

• Offline-Installation (fortgeschritten): Laden Sie das offizielle tunnel-client-<version>-windows-<arch>.zip selbst vorab herunter, verifizieren Sie es anhand der offiziellen SHA256SUMS.txt und zeigen Sie mit -TunnelClientPath auf die entpackte offizielle tunnel-client.exe. Dies ist eine erweiterte Operator-Überschreibung: Sie überspringt die festgelegte SHA-256-Garantie des Launchers (Existenz und --version werden weiterhin geprüft). Für den normalen Gebrauch nicht erforderlich.

Testen mit MCP Inspector

npx @modelcontextprotocol/inspector .venv\Scripts\safe-workspace-mcp -- args/config.toml

(Oder mcp dev aus der MCP-SDK-CLI.) Verifizieren Sie, dass tools/list genau neun Tools anzeigt, die Read-only-Anmerkungen korrekt sind, und testen Sie zuerst read → search → apply_changes → git_diff/git_history/git_restore gegen einen Wegwerf-Arbeitsbereich.

Verbinden von ChatGPT Desktop / ChatGPT Web

ChatGPT erreicht einen lokalen MCP-Server über den Secure MCP Tunnel von OpenAI (Entwicklermodus / Konnektoren). Dieses Projekt ist nur der Stdio-Server plus ein vom Operator betriebener Launcher – es enthält keinen Tunnel-Transport, kein OAuth, keine Speicherung von Anmeldedaten und liest oder schreibt niemals die ChatGPT-/Codex-Konfiguration.

Empfohlener Ablauf:

1. Bestehen Sie die vollständige lokale Testsuite mit einem Wegwerf-Arbeitsbereich (siehe oben).

2. Erstellen Sie einen Secure MCP Tunnel in der OpenAI-Plattform und führen Sie den portablen Launcher (oder selbst tunnel-client run) mit dieser Tunnel-ID aus.

3. Verbinden Sie in ChatGPT den vorhandenen Tunnel als Entwickler-/App-Konnektor, während das Launcher-Terminal läuft.

4. Verwenden Sie zuerst einen dedizierten Test-Arbeitsbereich und stellen Sie dann die Konfiguration auf Ihr echtes Projekt um.

Konfigurieren Sie ChatGPT immer manuell in seiner Benutzeroberfläche.

Sicherheitsübersicht

• Arbeitsbereich-Eingrenzung — nur arbeitsbereichsrelative Pfade; Traversal, absolute/Laufwerks-/UNC-Pfade, reservierte Gerätenamen, ADS-Doppelpunkte, Namen mit abschließendem Punkt/Leerzeichen werden alle abgelehnt; die Eingrenzung ist dateisystembewusst (realpath-basiert), niemals Zeichenketten-Präfix.

• Verknüpfungen — jeder Reparse-Punkt (Symlink, Junction, Mount, unbekanntes Tag) in einer Komponente eines vorhandenen Pfads ⇒ ablehnen. Hart verknüpfte reguläre Dateien (st_nlink > 1) ⇒ ablehnen.

• Interne Isolierung — .git ist für jedes Datei-Tool unzugänglich; es wird nur vom verwalteten Git-Store berührt.

• Atomare Schreibvorgänge — temporäre Schwesterdatei → fsync → validieren → os.replace; ein fehlgeschlagener Schreibvorgang kürzt das Original nie.

• Optimistische Nebenläufigkeit — veraltetes expected_sha256 ⇒ HASH_MISMATCH, die neuere Datei des Benutzers wird nie überschrieben.

• Keine Ausführung / kein Netzwerk — Produktionscode enthält keine Subprozess-/Socket-Nutzung (durch Tests AST-erzwungen, die jedes Modul auf Importe und Aufrufe scannen); dulwichs unbedingter Hook-Ausführungspfad wird beim Import neutralisiert und mit platzierten Hook-Dateien regressionstestet; das verwaltete Repository erhält nie Hooks, Filter oder Remotes.

• Ressourcengrenzen — maximale Datei-/Lese-/Transaktionsbytes und Suchergebnisse; beim Erreichen einer Grenze wird sicher geschlossen (fail closed).

• Prompt-Injection — nicht gelöst, aber eingedämmt: Ein fehlgeleitetes Modell kann nur strukturierte, checkpointete Dateibearbeitungen innerhalb eines Ordners durchführen, die Sie jederzeit zurückrollen können.

Siehe SECURITY.md und THREAT_MODEL.md für die vollständige Analyse und verbleibende Risiken.

Bekannte Einschränkungen (v0.1.0)

• Nur Textdateien (UTF-8); Binärdateien werden abgelehnt.

• Windows ist das primäre Sicherheitsziel; Linux wird unterstützt und CI-getestet.

• Keine gleichzeitige Multi-Client-Koordination über Hash-Prüfungen hinaus (einen Schreiber ausführen).

• Die Checkpoint-Historie wächst unbegrenzt (kein GC in v0.1.0).

• Wiederherstellungen erfolgen auf Dateiebene; ausgeschlossene Verzeichnisse bleiben bei der Wiederherstellung unberührt.

Sicherheitsmeldungen

Bitte eröffnen Sie ein privates Security Advisory (GitHub „Report a vulnerability“) anstelle eines öffentlichen Issues.

Lizenz

Apache-2.0 – siehe LICENSE.