使用说明
MCP代码模式
使用DSpy的代码执行MCP服务器的原型实现。“使用MCP执行代码”架构将大型语言模型在代码生成方面的优势与用于工具集成的模型上下文协议相结合。该系统使AI代理能够编写在隔离沙箱中运行的Python代码，同时无缝调用外部MCP工具。
快速开始
1.安装
需要Python 3.11+和Node.js 20+。
# Create virtual environment
python3.11 -m venv .venv
source .venv/bin/activate
# Install dependencies
pip install -e .[dev]
# Install Node.js dependencies for reference servers
npm install -g npm@latest
2.配置
复制示例环境文件并配置secrets：
cp .env.example .env
在中配置MCP服务器 mcp_servers.json:
{
"servers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/your-working-folder"],
"description": "Local file system operations"
}
}
}
3.运行服务器
启动代码执行MCP服务器：
python -m mcp_code_mode.executor_server
4.验证
通过运行调试执行器脚本验证您的设置。此脚本模拟MCP客户端，连接到服务器，并运行测试任务以确保代理和工具正常工作。
在运行脚本之前：
- 在中配置要与之交互的MCP服务器
mcp_servers.json. - 通过编辑
task变量inscripts/debug_executor.py.
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).
违规行为返回a POLICY_VIOLATION 错误。
备注：您可以通过设置强制使用Pyodide沙盒
MCP_EXECUTOR=pyodide，但这可能会中断工具调用，具体取决于您的环境。
建筑
概述
┌─────────────────────────────────────────────────────────────┐
│ MCP Client (Claude, etc.) │
└────────────────────────┬────────────────────────────────────┘
│ MCP Protocol (stdio/HTTP/SSE)
▼
┌─────────────────────────────────────────────────────────────┐
│ FastMCP Server │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ @mcp.tool │ │
│ │ async def execute_code(code: str): │ │
│ │ # 1. Execute in Local Executor (default) │ │
│ │ result = await executor.run(code) │ │
│ │ return result │ │
│ └──────────────────────────────────────────────────────┘ │
└────────────────────────┬────────────────────────────────────┘
│
▼
┌──────────────────────────────┐
│ Execution Engine: │
│ • LocalPythonExecutor │
│ (or Pyodide Sandbox) │
└──────────────────────────────┘
为什么是代码模式？
传统的MCP实施面临着严峻的挑战：
- 上下文窗口块：每个工具定义都消耗令牌，限制了可扩展性。
- 代币成本：多次来回的工具调用成本很高。
- 延迟：连续的工具调用会产生累积延迟。
- 可组合性：复杂的工作流程需要许多离散的步骤。
代码模式通过利用LLM的专长来解决这些问题：编写代码。代理编写一个Python脚本，在内部协调所有必要的操作，而不是进行多个工具调用。
核心组件
-
执行服务器（FastMCP） (
src/mcp_code_mode/executor_server.py) 服务器公开了一个execute_code由Python执行器（Local或Pyodide）支持的工具。用途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工具格式化为可读的文档，并传递给代码生成LLM，以便它知道存在哪些工具。 -
上下文注入 格式化的工具模式作为输入字段传递给LLM。LLM知道工具名称、参数和使用示例 之前 它编写代码。
信息流
1. mcp_servers.json (Defines servers)
↓
2. MCPServerManager.initialize()
├─ Connect to configured servers
├─ Call list_tools() on each
└─ Convert to DSpy tools
↓
3. ToolSchemaFormatter.format_for_llm()
└─ Creates readable documentation
↓
4. CodeExecutionAgent
└─ Stores both callable tools and schemas
↓
5. Agent Generation
└─ Passes tool_context to LLM
↓
6. Code Execution
└─ Code runs in sandbox, calling actual tools via MCP
故障排除
超时问题: 如果解释器超时，它可能会进入不良状态。目前，最好的解决方案是重新启动服务器或重新连接客户端以获取新的解释器实例。
缺少工具:
确保 mcp_servers.json 路径正确，并且您已经运行 npm install 如果使用基于节点的服务器。
