ファイル操作 MCP サーバー

ストリーミング、パッチ適用、変更追跡のサポートにより、強化されたファイル操作機能を提供するモデル コンテキスト プロトコル (MCP) サーバー。

特徴

• 基本的なファイル操作: ファイルのコピー、読み取り、書き込み、移動、削除

• ディレクトリ操作: ディレクトリの作成、削除、コピー

• ファイル監視: ファイルとディレクトリの変更を監視する

• 変更追跡: ファイル操作履歴の追跡と照会

• ストリーミングサポート:ストリーミングで大容量ファイルを効率的に処理

• リソースサポート: MCP リソースを通じてファイルとディレクトリにアクセスします

• 進捗レポート: 長時間の操作の進捗状況をリアルタイムで更新

• レート制限: 過剰なリクエストからの保護

• 強化されたセキュリティ: パス検証と入力のサニタイズ

• 堅牢なエラー処理: 包括的なエラー処理とレポート

• 型安全性: 厳密な型チェックによる完全な TypeScript サポート

Related MCP server: Filesystem MCP Server

インストール

Smithery経由でインストール

Smithery経由で Claude Desktop の File Operations Server を自動的にインストールするには:

npx -y @smithery/cli install @bsmi021/mcp-file-operations-server --client claude

手動インストール

npm install

使用法

サーバーの起動

npm start

自動リロードを使用した開発の場合:

npm run dev

利用可能なツール

基本的なファイル操作

• copy_file : ファイルを新しい場所にコピーする

• read_file : ファイルからコンテンツを読み取る

• write_file : ファイルにコンテンツを書き込む

• move_file : ファイルを移動/名前変更する

• delete_file : ファイルを削除する

• append_file : ファイルにコンテンツを追加する

ディレクトリ操作

• make_directory : ディレクトリを作成する

• remove_directory : ディレクトリを削除する

• copy_directory : ディレクトリを再帰的にコピーする（進行状況レポート付き）

監視業務

• watch_directory : ディレクトリの変更の監視を開始する

• unwatch_directory : ディレクトリの監視を停止する

変更追跡

• get_changes : 記録された変更のリストを取得する

• clear_changes : 記録されたすべての変更をクリアする

利用可能なリソース

静的リソース

• file:///recent-changes : 最近のファイルシステムの変更の一覧

リソーステンプレート

• file://{path} : ファイルの内容にアクセスする

• metadata://{path} : ファイルのメタデータにアクセスする

• directory://{path} : ディレクトリの内容を一覧表示する

使用例

// Copy a file
await fileOperations.copyFile({
    source: 'source.txt',
    destination: 'destination.txt',
    overwrite: false
});

// Watch a directory
await fileOperations.watchDirectory({
    path: './watched-dir',
    recursive: true
});

// Access file contents through resource
const resource = await mcp.readResource('file:///path/to/file.txt');
console.log(resource.contents[0].text);

// Copy directory with progress tracking
const result = await fileOperations.copyDirectory({
    source: './source-dir',
    destination: './dest-dir',
    overwrite: false
});
// Progress token in result can be used to track progress
console.log(result.progressToken);

レート制限

サーバーは不正使用を防ぐためにレート制限を実装しています。

• ツール: 1分あたり100リクエスト

• リソース: 1分あたり200リクエスト

• 時計操作：1分あたり20回

レート制限エラーには、エラー メッセージに再試行期間が含まれます。

セキュリティ機能

パス検証

ディレクトリトラバーサル攻撃を防ぐために、すべてのファイルパスが検証されます。

• 親ディレクトリ参照なし ( ../ )

• 適切なパスの正規化

• 入力サニタイズ

資源保護

• すべての操作に対するレート制限

• 適切なエラー処理とログ記録

• すべてのパラメータの入力検証

• 安全なリソースのクリーンアップ

進捗報告

ディレクトリのコピーなどの長時間実行される操作では、進行状況の更新が提供されます。

interface ProgressUpdate {
    token: string | number;
    message: string;
    percentage: number;
}

進行状況は、操作結果で返される進行状況トークンを通じて追跡できます。

発達

建物

npm run build

リンティング

npm run lint

書式設定

npm run format

テスト

npm test

構成

サーバーはさまざまな設定を通じて構成できます。

• レート制限: リクエスト制限とウィンドウを設定する

• 進捗レポート: 更新頻度と詳細レベルを制御する

• リソースアクセス: リソースの権限と制限を構成する

• セキュリティ設定: パス検証ルールを構成する

• 変更追跡: 保持期間と保存オプションを設定する

• 監視設定: デバウンス時間と再帰監視を設定する

エラー処理

サーバーは、 FileOperationErrorクラスと MCP エラー コードを通じて詳細なエラー情報を提供します。

標準MCPエラーコード

• InvalidRequest : 無効なパラメータまたはリクエスト形式

• MethodNotFound : 不明なツールまたはリソースが要求されました

• InvalidParams : 無効なパラメータ（例：パス検証の失敗）

• InternalError : サーバー側のエラー

カスタムエラータイプ

• ファイル操作の失敗

• レート制限を超えました

• パス検証エラー

• リソースアクセスエラー

各エラーには次の内容が含まれます。

• 特定のエラーコード

• 詳細なエラーメッセージ

• 関連するメタデータ (ファイル パス、制限など)

• 開発モードでのスタックトレース

貢献

1. リポジトリをフォークする

2. 機能ブランチを作成します（ git checkout -b feature/amazing-feature ）

3. 変更をコミットします（ git commit -m 'Add amazing feature' ）

4. ブランチにプッシュする ( git push origin feature/amazing-feature )

5. プルリクエストを開く

ライセンス

このプロジェクトは MIT ライセンスに基づいてライセンスされています - 詳細については LICENSE ファイルを参照してください。