MCP File Server

MCP ファイルサーバー

ファイルシステム操作のための標準インターフェースを提供する、Model Context Protocol（MCP）を使用したセキュアなファイルサーバーの実装です。

概要

MCP File Server は、ファイル操作専用の MCP サーバーを実装した Node.js アプリケーションです。MCP プロトコルを介してファイルシステムとやり取りするための、安全で標準化された方法を提供します。Claude などの AI アシスタントや、Cursor などの開発者ツールとの統合に適しています。

サーバーは以下のツールを提供します。

ファイル操作

• list_files：指定したディレクトリ内のファイルを一覧表示します
• read_file：ファイルの内容を読み取ります
• write_file：ファイルに内容を書き込みます
• delete_file：ファイルまたはディレクトリを削除します
• set_base_directory：チャットからファイル操作のベースディレクトリを直接設定します
• get_base_directory：現在のベースディレクトリを取得します

Git 操作

• git_command：ベースディレクトリ内で git コマンドを実行します

プロジェクト構成

プロジェクトは、責務ごとにサービスを整理したモジュール型アーキテクチャを採用しています。

mcp-file-server/
├── services/               # Service modules
│   ├── configService.js    # Configuration management
│   ├── fileService.js      # File system operations
│   ├── gitService.js       # Git operations
│   ├── loggerService.js    # Logging functionality
│   └── toolService.js      # MCP tool registration
├── files/                  # Default storage directory
├── log/                    # Log files
├── examples/               # Example scripts and usage demos
├── mcp_server.js           # Main application entry point
├── package.json            # Project metadata and dependencies
└── README.md               # Documentation

セキュリティ機能

• ディレクトリトラバーサル攻撃を防止する堅牢なパス検証
• ファイルパスの慎重な正規化と解決
• コマンドインジェクションを防止するコマンド検証
• 監査性を確保するため、専用のログファイルに操作を記録
• 相対パスの安全な取り扱い

前提条件

• Node.js >= 16.0.0
• npm または yarn パッケージマネージャー
• Git（git_command 機能を使用する場合）

インストール

1. このリポジトリをクローンします。

   git clone <repository-url>
   cd mcp-file-server
   

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

   npm install
   

設定

環境変数

• BASE_DIRECTORY：（任意）ファイル操作のベースディレクトリへのパスです。指定しない場合、プロジェクトルートの files ディレクトリがデフォルトで使用されます。

ディレクトリ構成

• /files：ファイル操作のデフォルトのベースディレクトリ
• /log：デバッグログファイルを格納します

使用方法

サーバーの起動

npm start

自動再読み込みを有効にして開発する場合：

npm run dev

サーバーが起動し、通信のために標準入力／出力に接続します。

チャットからベースディレクトリを設定する

この実装の主な機能の一つは、チャットインターフェースからベースディレクトリを直接設定できることです。つまり、ファイルの保存場所やアクセス先を変更するために、サーバーを再起動したり設定ファイルを変更したりする必要はありません。

たとえば、AI アシスタントにベースディレクトリの設定を依頼します。

• 「ベースディレクトリを C:/Users/username/Documents に設定してください」
• 「ファイルの保存場所を /home/user/data に変更してください」

アシスタントは set_base_directory ツールを使用して場所を更新します。現在のベースディレクトリを尋ねれば、いつでも現在の場所を確認できます。

Git コマンドの使用

サーバーでは、チャットインターフェースから Git コマンドを直接実行できます。たとえば、AI アシスタントに Git コマンドの実行を依頼します。

• 「git status を実行してください」
• 「git log --oneline を実行してください」
• 「git checkout -b feature/new-feature で新しいブランチを作成してください」

使用するシェルも指定できます。

• 「PowerShell で git status を実行してください」
• 「bash で git diff を実行してください」
• 「cmd で git pull origin main を実行してください」

設定オブジェクトの例

以下は、MCP File Server を Claude Desktop または Cursor と統合するための設定オブジェクトの例です。

{
  "mcpServers": {
    "file-server": {
      "command": "node",
      "args": ["/path/to/mcp-file-server/mcp_server.js"],
      "disabled": false,
      "autoApprove": ["list_files", "read_file", "write_file", "delete_file", "set_base_directory", "get_base_directory", "git_command"]
    }
  }
}

設定プロパティの説明：

• mcpServers：すべての MCP サーバー設定を格納するコンテナー
• file-server：この MCP サーバー固有の識別子
• command：実行するコマンド（この場合、JavaScript ファイルを実行するための node）
• args：コマンドに渡す引数の配列（サーバースクリプトへのパス）
• disabled：このサーバーが現在無効かどうか（false = 有効）
• autoApprove：ユーザー確認を必要とせず、自動承認するツールのリスト

サーバーの拡張

モジュール式アーキテクチャにより、新しい機能でサーバーを簡単に拡張できます。

1. services/ ディレクトリに新しいサービスを作成します
2. toolService.js ファイルにサービスの登録処理を追加します
3. メインの mcp_server.js ファイルを更新し、サービスを初期化します

たとえば、新しい圧縮サービスを追加するには、次の手順を実行します。

• services/compressionService.js を作成します
• toolService.js に registerCompressionTools() メソッドを追加します
• メインサーバーを更新し、圧縮サービスを初期化します

API リファレンス

set_base_directory

ファイル操作の新しいベースディレクトリを設定します。

パラメーター：

• path：新しいベースディレクトリの絶対パス

戻り値：

• 確認メッセージ

get_base_directory

現在のベースディレクトリのパスを取得します。

パラメーター：

• なし

戻り値：

• 現在のベースディレクトリのパス

list_files

指定したディレクトリ内のファイルを一覧表示します。

パラメーター：

• directory：（任意）一覧表示するディレクトリのパス（デフォルトはルート）

戻り値：

• ファイルとディレクトリの整形済みリスト

read_file

ファイルの内容を読み取ります。

パラメーター：

• path：読み取るファイルのパス

戻り値：

• ファイルの内容

write_file

ファイルに内容を書き込みます。

パラメーター：

• path：書き込み先のファイルのパス
• content：ファイルに書き込む内容

戻り値：

• 確認メッセージ

delete_file

ファイルまたはディレクトリを削除します。

パラメーター：

• path：削除するファイルまたはディレクトリのパス

戻り値：

• 確認メッセージ

git_command

ベースディレクトリで git コマンドを実行します。

パラメーター：

• command：実行する Git コマンド（git の接頭辞なし）
• shell：（任意）実行に使用するシェル（cmd、powershell、bash）

戻り値：

• コマンドの出力（stdout と stderr）

トラブルシューティング

サーバーの操作や発生する可能性のあるエラーの詳細については、ログファイル log/mcp_debug.log を確認してください。

よくある問題：

1. パスへのアクセスエラー：BASE_DIRECTORY が、プロセスにアクセス権限のある場所に設定されていることを確認してください。
2. 接続拒否：接続を試みる前に、サーバーが実行中であることを確認してください。
3. ツールが見つからない：設定内のツール名が、サーバーで定義されている名前と完全に一致していることを確認してください。
4. ポートの競合：複数の MCP サーバーを実行している場合、それぞれ異なるポートを使用していることを確認してください。
5. 無効なベースディレクトリ：チャットからベースディレクトリを設定する場合は、相対パスではなく絶対パスを指定してください。
6. Git コマンドエラー：Git がインストールされていること、および Git コマンドの使用時にベースディレクトリが有効な Git リポジトリであることを確認してください。

貢献

MCP File Server の改善への貢献を歓迎します。貢献する方法は次のとおりです。

貢献方法

• バグ報告：再現手順を含む詳細なバグ報告を提出する
• 機能リクエスト：新機能や改善を提案する
• ドキュメント：ドキュメントの改善や拡充に協力する
• コードの貢献：バグ修正や新機能を含むプルリクエストを提出する

開発プロセス

1. リポジトリをフォークする：プロジェクトをご自身のフォークとして作成します
2. ブランチを作成する：新しいブランチで変更を行います
3. コーディング規約に従う：既存のコードスタイルを維持します
4. テストを作成する：新機能やバグ修正のテストを追加します
5. ドキュメント：変更内容を反映するようにドキュメントを更新します
6. プルリクエストを提出する：変更内容を明確に説明する PR を作成します

プルリクエストのガイドライン

• PR は単一の機能またはバグ修正に絞ってください
• 変更内容とその理由を明確に説明してください
• すべてのテストが合格することを確認してください
• 関連するドキュメントを更新してください

問題の報告

問題を報告する際は、次の情報を含めてください。

• 問題の明確な説明
• 問題を再現する手順
• 期待される動作と実際の動作
• 環境の詳細（OS、Node.js のバージョンなど）