Isolator MCP Server

Isolator MCP Server

isolator-mcp は、TypeScript で記述された Model Context Protocol（MCP） サーバーです。組み込みの isolator Go CLI tool をラップし、MCP 経由で利用できる安全なコード実行サンドボックスを提供します。

LLM アプリケーション（MCP ホスト）はこのサーバーに接続し、execute_code ツールを使用して、直接指定するか、事前定義されたスニペットファイルから読み込んだ Python、Go、または JavaScript のコードスニペットを安全に実行できます。

機能

• execute_code MCP ツールを提供します。
• コードを直接指定する方法（language、entrypoint_code）と、名前付きスニペットを指定する方法（snippet_name）に対応しています。
• 複数の言語（Python、Go、JavaScript。設定可能）に対応しています。
• 組み込みの isolator Go CLI（isolator-cli/）を使用して、Docker コンテナー内で安全に実行します。
• isolator_config.json で、セキュリティのデフォルト設定（タイムアウト、リソース制限、ネットワーク）を構成できます。
• コード実行用の一時ディレクトリをホスト上で管理します。
• コンテナーへのファイルコピーに対応しています（isolator CLI に指示します）。
• MCP 経由で構造化された結果（stdout、stderr、ステータス）を返し、ツールレベルのエラーでは isError: true を設定します。

前提条件

• Docker： isolator-cli によるコンテナーの作成と実行に必要です。Docker デーモンが起動していることを確認してください。
• Go： 組み込みの isolator-cli Go バイナリのビルドに必要です。
• Node.js と npm： isolator-mcp TypeScript サーバーの依存関係のインストール、ビルド、実行に必要です。

インストール

1. isolator Go CLI をビルドする： 組み込みの Go CLI ディレクトリに移動し、バイナリをビルドします。

   cd isolator-cli
   go build -o isolator main.go
   cd .. 
   

   これにより、サーバーに必要な実行可能ファイル ./isolator-cli/isolator が作成されます。
2. isolator-mcp を構成する：
   • isolator_config.json を編集します。isolatorPath を、ビルドしたバイナリの絶対パス（例：/Users/ompragash/Documents/Cline/MCP/isolator-mcp/isolator-cli/isolator）に更新します。必要に応じて、デフォルトの制限、コンテナーの作業ディレクトリ、言語イメージ、または promptsDir（スニペットに使用）の場所を調整します。
   • prompts ディレクトリ（デフォルト：./prompts）が存在することを確認します。コードスニペットファイル（例：hello_world.py）を追加します。ファイル名のベース部分（例：hello_world）が snippet_name として使用されます。
3. サーバーの依存関係をインストールする： メインディレクトリ（isolator-mcp）に移動し、次を実行します。

   npm install
   

4. サーバーをビルドする： TypeScript コードをコンパイルします。

   npm run build
   

   これにより、build/index.js に実行可能スクリプトが作成されます。
5. MCP ホストを構成する： サーバーを MCP クライアントの設定ファイル（例：VS Code 拡張機能の cline_mcp_settings.json）に追加します。

   {
     "mcpServers": {
       "isolator": {
         "command": "node",
         "args": ["/Users/ompragash/Documents/Cline/MCP/isolator-mcp/build/index.js"],
         "env": {},
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

   （必要に応じて args 内のパスを調整してください）。MCP ホストがサーバーを自動的に検出して起動します。

重要な注意： isolator_config.json に指定されている Docker イメージ（例：python:3.11-alpine、golang:1.21-alpine）を、事前に docker pull <image_name> を使用してシステムに取得してください。isolator ツールは、不足しているイメージを自動的にダウンロードしません。

ローカルでの開発／テスト

MCP Host の設定からインストールせずに、開発またはテスト用にサーバーをローカルで実行するには、次の手順を実行します。

1. Go CLI をビルドする： isolator Go CLI がサブディレクトリ内でビルドされていることを確認します。

   cd isolator-cli
   go build -o isolator main.go
   cd ..
   

2. TS サーバーをビルドする： メインディレクトリ（isolator-mcp）で、npm install と npm run build を実行します。
3. 設定する： isolator_config.json の isolatorPath キーで、ビルドした ./isolator-cli/isolator バイナリが正しく指定されていることを確認します（絶対パスを使用してください）。
4. サーバーを実行する： Node を使って、ビルド済みサーバーを直接実行します。

   node build/index.js
   

   サーバーが起動し、stdio 経由で接続します。また、ログ（index.ts からの console.error メッセージを含む）がコンソールに出力されます。
5. 手動で操作する： JSON-RPC メッセージ（例：tools/list、tools/call）をサーバーの標準入力に手動で送信して、レスポンスをテストできます。@modelcontextprotocol/inspector などのツールも役立ちます（npm run inspector）。

（設定ファイルを使って MCP Host からサーバーを起動する前に、手動で実行したサーバーを停止してください。）

アーキテクチャと処理の流れ

1. MCP Host のリクエスト： LLM が MCP Host（例：VS Code Extension）に、引数を指定して isolator サーバーの execute_code ツールを呼び出すよう要求します。
2. サーバーでの処理（index.ts）：
   • stdio 経由で tools/call リクエストを受信します。
   • Zod を使って引数を検証します。
   • isolator_config.json から設定を読み込みます。
   • コードのソースを判定します。
     • snippet_name が指定されている場合、設定済みの promptsDir から対応するファイルを読み込み、ファイル拡張子から言語を判定します。
     • entrypoint_code と language が指定されている場合、それらを直接使用します。
   • ホスト上に一時ディレクトリを作成します。
   • エントリーポイントのコードと、additional_files があればそれらを一時ディレクトリに書き込みます。
   • 設定のセキュリティフラグと一時ディレクトリへのパスを含めて、組み込みの isolator Go CLI 用のコマンドライン引数を構築します。
   • Node.js の child_process.spawn を使って isolator プロセスを起動します。
3. Go CLI の実行（isolator-cli/isolator run）：
   • フラグ（新しい --env フラグを含む）を解析します。
   • 一時ディレクトリの内容から tar ストリームを作成します。
   • Docker SDK を使って、指定されたイメージ、リソース制限、環境変数（--env から取得）、セキュリティ設定（バインドマウントなし）でコンテナを作成します。
   • CopyToContainer を使って、tar ストリームをコンテナの作業ディレクトリにコピーします。
   • コンテナを起動し、指定されたコマンド（例：python /workspace/hello_world.py）を実行します。
   • 完了を待ち、stdout／stderr を取得します。
   • コンテナを削除します。
   • 結果（ステータス、出力など）を JSON として stdout に出力します。
4. サーバーでの結果処理（index.ts）：
   • 終了した isolator プロセスの stdout から JSON 出力を読み取ります。
   • JSON の結果を解析します。
   • stdout／stderr を結合し、Go CLI が成功以外のステータスを報告した場合に isError を設定して、MCP 用の CallToolResult を整形します。
   • 結果を MCP Host に返します。
   • ホスト上の一時ディレクトリをクリーンアップします。
5. MCP Host のレスポンス： 結果を LLM に中継し、LLM はそれをもとにユーザーへの回答を作成します。

execute_code ツール

説明

安全に隔離されたコンテナ環境でコード（Python、Go、JavaScript）を実行します。

入力スキーマ（arguments）

• language（文字列、任意）：プログラミング言語（例：「python」、「go」、「javascript」）です。snippet_name が指定されていない場合は必須です。
• entrypoint_code（文字列、任意）：実行するメインコードの内容です。snippet_name が指定されていない場合は必須です。
• entrypoint_filename（文字列、任意）：メインコードのファイル名（例：「main.py」、「script.js」）です。指定されていない場合は、言語に基づくデフォルト値が使用されます。
• additional_files（配列、任意）：それぞれ以下を含むオブジェクトの配列です。
  • filename（文字列、必須）：追加ファイルの名前です。
  • content（文字列、必須）：追加ファイルの内容です。
• snippet_name（文字列、任意）：設定済みの promptsDir にある、事前定義されたコードスニペットファイル（拡張子なし）の名前です。language および entrypoint_code とは相互排他です。

制約： snippet_name、または language と entrypoint_code の両方を指定する必要があります。

出力（CallToolResult）

• content：単一の TextContent オブジェクトを含む配列です。
  • type：「text」
  • text：実行による stdout と stderr を結合した文字列です。次の形式になります。

    --- stdout ---
    [Actual stdout output]
    --- stderr ---
    [Actual stderr output]
    

    実行中にエラーが発生した場合（終了コードが 0 以外、タイムアウト）、テキストの先頭に Execution Failed (status): [error message]\n\n が追加されます。
• isError（ブール値）：isolator CLI が報告した実行ステータスが「error」または「timeout」の場合は true、それ以外の場合は false です。

（無効な引数やプロセスの起動失敗など、プロトコルレベルのエラーが発生した場合は、CallToolResult ではなく標準の MCP エラーレスポンスが返されます。）