af-filesystem-mcp v0.1.3

MCP-сервер, который предоставляет пользователю AF (Analysis Facility) доступ на просмотр и чтение его собственных файлов в общей NFS-домашней директории AF (/home/<unixname>) и в области данных Ceph (/data/<unixname>) — и ничего больше. Предназначен для работы за брокером учётных данных af-mcp-platform, чтобы LLM-сессия могла просматривать результаты анализа пользователя, журналы condor и временные файлы без ручного копирования путей.

Что делает

• Список каталога (fs_list)

• Чтение файла по диапазону байт или строк, включая head/tail (fs_read)

• Статус пути — размер, mtime, тип, права доступа (fs_stat)

• Поиск по шаблону в файлах внутри каталога, с ограничением на количество просканированных файлов и возвращаемых совпадений (fs_grep)

Это весь набор инструментов v1. Здесь намеренно нет инструмента записи, удаления, chmod, произвольного выполнения команд и полного обхода дерева (размер каталога, поиск дубликатов). См. CLAUDE.md с обоснованием дизайна и планом фазы 2 (запись).

Related MCP server: Project Files Read-only MCP

Модель безопасности

Каждая операция с файловой системой для пользователя alice выполняется в короткоживущем вспомогательном подпроцессе, работающем под реальным uid/gid пользователя alice — сам процесс сервера (работающий от root и обладающий только CAP_SETUID/CAP_SETGID) никогда напрямую не читает и не записывает ни байта пользовательских данных. Это означает, что ядро (а для NFS-монтируемых домашних директорий — NFS-сервер) проверяет все права доступа относительно реальной идентичности: даже ошибка в собственной логике привязки путей этого сервера может позволить alice получить доступ только к тому, к чему реальный uid alice уже мог получить доступ. См. CLAUDE.md, раздел «Security model», и src/af_filesystem_mcp/paths.py для полного обоснования дизайна, а также maniaclab/af-mcp-platform#188 для плана работ и (отклонённых) альтернатив, вместо которых был выбран этот дизайн.

Установка

pip install af-filesystem-mcp

Или с помощью pixi:

pixi add af-filesystem-mcp

Требования

• Python 3.10+

• Linux (механизм имперсонации — это POSIX setuid/setgid; целевой платформы Windows/macOS нет — локальный режим stdio работает на любой ОС для разработки, поскольку он никогда не выполняет имперсонацию)

Быстрый старт (локальная разработка, stdio)

В режиме stdio есть ровно один вызывающий (вы), поэтому имперсонация не выполняется — сервер работает напрямую от вашего собственного uid/gid, ограниченный вашим $HOME и настраиваемым корнем данных:

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

Режим брокера (продакшн, 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-токены — это выпущенные брокером JWT идентичности (aud=af-filesystem-mcp) с POSIX-утверждениями uid/gid/unixname (в af-mcp-platform: identityProviders[].targetOptions.af-filesystem-mcp.includePosix: true). Требуется extra broker: pip install af-filesystem-mcp[broker].

Разработка

pixi install
pixi run test
pixi run lint

См. CLAUDE.md об архитектуре, дизайне имперсонации/ограничения путей и соглашениях по добавлению нового инструмента.