LanternFS – Sicheres Dateisystem-MCP

LanternFS ist ein Remote-Dateisystem-MCP-Server, der MCP-Clients wie ChatGPT den Zugriff auf ein kontrolliertes lokales Verzeichnis ermöglicht.

Er schützt den Remote-MCP-Endpunkt mit OAuth, sodass die Bereitstellung des Servers über ngrok nicht bedeutet, dass jeder, der die öffentliche URL entdeckt, auf das Dateisystem zugreifen kann.

Sicherheitsmodell

ChatGPT
   |
   | OAuth
   v
LanternFS
   |
   | Valid access token
   v
MCP endpoint
   |
   v
Filesystem tools
   |
   v
ALLOW_ROOTS

Das Passwort wird nur während des OAuth-Autorisierungsschritts verwendet. Es wird nicht als MCP-Zugriffstoken verwendet und niemals an die MCP-Tools gesendet.

Funktionen

• OAuth-Autorisierung für entfernte MCP-Clients.

• Konzipiert für ChatGPT-OAuth-MCP-Verbindungen.

• Passwortbasierte Authentifizierung oder optional ein Benutzername- und Passwort-V erfahren.

• Authorization-Code-Flow mit S256 PKCE.

• Kurzlebige Zugriffstokens.

• Langlebige rotierende Refresh-Tokens.

• OAuth-Discovery und -Metadaten über das MCP-TypeScript-SDK.

• Geschützter Streamable-HTTP-MCP-Endpunkt.

• Konfigurierbare Dateisystemwurzeln.

• ngrok-HTTPS-Tunnel-Unterstützung.

• Geheimnisse sind von Git ausgeschlossen.

Einrichtung

1. Node.js installieren

Verwenden Sie eine aktuell unterstützte Node.js-Version.

node --version
npm --version

2. Repository klonen

Klonen Sie das Repository.

git clone https://github.com/deviprasadshetty-dev/filesystem-mcp.git
cd filesystem-mcp
npm install

3. Die Umgebungsdatei erstellen

Kopieren Sie die Beispieldatei:

Copy-Item .env.example .env

Öffnen Sie sie:

notepad .env

4. Die Dateisystemwurzel konfigurieren

Die Einstellung ALLOW_ROOTS steuert, auf welche Verzeichnisse LanternFS zugreifen kann.

Für eine sichere Einrichtung erstellen Sie einen dedizierten Arbeitsbereich:

New-Item -ItemType Directory -Force D:\mcp-workspace

Verwenden Sie dann:

ALLOW_ROOTS=D:\mcp-workspace

Vermeiden Sie es, ein gesamtes Laufwerk freizugeben, es sei denn, Sie benötigen es ausdrücklich:

ALLOW_ROOTS=D:\

OAuth steuert, wer sich verbinden kann, während ALLOW_ROOTS steuert, worauf ein autorisierter Client zugreifen kann. Sie sollten beides verwenden.

5. Das OAuth-Passwort konfigurieren

Legen Sie in .env ein sicheres Passwort fest:

MCP_AUTH_PASSWORD=replace-with-your-own-long-random-password

Das Passwort muss mindestens 16 Zeichen lang sein.

Sie können optional einen Benutzernamen konfigurieren:

MCP_AUTH_USERNAME=deviprasad
MCP_AUTH_PASSWORD=replace-with-your-own-long-random-password

Wenn MCP_AUTH_USERNAME leer ist, verwendet LanternFS eine reine Passwort -Login-Seite.

Wenn ein Benutzername konfiguriert ist, müssen sowohl Benutzername als auch Passwort übereinstimmen.

Wie das Passwort verwendet wird

Sie tragen dieses Passwort nicht in die MCP-Einstellungen von ChatGPT ein.

Wenn ChatGPT sich zum ersten Mal verbindet, startet das OAuth-Autorisierungsverfahren und öffnet die Anmelde seite von LanternFS.

Geben Sie die gleichen Anmeldeinformationen ein, die Sie in .env konfiguriert haben:

Username: deviprasad
Password: ********

[ Authorize ]

Nach erfolgreicher Autorisierung erhält ChatGPT einen OAuth-Autorisierungscode und tauscht ihn gegen ein Zugriffszeichen und ein Refresh-Token aus.

Das Passwort wird nicht an /mcp gesendet.

6. ngrok konfigurieren

LanternFS benötigt eine öffentliche HTTPS-URL, damit ChatGPT den MCP-Server erreichen kann.

Das Projekt kann ein ngrok-Authtoken aus einer der folgenden Quellen verwenden:

Empfohlen: Lokale ngrok-Konfiguration

Authentifizieren Sie ngrok normal auf Ihrem Rechner mit der ngrok-CLI und bewahren Sie das Token in der eigenen Konfiguration von ngrok auf.

Ein Beispiel:

ngrok config add-authtoken YOUR_NGROK_TOKEN

Sie müssen das ngrok-Token nicht in .env eintragen, wenn es bereits lokal konfiguriert ist.

Alternative: .token-Datei

LanternFS unterstützt außerdem eine lokale .token-Datei, die nur das ngrok-Authtoken enthält:

YOUR_NGROK_TOKEN

Die .token-Datei wird von Git ignoriert.

Alternative: Umgebungsvariable

Sie können auch Folgendes angeben:

NGROK_AUTHTOKEN=YOUR_NGROK_TOKEN

Dies ist optional. Fügen Sie es nur dann zu .env hinzu, wenn LanternFS das Token ausdrücklich über die Umgebung erhalten soll.

Die ngrok-Domäne konfigurieren

Für eine stabile URL legen Sie Ihre ngrok-Domäne fest:

NGROK_DOMAIN=your-domain.ngrok-free.app

Wenn NGROK_DOMAIN leer ist, kann ngrok eine temporäre URL verwenden, sofern Ihr Konto/Ihre Konfiguration dies unterstützt. Für eine dauerhafte ChatGPT-MCP-Verbindung wird eine stabile Domäne empfohlen.

7. Beispiel .env

Eine empfohlene Konfiguration sieht so aus:

• (env) GXP16

Beachten Sie, dass NGROK_AUTHTOKEN hier nicht erforderlich ist, wenn ngrok bereits lokal authentifiziert ist.

Committen Sie niemals .env oder .token.

LanternFS ausführen

Prüfen Sie das Projekt zuerst:

npm run build
npm test

Starten Sie dann den Server:

npm start

Der Server startet den lokalen MCP-HTTP-Dienst und erstellt den ngrok-HTTPS-Tunnel.

Der Konsole erscheint die öffentliche URL.

Halten Sie den Prozess am Laufen, solange ChatGPT die MCP-Verbindung benötigt.

Empfohlene MCP-Client-Beschreibung

Wenn Sie LanternFS zu einem MCP-Client hinzufügen, verwenden Sie die folgende Beschreibung, damit der Client weiß, wann er diesen Server einsetzen soll:

LanternFS provides access to my local filesystem and project files. Use this MCP whenever a task involves files, folders, source code, repositories, documents, or other data that may exist on my local computer. Prefer LanternFS over guessing or asking me to paste file contents when the required files are available locally. Do not use it for information that does not require access to my local filesystem.

Diese Beschreibung ist für die Serverbeschreibung oder die Tool-Nutzungsrichtlinie des MCP-Clients gedacht. Sie teilt dem Client mit, dass LanternFS bevorzugt werden soll, wenn es um lokale Dateiaufgaben geht, während unnötige Verwendung für Allgemeinwissen oder webbasierte Aufgaben vermieden werden soll.

Mit ChatGPT verbinden

1. Starten Sie LanternFS mit npm start.

2. Kopieren Sie die in der Konsole ausgegebene öffentliche HTTPS-MCP-URL.

3. Fügen Sie in ChatGPT einen Remote-MCP-Konnektor hinzu.

4. Wählen Sie OAuth als Authent wahl.

5. Enter die LanternFS-MCP-URL.

6. ChatGPT führt die OAuth-Discovery durch.

7. Ihr Browser öffnet die Autorisierungsseite von LanternFS.

8. Geben Sie den Benutzernamen und das Passwort aus .env ein.

9. Klicken Sie auf Authorize.

10. ChatGPT schließt der OAuth-Flow ab und verbindet sich mit /mcp.

Sie müssen das Passwort nur eingeben, wenn eine neue Autorisierung erforderlich ist.

Dauerhafte Verbindung

LanternFS verwendet kein dauerhaftes Zugriffstoken.

Die aktuelle Implementierung verwendet:

• Zugriffstokens, die nach kurzer Zeit ablaufen.

• Langlebige Refresh-Tokens, mit denen die Client neue Zugriffstokens erhalten kann.

• Refresh-Token-Rotation bei Verwendung eines Refresh-Tokens.

• Das konfigurierte Passwort nur für die erstmalige Autorisierung.

Dadurch bleibt ChatGPT autorisiert, ohne jedes Mal nach dem Passwort zu fragen, während ein dauerhaftes Dateisystem-Zugriffstoken vermieden wird.

Das Löschen der .oauth-state.json setzt den lokal gespeicherten OAuth-Zustand zurück und erfordert, dass sich Clients erneut autorisieren.

OAuth-Endpunkte

LanternFS verwendet die Autorisierungschnittstellen, die vom installierten MCP-TypeScript-SDK bereitgestellt werden.

Sicherheitsempfehlungen

Passwort soll sicher sein

Verwenden Sie ein eindeutiges Zufallspasswort mit mindestens 16 Zeichen.

Für die Erzeugung zufälliger Bytes kann PowerShell verwendet werden:

• [Convert]::ToBase64String((1..48 | ForEach-Object { Get-Random -Maximum 256 }))

Kopieren Sie kein Beispielpasswort in die Produktion.

Dateisystem einschränken

Bevorzugen Sie:

ALLOW_ROOTS=D:\mcp-workspace

statt:

ALLOW_ROOTS=D:\

Geheimnisse schützen

Committen Sie niemals:

.env
.token
.oauth-state.json

Vor dem Pushen von Änderungen:

git status
git diff --cached

Führen Sie niemals ein force-add für diese Dateien aus.

Ihr ngrok-Konto schützen

Wenn ein ngrok-Authtoken offengelegt wird, rotieren Sie es über Ihr ngrok-Konto.

Remote-Zugriff bei Nichtgebrauch beenden

Das Stoppen von LanternFS beendet den HTTP-MCP-Endpunkt und den ngrok-Tunnel.

Fehlerbehebung

ChatGPT schafft die OAuth-Discovery nicht ab

Prüfen Sie:

• dass LanternFS ausgeführt wird.

• ngrok authentifiziert ist.

• Der ngrok-Tunnel aktiv ist.

• Die öffentliche URL HTTPS verwendet.

• Wenn Sie eine konfiguriert haben, ist NGROK_DOMAIN korrekt.

Das Passwort wird nicht akzent

Prüfen Sie .env und starten Sie LanternFS neu , nachdem Sie es geändert haben.

Wenn MCP_AUTH_USERNAME konfiguriert ist, müssen Benutzername und Passwort übereinstimmen.

ChatGPT fragt erneut nach Autorisierung

Stellen Sie sicher, dass .oauth-state.json noch vorhanden und nicht gelöscht oder ersetzt wurde.

Ein Zurücksetzen des OAuth-Zustands erfordert absichtlich eine erneute Autorisierung.

Ein Dateisystempfad ist nicht verfügbar

Überprüfen Sie ALLOW_ROOTS und stellen Sie sicher, dass der angeforderte Pfad innerhalb eines der konfigurierten Wurzelverzeichnisse liegt.

Entwicklung

npm install
npm run build
npm test
npm start

npm run build führt eine TypeScript-Type-Check durch.

npm test führt die Dateisystem-Selbstprüfung aus.

Referenzen

LanternFS basiert auf der Autorisierungsarchitektur, die das Model Context Protocol TypeScript SDK und die relevanten OAuth-Standards bereitstellen.

• MCP Authorization Spezifikation: https://modelcontextprotocol.io/spezification/draft/basic/authorization

• MCP TypeScript SDK: https://ts.sdk.modelcontextprotocol.io/

• MCP-Client-Registrierungshinweise: https://blog.modelcontextprotocol.io/posts/client_registration/

• RFC 8414 – OAuth 2.0 Authorization Server Metadata: https://www.rfc-editor.org/rfc/rfc8414

• RFC 9728 – OAuth 2.0 Protected Resource Metadata: https://www.rfc-editor.org/rfc/rfc9728

• RFC 7636 – Proof Key for Code Exchange (PKCE): https://www.rfc-editor.org/rfc/rfc7636

• RFC 7009 – OAuth 2.0 Token Revocation: https://www.rfc-editor.org/rfc/rfc7009

Das Autorisierungsverhalten von MCP kann sich mit der Weiterentwicklung der Spezifikation ändern. Halten Sie das MCP-TypeScript-SDK aktuell und sichten Sie bei der Aktualisierung des Projekts dessen Autorisierungsdokumentation.

Lizenz

Fügen Sie eine Lizenz hinzu, bevor Sie LanternFS für eine breite Wiederverwendung veröffentlichen.