MCP CodeMode

一个开源且与平台无关的MCP代码模式实现，适用于沙箱环境。

灵感来源：

• Cloudflare的Code Mode - 将MCP工具转换为TypeScript API
• Anthropic的MCP代码执行 - 安全的代码执行模式

什么是Code Mode？

传统的MCP（模型上下文协议）使用方式直接将工具暴露给大语言模型（LLMs），需要它们明确调用工具。然而，正如Cloudflare发现的那样，LLMs在编写调用MCP的代码方面比直接调用MCP更擅长。

为什么是Code Mode？

1. LLMs擅长编写代码：它们已经在数百万的真实世界TypeScript示例上进行了训练，但仅限于合成的工具调用示例。
2. 处理更复杂的工具：当工具以TypeScript API的形式呈现时，LLMs可以处理更大和更复杂的工具集。
3. 高效的多步骤操作：无需将每个工具的结果反馈到LLM上下文中，LLMs可以编写将多个调用链接在一起的代码。
4. 更好的推理能力：编写代码对于LLMs来说是一种更自然的问题解决模式，而不是结构化的工具调用。

工作原理

这个库实现了复杂的六步流水线：

用户查询 → 假设代码计划 → 工具过滤 → TypeScript生成 
           → 代码实现 → 编译 → 沙箱执行

架构

系统使用三个专门的LLMs：

• 策略LLM：高级规划和伪代码生成（最强大的模型）
• 小型LLM：快速筛选大型工具目录（轻量级、快速模型）
• 主LLM：代码生成和实现（擅长编码的模型）

执行流程

1. 生成伪代码（策略LLM）：创建高级执行计划
2. 筛选工具（小型LLM）：从可能数千个选项中智能选择相关工具
3. 生成TypeScript接口：将筛选出的MCP工具转换为TypeScript API定义
4. 实现代码（主LLM）：使用生成的API编写实际的TypeScript代码
5. 验证编译：确保类型安全后再执行
6. 在沙箱中执行：在安全、隔离的环境中运行代码

安装

npm install mcp-codemode

快速开始

import { CodeModeMCP } from 'mcp-codemode';
import { OpenRouterClient } from 'mcp-codemode/model_clients';
import { ComposioProvider } from 'mcp-codemode/mcp_providers';
import { E2BRunEnvironment } from 'mcp-codemode/run_environments';

// 初始化OpenRouter客户端以访问LLM
const openRouterClient = new OpenRouterClient();

// 设置Composio与你的项目
const composioProvider = new ComposioProvider({
  projectId: 'your-project-id', // 可选：配置connectedAccountId和userId
});

// 配置三个专门的LLMs
const codeMode = new CodeModeMCP({
  llms: {
    tinyLLM: openRouterClient.getLLM('openai/gpt-oss-20b'),      // 快速筛选模型
    mainLLM: openRouterClient.getLLM('openai/gpt-oss-120b'),     // 代码生成模型
    strategyLLM: openRouterClient.getLLM('anthropic/claude-sonnet-4.5')  // 战略规划
  },
  tools: await composioProvider.getTools({ 
    toolkits: ['slack', 'gmail', 'github'] // 指定你需要的工具包
  }),
  runEnvironment: new E2BRunEnvironment(), // 安全云沙箱
  logPath: './prompt_logs' // 可选：记录所有LLM交互
});

// 执行复杂的多步骤任务
const result = await codeMode.runMCPCode({
  query: "获取Slack中的所有频道，并向以'test'开头的每个频道发送消息，在以'e'开头的频道中设置表情符号",
  maxToolCalls: 100,
  totalExecutionTimeout: 60,
  toolCallTimeout: 10
});

console.log(`执行结果: ${result.resultType}`);
console.log(`持续时间: ${result.totalDurationMs}ms`);

主要特性

🎯 智能工具筛选

在可能有数千种工具的情况下，小型LLM迅速筛选出仅相关的工具，减少上下文大小并提高准确性。

🏗️ 类型安全代码生成

所有生成的代码都是TypeScript，并在执行前进行完整的类型检查，提前捕获错误。

🔒 安全沙箱

支持多种执行环境：

• 本地：Node.js进程隔离
• E2B：用于生产的云沙箱
• 自定义：实现自己的IRunEnvironment

📊 全面可观测性

• 每个流水线步骤的详细计时报告
• 可选的日志记录所有LLM提示和响应
• 调试用的执行跟踪

🔌 灵活架构

• MCP提供者无关：与Composio、Pipedream或自定义提供者一起工作
• 模型无关：使用OpenAI、OpenRouter或遵循接口的任何LLM
• 环境无关：本地运行或在云端运行

配置选项

CodeModeMCPConfig

interface CodeModeMCPConfig {
  llms: {
    tinyLLM: LLMFunction;      // 快速筛选模型
    mainLLM: LLMFunction;      // 代码生成模型
    strategyLLM: LLMFunction;  // 规划模型
  };
  tools?: ToolCatalog;          // 分层工具目录
  mcpProvider?: IMCPProvider;   // 可选的MCP提供者
  runEnvironment?: IRunEnvironment; // 执行沙箱
  logPath?: string;             // 可选的日志目录
}

RunMCPCodeOptions

interface RunMCPCodeOptions {
  query?: string;                    // 用户任务描述
  maxToolCalls: number;              // 工具调用限制
  totalExecutionTimeout: number;     // 总超时时间（秒）
  toolCallTimeout: number;           // 每个工具超时时间（秒）
  maxToolsPerPrompt?: number;        // 每批筛选工具数量（默认：20）
  maxConcurrentThreads?: number;     // 并发筛选线程数（默认：5）
  includeDescriptionsInFilter?: boolean; // 在日志中包含工具描述
}

高级用法

自定义LLM集成

import { LLMFunction } from 'mcp-codemode/model_clients';

const myCustomLLM: LLMFunction = async (prompt: string): Promise<string> => {
  // 你的LLM集成在这里
  const response = await myLLMService.complete(prompt);
  return response.text;
};

const codeMode = new CodeModeMCP({
  llms: {
    strategyLLM: myCustomLLM,
    tinyLLM: myCustomLLM,
    mainLLM: myCustomLLM
  },
  // ... 其他配置
});

自定义运行环境

import { IRunEnvironment } from 'mcp-codemode/run_environments';

class MyCustomEnvironment implements IRunEnvironment {
  async execute(code: string): Promise<{ success: boolean; output: string }> {
    // 你的执行逻辑
  }
}

工具目录管理

// 列出所有可用工具
const toolPaths = codeMode.listToolPaths();
console.log(toolPaths); // ['slack.message.send', 'github.issues.create', ...]

// 获取特定工具
const tool = codeMode.getTool('slack.message.send');

// 更新目录
codeMode.setToolCatalog(newCatalog);

项目结构

src/
├── CodeModeMCP.ts           # 主协调类
├── steps/                   # 流水线步骤
│   ├── generatePseudocode.ts
│   ├── filterTools.ts
│   ├── generateToolsCode.ts
│   ├── implementCode.ts
│   └── executeCode.ts
├── model_clients/           # LLM集成
│   ├── openai.ts
│   └── openrouter.ts
├── run_environments/        # 执行沙箱
│   ├── local.ts
│   └── e2b.ts
└── mcp_providers/          # MCP服务器集成
    ├── composio.ts
    └── pipedream.ts

这为何重要

随着MCP的采用增加，代理将拥有数百或数千种工具的访问权限。传统的工具调用方法在规模上会失效：

• 上下文限制：无法将所有工具定义放入提示中
• 差的选择：LLMs难以从众多选项中选择正确的工具
• 低效的链接：每个工具的结果必须往返通过LLM

Code Mode通过利用LLMs最擅长的事情——编写代码——解决了这些问题。这个库提供了一个模块化、可扩展且平台无关的生产就绪实现。

贡献

这是一个完全免费且开放合作的仓库。欢迎贡献！

• 报告问题
• 提交拉取请求
• 建议改进
• 分享你的使用案例

许可证

MIT

学习更多

• Cloudflare的Code Mode公告
• Anthropic的MCP代码执行
• 模型上下文协议文档