Project Files Read-only MCP

Ein lokaler, mehrwurzeliger, schreibgeschützter Dateisystem-MCP-Dienst. Er öffnet MCP-Clients ausschließlich die explizit registrierten Projektverzeichnisse und bietet begrenzte Verzeichnisdurchsuchung, Dateinamenssuche, Textlesen sowie Inhaltsgewinnung aus DOCX-, PDF- und XLSX-Dateien.

Der Dienst registriert keine Werkzeuge zum Schreiben, Bearbeiten, Kopieren, Verschieben, Löschen oder zur Befehlsausführung. Er eignet sich, um wenige lokale Projektdateien sicher an MCP-fähige Clients wie ChatGPT zum Lesen weiterzugeben, ohne das gesamte Benutzerverzeichnis oder die Festplatte offenzulegen.

Dies ist ein unabhängiges Community-Projekt, kein offizielles OpenAI-Produkt, und stellt keine Zusicherung von OpenAI hinsichtlich Sicherheit oder Kompatibilität dar.

Die Projektadresse lautet github.com/13030109506/project-files-readonly-mcp.

Funktionen

Der Dienst stellt fest 9 schreibgeschützte Werkzeuge bereit.

Alle Werkzeuge sind als schreibgeschützt und nicht destruktiv markiert. Integrationstests prüfen außerdem, dass die Werkzeugliste keine Schreib-, Lösch-, Verschiebe-, Kopier- oder Befehlsausführungsfähigkeiten enthält.

Related MCP server: Local File Management MCP Server

Sicherheitsgrenzen

• Es werden nur absolute Pfade akzeptiert, die in roots.json registriert sind.

• Lexikalische Pfade und realpath-Ergebnisse werden doppelt auf Grenzen geprüft.

• Relative Pfade, UNC-Pfade, Gerätepfade, Windows-ADS, Symlink- und Junction-Escapes werden abgelehnt.

• .git, .env, Anmeldedatendateien, private Schlüssel, virtuelle Umgebungen und Abhängigkeitsverzeichnisse werden standardmäßig blockiert.

• Text-, Verzeichnis-, Such- und Dokumentantworten haben Größen- und Mengenobergrenzen.

• Vor dem Parsen von DOCX und XLSX werden Archivpfade, Eintragsanzahl, entpacktes Volumen, Kompressionsverhältnis, Verschlüsselung, Makros, ActiveX und eingebettete Objekte geprüft.

• Binärdokumente werden in einem separaten Worker mit Zeit- und Speicherlimits geparst.

• XLSX-Formeln werden nicht ausgeführt, externe Verknüpfungen werden nicht aufgerufen.

Eine ausführlichere Beschreibung der Grenzen findet sich im Sicherheitsmodell. Diese Schutzmaßnahmen verkleinern die MCP-Angriffsfläche, ersetzen aber nicht Windows-Kontoberechtigungen und Hostsicherheit. Führe den Dienst nur auf Computern und mit MCP-Clients aus, denen du vertraust.

Umgebungsanforderungen

• Windows 10 oder Windows 11

• Node.js 22.13–22.x oder Node.js 24+

• npm

• Optional der OpenAI tunnel-client, nur für die Verbindung mit dem ChatGPT Secure MCP Tunnel erforderlich

Schnellstart

Projekt klonen.

git clone https://github.com/13030109506/project-files-readonly-mcp.git
Set-Location .\project-files-readonly-mcp

Abhängigkeiten installieren.

npm ci

Lokale Konfiguration erstellen. roots.json ist in .gitignore aufgenommen und wird nicht an Git übergeben.

Copy-Item .\roots.example.json .\roots.json
notepad .\roots.json

Die Beispielpfade in die konkreten Projektverzeichnisse ändern, die du freigeben möchtest. Nicht die gesamte Festplatte, das Benutzerverzeichnis, Desktop oder Documents konfigurieren.

{
  "roots": [
    {
      "name": "my-project",
      "path": "C:\\Projects\\my-project"
    }
  ]
}

Tests ausführen.

npm test

Lokal starten.

npm start

Der Dienst verwendet STDIO und wird normalerweise von einem MCP-Client oder Tunnel-Prozess gestartet. Wenn nach direktem Start keine interaktive Eingabeaufforderung erscheint, ist das normal.

Über Umgebungsvariablen können auch andere Konfigurationsdateien verwendet werden.

$env:MCP_PROJECT_ROOTS_CONFIG = 'D:\Config\project-files-roots.json'
npm start

Projektwurzelverzeichnis hinzufügen

Zuerst den MCP-Dienst stoppen, dann die folgenden Befehle ausführen.

.\add-project-root.ps1 -Path 'D:\Projects\another-project' -Name 'another-project'
npm test

Das Skript lehnt die gesamte Festplatte, das Benutzerverzeichnis, Desktop und Documents ab. Nach einer Konfigurationsänderung muss MCP oder der Tunnel neu gestartet werden; ein laufender Dienst lädt Wurzelverzeichnisse nicht heiß nach.

Verbindung mit dem ChatGPT Secure MCP Tunnel

Zuerst den offiziellen tunnel-client von der OpenAI Platform Tunnel-Einstellungsseite herunterladen. Dieses Projekt sucht das Programm in der folgenden Reihenfolge.

1. Umgebungsvariable TUNNEL_CLIENT_PATH

2. tunnel-client\tunnel-client.exe im Projekt

3. System-PATH

4. Lokales Versionsverzeichnis unter %USERPROFILE%\Tools\OpenAI\tunnel-client

Nach dem Erstellen des Tunnels ein lokales Profil generieren.

.\configure-tunnel.ps1 -TunnelId 'tunnel_your_id'

Das Skript setzt den lokalen Healthcheck-Port standardmäßig auf 127.0.0.1:8081 und speichert im Profil einen env:CONTROL_PLANE_API_KEY-Verweis, nicht den API-Key selbst.

Der Start im Vordergrund erfolgt wie folgt. Der Runtime-API-Key gelangt über verdeckte Eingabe in die Umgebung des aktuellen Prozesses und wird nach Beenden des Tunnels gelöscht.

.\start-tunnel.ps1

Erstellung, Berechtigungen und ChatGPT-Verbindungsschritte des OpenAI Secure MCP Tunnels richten sich nach der offiziellen Dokumentation.

Versteckter Start nach Windows-Anmeldung

Für langfristige Nutzung kann eine geplante Aufgabe für den aktuellen Windows-Benutzer installiert werden.

.\install-tunnel-autostart.ps1

Der Installer speichert nur den mit DPAPI des aktuellen Benutzers verschlüsselten Runtime-API-Key und schreibt keinen Klartext in Aufgabenparameter, Projektdateien oder Protokolle. Die geplante Aufgabe startet über einen versteckten VBS-Wrapper, führt zuerst doctor aus, startet dann den Tunnel und prüft healthz und readyz.

Status- und Protokollspeicherorte sind wie folgt.

Get-ScheduledTask -TaskName 'OpenAI Project Files Read Only Tunnel'
Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8081/healthz
Invoke-WebRequest -UseBasicParsing http://127.0.0.1:8081/readyz

%LOCALAPPDATA%\OpenAI\ProjectFilesReadOnly\tunnel-client.log

Aufgabe und verschlüsselte Schlüsseldatei entfernen.

.\remove-tunnel-autostart.ps1

Die vollständige Anleitung findet sich im Windows-Tunnel-Betriebshandbuch.

Dateiunterstützung

Dokumentinhalte sind stets nicht vertrauenswürdige Eingaben. MCP-Clients sollten Text aus Dateien nicht als Systemanweisungen behandeln.

Tests

npm test

Die Tests decken folgende Bereiche ab.

• Lesen innerhalb des Wurzelverzeichnisses und Ablehnung außerhalb des Wurzelverzeichnisses

• Ablehnung sensibler Dateien

• Ablehnung relativer Pfade

• Symlink- und Windows-Junction-Grenzen

• Schreibgeschützte Werkzeugliste und annotations

• CSV-, DOCX-, PDF-, XLSX-Lesen

• Ablehnung aktiver Office-Inhalte und anomaler Archive

• Dokumentformat, Seiten, Arbeitsblätter und Antwortobergrenzen

Projektstruktur

server.mjs                 MCP 工具注册与文本读取
path-guard.mjs             路径、白名单和敏感文件边界
document-reader.mjs        安全读取与 Worker 调度
document-worker.mjs        DOCX、PDF、XLSX 内容提取
archive-guard.mjs          Office 压缩包检查
roots.example.json         可提交的配置示例
*-test.mjs                 安全、文档和集成测试
*.ps1 / *.vbs / *.cmd      Windows Tunnel 与计划任务脚本

Verantwortungsvolle Offenlegung

Wenn du Pfad-Escapes, unbefugtes Lesen, Leck sensibler Informationen oder Dokumentparsing-Probleme findest, veröffentliche bitte kein Reproduktionsmaterial mit echten sensiblen Dateien. Das Vorgehen ist in SECURITY.md beschrieben.

Lizenz

Das Projekt verwendet die MIT License.