MCP File Operations Server

🚀 MCPファイル操作サーバー

このサーバーは、ファイルとディレクトリの操作を行うためのMCP（Meta Computing Protocol）サーバーです。基本的なファイル操作、ディレクトリ管理、変更追跡などの機能を提供します。

🚀 クイックスタート

インストール

自動インストール

Smitheryを通じて自動インストールします。

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}：ディレクトリの内容を一覧表示します。

💻 使用例

基本的な使用法

// ファイルのコピー
await fileOperations.copyFile({
    source: 'source.txt',
    destination: 'destination.txt',
    overwrite: false
});

// ディレクトリの監視
await fileOperations.watchDirectory({
    path: './watched-dir',
    recursive: true
});

// リソースを通じてファイルの内容にアクセス
const resource = await mcp.readResource('file:///path/to/file.txt');
console.log(resource.contents[0].text);

// 進捗追跡付きでディレクトリをコピー
const result = await fileOperations.copyDirectory({
    source: './source-dir',
    destination: './dest-dir',
    overwrite: false
});
// 結果の進捗トークンを通じて進捗を追跡
console.log(result.progressToken);

📚 ドキュメント

レート制限

サーバーは乱用を防止するためにレート制限を実装しています。

レート制限エラーには、再試行までの時間情報が含まれています。

セキュリティ機能

パス検証

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

• 親ディレクトリの参照（../）は禁止されています。
• パスは正しく正規化されます。
• 入力パラメータは浄化されます。

リソース保護

• すべての操作にはレート制限があります。
• 適切なエラー処理とログ記録が行われます。
• すべてのパラメータ入力が検証されます。
• 安全なリソースクリーンアップメカニズムがあります。

進捗報告

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

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

操作結果の進捗トークンを通じて進捗を追跡できます。

設定

基本設定

環境変数または設定ファイルを使用して、以下のオプションを設定できます。

高度な設定

• 変更追跡の有効/無効化：

{
    enableChangeTracking: true // デフォルトはtrue
}

• ディレクトリコピーの並列数の設定：

{
    copyConcurrency: 5 // コピー操作のデフォルト並列数は5
}

エラー処理

一般的なエラー

1. ファイルが存在しない：存在しないファイルにアクセスまたは操作しようとすると発生します。

Error: File not found

2. 権限不足：操作に必要な権限がない場合に発生します。

Error: Permission denied

3. ディレクトリトラバーサル拒否：ディレクトリトラバーサル攻撃を試みた場合に阻止されます。

Error: Directory traversal attempt detected

カスタムエラー処理

グローバルエラーハンドラーを登録することで、エラーをキャッチして処理できます。

mcp errorHandler(error) {
    console.error('An error occurred:', error);
    // カスタム処理ロジック
}

ログ記録

ログ形式

デフォルトのログ形式は以下の通りです。

[timestamp] - [level] - message

例：

2023-10-05 12:34:56 - info - File operation completed successfully.

ログレベル

以下のログレベルがサポートされています。

• debug：デバッグ情報
• info：一般情報
• warning：警告メッセージ
• error：エラー情報

パフォーマンス最適化

キャッシュメカニズム

サーバーはファイル操作のキャッシュを内蔵しており、繰り返しの操作の効率を向上させます。デフォルトで有効になっています。

並列処理

システムの負荷と設定に応じて、マルチスレッドと並行操作をサポートしてパフォーマンスを向上させます。

FAQ

1. 現在のログを確認するには？
   • mcp logsコマンドを使用して、リアルタイムログを確認できます。
2. 変更追跡を無効にできますか？
   • はい、enableChangeTracking: falseを設定することで、変更追跡機能を無効にできます。
3. サーバーはどのプロトコルをサポートしていますか？
   • 現在のバージョンはMCPプロトコルのみをサポートしており、将来的には他のプロトコルのサポートが計画されています。

貢献者

• 開発者：[あなたの名前]
• メンテナ：[プロジェクトメンテナンスチーム]

以上が、プロジェクトの完全なドキュメントです。インストール、設定、使用方法、よくある質問への回答が含まれています。何か質問や追加の支援が必要な場合は、プロジェクトメンテナンスチームにお問い合わせください。