af-filesystem-mcp v0.1.2

An MCP server that gives an AF (Analysis Facility) user browse/read access to their own files on the AF's shared NFS home (/home/<unixname>) and Ceph data area (/data/<unixname>) — nothing more. Designed to sit behind af-mcp-platform's credential broker so an LLM session can look at a user's own analysis outputs, condor logs, and scratch files without a human copying paths around.

What it does

• List a directory (fs_list)
• Read a file, by byte range or line range, including head/tail (fs_read)
• Stat a path — size, mtime, type, permissions (fs_stat)
• Grep for a pattern across files under a directory, capped in files scanned and matches returned (fs_grep)

That is the entire v1 tool surface. There is deliberately no write tool, no delete, no chmod, no arbitrary command execution, and no full-tree walk (directory-size, duplicate-finder). See CLAUDE.md for the design rationale and phase-2 (write) plan.

Security model

Every filesystem operation for user alice runs in a short-lived helper subprocess impersonating alice's real uid/gid — the server process itself (running as root, holding only CAP_SETUID/CAP_SETGID) never reads or writes a byte of user data directly. This means the kernel (and, for the NFS-mounted homes, the NFS server) enforces every permission check against the real identity: even a bug in this server's own path-pinning logic can only let alice reach what alice's real uid could already reach. See CLAUDE.md § "Security model" and src/af_filesystem_mcp/paths.py for the full design rationale, and maniaclab/af-mcp-platform#188 for the workplan and the (rejected) alternatives this design was chosen over.

Installation

pip install af-filesystem-mcp

Or with pixi:

pixi add af-filesystem-mcp

Requirements

• Python 3.10+
• Linux (the impersonation mechanism is POSIX setuid/setgid; there is no Windows/macOS deployment target — local stdio mode runs fine on any OS for development, since it never impersonates)

Quick start (local development, stdio)

In stdio mode there is exactly one caller (you), so no impersonation happens — the server operates directly as your own uid/gid, confined to your own $HOME and a configurable data root:

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

Broker mode (production, 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

Bearers are broker-issued identity JWTs (aud=af-filesystem-mcp) carrying uid/gid/unixname POSIX claims (af-mcp-platform's identityProviders[].targetOptions.af-filesystem-mcp.includePosix: true). Requires the broker extra: pip install af-filesystem-mcp[broker].

Development

pixi install
pixi run test
pixi run lint

See CLAUDE.md for architecture, the impersonation/path-confinement design, and conventions for adding a new tool.