af-filesystem-mcp v0.1.3

一个 MCP 服务器，让 AF（Analysis Facility，即分析设施）用户能够浏览并读取自己位于 AF 共享 NFS 主目录（/home/<unixname>）和 Ceph 数据区（/data/<unixname>）中的文件——仅此而已。它被设计为部署在 af-mcp-platform 的凭证代理之后，这样 LLM 会话就能查看用户自己的分析输出、condor 日志和临时文件，而无需人工来回复制路径。

它能做什么

• List（列出） 一个目录（fs_list）

• Read（读取） 文件，支持按字节范围或行范围读取，包括头部/尾部（fs_read）

• Stat（获取状态） 一个路径——大小、修改时间、类型、权限（fs_stat）

• Grep（搜索） 在目录下的文件中按模式搜索，并限制扫描的文件数和返回的匹配数（fs_grep）

这就是 v1 的整个工具集。这里刻意不提供写入工具，没有删除、没有 chmod、没有任意命令执行，也不做全树遍历（目录大小、重复文件查找）。设计理由和阶段 2（写入）计划请见 CLAUDE.md。

Related MCP server: Project Files Read-only MCP

安全模型

针对用户 alice 的每次文件系统操作都在一个短暂生命周期的辅助子进程中运行，该子进程模拟 alice 的真实 uid/gid——服务器进程本身（以 root 运行，且只持有 CAP_SETUID/CAP_SETGID）从不直接读取或写入一个字节的用户数据。这意味着内核（对于 NFS 挂载的主目录，则是 NFS 服务器）会针对真实身份强制执行每一项权限检查：即使本服务器的路径固定逻辑存在 bug，也只能让 alice 访问到 alice 的真实 uid 原本就能访问的内容。完整设计说明见 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

Broker 模式（生产环境，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 是 broker 签发的身份 JWT（aud=af-filesystem-mcp），携带 uid/gid/unixname POSIX 声明（af-mcp-platform 的 identityProviders[].targetOptions.af-filesystem-mcp.includePosix: true）。需要安装 broker 附加依赖：pip installaf-filesystem-mcp[broker]。

开发

pixi install
pixi run test
pixi run lint

架构、身份模拟/路径限制设计，以及新增工具的规范请见 CLAUDE.md。