af-filesystem-mcp v0.1.3

AF(분석 시설) 사용자에게 AF의 공유 NFS 홈(/home/<unixname>)과 Ceph 데이터 영역(/data/<unixname>)에 있는 자신의 파일에 대한 탐색/읽기 액세스를 제공하는 MCP 서버입니다. 그 이상은 제공하지 않습니다. af-mcp-platform의 자격 증명 브로커 뒤에 위치하도록 설계되어, 사람이 경로를 복사해 줄 필요 없이 LLM 세션이 사용자 자신의 분석 출력물, condor 로그, 임시 파일을 살펴볼 수 있습니다.

제공 기능

• 디렉터리 목록 조회 (fs_list)

• 파일 읽기 — 바이트 범위 또는 줄 범위로, head/tail 포함 (fs_read)

• 경로 상태 조회 — 크기, mtime, 유형, 권한 (fs_stat)

• 패턴 검색 — 디렉터리 아래 파일들에서 패턴을 검색하며, 검색 대상 파일 수와 반환되는 일치 항목 수에 상한이 있음 (fs_grep)

이것이 v1 도구가 제공하는 전부입니다. 쓰기 도구, 삭제, chmod, 임의 명령 실행, 전체 트리 순회(디렉터리 크기, 중복 파일 검색기)는 의도적으로 없습니다. 설계 근거와 phase-2(쓰기) 계획은 CLAUDE.md를 참조하세요.

Related MCP server: Project Files Read-only MCP

보안 모델

사용자 alice에 대한 모든 파일 시스템 작업은 alice의 실제 uid/gid를 가장하는 단기 헬퍼 서브프로세스에서 실행됩니다. 서버 프로세스 자체는(root로 실행되며 CAP_SETUID/CAP_SETGID만 보유) 사용자 데이터를 한 바이트도 직접 읽거나 쓰지 않습니다. 즉, 커널(그리고 NFS 마운트된 홈의 경우 NFS 서버)이 모든 권한 검사를 실제 신원을 기준으로 적용합니다. 이 서버 자체의 경로 고정 로직에 버그가 있더라도 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 모드는 가장을 수행하지 않으므로 개발 중에는 모든 OS에서 정상 작동합니다.)

빠른 시작 (로컬 개발, 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

베어러는 브로커가 발급한 신원 JWT(aud=af-filesystem-mcp)로, uid/gid/unixname POSIX 클레임을 담고 있습니다(af-mcp-platform의 identityProviders[].targetOptions.af-filesystem-mcp.includePosix: true). broker 엑스트라가 필요합니다: pip install af-filesystem-mcp[broker].

개발

pixi install
pixi run test
pixi run lint

아키텍처, 가장/경로 제한 설계, 새 도구 추가 규칙은 CLAUDE.md를 참조하세요.