FolderBridge MCP

简体中文 | English

Eine sicherere, lokal orientierte Brücke zwischen KI-Clients und einem Ordner, den Sie ausdrücklich auswählen.

FolderBridge MCP ist ein Python-MCP-Server ohne Abhängigkeiten plus ein Desktop-Launcher. Er ermöglicht es ChatGPT im Web – oder jedem Client, der lokales stdio-MCP unterstützt – einen begrenzten lokalen Arbeitsbereich zu inspizieren und sorgfältig zu bearbeiten. Er verzichtet bewusst auf einen öffentlichen HTTP-Server, beliebigen Shell-Zugriff, Telemetrie und stille Hintergrunddienste.

[!WICHTIG] Dieses Projekt befindet sich in einer frühen öffentlichen Beta. Es reduziert die Angriffsfläche; es ist keine Betriebssystem-Sandbox. Setzen Sie nur Ordner und Repositorys ein, denen Sie vertrauen.

Warum FolderBridge?

• Ein-Ordner-Grenze: Jeder Serverprozess ist auf einen kanonischen Arbeitsbereich beschränkt.

• Standardmäßig schreibgeschützt: Wechseln Sie im Launcher explizit auf Lesen/Schreiben.

• Konfliktsichere Bearbeitungen: Vorhandene Dateien erfordern den SHA-256-Hash des letzten Lesevorgangs; veraltete Änderungen schlagen fehl, anstatt neuere Arbeit zu überschreiben.

• Keine beliebige Shell: Optionale Aufgaben sind benannt, lokal geprüft und durch einen exakten Konfigurations-Hash genehmigt.

• Kein öffentlicher Listener: Der MCP-Server verwendet nur stdio.

• Keine Telemetrie: FolderBridge selbst stellt keine Netzwerkanfragen.

• Geheimnisbewusster Launcher: Der OpenAI-Runtime-API-Schlüssel bleibt im Speicher und wird entfernt, bevor der lokale MCP-Prozess ihn verwenden kann.

• Anfängerfreundliche Desktop-Oberfläche: Ordnerauswahl, Zugriffsmodus, Tunnel-Einrichtung, Diagnose, Start/Stopp, Prozessüberwachung und geschwärzte Protokolle in einem Fenster.

• Windows-Skalierungsunterstützung: Schriftarten und Fenstergrößen folgen der aktuellen Anzeige-DPI und werden beim Wechsel zwischen Monitoren mit unterschiedlichen Skalierungsfaktoren aktualisiert.

Related MCP server: mcp-readonly-code-server

Schnellstart

Voraussetzungen:

• Python 3.11 oder neuer;

• Windows für die getestete Doppelklick-Launcher-Erfahrung (der stdio-Server ist plattformübergreifend);

• Git ist optional und wird nur für begrenzte status- und diff-Ansichten verwendet.

Windows-Programm – empfohlen

Laden Sie FolderBridge.exe und FolderBridge.exe.sha256 von der neuesten GitHub-Version herunter. Es ist keine Python-Installation erforderlich. Überprüfen Sie die Prüfsumme und doppelklicken Sie dann auf FolderBridge.exe.

Das Programm enthält FolderBridge und seine Python-Laufzeit, aber es bündelt nicht den tunnel-client von OpenAI; laden Sie den offiziellen Client separat von der OpenAI-Version herunter und wählen Sie ihn im Launcher aus, wenn Sie ChatGPT im Web verwenden.

[!HINWEIS] Der aktuelle Community-Build ist nicht code-signiert, daher identifiziert Windows seinen Herausgeber als unbekannt. Wenn Sie einer unsignierten Binärdatei nicht vertrauen, erstellen Sie sie stattdessen aus dem geprüften Quellcode.

Aus dem Quellcode ausführen

Klonen Sie das Repository und starten Sie die GUI:

git clone https://github.com/MoonTzai/folderbridge-mcp.git
cd folderbridge-mcp
python .\folderbridge_launcher.py gui

Wählen Sie einen Arbeitsbereich, behalten Sie Nur lesen für den ersten Lauf bei und verwenden Sie das Statusfenster, um die Einrichtung abzuschließen. Launcher-Einstellungen werden außerhalb des Repositorys gespeichert; der Runtime-API-Schlüssel wird nie gespeichert.

folderbridge_gui.pyw bleibt als reine Quellcode-Komfortdatei für Python-Installationen erhalten, deren .pyw-Zuordnung auf einen Interpreter mit Tkinter verweist. Das eigenständige FolderBridge.exe ist der unterstützte Doppelklick-Einstiegspunkt.

ChatGPT im Web verbinden

ChatGPT kann keine direkte Verbindung zu einem lokalen stdio-Prozess herstellen. FolderBridge verwendet für diesen Pfad den offiziellen Secure MCP Tunnel von OpenAI. Sie benötigen:

• eine tunnel_id aus den OpenAI Platform Tunnel-Einstellungen;

• einen Schlüssel für tunnel-client aus den Runtime API Keys derselben Organisation;

• den offiziellen tunnel-client;

• ChatGPT-Entwicklermodus-Zugriff, der für Ihr Konto oder Ihren Arbeitsbereich geeignet ist.

Klicken Sie auf 网页端一键引导 (Web-Setup-Anleitung) in der oberen rechten Ecke des Launchers für dieselben vier Schritte und Verknüpfungen unten.

1. Laden Sie den offiziellen Windows-x64-Client herunter

1. Öffnen Sie die neueste openai/tunnel-client-Version und erweitern Sie Assets.

2. Laden Sie das vollständige Archiv mit dem Namen tunnel-client-v<version>-windows-amd64.zip herunter. In Versionsdateinamen bedeutet amd64 Windows x64 und ist für die meisten Intel/AMD-PCs korrekt.

3. Optional können Sie SHA256SUMS.txt zur Überprüfung herunterladen. Wählen Sie nicht tunnel-client-runtime-*, windows-arm64, all.zip, Quellcode-Archive oder Lizenzdateien.

4. Entpacken Sie das gesamte ZIP in einen stabilen Ordner; es gibt keinen Installer, und Sie sollten es nicht aus dem Archiv heraus ausführen. Die Anleitung kann %LOCALAPPDATA%\FolderBridge\bin als empfohlenen Speicherort erstellen und öffnen.

5. Kehren Sie zu FolderBridge zurück, klicken Sie auf 选择已解压的 EXE und wählen Sie tunnel-client.exe.

2. Erstellen Sie den Platform Tunnel

Öffnen Sie die OpenAI Platform Tunnel-Einstellungen, klicken Sie auf Create tunnel und verwenden Sie diese aktuellen Auswahlmöglichkeiten:

Nach der Erstellung kopieren Sie die Tunnel-ID, die mit tunnel_ beginnt. Für die Ausführung und Auswahl sind Tunnels Read + Use erforderlich; für die Erstellung oder Bearbeitung ist auch Manage erforderlich. Verknüpfen Sie nur die Organisationen und ChatGPT-Arbeitsbereiche, die Zugriff auf diesen lokalen Arbeitsbereich benötigen.

Erstellen Sie den Schlüssel für tunnel-client unter den Runtime API Keys derselben Platform-Organisation; sein Ersteller benötigt Tunnels Read + Use. Fügen Sie ihn nur in FolderBridge ein, wo er im Prozessspeicher bleibt. Verwenden Sie keinen Admin-API-Schlüssel und fügen Sie den Runtime-Schlüssel nicht in das Authentifizierungsfeld der ChatGPT-App ein.

3. Starten Sie FolderBridge

1. Wählen Sie genau einen Arbeitsbereichsordner aus und behalten Sie für den ersten Lauf Nur lesen (empfohlen) bei.

2. Wählen Sie die entpackte tunnel-client.exe; das Standardprofil folderbridge ist geeignet.

3. Geben Sie dieselbe Tunnel-ID und denselben Runtime-API-Schlüssel ein und lassen Sie erweiterte benannte Aufgaben deaktiviert.

4. Klicken Sie auf Start connection. Der Launcher führt den offiziellen init-, doctor- und run-Ablauf aus. Fahren Sie erst fort, wenn der obere Status 运行中 (Läuft) anzeigt.

4. Erstellen Sie die ChatGPT-Entwicklermodus-App

Öffnen Sie ChatGPT Plugins, klicken Sie auf + und verwenden Sie diese kritischen Auswahlmöglichkeiten:

[!WARNUNG] Lassen Sie das Formular nicht auf der Standardauswahl OAuth und fügen Sie keine https://tunnel-service...-Adresse in die Server-URL ein. FolderBridge implementiert kein Benutzer-OAuth, daher erzeugt diese Konfiguration einen Fehler does not implement OAuth.

Lassen Sie den Launcher laufen, während ChatGPT den Arbeitsbereich verwendet. Das Schließen stoppt den Tunnel-Prozess. Bestätigungen für den Entwicklermodus und die App-Installation auf Kontoebene bleiben in ChatGPT; FolderBridge automatisiert nicht Ihre Browsersitzung oder Sicherheitseinstellungen.

Es ist keine Browsererweiterung erforderlich. FolderBridge lädt absichtlich keine über das Netzwerk gelieferten Binärdateien herunter oder führt sie aus.

Anderen lokalen MCP-Client verbinden

Drucken Sie eine gebrauchsfertige Konfiguration:

python .\folderbridge_launcher.py client-config --workspace C:\path\to\repo --format toml
python .\folderbridge_launcher.py client-config --workspace C:\path\to\repo --format json

Generieren Sie einen schreibgeschützten Befehl:

python .\folderbridge_launcher.py client-config --workspace C:\path\to\repo --format tunnel --read-only

Tools und Bearbeitungsworkflow

Der Standard-Server stellt bereit:

• server_info: meldet den aktiven Arbeitsbereich und die Sicherheitsgrenze;

• workspace: listet, liest, sucht und zeigt begrenzte Git-Status-/Diff-Ausgaben;

• edit_file: erstellt eine UTF-8-Datei oder führt atomare, eindeutige exakte Ersetzungen durch.

Ein sicherer Bearbeitungsablauf ist:

1. Liste oder Suche nach einer Datei;

2. Lesen Sie sie und behalten Sie den zurückgegebenen SHA-256-Hash;

3. Senden Sie eine exakte Ersetzung mit diesem Hash;

4. Prüfen Sie den Git-Diff.

Der Server kann keine Dateien löschen oder verschieben. Absolute Pfade, .., Symlinks, Junctions/Reparse-Punkte, VCS-Interna, gängige Abhängigkeits-/Build-Ordner und anmeldeinformationsähnliche Namen werden abgelehnt.

Optionale benannte Aufgaben

Beliebiger Befehlstext wird über MCP nie akzeptiert. Wenn Sie eine Test-nach-Bearbeitung-Schleife benötigen, erstellen und prüfen Sie eine lokale Aufgabenrichtlinie:

python .\folderbridge_launcher.py init --workspace C:\path\to\repo
# Review C:\path\to\repo\.folderbridge.json
python .\folderbridge_launcher.py approve --workspace C:\path\to\repo

Aktivieren Sie dann genehmigte Aufgaben im Launcher oder fügen Sie --allow-tasks zum generierten Serverbefehl hinzu. Das Modell kann nur einen Aufgabennamen auswählen; es kann keinen Befehl, keine Argumente, keine Umgebungsvariablen oder kein Arbeitsverzeichnis angeben.

[!WARNUNG] Tests, Build-Tools und Paketskripte führen Repository-Code mit Ihren aktuellen OS-Benutzerrechten aus. Verwenden Sie für nicht vertrauenswürdige Repositorys eine Wegwerf-VM oder einen Container, oder lassen Sie die Aufgabenausführung deaktiviert.

Sicherheitsmodell

FolderBridge behandelt MCP-Anfragen, Repository-Text und Tool-Ausgaben als nicht vertrauenswürdige Daten. Die Durchsetzung erfolgt in der Tool-Implementierung und nicht nur in MCP-Annotationen. Die Hauptkontrollen sind:

• kanonische Pfadbegrenzung und Link-Ablehnung;

• begrenzte UTF-8-Lesevorgänge, Suchvorgänge, Git-Ausgaben, Subprozess-Ausgaben und Protokollnachrichten;

• atomare Schreibvorgänge mit einer Voraussetzung für den aktuellen Inhalts-Hash;

• geschützte lokale Richtliniendateien;

• shell=False, feste Argumentarrays, saubere Aufgabenumgebungen und Timeouts;

• kein eingehender Netzwerk-Listener und keine FolderBridge-Telemetrie.

Lesen Sie das vollständige Sicherheitsmodell und die vorgelagerte Design-Forschung. Um eine Sicherheitslücke zu melden, folgen Sie SECURITY.md.

Entwicklung

Es gibt keine Abhängigkeiten von Drittanbietern zur Laufzeit.

python -m unittest discover -s tests -v

Lesen Sie CONTRIBUTING.md, bevor Sie einen Pull-Request öffnen.

Windows-Programm erstellen

Builds verwenden eine festgelegte, nur zur Build-Zeit verwendete PyInstaller-Abhängigkeit. Das veröffentlichte EXE verwendet den Konsolen-Bootloader mit hide-console=hide-early: Ein Doppelklick öffnet nur die GUI, während dasselbe Programm stdio beibehält, wenn Tunnel seinen serve-Unterbefehl startet.

python -m venv .build-venv
.\.build-venv\Scripts\python.exe -m pip install -r requirements-build.txt
.\scripts\build_windows.ps1 -Python .\.build-venv\Scripts\python.exe

Artefakte und eine SHA-256-Datei werden in release\windows-x64 geschrieben.

Lizenz

Lizenziert unter der Apache License 2.0.

FolderBridge MCP ist ein unabhängiges Open-Source-Projekt. Es ist nicht mit OpenAI verbunden, von OpenAI unterstützt oder gesponsert. ChatGPT, OpenAI, MCP und andere Produktnamen gehören ihren jeweiligen Eigentümern.