MCP Stdio Wrapper

MCP Stdio Wrapperは、あるMCPクライアントが別のstdio MCPサーバーをオンデマンドで起動および検査できるようにする小さなMCPサーバーです。

その役割は、厄介なMCP開発ループを解消することです。一部の主要なMCPホストは実際のサーバープロセスをキャッシュするため、コードを変更するたびに、変更をスモークテストするためだけにウィンドウを更新したり、拡張ホストを再起動したりする必要があります。このラッパーは実際のターゲットサーバーの前に配置され、ターゲットの実装がその下で変更され続けている間も、エージェントが繰り返しスモークテストを行うための安定したブリッジを提供します。

なぜこれが存在するのか

以下のような場合にこのプロジェクトを使用してください：

• stdio MCPサーバーを積極的に開発している場合

• メインのMCPホストが変更のたびにターゲットサーバーを確実にリロードしない場合

• 開発中を通じて、エージェントにツールの一覧表示、ツールの呼び出し、リソースの読み取り、プロンプトの検査を行わせたい場合

このプロジェクトは意図的に範囲を絞っています。本番環境のトラフィックプロキシ用ではなく、ローカル開発およびスモークテスト用です。

また、このラッパーはエージェントが直接発見できる組み込みのガイダンスを公開しています：

• リソース: wrapper://how-to-use

• プロンプト: tool_usage_guide

Related MCP server: Multi MCP

仕組み

このラッパーは2つのモードを公開しています。

デフォルトのワンショットツール：

• stdio_mcp_list_tools

• stdio_mcp_call_tool

• stdio_mcp_list_resources

• stdio_mcp_read_resource

• stdio_mcp_list_prompts

• stdio_mcp_get_prompt

各ワンショットブリッジ呼び出しは以下の手順で行われます：

1. ターゲットのstdio MCPサーバーを起動する

2. 1つのMCP操作を実行する

3. 結果を返す

4. ターゲットプロセスを終了する

オプションのセッションツール：

• stdio_mcp_open_session

• stdio_mcp_get_session

• stdio_mcp_close_session

• stdio_mcp_session_list_tools

• stdio_mcp_session_call_tool

• stdio_mcp_session_list_resources

• stdio_mcp_session_read_resource

• stdio_mcp_session_list_prompts

• stdio_mcp_session_get_prompt

つまり、以下の利点があります：

• ワンショットスモークテストごとにクリーンなターゲットプロセスが使用される

• 多段階検証のための明示的な短期間セッションオプション

• 隠れたキャッシュ動作がない

• 失敗時にターゲットのstderrが表示されるため、デバッグが容易

クイックスタート

リポジトリをクローンし、依存関係をインストールします：

nvm use
npm install

ラッパーを起動します：

npm start

公開されているパッケージは、以下を使用して直接実行することもできます：

npx mcp-stdio-wrapper

パッケージは https://www.npmjs.com/package/mcp-stdio-wrapper で公開されています。

このリポジトリは、GitHub Actionsからのnpm信頼済み公開用に設定されています。最初の公開シーケンスとOIDC信頼済み公開の引き継ぎについては、公開チェックリストを参照してください。

メインのMCPクライアントをこのラッパーに向け、以下のような起動入力を使用してブリッジツールのいずれかを使用します：

{
  "command": "node",
  "args": ["C:\\path\\to\\your-mcp\\dist\\index.js"],
  "cwd": "C:\\path\\to\\your-mcp",
  "inheritParentEnv": true,
  "env": {
    "EXAMPLE_ENV": "value"
  },
  "startupTimeoutMs": 30000,
  "operationTimeoutMs": 30000
}

次に、エージェントに以下を依頼します：

• 実際のターゲットサーバーからツールを一覧表示する

• コードを変更するたびにターゲットツールを1つ呼び出す

• リソースの読み取りやプロンプトを検証する

初期検査や小さなステートレスな呼び出しにはワンショットモードを使用してください。ターゲットが jobId 形式のハンドルを返す場合、呼び出し間でメモリ内状態を期待する場合、または単に起動コストが高い場合は、明示的にセッションを開き、閉じる前に stdio_mcp_session_* ツールを使用してください。

ツールインターフェース

一般的な起動フィールド：

• command: ターゲット実行ファイル

• args: ターゲットコマンド引数

• cwd: オプションのターゲット作業ディレクトリ

• inheritParentEnv: true の場合、ラッパープロセスの環境をターゲットの起動にマージする

• env: 追加のターゲット環境変数

• startupTimeoutMs: オプションのワンショット起動およびMCP初期化タイムアウト

• operationTimeoutMs: オプションのワンショット操作タイムアウト

• timeoutMs: 両方のフェーズに対するレガシーなワンショットショートカット。セッションツールは引き続き timeoutMs を使用します

ブリッジ操作：

• stdio_mcp_list_tools: ターゲットツールを検査する

• stdio_mcp_call_tool: ターゲットツールを1つ呼び出す

• stdio_mcp_list_resources: ターゲットリソースを検査する

• stdio_mcp_read_resource: ターゲットリソースを1つ読み取る

• stdio_mcp_list_prompts: ターゲットプロンプトを検査する

• stdio_mcp_get_prompt: ターゲットプロンプト定義を1つ取得する

セッション操作：

• stdio_mcp_open_session: ターゲットプロセスを1つ起動し、複数の操作のために維持する

• stdio_mcp_get_session: ステータス、タイムスタンプ、PID、終了コード、stderrの末尾などのセッション診断を検査する

• stdio_mcp_close_session: ライブまたは終了したセッションを閉じ、その記録を削除する

• stdio_mcp_session_list_tools: 既存のセッションを通じてツールを検査する

• stdio_mcp_session_call_tool: 既存のセッションを通じてターゲットツールを1つ呼び出す

• stdio_mcp_session_list_resources: 既存のセッションを通じてリソースを検査する

• stdio_mcp_session_read_resource: 既存のセッションを通じてターゲットリソースを1つ読み取る

• stdio_mcp_session_list_prompts: 既存のセッションを通じてプロンプトを検査する

• stdio_mcp_session_get_prompt: 既存のセッションを通じてターゲットプロンプト定義を1つ取得する

ラッパーガイダンスの公開：

• wrapper://how-to-use: プレーンテキストの使用ガイド

• tool_usage_guide: 同じ指示のプロンプト形式

セッションモードが適している場合：

• ターゲットが jobId のような遅延ハンドルを返す場合

• 後続の呼び出しが同じライブターゲットプロセスにヒットする必要がある場合

• ターゲットの起動コストが高く、繰り返すと実際のフィードバックループが不明瞭になる場合

安全上の注意

• このラッパーは、呼び出し元によって提供された任意のコマンドを起動します。

• 起動引数と環境変数は機密情報として扱ってください。

• 信頼できるターゲットコマンドと信頼できるローカルプロジェクトでのみ使用してください。

• これをパブリックなマルチテナントサービスとして公開しないでください。

ドキュメント

• セットアップガイド

• ツールリファレンス

• トラブルシューティング

• ブランチ戦略

• メンテナーガイド

• 公開チェックリスト

• ファジングワークフロー

• セキュリティポリシー

• 貢献

• 変更履歴

スター履歴