Filesystem-Connector
Der Filesystem-Connector (Dateisystem-Connector) gibt ein oder mehrere lokale Verzeichnisse als MCP-Ressourcen (filesystem://...) und Datei-Werkzeuge (Tools) für den CLYE AI frei.
Der Zugriff ist streng auf die konfigurierten Stammverzeichnisse (Roots) beschränkt, um maximale Sicherheit zu gewährleisten.
Lokale Dateien sicher anbinden
Mit dem Filesystem-Connector kann CLYE AI auf ausgewählte Ordner im lokalen Unternehmensnetzwerk oder auf einem lokalen System zugreifen. Bereitgestellt werden dabei ausschließlich Stammverzeichnisse, die zuvor ausdrücklich konfiguriert und freigegeben wurden.
Je nach Konfiguration erfolgt der Zugriff nur lesend (read-only) oder mit Schreibrechten (full). Typische Einsatzfälle sind die Suche in Projektablagen, die Analyse lokaler Dokumente sowie die unterstützte Verarbeitung oder Ablage von Dateien.
Wie du den Connector technisch einrichtest und welche Optionen dafür verfügbar sind, zeigen die folgenden Abschnitte auf dieser Seite.
Funktionsweise
Der Connector ermöglicht dem Assistenten den sicheren Zugriff auf lokale Verzeichnisse. Dabei wird unterschieden zwischen:
- Hauptpfad (Primary Path): Das Standard-Wurzelverzeichnis. Pfade ohne Präfix beziehen sich auf diesen Ordner.
- Zusätzliche Volumes: Weitere Verzeichnisse können im Docker-Stil im Format
NAME=ABSOLUTER_PFADeingebunden werden. Sie werden alsNAME/...bzw.filesystem://NAME/...dargestellt.
Konfigurationsparameter (Flags)
| Parameter | Standardwert | Beschreibung |
|---|---|---|
--path | Erforderlich (oder Volume) | Absoluter Pfad zum primären Wurzelverzeichnis. Relative Pfade ohne Volume-Präfix beziehen sich hierauf. |
--volume / -v | Zusätzliches Verzeichnis im Format NAME=ABSOLUTER_PFAD. Kann mehrfach angegeben werden, um mehrere Verzeichnisse einzubinden. | |
--permission | read-only | Definiert die Zugriffsstufe: read-only (nur Lesen, blockiert Schreib-/Löschwerkzeuge) oder full (alle Operationen erlaubt). |
--tools | Kommagetrennte Allowlist von erlaubten Werkzeugen (z. B. --tools read_file,list_directory). | |
--change-tracking-file | Pfad zu einer JSON-Datei, um das Werkzeug list_changes zu aktivieren, welches Dateiveränderungen überwacht. |
Verwendung & Beispiele
Um den Connector in CLYE AI zu registrieren, musst du dem Befehl immer den Wrapper ai-hub-cli mcp voranstellen.
Beispiel:
ai-hub-cli mcp ai-hub-cli filesystem-connector --path /pfad
- Linux & macOS
- Windows
Einfache Nutzung (Einzelner Ordner)
ai-hub-cli mcp ai-hub-cli filesystem-connector --path /home/you/project
Schreib-/Lese-Zugriff (Full Permission)
ai-hub-cli mcp ai-hub-cli filesystem-connector --path /path/to/folder --permission full
Eingeschränkte Werkzeuge
ai-hub-cli mcp ai-hub-cli filesystem-connector --path /path/to/folder --tools search_files,read_file,list_directory
Einfache Nutzung (Einzelner Ordner)
ai-hub-cli mcp ai-hub-cli filesystem-connector --path C:\Users\you\project
Schreib-/Lese-Zugriff (Full Permission)
ai-hub-cli mcp ai-hub-cli filesystem-connector --path C:\path\to\folder --permission full
Eingeschränkte Werkzeuge
ai-hub-cli mcp ai-hub-cli filesystem-connector --path C:\path\to\folder --tools search_files,read_file,list_directory
Hauptpfad + Zusätzliche Volumes
Du kannst den Hauptpfad mit einem oder mehreren Volumes kombinieren:
ai-hub-cli mcp ai-hub-cli filesystem-connector \
--path /home/you/monorepo \
-v frontend=/home/you/frontend-app \
-v backend=/home/you/backend-api
Pfade, die mit frontend/ oder backend/ beginnen, greifen auf das jeweilige Volume zu. Unpräfixte Pfade nutzen das Hauptverzeichnis.
Hinweis: Wenn ein Volume-Name mit einem Verzeichnis im Hauptpfad kollidiert, gewinnt das gemountete Volume, und es wird eine Warnung auf stderr ausgegeben.
Bereitgestellte MCP-Werkzeuge (Tools)
Der Connector stellt folgende Tools zur Verfügung:
| Werkzeug | Parameter | Beschreibung |
|---|---|---|
search_files | pattern, content, recursive, mime_type | Sucht nach Dateien, die einem Namensmuster entsprechen oder bestimmten Text enthalten. (Schreibgeschützt) |
read_file | path, base64 | Liest den Inhalt einer Datei (als Text oder Base64-kodiert). (Schreibgeschützt) |
write_file | path, content, base64, append | Schreibt oder hakt Inhalt an eine Datei an. (Nur im Modus full verfügbar) |
delete_file | path, recursive | Löscht eine Datei oder ein Verzeichnis. (Nur im Modus full verfügbar) |
move_file | source, destination | Verschiebt oder benennt eine Datei oder ein Verzeichnis um. (Nur im Modus full verfügbar) |
copy_file | source, destination, recursive | Kopiert eine Datei oder ein Verzeichnis. (Nur im Modus full verfügbar) |
create_directory | path, parents | Erstellt eine neue Verzeichnisstruktur. (Nur im Modus full verfügbar) |
list_directory | path, recursive, include_hidden | Listet Dateien und Ordner innerhalb eines Pfads auf. (Schreibgeschützt) |
get_file_info | path | Ruft Metadaten wie Größe, Änderungsdatum und Typ einer Datei ab. (Schreibgeschützt) |
glob_files | pattern, path, recursive, modified_since | Findet Dateien über ein Glob-Muster, optional gefiltert nach Änderungszeitpunkt. (Schreibgeschützt) |
list_changes | pattern, last_modified | Meldet erstellte, geänderte und gelöschte Dateien seit einem Zeitstempel. Erfordert konfiguriertes Tracking. (Schreibgeschützt) |
Ressourcen & Autovervollständigung
Dateien werden als MCP-Ressourcen über das URI-Template filesystem://{+path} bereitgestellt.
- Aktualisierungen: Sofern vom Client unterstützt, verwendet der Connector
fsnotify, um automatische Benachrichtigungen über hinzugefügte oder geänderte Dateien zu senden. Dies kann über die UmgebungsvariableAI_HUB_FS_RESOURCE_NOTIFICATIONSgesteuert werden. - Autovervollständigung (Autocomplete): Der Client unterstützt die Autovervollständigung von Pfaden bei der Interaktion im Chat.
Sicherheitsarchitektur & Sandboxing
Sicherheit steht beim Filesystem-Connector an oberster Stelle. Folgende Schutzmechanismen sind implementiert:
- Verhinderung von Directory Traversal: Alle Pfade werden vollständig zu ihrer absoluten, kanonischen Form aufgelöst. Der aufgelöste Pfad muss logisch innerhalb des primären Wurzelverzeichnisses oder eines der explizit registrierten Volumes liegen. Versuche, diese Grenzen zu überschreiten (z. B. mittels
..oder Symlinks), werden sofort mit einem Fehler abgelehnt. - Isolation der Verzeichnisse (Cross-Root Isolation): Das Verschieben von Dateien mit
move_fileist über Volume-Grenzen hinweg untersagt (z. B. vom Hauptpfad in ein Volume). Dadurch wird sichergestellt, dass keine unbefugte Datenmigration zwischen isolierten Sandboxes stattfindet. Für solche Aktionen müssen Clients explizit Kopier- und Löschoperationen nacheinander ausführen.