Python (MCP) Filesystem Server

Python（MCP）ファイルシステムサーバー

このリポジトリには、堅牢な Python ベースの Model Context Protocol（MCP）ファイルシステムサーバーが含まれています。定義済みのツールセットを通じて AI モデルやアプリケーションがホストシステムのファイルディレクトリを安全に操作できるようにし、ファイルやディレクトリの読み取り、書き込み、移動、一覧表示などの操作を可能にします。

このサーバーは fastmcp ライブラリを基盤として構築され、Model Context Protocol に準拠しており、指定された範囲内で AI ツールがファイルを管理、アクセスするための標準化された方法を提供します。

この TypeScript の実装例に着想を得ています。

---

機能

• 安全なディレクトリアクセス： すべてのファイル操作は、事前に定義された許可ディレクトリのリスト内に厳密に制限されているため、ファイルシステムの他の部分への不正アクセスを防止できます。
• 包括的なファイル操作：
  • read_file：単一の UTF-8 テキストファイルの全内容を読み取ります。バイナリなどの有効な UTF-8 ではないファイルは、文字化けした内容を返すのではなく、エラーとして報告されます。
  • read_multiple_files：複数のファイルの内容を効率的に読み取り、パスを明示した結果を返します。
  • write_file：指定した内容で新しいファイルを作成するか、既存のファイルを上書きします。
  • edit_file：テキストファイルに行単位の編集を適用します。Git スタイルの差分として変更をプレビューできるドライランのオプションもあります。
  • create_directory：ネストされたディレクトリを含む新しいディレクトリを作成するか、その存在を保証します。
  • list_directory：指定したパス内のファイルとサブディレクトリの詳細な一覧を取得します。
  • directory_tree：ファイルとディレクトリの再帰的な JSON ツリー構造を生成し、階層を明確に表示します。
  • move_file：ファイルやディレクトリを移動または名前変更します。移動先がすでに存在する場合は上書きしません。
  • search_files：除外パターンを任意で指定して、パターンに一致するファイルやディレクトリを再帰的に検索します。
  • get_file_info：ファイルやディレクトリの詳細なメタデータ（サイズ、タイムスタンプ、アクセス許可）を取得します。Linux では、報告される作成時刻は inode の変更時刻です。プラットフォームから取得できる時刻はこれだけです。
• 許可ディレクトリの動的設定： コマンドライン引数で、サーバーがアクセスできるディレクトリを正確に指定できます。
• 堅牢なログ記録： 包括的なログ記録機能を統合しており、異なるログレベルに対応するほか、stderr（MCP 準拠のため）と任意のローテーションログファイルの両方に出力できます。
• エラー処理： アクセス拒否、ファイル未検出、アクセス許可エラーなど、一般的な問題に対する詳細なエラーメッセージを提供します。
• 改行コードの正規化： edit_file 操作で \r\n と \n の改行コードを一貫して処理します。
• パスの正規化： パスの包含チェックの前に、要求されたパスと許可ディレクトリの両方を完全に解決します。そのため、シンボリックリンク、.. セグメント、Windows 8.3 形式の短い名前によって、許可されたツリーの外へ抜け出したり、ツリー内の正当なパスが拒否されたりすることはありません。

---

はじめに

前提条件

• Python 3.10+：pyproject.toml の requires-python に一致します。CI では Linux と Windows の両方で 3.10、3.12、3.13 を対象にテストしています。
• fastmcp ライブラリ：このサーバーは MCP プロトコルの処理に fastmcp ライブラリを使用します。インストールが必要です。

インストール

1. リポジトリをクローンします：

   git clone https://github.com/hypercat/PyMCP-FS.git
   cd PyMCP-FS
   

2. uv で依存関係をインストールします：

   uv sync
   

   uv.lock を使ってインストールするため、CI のテスト対象と同じバージョンがインストールされます。テストツールを省略するには --no-dev を指定します。

---

使い方

MCP サーバーの実行（main.py）

MCP サーバーには、コマンドライン引数として許可するディレクトリのリストを指定する必要があります。サーバーは指定されたパス内でのみ動作します。

python3 main.py -d /path/to/allowed/dir1 /path/to/another/allowed/dir2 --log-level INFO --log-file mcp_server.log

引数：

• -d、--directories：（必須） サーバーがアクセスを許可されるディレクトリのパスを1つ以上指定します。複数のディレクトリを指定できます。
• --log-file：（任意） サーバーログの出力先ファイルのパスです。ログファイルが過度に大きくならないよう、ローテーションされます。
• --log-level：（任意） 出力するログの最低レベルです。DEBUG、INFO、WARNING、ERRORから選択します。デフォルトはINFOです。

例：

ホームディレクトリのprojectsフォルダーと一時的なdataフォルダーへのアクセスをサーバーに許可するには、次のようにします。

uv run main.py -d ~/projects /tmp/data --log-level DEBUG --log-file mcp_debug.log

起動すると、サーバーは標準入力（stdin）でMCPメッセージを受信し、標準出力（stdout）で応答します。

テストの実行

テストスイートでは、パスの検証と制限、ファイル操作ヘルパー、 MCP ツール関数、サーバーの起動を対象としています。

uv sync
uv run pytest

tests/test_path_confinement.pyでは、許可されたディレクトリの境界を具体的にテストします。 これには、兄弟ディレクトリのプレフィックスとエイリアスされたディレクトリのケースが含まれます。

test_mcp_server.pyは、統合テストとデバッグ支援の両方を兼ねています。 main.pyをサブプロセスとして起動し、stdio経由でMCPのinitializeハンドシェイクを実行して、 応答を検証します。やり取り全体を表示するには、単独で実行してください。

uv run test_mcp_server.py

CIでは、Python 3.10、3.12、3.13を対象に、LinuxとWindowsでテストスイート全体を実行します。 すべてのジョブに合格しない限り、プルリクエストはマージできません。

---

トラブルシューティング

問題が発生した場合は、次の項目を確認してください。

1. コマンドライン引数を確認する：main.pyに少なくとも1つの許可ディレクトリを指定していることを確認してください。指定がない場合、サーバーは起動しません。
2. 依存関係：環境がロックファイルと同期していることを確認してください（uv sync）。
3. 権限：サーバーを実行するユーザーに、指定した許可ディレクトリとログファイルのパスに対する読み取り／書き込み権限があることを確認してください。
4. ログを確認する（mcp_debug.log）：ログファイル（特に--log-level DEBUGを指定した場合）には、サーバーの動作や、問題が発生している可能性のある箇所が詳しく記録されます。
5. MCP プロトコルへの準拠：クライアントが、MCP 仕様に従った適切な形式のJSON-RPC 2.0メッセージを送信していることを確認してください。サーバーはstdinでメッセージを受信し、stdoutで応答します。
6. パス検証エラー：「Access denied」エラーが表示される場合は、要求されたパスが設定済みの許可ディレクトリ内に厳密に収まっていることを確認してください。パスは完全に解決した後に比較されるため、シンボリックリンクはリンクの場所ではなく、そのリンク先で判定されます。
7. edit_fileの一致に関する問題：edit_fileで「Could not find exact match」と表示される場合は、編集操作のoldTextが、空白や改行コードも含めてファイルの内容と完全に一致していることを確認してください。

---

セキュリティ

すべてのファイル操作は、--directoriesで渡されたディレクトリ内に制限されます。 包含チェックの前に、要求されたパスと許可されたディレクトリの両方が完全に解決されるため、 シンボリックリンク、..セグメント、Windows 8.3形式の短い名前を使って許可されたツリーの外に出ることはできません。

この制限が、このプロジェクトで重視しているセキュリティ特性です。回避方法を見つけた場合は、 イシューを公開するのではなく、非公開で報告してください。報告先と対象範囲については SECURITY.mdを参照してください。

境界の厳しさは、許可した範囲によってのみ決まります。サーバーに機密ディレクトリや/を指定すると、 接続されたモデルにその範囲へのアクセスがそのまま許可されます。

---

サーバーの拡張

このサーバーは、ファイルシステムとのやり取りを行うための強固な基盤を提供します。以下の方法で機能を拡張できます。

• ツールの追加：copy_file、delete_file、checksum_file など、ほかのファイルシステム操作を行う新しい @mcp.tool() 関数を実装します。
• ほかのシステムとの統合：ツールを変更して、クラウドストレージ、データベース、バージョン管理システムと連携させながら、ファイルシステムのようなインターフェースを提供します。
• 検証のカスタマイズ：必要に応じて、validate_path 関数を拡張し、より複雑なアクセス制御ルールを追加します。

---

ライセンス

BSD Zero Clause License（0BSD）のもとで公開されています。これは Open Source Initiative が承認した、最も制約の少ないライセンスです。このソフトウェアは、 著作権表示を保持したり、ライセンス文書を同梱したりする義務なく、あらゆる目的で 使用、変更、再配布できます。