File Operations MCP Server

ファイル操作 MCP サーバー

ストリーミング、パッチ適用、変更追跡に対応した、高度なファイル操作機能を提供する Model Context Protocol（MCP）サーバーです。

機能

• 基本的なファイル操作：ファイルのコピー、読み取り、書き込み、移動、削除
• ディレクトリ操作：ディレクトリの作成、削除、コピー
• ファイル監視：ファイルとディレクトリの変更を監視
• 変更追跡：ファイル操作の履歴を追跡、照会
• ストリーミング対応：ストリーミングを使用して大容量ファイルを効率的に処理
• HTTP インターフェース：Server-Sent Events（SSE）を使用したストリーミング可能な HTTP インターフェース
• リソース対応：MCP リソースを介してファイルとディレクトリにアクセス
• 進捗レポート：時間のかかる操作の進捗をリアルタイムで更新
• レート制限：過剰なリクエストから保護
• 強化されたセキュリティ：パスの検証と入力のサニタイズ
• 堅牢なエラー処理：包括的なエラー処理とレポート
• 型安全性：厳格な型チェックによる完全な TypeScript 対応
• Docker 対応：ボリュームマウントを使用したコンテナ化デプロイ

インストール

Smithery 経由でインストール

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

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

手動インストール

npm install

Docker インストール

Windows および Linux でのローカルドライブのマウントを含む、Docker のセットアップ手順については、DOCKER.md を参照してください。

Docker クイックスタート：

# Stdio transport (for MCP clients)
docker run -it --rm -v "$(pwd):/workspace" ghcr.io/bsmi021/mcp-file-operations-server

# HTTP transport (for web/remote access)
docker run -it --rm -p 3001:3001 -v "$(pwd):/workspace" -e MCP_TRANSPORT=http ghcr.io/bsmi021/mcp-file-operations-server

使用方法

トランスポートモード

サーバーは 2 つのトランスポートモードに対応しています。

1. Stdio トランスポート（デフォルト）

Claude Desktop のような MCP クライアントとの直接統合向け：

npm start

2. SSE を使用した HTTP トランスポート（v1.5 で追加）

リモート接続や Web アプリケーション向け：

npm run start:http

HTTP サーバーは以下を提供します：

• SSE エンドポイント：GET http://localhost:3001/sse - ストリーミング接続を確立
• メッセージエンドポイント：POST http://localhost:3001/messages - クライアントメッセージを受信
• ヘルスチェック：GET http://localhost:3001/health - サーバーの状態
• セッション：GET http://localhost:3001/sessions - アクティブな接続情報

サーバーの起動

開発モード

# Stdio transport with auto-reload
npm run dev

# HTTP transport with auto-reload
npm run dev:http

本番モード

# Stdio transport
npm start

# HTTP transport
npm run start:http

# Custom port for HTTP
npm run start:http -- --port 8080

利用可能なツール

基本的なファイル操作

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

使用例

Stdio トランスポートを使用（MCP クライアント）

// 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);

HTTP トランスポートを使用（Web／リモート）

JavaScript で接続：

// Establish SSE connection
const eventSource = new EventSource('http://localhost:3001/sse');
let sessionId = null;

eventSource.onopen = function() {
    console.log('Connected to MCP server');
};

eventSource.onmessage = function(event) {
    const message = JSON.parse(event.data);
    
    // Extract session ID from first message
    if (!sessionId && message.sessionId) {
        sessionId = message.sessionId;
    }
    
    console.log('Received:', message);
};

// Send a message to the server
async function sendMessage(method, params) {
    const message = {
        jsonrpc: '2.0',
        id: Date.now(),
        method: method,
        params: params
    };
    
    const response = await fetch('http://localhost:3001/messages', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-Session-ID': sessionId
        },
        body: JSON.stringify(message)
    });
    
    return response.json();
}

// Example: List tools
sendMessage('tools/list', {});

// Example: Read a file
sendMessage('tools/call', {
    name: 'read_file',
    arguments: { path: '/workspace/example.txt' }
});

テストに curl を使用：

# Start SSE connection in background
curl -N http://localhost:3001/sse &

# Check server health
curl http://localhost:3001/health

# List active sessions
curl http://localhost:3001/sessions

対話型 Web クライアント：

完全な対話型のサンプルは examples/http-client.html にあります。このファイルを Web ブラウザーで開くと、使いやすい GUI で HTTP インターフェースをテストできます。

v1.5 の新機能

MCP SDK v1.5 へのアップグレード

• ストリーミング可能な HTTP インターフェース：Server-Sent Events（SSE）を備えた新しい HTTP トランスポート
• 強化された API：MCP SDK v1.5 にアップグレードし、zod ベースのスキーマを改善
• 複数の接続：セッション管理による同時 HTTP 接続をサポート
• より優れた型安全性：TypeScript との統合とエラー処理を改善

ストリーミング機能

• 大容量ファイルのサポート：大容量ファイル操作を効率的にストリーミング
• リアルタイムの進捗状況：時間のかかる操作について、SSE 経由で進捗状況を更新
• セッション管理：分離されたセッションを使った複数のクライアント接続
• HTTP API：従来の MCP プロトコルに加え、RESTful エンドポイントを提供

Docker のサポート

Docker を使ったクイックスタート

# Build the image
docker build -t mcp-file-operations-server .

# Run with stdio (for MCP clients)
docker run -it --rm -v "$(pwd):/workspace" mcp-file-operations-server

# Run with HTTP interface
docker run -it --rm -p 3001:3001 -v "$(pwd):/workspace" -e MCP_TRANSPORT=http mcp-file-operations-server

ボリュームのマウント

Windows：

docker run -it --rm -v "C:\MyProject:/workspace" -p 3001:3001 -e MCP_TRANSPORT=http mcp-file-operations-server

Linux/macOS：

docker run -it --rm -v "/home/user/project:/workspace" -p 3001:3001 -e MCP_TRANSPORT=http mcp-file-operations-server

Windows および Linux でのローカルドライブのマウントを含む、Docker の包括的なセットアップ手順については、DOCKER.md を参照してください。

レート制限

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

• ツール：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

設定

環境変数

変数	デフォルト	説明
MCP_TRANSPORT	stdio	トランスポートモード：stdio または http
MCP_HTTP_PORT	3001	HTTP トランスポートのポート

トランスポートの選択

• Stdio：Claude Desktop などの MCP クライアントや、直接統合する場合に最適
• HTTP：Web アプリケーション、リモートアクセス、開発／テストに最適

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

• レート制限：リクエスト数の上限と期間を設定
• 進捗状況の報告：更新頻度と詳細度を制御
• リソースアクセス：リソースの権限と上限を設定
• セキュリティ設定：パス検証ルールを設定
• 変更の追跡：保持期間とストレージオプションを設定
• 監視設定：デバウンス時間と再帰的な監視を設定

エラー処理

サーバーは、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 ファイルを参照してください。