mcp-http-proxy

mcp-http-proxy

stdio を使用する Model Context Protocol（MCP）アプリケーション向けの HTTP/SSE プロキシサーバーです。HTTP 経由で生の JSON-RPC コマンドをサポートし、MCP SDK を使わずに stdio 通信を直接実装します。

MCP RPC プロキシワーカー

概要

この Node.js スクリプト（rpc-proxy-worker.js）は、HTTP クライアントと、その基盤となる MCP（Model Context Protocol）サーバープロセスの間に立つプロキシサーバーとして機能します。MCP サーバーとのやり取りを簡素化するため、次の機能を備えています。

1. MCP プロセスの管理： 子プロセスとして実行される、設定済みの MCP サーバーを起動し、そのライフサイクルを管理します。
2. HTTP エンドポイントの提供： クライアントが MCP プロトコルの stdio 通信を直接処理することなく、MCP サーバーのツールやリソースを利用できる HTTP エンドポイントを公開します。
3. リアルタイムイベントの提供： クライアントが MCP サーバーから非同期の通知や応答を受信できる、Server-Sent Events（SSE）エンドポイントを提供します。
4. ウェブインターフェースの提供： 利用可能なツールを表示する基本的なウェブダッシュボードと、デバッグやコマンド送信のためのシンプルなインターフェースを備えています。

メリット

この mcp-http-proxy には、次のような利点があります。

• 標準的なウェブプロトコルでのアクセス： stdio ベースの MCP サーバーを、標準的な HTTP（GET/POST）と Server-Sent Events（SSE）経由で公開するため、ウェブアプリケーションやさまざまな HTTP クライアント（curl、Python requests、JavaScript fetch など）から利用できます。
• 分離と一元管理： 安定した仲介役として機能し、複数のクライアントが、各自でプロセスを管理することなく、単一の管理対象 MCP プロセスインスタンスを利用できます。
• 柔軟なクライアント連携： 複数の連携方法をサポートします。
  • シンプルな URL パラメーター（/tool/:toolName）： シンプルな GET リクエストを必要とするクライアントに適しています。プロキシが JSON-RPC への変換を処理します。
  • 生の JSON-RPC（/rpc/raw/command）： HTTP POST 経由でクライアントが独自の JSON-RPC コマンドを作成し、完全に制御できます。
• リアルタイム通信： /sse エンドポイントを通じて、サーバーから接続済みのクライアントへ非同期応答、ログ、イベントをプッシュできます。長時間実行されるタスクや応答性の高い UI に最適です。
• クライアント側の依存関係を簡素化： クライアントは標準的な HTTP 経由で連携するため、特定の MCP SDK をインストールまたは使用したり、stdio 通信を処理したりする必要がありません。
• 組み込みのイントロスペクションとデバッグ： ツールの検出、手動テスト、生の通信フローの確認に使える基本的なウェブインターフェース（/、/rpc/command、/debug など）を備えています。
• プロキシを直接制御： プロキシ内で（プロキシ内では MCP SDK に依存せず）stdio 通信を直接実装することで、プロキシと MCP 間のやり取りを細かく制御し、内部依存関係を最小限に抑えます。

仕組み

このシステムは、主に次の 2 つのプロセスで動作します。

1. プロキシワーカー（このスクリプト）：

   • Node.js プロセスとして実行されます。
   • クライアントからのリクエストを待ち受ける HTTP サーバー（Express を使用）を起動します。
   • 設定（MCP_CONFIG）に基づいて、実際の MCP サーバーを子プロセスとして起動します。
   • 標準入力（stdin）、標準出力（stdout）、標準エラー出力（stderr）を使用して、子 MCP プロセスと通信します。
   • 一部の HTTP リクエスト（URL パラメーターなど）を MCP プロセス向けの JSON-RPC コマンドに変換します。
   • 特定の HTTP エンドポイント経由で受信した生の JSON-RPC コマンドを MCP プロセスに転送します。
   • MCP プロセスの stdout/stderr から応答とイベントを読み取ります。
   • HTTP クライアントに応答を返します。
   • 接続済みの SSE クライアントにイベントと非同期応答をプッシュします。

2. MCP サーバー（子プロセス）：

   • プロキシワーカーによって起動されます。
   • stdin 上で JSON-RPC コマンドを待ち受けます。
   • ツールの一覧表示や呼び出しなどの MCP 操作を実行します。
   • JSON-RPC 応答とプロトコルメッセージを stdout に書き込みます。
   • ログやエラーを stderr に書き込みます。

サーバーの起動

1. 前提条件： Node.js がインストールされていることを確認します。
2. 移動： ターミナルを開き、rpc-proxy-worker.js があるディレクトリに移動します。
3. 実行： 次のコマンドを実行します。

   node rpc-proxy-worker.js
   

4. 出力： サーバーが実行中であることを示す出力が表示されます。通常、次の内容が含まれます。

   Web interface running on http://localhost:3005
   SSE endpoint available at http://localhost:3005/sse
   

   サーバーはデフォルトでポート 3005 をリッスンします。

通信メカニズム

1. Stdio（プロキシ <-> MCP プロセス）- 内部

これは、プロキシワーカースクリプトと、プロキシが管理する子 MCP サーバープロセス間の内部通信チャネルです。

• プロキシ -> MCP： プロキシは、検証済みの JSON-RPC コマンド文字列を MCP プロセスの stdin に送信します。
• MCP -> プロキシ：
  • MCP プロセスは、JSON-RPC レスポンス文字列（結果、エラー、プロトコルメッセージ）を stdout に送信します。
  • MCP プロセスは、ログメッセージまたは致命的なエラーを stderr に送信します。
• ユーザーとのやり取り： ユーザーがコマンドを送信するために、プロキシの stdio を直接利用することはありません。すべてのやり取りは HTTP エンドポイント経由で行われます。

2. Server-Sent Events（SSE）（プロキシ -> クライアント）- 外部

これは、プロキシが接続中の HTTP クライアントにリアルタイムでイベントをプッシュできる、主に一方向の外部通信チャネルです。

• 接続： クライアントは /sse エンドポイントに HTTP GET リクエストを送信して、SSE 接続を確立します。プロキシはこの接続を開いたままにします。
• イベントのプッシュ： プロキシが MCP プロセスの stdout（レスポンス）または stderr（ログ／エラー）からデータを受信すると、SSE プロトコル（data: <json_string>\n\n）に従ってデータをフォーマットし、開いている接続を通じて、現在接続中のすべての SSE クライアントにプッシュします。
• コマンドの送信： クライアントは、同じ SSE 接続を通じてプロキシにコマンドを送り返すことはできません。コマンドを実行するには、SSE クライアントは別途、標準の HTTP リクエスト（例：POST /rpc/raw/command または GET /tool/:toolName）を送信する必要があります。そのコマンドの結果は通常、クライアントが受信している /sse ストリームを通じてプッシュされます。

プロキシとのやり取り（HTTP エンドポイント）

プロキシは、いくつかの HTTP エンドポイントを公開しています。

• GET /

  • メインの HTML ダッシュボードを表示し、子プロセスから検出された利用可能な MCP ツールを一覧表示します。/tool/:toolName エンドポイントを介してツールを実行するためのフォームも提供します。

• GET /tools

  • MCP サーバーが提供する利用可能なすべてのツールについて、名前、説明、入力スキーマを含む JSON 配列を返します。

• GET /tool/:toolName

  • 特定のツールを実行します。
  • ツールのパラメーターは、URL クエリパラメーターとして指定します（例：/tool/my_tool?param1=valueA&param2=123）。
  • プロキシは、これらの URL パラメーターを有効な JSON-RPC tools/call リクエストオブジェクトに変換し、ツールのスキーマに照らして検証します。
  • stdio を介して MCP プロセスにコマンドを送信します。
  • 送信された RPC コマンドと MCP プロセスから受信した応答を表示する HTML ページを返します。

• POST /rpc/raw/command

  • 生の JSON-RPC コマンドを実行します。
  • Content-Type: application/json を指定した POST リクエストの本文に、完全な JSON-RPC 2.0 リクエストオブジェクトを指定する必要があります。
  • プロキシは、受信したリクエスト本文の構造を基本的な RPC スキーマに照らして検証します。
  • 検証済みの生コマンドを MCP プロセスの stdin に直接転送します。
  • MCP プロセスの stdout から受信した 生の JSON-RPC 応答を、JSON として HTTP 応答本文に直接返します。RPC 呼び出し全体を自分で構成してプログラムからやり取りする場合に使用する主要なエンドポイントです。

• GET /sse

  • Server-Sent Events ストリームを確立します。クライアントはここに接続し、サーバーからプッシュされるリアルタイムイベント（MCP の応答、ログ）を受信します。

• GET /sse-client

  • /sse エンドポイントに接続し、受信したイベントを表示するシンプルな HTML ページを提供します。SSE ストリームのデバッグに便利です。

• GET /help

  • 利用可能なツールと /tool/:toolName エンドポイントの使い方を説明する HTML ページを表示します。

• デバッグ用エンドポイント：

  • GET /rpc/command：Web フォームから RPC コマンドを手動で作成して送信するための HTML インターフェースを表示します（内部で /rpc/raw/command を使用します）。
  • GET /rpc/raw：プロキシと MCP プロセス間でやり取りされた生メッセージの履歴を JSON 形式で表示します。
  • POST /rpc/raw/clear：生メッセージの履歴を消去します。
  • GET /debug：RPC、プロセス、SSE の各イベントを表示する、より包括的な HTML デバッグインターフェースを表示します。
  • GET /debug/logs：現在のデバッグログを JSON 形式で返します。
  • GET /debug/sse：デバッグログイベント専用の SSE ストリームです。

• （任意）MCP 管理用エンドポイント：（/mcp/*）

  • mcp-manager.js を使用する場合、/mcp/install、/mcp/start、/mcp/stop、/mcp/list などのエンドポイントを使って、さまざまな MCP サーバーのインストールを動的に管理できます。

コマンドの送信（例）

POST /rpc/raw/command を使用（プログラムからの利用に推奨）

リクエスト本文に JSON-RPC リクエスト全体を送信します。

curl（Bash/zsh/WSL）：

curl -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
  http://localhost:3005/rpc/raw/command

curl（Windows cmd - 引用符の扱いに注意）：

curl -X POST -H "Content-Type: application/json" -d "{\"jsonrpc\":\"2.0\",\"method\":\"tools/list\",\"id\":1}" http://localhost:3005/rpc/raw/command

PowerShell：

$rpcBody = @{
    jsonrpc = "2.0"
    method = "tools/call"
    id = 2
    params = @{
        name = "your_tool_name"
        arguments = @{
            param1 = "value1"
            count = 10
        }
    }
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Uri http://localhost:3005/rpc/raw/command -Method Post -ContentType 'application/json' -Body $rpcBody

GET /tool/:toolName を使用（シンプルな GET リクエストに便利）

URL のクエリ文字列にパラメーターを指定します。

curl：

# Assuming a tool 'worker_get' exists that takes a 'name' parameter
curl "http://localhost:3005/tool/worker_get?name=my-worker"

エラー処理

プロキシはエラーを適切に処理するよう試みます。

• HTTP エラー： 標準の HTTP ステータスコードを返します（例：不明なツール／エンドポイントには 404、/tool/:toolName の無効なパラメーターには 400）。
• パラメーターの検証： /tool/:toolName エンドポイントは、コマンドを送信する前に、クエリパラメーターをツールのスキーマに照らして検証します。エラーは HTML レスポンスで返されます。/rpc/raw/command エンドポイントでは、JSON-RPC の構造を基本的に検証します。
• MCP エラー： 基盤となる MCP プロセスから返されるエラー（例：ツールの実行失敗）は、その stdout（JSON-RPC エラーレスポンスとして）または stderr から取得され、直接の HTTP レスポンス（/rpc/raw/command の場合）または HTML ページ内（/tool/:toolName の場合）でクライアントに中継され、SSE 経由でプッシュされる場合もあります。

クリーンアップ

スクリプトは exit と SIGINT（Ctrl+C）のハンドラーを登録します。終了時には、次の処理を試みます。

1. 子 MCP プロセス（MCPWorker.mcpProcess.kill()）を終了します。
2. すべてのアクティブな SSE クライアント接続を閉じます。