mako10k/mcp-async

MCP Async Bridge Server

MCPサーバをブリッジし、非同期処理機能を追加するMCPサーバです。

機能

• 非同期化: 既存のMCPサーバのすべてのツールに sync パラメータを追加（デフォルト：async）
• タイムアウト処理: 1秒で応答がない場合、実行制御用ハンドルを返却
• 状況確認: 非同期ツールの実行状況管理とキャンセル機能
• リソース/サブスクリプション: task://{taskId} でタスクの状態/結果をリソースとして公開。resources/subscribe で更新を購読可能

セットアップ

1. 依存関係のインストール

npm install

2. ビルド

npm run build

3. 実行

npm start

4. 開発モード

npm run dev

設定

環境変数

• MCP_TARGET_SERVER: ブリッジ先MCPサーバのコマンド（例：python server.py）
• MCP_TIMEOUT_MS: タイムアウト時間（ミリ秒、デフォルト：1000）
• MCP_ENV: ターゲットMCPプロセスへ渡す環境変数の宣言（空白区切り）。
  • 形式: <ENV_ITEM> ::= NAME | NAME=VALUE を空白で列挙
  • VALUE はシェル風にクオート/展開可能（'...' はリテラル、"..."/非クオートは $VAR ${VAR} 展開、" \ $ をエスケープ）
  • 値省略時は NAME="$NAME" と等価（現在の環境からコピー）
  • 宣言順にカスケード展開（前に定義した変数を後段で参照可能）
  • 例: MCP_ENV='FOO=abc BAR="$FOO-suf" BAZ=${BAR}-end'
• MCP_WORKDIR: ターゲットMCPプロセスの作業ディレクトリ（未指定時は継承）

既定で未指定でも引き継ぐ環境変数: PATH, HOME, SHELL（安全のため値はログ表示しません）。

VS Codeでのデバッグ

このプロジェクトにはMCP設定が含まれています（.vscode/mcp.json）。VS CodeでMCPサーバとしてデバッグできます。

アーキテクチャ

コンポーネント

1. AsyncBridgeServer: メインのMCPサーバ
2. TargetServerProxy: 既存MCPサーバへのプロキシ
3. AsyncTaskManager: 非同期タスクの管理
4. TimeoutHandler: タイムアウト処理

提供ツール

ブリッジツール

• 既存MCPサーバのすべてのツールに sync パラメータを追加
• デフォルトで非同期実行、sync: true で同期実行

リクエストペイロード形式

Model Context Protocol の仕様に合わせ、ブリッジ経由のツール呼び出しは次のように arguments オブジェクト内へ元のパラメータを格納してください。

{
    "arguments": {
        "a": 1,
        "b": 2
    },
    "sync": false // 省略時は false（非同期実行）
}

既存クライアントとの互換性のため、トップレベルに置かれたパラメータ （例: { "a": 1, "b": 2 }）も自動的に arguments にラップされますが、 仕様準拠のため上記形式での利用を推奨します。

管理ツール

• async_list_pending_tasks: 未完了の非同期タスク一覧
• async_get_task_result: タスク結果の取得（完了時にハンドル開放）
• async_cancel_task: 実行中タスクのキャンセル

応答取得用リソースとサブスクリプション

• ブリッジは resources 機能を公開し、task://{taskId} でタスクの状態と結果を読み取れます。
• 非同期ツール開始時の応答には ResourceLink（task://{taskId}）が含まれます。
• クライアントは以下の流れで最新状態を追跡します。

1. resources/subscribe で task://{taskId} を購読
2. サーバーから notifications/resources/updated が届いたら
3. resources/read で task://{taskId} を取得（JSON: status, result）

例（概念）:

// リソース購読
{
    "method": "resources/subscribe",
    "params": { "uri": "task://<taskId>" }
}

// 更新通知（サーバー→クライアント）
{
    "method": "notifications/resources/updated",
    "params": { "uri": "task://<taskId>" }
}

// リソース読み取り
{
    "method": "resources/read",
    "params": { "uri": "task://<taskId>" }
}

使用例

// 非同期実行（デフォルト）
const handle = await callTool('some_tool', { param: 'value' });

// 同期実行
const result = await callTool('some_tool', { param: 'value', sync: true });

// 非同期結果の確認
const tasks = await callTool('async_list_pending_tasks');
const result = await callTool('async_get_task_result', { taskId: handle });

開発

プロジェクト構造

src/
├── index.ts                 # エントリーポイント
├── server/
│   ├── AsyncBridgeServer.ts # メインサーバー
│   └── TargetServerProxy.ts # プロキシ実装
├── async/
│   ├── TaskManager.ts       # タスク管理
│   └── TimeoutHandler.ts    # タイムアウト処理
├── types/
│   └── index.ts            # 型定義
└── utils/
    └── logger.ts           # ログ機能

テスト

npm test

ライセンス

MIT