MCP 代码模式

使用 DSpy 实现的代码执行 MCP 服务器原型。"代码执行与 MCP" 架构结合了大型语言模型在代码生成方面的优势以及用于工具集成的模型上下文协议。该系统使 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. 运行服务器

启动代码执行 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

开发命令

命令	描述
pytest	运行所有测试
ruff check .	检查代码库
black .	格式化代码库
mypy src	源码类型检查
python scripts/test_dspy_sandbox.py	检查沙箱
python scripts/debug_executor.py	使用模拟客户端进行集成测试

执行环境及防护措施

默认情况下，系统使用 本地 Python 执行器 (LocalPythonExecutor)，它在同一进程中运行代码。这是因为严格的 Pyodide 沙箱在网络 I/O 方面存在限制，这可能会阻止其在某些环境中调用其他 MCP 工具。

防护措施

即使使用本地执行器，系统也会在代码执行前实施策略：

• 限制：最多 8k 字符 / 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 沙箱)         │
          └──────────────────────────────┘

为什么选择代码模式？

传统的 MCP 实现面临关键挑战：

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

代码模式通过利用 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，使其知道有哪些工具存在。

4. 上下文注入 格式的工具模式作为输入字段传递给 LLM。LLM 在编写代码之前就知道工具名称、参数和使用示例。

信息流

1. mcp_servers.json (定义服务器)
   ↓
2. MCPServerManager.initialize()
   ├─ 连接到配置的服务器
   ├─ 对每个服务器调用 list_tools()
   └─ 转换为 DSpy 工具
   ↓
3. ToolSchemaFormatter.format_for_llm()
   └─ 创建可读文档
   ↓
4. CodeExecutionAgent
   └─ 存储可调用工具和模式
   ↓
5. 代理生成
   └─ 将 tool_context 传递给 LLM
   ↓
6. 代码执行
   └─ 代码在沙箱中运行，通过 MCP 调用实际工具

故障排除

超时问题： 如果解释器超时，可能会进入不良状态。目前最好的解决方法是重启服务器或重新连接客户端以获取新的解释器实例。

缺少工具： 确保 mcp_servers.json 路径正确，并且如果你使用基于 Node 的服务器，请运行 npm install。

参考资料

• DSpy 文档
• 模型上下文协议
• FastM MCP

mcp-code-mode