Filesystem MCP Server

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

ファイルシステム操作のための、安全な Model Context Protocol（MCP）サーバー実装です。

概要

ファイルシステム MCP サーバーは、Model Context Protocol を介してローカルファイルシステムとやり取りするための標準インターフェースを提供します。クライアントは、ディレクトリの一覧表示、ファイルの読み取り、ファイル内容の検索など、一般的なファイル操作を安全かつ制御された方法で実行できます。

機能

サーバーは、次の MCP ツールを提供します。

1. list：メタデータとともにファイルとディレクトリを一覧表示します
2. read：さまざまなエンコーディングオプションでファイル内容を読み取ります
3. write：内容を指定してファイルを作成または更新します
4. mkdir：ディレクトリを作成します
5. delete：ファイルまたはディレクトリを削除します
6. copy：ファイルまたはディレクトリをコピーします
7. move：ファイルまたはディレクトリを移動または名前変更します
8. info：ファイルやディレクトリの詳細情報を取得します
9. search：ファイル内容を検索します（grep のような機能）
10. list_allowed_dirs：サーバーで設定されている許可済みディレクトリをすべて一覧表示します
11. edit：ファイル全体を書き換えずに、部分的な編集を行います

セキュリティのため、すべての操作は設定可能な許可済みディレクトリ内に制限されます。

セキュリティ

すべてのファイルシステム操作は、設定可能な許可済みディレクトリのセット内に制限されます。サーバーはパスを検証し、ディレクトリトラバーサル攻撃やその他のセキュリティ上の問題を防ぎます。許可済みディレクトリ外のファイルにアクセスする操作は、適切なエラーメッセージとともに拒否されます。

パス要件

サーバーに渡すファイルとディレクトリのパスは、すべて完全な絶対パスで指定する必要があります。アクセスするには、これらのパスが設定済みの許可済みディレクトリのいずれかに含まれている必要があります。

インストール

前提条件：

• Rust ツールチェーン（1.70.0 以降）
• Cargo パッケージマネージャー

サーバーをビルドするには：

cargo build --release

使用方法

サーバーの実行

# Run with current directory as the allowed directory
./target/release/fs-mcp-server

# Specify allowed directories (comma-separated)
./target/release/fs-mcp-server --allowed-dirs /path/to/dir1,/path/to/dir2

# Use a configuration file listing allowed directories
./target/release/fs-mcp-server --config-file /path/to/config.txt

# Set maximum file size
./target/release/fs-mcp-server --max-file-size 5242880  # 5MB

設定ファイル

設定ファイルでは、1 行に 1 つのディレクトリを指定して、許可済みディレクトリを設定できます。

# This is a comment
/path/to/directory1
/path/to/directory2
/another/path

環境変数

次の環境変数を使用してサーバーを設定できます。

• FS_ALLOWED_DIRS：ファイルシステム操作で許可するディレクトリをカンマ区切りで指定したリスト
• FS_CONFIG_FILE：許可済みディレクトリを記載した設定ファイルのパス
• FS_MAX_FILE_SIZE：読み取り操作における最大ファイルサイズ（バイト単位）
• FS_REQUEST_TIMEOUT：リクエストのタイムアウト（秒単位）
• FS_LOG_LEVEL：ログレベル（error、warn、info、debug、trace）
• FS_LOG_FILE：ログファイルのパス

例：

FS_ALLOWED_DIRS=/data,/home/user/docs FS_LOG_LEVEL=debug ./target/release/fs-mcp-server

プロトコルツール

サーバーは、次の MCP ツールを提供します。

list

指定されたパスにあるファイルとディレクトリを一覧表示します。

パラメーター：

• path：一覧表示するファイルが含まれるディレクトリの完全なパス
• pattern：ファイルを絞り込むための任意の glob パターン（デフォルト：「*」）
• recursive：ファイルを再帰的に一覧表示するかどうか（デフォルト：false）
• include_hidden：隠しファイルを含めるかどうか（デフォルト：false）
• metadata：ファイルのメタデータを含めるかどうか（デフォルト：true）

read

さまざまなエンコーディングと部分読み取りに対応して、ファイル内容を読み取ります。

パラメーター：

• path：読み取るファイルの完全なパス
• encoding：ファイルのエンコーディング（utf8、base64、binary）（デフォルト：utf8）
• start_line：部分読み取りの開始行（0 始まり）
• end_line：部分読み取りの終了行（含む）
• max_size：読み取る最大バイト数（デフォルト：1MB）

検索

一致するパターンをファイルの内容から検索します（grep のような機能です）。

パラメーター：

• root_path：検索を開始するルートディレクトリの完全パス
• pattern：ファイル内で検索するテキストパターン
• regex：パターンを正規表現として扱うかどうか（デフォルト：false）
• file_pattern：検索対象のファイルを絞り込むための任意の glob パターン（デフォルト："*"）
• recursive：ディレクトリを再帰的に検索するかどうか（デフォルト：true）
• case_sensitive：大文字と小文字を区別して検索するかどうか（デフォルト：false）
• max_results：返す結果の最大数（デフォルト：100）
• max_file_size：検索するファイルサイズの上限（デフォルト：10MB）
• context_lines：含める前後のコンテキスト行数（デフォルト：0）
• timeout_secs：検索にかける最大時間（デフォルト：30s）

編集

ファイル全体を書き換えることなく、部分的に編集します。

パラメーター：

• path：編集するファイルの完全パス
• operations：実行する編集操作のリスト（順番どおり）
  • 置換操作：
    • type："replace"
    • find：検索するテキスト（完全一致）
    • replace：置換後に挿入するテキスト
    • occurrence：置換する出現箇所（0始まり。すべて置換する場合は-1）（デフォルト：0）
    • case_sensitive：大文字と小文字を区別して検索するかどうか（デフォルト：true）
  • 挿入操作：
    • type："insert"
    • position：挿入位置の文字インデックス（0始まり）
    • content：挿入するテキスト
  • 削除操作：
    • type："delete"
    • start：開始位置の文字インデックス（0始まり、含む）
    • end：終了位置の文字インデックス（0始まり、含まない）
  • 行置換操作：
    • type："replace_lines"
    • start_line：開始行番号（0始まり、含む）
    • end_line：終了行番号（0始まり、含む）
    • content：置換後に挿入するテキスト
• create_if_missing：ファイルが存在しない場合に作成するかどうか（デフォルト：false）
• backup：編集前に元のファイルのバックアップを作成するかどうか（デフォルト：false）

例：

{
  "path": "/path/to/file.txt",
  "operations": [
    {
      "type": "replace",
      "find": "hello",
      "replace": "hello world",
      "occurrence": 0,
      "case_sensitive": true
    },
    {
      "type": "insert",
      "position": 100,
      "content": "new text at position 100"
    },
    {
      "type": "replace_lines",
      "start_line": 5,
      "end_line": 7,
      "content": "new line 6\nnew line 7\nnew line 8"
    }
  ],
  "backup": true
}

list_allowed_dirs

サーバーがアクセスを許可するよう設定されているすべてのディレクトリを一覧表示します。

パラメーター：

• なし

クライアントとの連携

このサーバーを MCP クライアントで使用するには：

1. 使用する言語の MCP クライアントライブラリをインポートします
2. stdio トランスポートを使用してサーバーに接続します
3. MCP プロトコルを使用して利用可能なツールを呼び出します

クライアントコードの例（Rust MCP クライアントを使用）：

use mcp_client::{ClientBuilder, transport::StdioTransport};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<()> {
    // Path to the server executable
    let server_path = "path/to/fs-mcp-server";
    
    // Create and connect to server
    let (transport, mut receiver) = StdioTransport::new(server_path, vec![]);
    
    let client = ClientBuilder::new("fs-client", "0.1.0")
        .with_transport(transport)
        .build()?;
    
    // Start message handling
    let client_for_handler = client.clone();
    tokio::spawn(async move {
        while let Some(message) = receiver.recv().await {
            if let Err(e) = client_for_handler.handle_message(message).await {
                eprintln!("Error handling message: {}", e);
            }
        }
    });
    
    // Initialize the client
    let init_result = client.initialize().await?;
    println!("Connected to: {} v{}", init_result.server_info.name, init_result.server_info.version);
    
    // List all allowed directories
    let allowed_dirs_result = client.call_tool("list_allowed_dirs", &json!({})).await?;
    println!("Allowed directories: {:?}", allowed_dirs_result);
    
    // List files in a directory
    let list_result = client.call_tool("list", &json!({
        "path": "/path/to/directory"
    })).await?;
    
    // Process result
    println!("List result: {:?}", list_result);
    
    // Edit a file by replacing text
    let edit_result = client.call_tool("edit", &json!({
        "path": "/path/to/file.txt",
        "operations": [
            {
                "type": "replace",
                "find": "TODO",
                "replace": "DONE",
                "occurrence": -1
            }
        ],
        "backup": true
    })).await?;
    
    // Process result
    println!("Edit result: {:?}", edit_result);
    
    // Shutdown
    client.shutdown().await?;
    
    Ok(())
}

開発

プロジェクト構成

• src/main.rs：サーバーのエントリーポイントと初期化
• src/tools/：ツールの実装（一覧表示、読み取り、検索、編集など）
• src/utils/：ユーティリティ関数（パスの検証など）

新しいツールの追加

新しいファイルシステムツールを追加するには：

1. ツール用の新しいファイルを src/tools/ に作成します
2. ツールのスキーマと実行関数を実装します
3. main.rs の build_server() にあるサーバービルダーにツールを追加します

各種プラットフォーム向けのビルド

# Build for Linux
cargo build --release --target x86_64-unknown-linux-gnu

# Build for macOS
cargo build --release --target x86_64-apple-darwin

# Build for Windows
cargo build --release --target x86_64-pc-windows-msvc

ライセンス

MIT