af-filesystem-mcp v0.1.3

AF（Analysis Facility）ユーザーに対し、AF の共有 NFS ホーム（/home/<unixname>）と Ceph データ領域（/data/<unixname>）にある自分のファイルへの閲覧/読み取りアクセスを提供する MCP サーバーです。それだけです。af-mcp-platform のクレデンシャルブローカーの背後に配置されるよう設計されており、人間がパスをコピーして回らなくても、LLM セッションがユーザー自身の解析出力、condor ログ、スクラッチファイルを確認できます。

機能

• 一覧表示: ディレクトリを一覧表示する（fs_list）

• 読み取り: バイト範囲または行範囲でファイルを読み取る。head/tail にも対応（fs_read）

• stat: パスのサイズ、mtime、タイプ、パーミッションを取得する（fs_stat）

• grep: ディレクトリ配下のファイルからパターンを検索する。スキャンするファイル数と返す一致数の上限あり（fs_grep）

これが v1 のツールの全容です。書き込みツール、削除、chmod、任意のコマンド実行、フルツリーウォーク（ディレクトリサイズ、重複検出）は意図的に設けていません。設計の根拠とフェーズ 2（書き込み）計画については CLAUDE.md を参照してください。

Related MCP server: Context MCP

セキュリティモデル

ユーザー alice のすべてのファイルシステム操作は、alice の実際の uid/gid を偽装する短命のヘルパーサブプロセスで実行されます。サーバープロセス自体（root として実行され、CAP_SETUID/CAP_SETGID のみを保持）は、ユーザーデータを直接 1 バイトも読み書きしません。つまり、カーネル（NFS マウントされたホームの場合は NFS サーバー）が、すべての権限チェックを実際の ID に対して強制します。このサーバー自身のパス固定ロジックにバグがあったとしても、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 モードは、偽装を行わないため、開発用途であればどの 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

Bearer トークンは、ブローカーが発行するアイデンティティ 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 を参照してください。