af-filesystem-mcp v0.1.3

Ein MCP-Server, der einem AF-Benutzer (Analysis Facility) Lese-/Browsen-Zugriff auf seine eigenen Dateien im gemeinsamen NFS-Home-Verzeichnis (/home/<unixname>) und im Ceph-Datenbereich (/data/<unixname>) gewährt – und sonst nichts. Entwickelt, um hinter dem Credential-Broker von af-mcp-platform zu sitzen, damit eine LLM-Sitzung die eigenen Analyseausgaben, Condor-Logs und temporären Dateien eines Benutzers ansehen kann, ohne dass ein Mensch Pfade kopieren muss.

Was es tut

• Listet ein Verzeichnis auf (fs_list)

• Liest eine Datei, nach Bytebereich oder Zeilenbereich, einschließlich Kopf/Ende (fs_read)

• Ermittelt den Status eines Pfads – Größe, Änderungszeit, Typ, Berechtigungen (fs_stat)

• Durchsucht mit Grep nach einem Muster in Dateien unter einem Verzeichnis, begrenzt auf gescannte Dateien und zurückgegebene Treffer (fs_grep)

Das ist die gesamte v1-Tool-Oberfläche. Es gibt bewusst kein Schreib-Tool, kein Löschen, kein chmod, keine beliebige Befehlsausführung und keinen vollständigen Verzeichnisbaum-Durchlauf (Verzeichnisgröße, Duplikatsuche). Siehe CLAUDE.md für die Design-Begründung und den Phase-2-Plan (Schreiben).

Related MCP server: Project Files Read-only MCP

Sicherheitsmodell

Jede Dateisystemoperation für Benutzer alice läuft in einem kurzlebigen Helfer-Subprozess, der alices echte uid/gid annimmt – der Serverprozess selbst (läuft als root, hält nur CAP_SETUID/CAP_SETGID) liest oder schreibt nie direkt ein Byte Benutzerdaten. Das bedeutet, dass der Kernel (und für die NFS-gemounteten Home-Verzeichnisse der NFS-Server) jede Berechtigungsprüfung gegen die echte Identität durchsetzt: Selbst ein Fehler in der eigenen Pfad-Pinning-Logik dieses Servers kann alice nur dorthin gelangen lassen, wohin alices echte uid bereits gelangen könnte. Siehe CLAUDE.md § „Sicherheitsmodell" und src/af_filesystem_mcp/paths.py für die vollständige Design-Begründung sowie maniaclab/af-mcp-platform#188 für den Arbeitsplan und die (abgelehnten) Alternativen, über die dieses Design gewählt wurde.

Installation

pip install af-filesystem-mcp

Oder mit pixi:

pixi add af-filesystem-mcp

Anforderungen

• Python 3.10+

• Linux (der Impersonationsmechanismus ist POSIX setuid/setgid; es gibt kein Windows/macOS-Bereitstellungsziel – der lokale stdio-Modus funktioniert auf jedem Betriebssystem für die Entwicklung, da er nie impersoniert)

Schnellstart (lokale Entwicklung, stdio)

Im stdio-Modus gibt es genau einen Aufrufer (Sie), daher findet keine Impersonation statt – der Server arbeitet direkt mit Ihrer eigenen uid/gid, beschränkt auf Ihr eigenes $HOME und ein konfigurierbares Daten-Root:

af-filesystem-mcp serve --data-root /data

Broker-Modus (Produktion, HTTP)

af-filesystem-mcp serve --transport http \
  --broker-url https://mcp.af.uchicago.edu \
  --broker-audience af-filesystem-mcp \
  --home-root /home --data-root /data

Bearer-Tokens sind vom Broker ausgestellte Identitäts-JWTs (aud=af-filesystem-mcp), die uid/gid/unixname-POSIX-Ansprüche tragen (af-mcp-platforms identityProviders[].targetOptions.af-filesystem-mcp.includePosix: true). Erfordert das broker-Extra: pip install af-filesystem-mcp[broker].

Entwicklung

pixi install
pixi run test
pixi run lint

Siehe CLAUDE.md für Architektur, das Impersonations-/Pfad-Einschränkungs-Design und Konventionen zum Hinzufügen eines neuen Tools.