JinDaGe - mcp-code-mode MCP Details

article

README

🚀 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客户端，连接到服务器，并运行一个测试任务，以确保代理和工具正常工作。

在运行脚本之前：

在mcp_servers.json中配置你要与之交互的MCP服务器。
通过编辑scripts/debug_executor.py中的task变量来定义你希望代理执行的特定任务。

python scripts/debug_executor.py

⚙️ 开发命令

| 命令 | 描述 | |---------|-------------| | pytest | 运行所有测试 | | ruff check . | 对代码库进行代码检查 | | black . | 格式化代码库 | | mypy src | 对源代码进行类型检查 | | python scripts/test_dspy_sandbox.py | 对沙箱进行健全性检查 | | 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实现面临着关键挑战：

上下文窗口膨胀：每个工具定义都会消耗令牌，限制了可扩展性。
令牌成本：多次来回调用工具成本高昂。
延迟：顺序调用工具会产生累积延迟。
可组合性：复杂的工作流需要许多离散的步骤。

代码模式通过利用大语言模型擅长的代码编写来解决这些问题。代理不是进行多次工具调用，而是编写一个Python脚本，在内部编排所有必要的操作。

🧩 核心组件

执行器服务器（FastMCP） (src/mcp_code_mode/executor_server.py) 该服务器公开一个由Python执行器（本地或Pyodide）支持的execute_code工具。使用fastmcp处理MCP协议，使用dspy进行执行逻辑。
配置驱动的发现 (mcp_servers.json) 系统使用mcp_servers.json显式配置要连接的MCP服务器。由src/mcp_code_mode/mcp_manager.py加载。
工具模式格式化 (src/mcp_code_mode/tool_formatter.py) 将发现的MCP工具格式化为可读的文档，并传递给代码生成大语言模型，以便它知道存在哪些工具。
上下文注入 格式化后的工具模式作为输入字段传递给大语言模型。大语言模型在编写代码之前就知道工具名称、参数和使用示例。

🔄 信息流

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。

mcp-code-mode