代码执行器-MCP

Name: 代码执行器-MCP
Author: aberemia24

作者：aberemia24105 星标更新：2025-11-23

安装使用来源：spider==github.com

项目介绍

Code Executor MCP

不要再被2-3个MCP服务器限制了。 一个MCP来协调所有工具 - 节省98%的令牌，无限访问工具。

为什么使用 Code Executor MCP？

98% 令牌减少 - 从141k减少到1.6k令牌（加载1个执行器而不是50多个工具）
沙箱安全 - 隔离的 Deno/Python 执行，默认无互联网连接，审计日志
类型安全包装器 - 自动生成带有完整 IntelliSense 的 TypeScript/Python SDK
逐步披露 - 工具按需在沙箱中加载，而不是一次性加载到上下文中
零配置设置 - 向导自动检测来自 Claude Code/Cursor 的现有 MCP 服务器
生产就绪 - 606 项测试，覆盖率超过 95%，支持 Docker 和速率限制

问题

在上下文耗尽之前，你不能使用超过2-3个MCP服务器。

研究证实： 超过2-3个服务器后工具准确性显著下降
有6,490多个MCP服务器可用，但你只能使用2-3个
47个工具 = 141k令牌 在你写第一个单词之前就已经消耗完了

你被迫选择： 文件系统 OR 浏览器 OR Git OR AI 工具。永远不可能全部使用。

解决方案

禁用所有MCP。仅启用 code-executor-mcp。

# 之前：47个工具，141k令牌
mcp__filesystem__read_file
mcp__filesystem__write_file
mcp__git__commit
mcp__browser__navigate
... 更多43个工具

# 之后：2个工具，1.6k令牌（98%减少）
run-typescript-code
run-python-code

在沙箱内，按需访问任何MCP工具：

// Claude 自动编写
const file = await callMCPTool('mcp__filesystem__read_file', { path: '/src/app.ts' });
const review = await callMCPTool('mcp__zen__codereview', { code: file });
await callMCPTool('mcp__git__commit', { message: review.suggestions });

结果： 无限MCP访问，零上下文开销。

如何逐步披露工作

sequenceDiagram
    participant C as Claude/Cursor
    participant E as Code Executor
    participant M as 其他 MCPs

    Note over C: ❌ 传统方式：加载50+工具（141k令牌）

    Note over C: ✅ Code Executor 方式：加载2个工具（1.6k令牌）
    C->>E: run-typescript-code

    rect rgb(240, 248, 255)
        Note right of E: 沙箱（按需发现）
        E->>M: callMCPTool('mcp__filesystem__read_file')
        M-->>E: 返回数据
    end

    E-->>C: 返回结果

传统MCP提前暴露所有47个工具（141k令牌）。Code Executor 提前暴露2个工具（1.6k令牌），并在需要时在沙箱内按需加载其他工具。

快速开始

选项1：交互式设置向导（推荐）

不要手动配置。我们的向导会处理一切：

npm install -g code-executor-mcp
code-executor-mcp setup

向导做了什么：

🔍 扫描现有的MCP配置（Claude Code ~/.claude.json，Cursor ~/.cursor/mcp.json，项目 .mcp.json）
⚙️ 使用智能默认值进行配置（或交互式自定义）
🤖 新功能：写入完整的MCP配置（采样 + 安全 + 沙箱 + 性能）
📦 生成类型安全的TypeScript/Python包装器以实现自动完成功能
📅 可选：设置每日同步以保持包装器更新

完整配置（所有内容都会自动写入）：

AI采样：多提供商支持（Anthropic，OpenAI，Gemini，Grok，Perplexity）
安全：审计日志，内容过滤，项目限制
沙箱：Deno/Python执行带有时限
性能：速率限制，模式缓存，执行时限

智能默认值（只需按Enter键）：

端口：3333 | 超时：120秒 | 速率限制：每分钟60次
审计日志：~/.code-executor/audit-logs/
采样：禁用（可选通过API密钥启用）

支持的AI工具：Claude Code 和 Cursor（更多即将推出）

首次运行检测： 如果你尝试运行 code-executor-mcp 而没有配置：

❌ 未找到MCP配置

📝 要配置 code-executor-mcp，请运行：
   code-executor-mcp setup

配置将在以下位置创建：~/.claude.json

包装器是什么？

向导会为你的MCP工具生成TypeScript/Python包装器函数：

之前（手动）：

const file = await callMCPTool('mcp__filesystem__read_file', {
  path: '/src/app.ts'
});

之后（包装器）：

import { filesystem } from './mcp-wrappers';
const file = await filesystem.readFile({ path: '/src/app.ts' });

好处：

✅ 类型安全并具有完整的IntelliSense/自动完成功能
✅ 自我文档化的JSDoc注释来自模式
✅ 不需要记住确切的工具名称
✅ 匹配实际的MCP工具API（根据模式生成）

保持包装器更新：

向导可以设置每日同步（可选）以自动重新生成包装器：

macOS：launchd plist 在凌晨4-6点运行
Linux：systemd定时器在凌晨4-6点运行
Windows：任务计划程序在凌晨4-6点运行

每日同步会重新扫描你的AI工具配置和项目配置，以查找新增或移除的MCP服务器。你也可以随时手动更新，只需运行 code-executor-mcp setup。

选项2：手动配置

1. 安装

npm install -g code-executor-mcp

2. 配置

重要：Code-executor 会发现并合并来自两个位置的MCP服务器：

全局：~/.claude.json（跨项目的MCP，如语音模式，个人工具）
项目：.mcp.json（团队共享的MCP，在项目根目录下）

配置合并：全局MCP + 项目MCP = 所有可用（项目配置覆盖全局同名配置）

添加到你的项目 .mcp.json 或全局 ~/.claude.json：

{
  "mcpServers": {
    "code-executor": {
      "command": "npx",
      "args": ["-y", "code-executor-mcp"],
      "env": {
        "MCP_CONFIG_PATH": "/full/path/to/this/.mcp.json",
        "DENO_PATH": "/path/to/.deno/bin/deno"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp", "--headless"]
    }
  }
}

配置指南：

MCP_CONFIG_PATH：可选 - 指向项目 .mcp.json（仍然会发现全局 ~/.claude.json）
DENO_PATH：运行 which deno 查找它（用于TypeScript执行）
全局MCP (~/.claude.json)：跨所有项目的个人服务器
项目MCP (.mcp.json)：版本控制下的团队共享服务器
连接流程：Claude Code → code-executor 仅此而已，然后 code-executor → 所有其他MCP

快速设置：

# 查找Deno路径
which deno
# 输出：/home/user/.deno/bin/deno

# 项目配置（团队共享）
realpath .mcp.json
# 输出：/home/user/projects/myproject/.mcp.json

# 全局配置（个人）
ls ~/.claude.json
# 输出：/home/user/.claude.json

# Code-executor 自动合并两者！

最小配置（仅Python）：

{
  "mcpServers": {
    "code-executor": {
      "command": "npx",
      "args": ["-y", "code-executor-mcp"],
      "env": {
        "MCP_CONFIG_PATH": "/path/to/.mcp.json",
        "PYTHON_ENABLED": "true"
      }
    }
  }
}

3. 使用

Claude现在可以通过代码执行访问任何MCP工具：

// 当你请求“读取 package.json”时，Claude 会写这个
const result = await callMCPTool('mcp__filesystem__read_file', {
  path: './package.json'
});
console.log(result);

就这样。无需配置，无需允许列表，无需手动工具设置。

实际案例

任务："审查 auth.ts 中的安全问题并提交修复"

没有 code-executor（不可能 - 达到上下文限制）：

无法启用：文件系统 + Git + Zen 代码审查
选择2个，手动完成第3个

有了 code-executor（单个AI消息）：

// 读取文件
const code = await callMCPTool('mcp__filesystem__read_file', {
  path: '/src/auth.ts'
});

// 使用AI进行审查
const review = await callMCPTool('mcp__zen__codereview', {
  step: '安全审核',
  code: code,
  step_number: 1,
  total_steps: 1
});

// 应用修复
const fixed = review.suggestions.replace(/timing-attack/g, 'constant-time');

await callMCPTool('mcp__filesystem__write_file', {
  path: '/src/auth.ts',
  content: fixed
});

// 提交
await callMCPTool('mcp__git__commit', {
  message: '修复：常数时间令牌比较'
});

console.log('安全修复已应用并提交');

所有操作在一个工具调用中完成。 变量持久化，无需上下文切换。

功能

功能	描述
98% 令牌节省	141k → 1.6k令牌（47个工具 → 2个工具）
无限MCP	访问6,490+ MCP服务器，不受上下文限制
多步骤工作流	在一次执行中链接多个MCP调用
自动发现	AI代理按需查找工具（0令牌成本）
深度验证	AJV模式验证，附带有用的错误消息
安全	沙箱（Deno/Python），允许列表，审计日志，速率限制
生产就绪	TypeScript，606项测试，覆盖率超过95%，支持Docker

MCP采样（测试版） - LLM-in-the-Loop执行

v1.0.0 新增：启用Claude在代码执行期间调用自身，进行动态推理和分析。

什么是采样？

MCP采样允许在隔离环境中运行的TypeScript和Python代码通过简单接口调用Claude（通过Anthropic的API）。你的代码现在可以在执行中途“请求Claude的帮助”。

使用场景：

代码分析：读取文件，请求Claude分析其中的安全问题
多步推理：让Claude将复杂任务分解成步骤
数据处理：每个文件/记录都由Claude的智能处理
交互式调试：请求Claude解释错误或建议修复

快速示例

TypeScript：

// 在执行中启用采样
const result = await callMCPTool('mcp__code-executor__executeTypescript', {
  code: `
    // 读取文件
    const code = await callMCPTool('mcp__filesystem__read_file', {
      path: './auth.ts'
    });

    // 请求Claude进行分析
    const analysis = await llm.ask(
      '分析这段代码中的安全漏洞：' + code
    );

    console.log(analysis);
  `,
  enableSampling: true,  // 启用采样
  allowedTools: ['mcp__filesystem__read_file']
});

// 检查采样指标
console.log('轮次：', result.samplingMetrics.totalRounds);
console.log('令牌：', result.samplingMetrics.totalTokens);

Python：

# Python示例，启用采样
code = """
import json

# 读取数据
data = call_mcp_tool('mcp__filesystem__read_file', {'path': './data.json'})

# 请求Claude进行总结
summary = await llm.ask(f'总结这些数据：{data}')

print(summary)
"""

result = call_mcp_tool('mcp__code-executor__executePython', {
    'code': code,
    'enableSampling': True
})

API参考

TypeScript API：

llm.ask(prompt: string, options?) - 简单查询，返回响应文本
llm.think({messages, model?, maxTokens?, systemPrompt?}) - 多轮对话

Python API：

llm.ask(prompt: str, system_prompt='', max_tokens=1000) - 简单查询
llm.think(messages, model='', max_tokens=1000, system_prompt='') - 多轮对话

安全控制

采样包括企业级安全控制：

控制	描述
速率限制	每次执行最多10轮，10,000个令牌（可配置）
内容过滤	自动屏蔽秘密（API密钥，令牌）和个人信息（电子邮件，SSN）
系统提示允许列表	只接受预先批准的提示（防止提示注入）
承载令牌认证	每个桥接会话256位安全令牌
本地绑定	桥接服务器仅本地可访问（无外部访问）
审计日志	所有调用记录SHA-256哈希（无明文秘密）

配置

启用采样：

选项1 - 每次执行（推荐）：

{ enableSampling: true }

选项2 - 环境变量：

export CODE_EXECUTOR_SAMPLING_ENABLED=true
export CODE_EXECUTOR_MAX_SAMPLING_ROUNDS=10
export CODE_EXECUTOR_MAX_SAMPLING_TOKENS=10000

选项3 - 配置文件（~/.code-executor/config.json）：

{
  "sampling": {
    "enabled": true,
    "maxRoundsPerExecution": 10,
    "maxTokensPerExecution": 10000,
    "allowedSystemPrompts": [
      "",
      "你是一个乐于助人的助手",
      "你是一个代码分析专家"
    ]
  }
}

混合架构

Code Executor 自动检测最佳采样方法：

MCP SDK 采样（免费） - 如果你的MCP客户端支持 sampling/createMessage
直接 Anthropic API（付费） - 如果MCP采样不可用（需要 ANTHROPIC_API_KEY）

⚠️ Claude Code 限制（截至2025年11月）： Claude Code 目前不支持MCP采样（Issue #1785）。使用Claude Code时，采样将回退到直接API模式（需要 ANTHROPIC_API_KEY）。

兼容采样的客户端：

✅ VS Code（v0.20.0+）
✅ GitHub Copilot
❌ Claude Code（等待 Issue #1785 解决）

当 Claude Code 添加采样支持时，不需要更改代码 - 它将自动切换到免费的MCP采样。

文档

参阅全面的采样指南：docs/sampling.md

涵盖：

什么是采样，为什么以及如何使用，附带架构图
完整的TypeScript和Python API参考
安全模型及威胁矩阵
配置指南（环境变量，配置文件，每次执行）
故障排除指南（8个常见错误）
性能基准（<50毫秒的桥接启动时间）
常见问题解答（15+个问题）

安全（企业级）

Code Executor 不仅仅是“运行代码”。它还确保代码的安全性