MCP Code Mode

🚀 MCP代碼模式

MCP代碼模式是使用DSpy實現代碼執行MCP服務器的原型。“基於MCP的代碼執行”架構結合了大語言模型在代碼生成方面的優勢以及用於工具集成的模型上下文協議。該系統使AI代理能夠編寫在隔離沙箱中運行的Python代碼，同時無縫調用外部MCP工具。

🚀 快速開始

📦 安裝

需要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

⚙️ 配置

複製示例環境文件並配置密鑰：

cp .env.example .env

在mcp_servers.json中配置你的MCP服務器：

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/your-working-folder"],
      "description": "本地文件系統操作"
    }
  }
}

▶️ 啟動服務器

啟動代碼執行MCP服務器：

python -m mcp_code_mode.executor_server

✅ 驗證

通過運行調試執行器腳本驗證你的設置。此腳本模擬一個MCP客戶端，連接到服務器，並運行一個測試任務，以確保代理和工具正常工作。

在運行腳本之前：

1. 在mcp_servers.json中配置你要與之交互的MCP服務器。
2. 通過編輯scripts/debug_executor.py中的task變量來定義你希望代理執行的特定任務。

python scripts/debug_executor.py

⚙️ 開發命令

🛡️ 執行環境與防護機制

默認情況下，系統使用本地Python執行器 (LocalPythonExecutor)，它在與服務器相同的進程中運行代碼。這是必要的，因為嚴格的Pyodide沙箱在網絡I/O方面存在限制，在某些環境中無法回調到其他MCP工具。

🛠️ 防護機制

即使使用本地執行器，系統在代碼執行前也會強制執行策略：

• 限制：最大8000個字符 / 400行。
• 導入：僅允許白名單中的模塊（如json、math、re、datetime等）。
• 令牌：禁止使用可能危險的令牌（如subprocess、exec、eval）。

違反這些策略將返回POLICY_VIOLATION錯誤。

⚠️ 重要提示

你可以通過設置MCP_EXECUTOR=pyodide強制使用Pyodide沙箱，但這可能會根據你的環境中斷工具調用。

🏗️ 架構

🌟 概述

┌─────────────────────────────────────────────────────────────┐
│                   MCP客戶端（Claude等）                   │
└────────────────────────┬────────────────────────────────────┘
                         │ MCP協議（標準輸入輸出/HTTP/SSE）
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                    FastMCP服務器                            │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  @mcp.tool                                           │  │
│  │  async def execute_code(code: str):                 │  │
│  │      # 1. 在本地執行器中執行（默認）                 │  │
│  │      result = await executor.run(code)              │  │
│  │      return result                                   │  │
│  └──────────────────────────────────────────────────────┘  │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
          ┌──────────────────────────────┐
          │    執行引擎：               │
          │  • 本地Python執行器          │
          │    （或Pyodide沙箱）         │
          └──────────────────────────────┘

❓ 為什麼使用代碼模式？

傳統的MCP實現面臨著關鍵挑戰：

1. 上下文窗口膨脹：每個工具定義都會消耗令牌，限制了可擴展性。
2. 令牌成本：多次來回調用工具成本高昂。
3. 延遲：順序調用工具會產生累積延遲。
4. 可組合性：複雜的工作流需要許多離散的步驟。

代碼模式通過利用大語言模型擅長的代碼編寫來解決這些問題。代理不是進行多次工具調用，而是編寫一個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工具格式化為可讀的文檔，並傳遞給代碼生成大語言模型，以便它知道存在哪些工具。

4. 上下文注入 格式化後的工具模式作為輸入字段傳遞給大語言模型。大語言模型在編寫代碼之前就知道工具名稱、參數和使用示例。

🔄 信息流

1. mcp_servers.json（定義服務器）
   ↓
2. MCPServerManager.initialize()
   ├─ 連接到配置的服務器
   ├─ 對每個服務器調用list_tools()
   └─ 轉換為DSpy工具
   ↓
3. ToolSchemaFormatter.format_for_llm()
   └─ 創建可讀的文檔
   ↓
4. CodeExecutionAgent
   └─ 存儲可調用的工具和模式
   ↓
5. 代理生成
   └─ 將工具上下文傳遞給大語言模型
   ↓
6. 代碼執行
   └─ 代碼在沙箱中運行，通過MCP調用實際工具

🐞 故障排除

超時問題： 如果解釋器超時，它可能會進入錯誤狀態。目前，最好的解決方法是重啟服務器或重新連接客戶端以獲取新的解釋器實例。

工具缺失問題： 確保mcp_servers.json中的路徑正確，並且如果你使用基於Node的服務器，請運行npm install。

📚 參考資料

• DSpy文檔
• 模型上下文協議
• FastMCP