MCP Code Mode

🚀 MCP Code Mode

このプロジェクトは、DSpyを用いたCode Execution MCP Serverのプロトタイプ実装です。「Code Execution with MCP」アーキテクチャは、コード生成における大規模言語モデルの強みと、ツール統合のためのModel Context Protocolを組み合わせています。このシステムにより、AIエージェントは、隔離されたサンドボックス内で実行されるPythonコードを記述し、外部のMCPツールをシームレスに呼び出すことが可能です。

🚀 クイックスタート

1. インストール

Python 3.11以上とNode.js 20以上が必要です。

# 仮想環境の作成
python3.11 -m venv .venv
source .venv/bin/activate

# 依存関係のインストール
pip install -e .[dev]

# 参照サーバーのNode.js依存関係のインストール
npm install -g npm@latest

2. 設定

サンプルの環境ファイルをコピーし、シークレットを設定します。

cp .env.example .env

mcp_servers.jsonでMCPサーバーを設定します。

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/your-working-folder"],
      "description": "ローカルファイルシステム操作"
    }
  }
}

3. サーバーの起動

Code Execution MCPサーバーを起動します。

python -m mcp_code_mode.executor_server

4. 検証

デバッグエグゼキュータースクリプトを実行して設定を検証します。このスクリプトはMCPクライアントをシミュレートし、サーバーに接続し、テストタスクを実行して、エージェントとツールが正しく動作していることを確認します。

スクリプトを実行する前に：

1. mcp_servers.jsonで対話したいMCPサーバーを設定します。
2. scripts/debug_executor.pyのtask変数を編集して、エージェントに実行させたい特定のタスクを定義します。

python scripts/debug_executor.py

🛠️ 開発コマンド

⚙️ 実行環境とガードレール

デフォルトでは、システムはLocal Python Executor (LocalPythonExecutor) を使用しており、コードはサーバーと同じプロセス内で実行されます。これは、厳格なPyodideサンドボックスがネットワークI/Oに制限があり、一部の環境で他のMCPツールにコールバックできないため必要です。

ガードレール

ローカルエグゼキューターを使用しても、システムはコード実行前にポリシーを適用します。

• 制限: 最大8000文字 / 400行。
• インポート: 許可リストのみ (json, math, re, datetimeなど)。
• トークン: 潜在的に危険なトークン (subprocess, exec, eval) は許可されません。

違反がある場合は、POLICY_VIOLATIONエラーが返されます。

⚠️ 重要提示

MCP_EXECUTOR=pyodideを設定することで、Pyodideサンドボックスの使用を強制することができますが、環境によってはツールコールが機能しない場合があります。

🏗️ アーキテクチャ

概要

┌─────────────────────────────────────────────────────────────┐
│                   MCPクライアント (Claudeなど)                  │
└────────────────────────┬────────────────────────────────────┘
                         │ MCPプロトコル (stdio/HTTP/SSE)
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                    FastMCPサーバー                            │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  @mcp.tool                                           │  │
│  │  async def execute_code(code: str):                 │  │
│  │      # 1. ローカルエグゼキューターで実行 (デフォルト)       │  │
│  │      result = await executor.run(code)              │  │
│  │      return result                                   │  │
│  └──────────────────────────────────────────────────────┘  │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
          ┌──────────────────────────────┐
          │    実行エンジン:         │
          │  • LocalPythonExecutor       │
          │    (またはPyodideサンドボックス)      │
          └──────────────────────────────┘

なぜCode Modeなのか？

従来のMCP実装には、いくつかの重要な課題があります。

1. コンテキストウィンドウの肥大化: すべてのツール定義がトークンを消費し、拡張性が制限されます。
2. トークンコスト: 複数のツールコールを繰り返すことはコストがかかります。
3. レイテンシー: 逐次的なツール呼び出しにより、累積的な遅延が発生します。
4. 組み合わせ性: 複雑なワークフローには多くの個別のステップが必要です。

Code Modeは、LLMが得意なコード記述を活用することで、これらの問題を解決します。複数のツールコールを行う代わりに、エージェントは内部で必要なすべての操作を調整するPythonスクリプトを記述します。

コアコンポーネント

1. エグゼキューターサーバー (FastMCP) (src/mcp_code_mode/executor_server.py) このサーバーは、Pythonエグゼキューター (ローカルまたはPyodide) をバックエンドに持つexecute_codeツールを公開します。fastmcpを使用してMCPプロトコルを処理し、dspyを使用して実行ロジックを処理します。

2. 設定駆動型のディスカバリー (mcp_servers.json) システムはmcp_servers.jsonを使用して、接続するMCPサーバーを明示的に設定します。src/mcp_code_mode/mcp_manager.pyによって読み込まれます。

3. ツールスキーマのフォーマット (src/mcp_code_mode/tool_formatter.py) 検出されたMCPツールを、コード生成LLMに渡される読みやすいドキュメントにフォーマットします。これにより、LLMはどのツールが存在するかを知ることができます。

4. コンテキストの注入 フォーマットされたツールスキーマは、LLMの入力フィールドとして渡されます。LLMはコードを記述する前に、ツール名、パラメーター、および使用例を知っています。

情報の流れ

1. mcp_servers.json (サーバーを定義)
   ↓
2. MCPServerManager.initialize()
   ├─ 設定されたサーバーに接続
   ├─ 各サーバーでlist_tools()を呼び出し
   └─ DSpyツールに変換
   ↓
3. ToolSchemaFormatter.format_for_llm()
   └─ 読みやすいドキュメントを作成
   ↓
4. CodeExecutionAgent
   └─ 呼び出し可能なツールとスキーマの両方を保存
   ↓
5. エージェント生成
   └─ ツールコンテキストをLLMに渡す
   ↓
6. コード実行
   └─ コードはサンドボックス内で実行され、MCPを介して実際のツールを呼び出す

トラブルシューティング

タイムアウト問題: インタープリターがタイムアウトすると、不良状態に入る可能性があります。現在のところ、最善の解決策はサーバーを再起動するか、クライアントを再接続して新しいインタープリターインスタンスを取得することです。

ツールが見つからない: mcp_servers.jsonのパスが正しいことを確認し、Nodeベースのサーバーを使用する場合はnpm installを実行してください。

📚 参考文献

• DSpy Documentation
• Model Context Protocol
• FastMCP