af-filesystem-mcp v0.1.3

Un servidor MCP que da a un usuario de AF (Analysis Facility) acceso de exploración/lectura a sus propios archivos en el directorio personal NFS compartido de AF (/home/<unixname>) y en el área de datos de Ceph (/data/<unixname>) — nada más. Diseñado para situarse detrás del broker de credenciales de af-mcp-platform, de modo que una sesión de LLM pueda examinar los resultados de análisis, los registros de condor y los archivos temporales del propio usuario sin que una persona tenga que copiar rutas.

Qué hace

• Listar un directorio (fs_list)

• Leer un archivo, por rango de bytes o de líneas, incluidos el principio y el final (fs_read)

• Stat de una ruta — tamaño, mtime, tipo, permisos (fs_stat)

• Grep de un patrón en archivos dentro de un directorio, con límite de archivos examinados y coincidencias devueltas (fs_grep)

Esa es toda la superficie de herramientas de la v1. Deliberadamente no hay herramienta de escritura, ni de borrado, ni chmod, ni ejecución arbitraria de comandos, ni recorrido completo del árbol (tamaño de directorio, buscador de duplicados). Consulta CLAUDE.md para conocer la justificación del diseño y el plan de la fase 2 (escritura).

Related MCP server: Project Files Read-only MCP

Modelo de seguridad

Cada operación de sistema de archivos para el usuario alice se ejecuta en un subproceso auxiliar de corta duración que suplanta el uid/gid real de alice — el propio proceso del servidor (que se ejecuta como root, con solo CAP_SETUID/CAP_SETGID) nunca lee ni escribe directamente ningún byte de los datos del usuario. Esto significa que el kernel (y, para los directorios personales montados por NFS, el servidor NFS) aplica todas las comprobaciones de permisos contra la identidad real: incluso un error en la lógica de fijación de rutas de este servidor solo puede permitir que alice llegue a lo que el uid real de alice ya podría alcanzar. Consulta CLAUDE.md § "Modelo de seguridad" y src/af_filesystem_mcp/paths.py para conocer la justificación completa del diseño, y maniaclab/af-mcp-platform#188 para el plan de trabajo y las alternativas (rechazadas) sobre las que se eligió este diseño.

Instalación

pip install af-filesystem-mcp

O con pixi:

pixi add af-filesystem-mcp

Requisitos

• Python 3.10+

• Linux (el mecanismo de suplantación es setuid/setgid de POSIX; no hay objetivo de despliegue en Windows/macOS — el modo local stdio funciona bien en cualquier sistema operativo para desarrollo, ya que nunca suplanta identidades)

Inicio rápido (desarrollo local, stdio)

En el modo stdio hay exactamente un llamador (tú), por lo que no se produce ninguna suplantación: el servidor opera directamente con tu propio uid/gid, limitado a tu $HOME y a una raíz de datos configurable:

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

Modo broker (producción, 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

Los tokens bearer son JWT de identidad emitidos por el broker (aud=af-filesystem-mcp) que contienen los reclamos POSIX uid/gid/unixname (el identityProviders[].targetOptions.af-filesystem-mcp.includePosix: true de af-mcp-platform). Requiere el extra broker: pip install af-filesystem-mcp[broker].

Desarrollo

pixi install
pixi run test
pixi run lint

Consulta CLAUDE.md para conocer la arquitectura, el diseño de suplantación/confinamiento de rutas y las convenciones para añadir una nueva herramienta.