DrDexter6000/talking-cli

Filesystem MCP Server

Node.js-Server, der das Model Context Protocol (MCP) für Dateisystemoperationen implementiert.

Funktionen

• Dateien lesen/schreiben
• Verzeichnisse erstellen/auflisten/löschen
• Dateien/Verzeichnisse verschieben
• Dateien suchen
• Dateimetadaten abrufen
• Dynamische Verzeichniszugriffskontrolle über Roots

Verzeichniszugriffskontrolle

Der Server verwendet ein flexibles System zur Zugriffskontrolle auf Verzeichnisse. Verzeichnisse können über Kommandozeilenargumente oder dynamisch über Roots angegeben werden.

Methode 1: Kommandozeilenargumente

Geben Sie beim Starten des Servers erlaubte Verzeichnisse an:

mcp-server-filesystem /pfad/zu/verz1 /pfad/zu/verz2

Methode 2: MCP Roots (Empfohlen)

MCP-Clients, die Roots unterstützen, können die erlaubten Verzeichnisse dynamisch aktualisieren.

Roots, die vom Client an den Server gemeldet werden, ersetzen vollständig alle serverseitig erlaubten Verzeichnisse, sofern sie bereitgestellt werden.

Wichtig: Wenn der Server ohne Kommandozeilenargumente startet UND der Client das Roots-Protokoll nicht unterstützt (oder leere Roots bereitstellt), wird der Server während der Initialisierung einen Fehler auslösen.

Dies ist die empfohlene Methode, da sie Laufzeitaktualisierungen von Verzeichnissen über roots/list_changed-Benachrichtigungen ohne Serverneustart ermöglicht und so eine flexiblere und modernere Integration bietet.

Funktionsweise

Die Verzeichniszugriffskontrolle des Servers folgt diesem Ablauf:

1. Serverstart

   • Server startet mit Verzeichnissen aus Kommandozeilenargumenten (falls vorhanden)
   • Wenn keine Argumente angegeben werden, startet der Server mit leeren erlaubten Verzeichnissen

2. Client-Verbindung und Initialisierung

   • Client verbindet sich und sendet eine initialize-Anfrage mit Fähigkeiten
   • Server prüft, ob der Client das Roots-Protokoll unterstützt (capabilities.roots)

3. Roots-Protokoll-Handling (falls Client Roots unterstützt)

   • Bei der Initialisierung: Server fordert Roots vom Client über roots/list an
   • Client antwortet mit seinen konfigurierten Roots
   • Server ersetzt ALLE erlaubten Verzeichnisse durch die Roots des Clients
   • Bei Laufzeitaktualisierungen: Client kann notifications/roots/list_changed senden
   • Server fordert aktualisierte Roots an und ersetzt erlaubte Verzeichnisse erneut

4. Fallback-Verhalten (falls Client Roots nicht unterstützt)

   • Server verwendet weiterhin nur die Kommandozeilenverzeichnisse
   • Keine dynamischen Aktualisierungen möglich

5. Zugriffskontrolle

   • Alle Dateisystemoperationen sind auf erlaubte Verzeichnisse beschränkt
   • Verwenden Sie das Tool list_allowed_directories, um aktuelle Verzeichnisse anzuzeigen
   • Der Server benötigt mindestens EIN erlaubtes Verzeichnis, um zu funktionieren

Hinweis: Der Server erlaubt nur Operationen innerhalb von Verzeichnissen, die entweder über args oder Roots angegeben wurden.

API

Tools

• read_text_file

  • Vollständigen Inhalt einer Datei als Text lesen
  • Eingaben:
    • path (Zeichenkette)
    • head (Zahl, optional): Erste N Zeilen
    • tail (Zahl, optional): Letzte N Zeilen
  • Behandelt die Datei immer als UTF-8-Text, unabhängig von der Erweiterung
  • head und tail können nicht gleichzeitig angegeben werden

• read_media_file

  • Eine Bild- oder Audiodatei lesen
  • Eingaben:
    • path (Zeichenkette)
  • Streamt die Datei und gibt base64-Daten mit dem entsprechenden MIME-Typ zurück

• read_multiple_files

  • Mehrere Dateien gleichzeitig lesen
  • Eingabe: paths (Zeichenkette[])
  • Fehlgeschlagene Lesevorgänge stoppen nicht die gesamte Operation

• write_file

  • Neue Datei erstellen oder vorhandene überschreiben (Vorsicht geboten)
  • Eingaben:
    • path (Zeichenkette): Dateipfad
    • content (Zeichenkette): Dateiinhalt

• edit_file

  • Gezielte Änderungen mit erweitertem Musterabgleich und Formatierung vornehmen
  • Funktionen:
    • Zeilenbasierter und mehrzeiliger Inhaltsabgleich
    • Leerraum-Normalisierung mit Einrückungserhaltung
    • Mehrere gleichzeitige Änderungen mit korrekter Positionierung
    • Erkennung und Erhaltung des Einrückungsstils
    • Git-ähnliche Diff-Ausgabe mit Kontext
    • Vorschau von Änderungen im Trockenlaufmodus
  • Eingaben:
    • path (Zeichenkette): Zu bearbeitende Datei
    • edits (Array): Liste der Bearbeitungsoperationen
      • oldText (Zeichenkette): Zu suchender Text (kann Teilzeichenfolge sein)
      • newText (Zeichenkette): Text, der ersetzt werden soll
    • dryRun (Boolean): Änderungen in der Vorschau anzeigen, ohne sie anzuwenden (Standard: false)
  • Gibt detaillierte Diff- und Trefferinformationen für Trockenläufe zurück, ansonsten werden Änderungen angewendet
  • Beste Praxis: Vor dem Anwenden von Änderungen immer zuerst dryRun verwenden

• create_directory

  • Neues Verzeichnis erstellen oder sicherstellen, dass es existiert
  • Eingabe: path (Zeichenkette)
  • Erstellt bei Bedarf übergeordnete Verzeichnisse
  • Wird im Stillen erfolgreich ausgeführt, wenn das Verzeichnis bereits existiert

• list_directory

  • Verzeichnisinhalt mit Präfixen [FILE] oder [DIR] auflisten
  • Eingabe: path (Zeichenkette)

• list_directory_with_sizes

  • Verzeichnisinhalt mit Präfixen [FILE] oder [DIR] und Dateigrößen auflisten
  • Eingaben:
    • path (Zeichenkette): Pfad des aufzulistenden Verzeichnisses
    • sortBy (Zeichenkette, optional): Einträge nach "name" oder "size" sortieren (Standard: "name")
  • Gibt detaillierte Auflistung mit Dateigrößen und zusammenfassenden Statistiken zurück
  • Zeigt Gesamtanzahl an Dateien, Verzeichnissen und die kombinierte Größe

• move_file

  • Dateien und Verzeichnisse verschieben oder umbenennen
  • Eingaben:
    • source (Zeichenkette)
    • destination (Zeichenkette)
  • Schlägt fehl, wenn das Ziel bereits existiert

• search_files

  • Rekursiv nach Dateien/Verzeichnissen suchen, die Mustern entsprechen oder nicht entsprechen
  • Eingaben:
    • path (Zeichenkette): Startverzeichnis
    • pattern (Zeichenkette): Suchmuster
    • excludePatterns (Zeichenkette[]): Auszuschließende Muster
  • Glob-ähnlicher Musterabgleich
  • Gibt vollständige Pfade zu den Treffern zurück

• directory_tree

  • Rekursive JSON-Baumstruktur des Verzeichnisinhalts abrufen
  • Eingaben:
    • path (Zeichenkette): Startverzeichnis
    • excludePatterns (Zeichenkette[]): Auszuschließende Muster. Glob-Formate werden unterstützt.
  • Gibt zurück:
    • JSON-Array, bei dem jeder Eintrag Folgendes enthält:
      • name (Zeichenkette): Datei-/Verzeichnisname
      • type ('file'|'directory'): Eintragstyp
      • children (Array): Nur für Verzeichnisse vorhanden
        • Leeres Array für leere Verzeichnisse
        • Für Dateien weggelassen
  • Die Ausgabe ist zur besseren Lesbarkeit mit 2 Leerzeichen eingerückt

• get_file_info

  • Detaillierte Datei-/Verzeichnismetadaten abrufen
  • Eingabe: path (Zeichenkette)
  • Gibt zurück:
    • Größe
    • Erstellungszeitpunkt
    • Änderungszeitpunkt
    • Zugriffszeitpunkt
    • Typ (Datei/Verzeichnis)
    • Berechtigungen

• list_allowed_directories

  • Alle Verzeichnisse auflisten, auf die der Server zugreifen darf
  • Keine Eingabe erforderlich
  • Gibt zurück:
    • Verzeichnisse, die dieser Server lesen/beschreiben kann

Tool-Annotationen (MCP-Hinweise)

Dieser Server setzt MCP-ToolAnnotationen auf jedem Tool, damit Clients:

• schreibgeschützte Tools von schreibfähigen Tools unterscheiden können.
• Verstehen können, welche Schreiboperationen idempotent sind (sicher mit denselben Argumenten zu wiederholen).
• Operationen hervorheben können, die destruktiv sein können (Daten überschreiben oder stark verändern).

Die Zuordnung für Dateisystem-Tools ist:

Tool	readOnlyHint	idempotentHint	destructiveHint	Hinweise
read_text_file	true	–	–	Reiner Lesevorgang
read_media_file	true	–	–	Reiner Lesevorgang
read_multiple_files	true	–	–	Reiner Lesevorgang
list_directory	true	–	–	Reiner Lesevorgang
list_directory_with_sizes	true	–	–	Reiner Lesevorgang
directory_tree	true	–	–	Reiner Lesevorgang
search_files	true	–	–	Reiner Lesevorgang
get_file_info	true	–	–	Reiner Lesevorgang
list_allowed_directories	true	–	–	Reiner Lesevorgang
create_directory	false	true	false	Erneutes Erstellen desselben Verzeichnisses ist ein No‑op
write_file	false	true	true	Überschreibt vorhandene Dateien
edit_file	false	false	true	Erneutes Anwenden von Änderungen kann fehlschlagen oder doppelt anwenden
move_file	false	false	true	Löscht die Quelldatei

Hinweis: idempotentHint und destructiveHint sind nur sinnvoll, wenn readOnlyHint false ist, wie in der MCP-Spezifikation definiert.

Verwendung mit Claude Desktop

Fügen Sie dies zu Ihrer claude_desktop_config.json hinzu:

Hinweis: Sie können dem Server Sandbox-Verzeichnisse bereitstellen, indem Sie sie in /projects einbinden. Das Hinzufügen des Flags ro macht das Verzeichnis für den Server schreibgeschützt.

Docker

Hinweis: Standardmäßig müssen alle Verzeichnisse in /projects eingebunden werden.

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
        "--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
        "--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

NPX

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

Unter Windows verwenden Sie cmd /c, um npx zu starten:

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Desktop",
        "/path/to/other/allowed/dir"
      ]
    }
  }
}

Verwendung mit VS Code

Für eine schnelle Installation klicken Sie auf die Installationsbuttons unten...

Für eine manuelle Installation können Sie den MCP-Server mit einer dieser Methoden konfigurieren:

Methode 1: Benutzerkonfiguration (Empfohlen) Fügen Sie die Konfiguration zu Ihrer MCP-Konfigurationsdatei auf Benutzerebene hinzu. Öffnen Sie die Befehlspalette (Strg + Umschalt + P) und führen Sie MCP: Benutzerkonfiguration öffnen aus. Dadurch wird Ihre Benutzerdatei mcp.json geöffnet, in der Sie die Serverkonfiguration hinzufügen können.

Methode 2: Arbeitsbereichskonfiguration Alternativ können Sie die Konfiguration zu einer Datei namens .vscode/mcp.json in Ihrem Arbeitsbereich hinzufügen. Auf diese Weise können Sie die Konfiguration mit anderen teilen.

Weitere Informationen zur MCP-Konfiguration in VS Code finden Sie in der offiziellen VS Code MCP-Dokumentation.

Sie können dem Server Sandbox-Verzeichnisse bereitstellen, indem Sie sie in /projects einbinden. Das Hinzufügen des Flags ro macht das Verzeichnis für den Server schreibgeschützt.

Docker

Hinweis: Standardmäßig müssen alle Verzeichnisse in /projects eingebunden werden.

{
  "servers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=${workspaceFolder},dst=/projects/workspace",
        "mcp/filesystem",
        "/projects"
      ]
    }
  }
}

NPX

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

Unter Windows verwenden Sie:

{
  "servers": {
    "filesystem": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${workspaceFolder}"
      ]
    }
  }
}

...

[Gekürzt für die Übersetzung]