Code Executor MCP

🚀 Code Executor MCP

Code Executor MCP 打破了只能使用 2 - 3 個 MCP 服務器的限制。它憑藉單一的 MCP 便能統籌全局，實現高達 98% 的令牌節省，讓你無需擔憂上下文耗盡的問題，可無限制地訪問各類工具。

🚀 快速開始

選項 1：交互式設置嚮導（推薦）

無需手動配置，我們的嚮導將為你完成一切：

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

嚮導的功能如下：

1. 🔍 掃描現有的 MCP 配置（Claude Code 的 ~/.claude.json、Cursor 的 ~/.cursor/mcp.json 以及項目的 .mcp.json）
2. ⚙️ 使用智能默認值進行配置（也可交互式自定義）
3. 🤖 新增功能：寫入完整的 MCP 配置（採樣 + 安全 + 沙箱 + 性能）
4. 📦 生成類型安全的 TypeScript/Python 包裝器，以實現自動補全
5. 📅 可選：設置每日同步，以自動更新包裝器

完整配置（全部自動寫入）：

• AI 採樣：支持多供應商（Anthropic、OpenAI、Gemini、Grok、Perplexity）
• 安全：審計日誌、內容過濾、項目限制
• 沙箱：帶有超時設置的 Deno/Python 執行環境
• 性能：速率限制、模式緩存、執行超時

智能默認值（只需按回車鍵）：

• 端口：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' });

好處：

• ✅ 類型安全，具備完整的智能感知/自動補全功能
• ✅ 帶有來自模式的自文檔化 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（項目配置會覆蓋全局配置中重複的名稱）

將以下內容添加到你的 項目 .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);

就是這麼簡單，無需配置、無需白名單、無需手動設置工具。

✨ 主要特性

📦 安裝指南

npm（推薦）

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

Docker（生產環境）

快速開始：

docker pull aberemia24/code-executor-mcp:latest
docker run -p 3333:3333 aberemia24/code-executor-mcp:latest

使用 docker-compose（推薦）：

# 1. 複製示例配置
cp docker-compose.example.yml docker-compose.yml

# 2. 編輯 docker-compose.yml 以添加你的 API 密鑰（可選）
#    - 設置 CODE_EXECUTOR_SAMPLING_ENABLED="true"
#    - 設置你的供應商：CODE_EXECUTOR_AI_PROVIDER="gemini"
#    - 添加 API 密鑰：GEMINI_API_KEY="your-key-here"

# 3. 啟動服務
docker-compose up -d

# 4. 查看日誌
docker-compose logs -f

首次運行自動配置： Docker 部署會在首次運行時根據環境變量自動生成完整的 MCP 配置：

• ✅ 所有環境變量 → 全面的配置
• ✅ 包括採樣、安全、沙箱和性能設置
• ✅ 配置保存到 /app/config/.mcp.json
• ✅ 在容器重啟時保持持久化（使用卷掛載）

本地開發

git clone https://github.com/aberemia24/code-executor-MCP.git
cd code-executor-mcp
npm install && npm run build
npm run server

💻 使用示例

基礎用法

# 之前：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

高級用法

// 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 });

實際示例

任務：“審查 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: 'fix: 常量時間令牌比較'
});

console.log('安全修復已應用並提交');

所有操作只需一次工具調用。變量會持續存在，無需上下文切換。

📚 詳細文檔

MCP 採樣（Beta） - 循環內大語言模型執行

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='') - 多輪對話

安全控制

採樣包含企業級安全控制：

配置

啟用採樣：

選項 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 會自動檢測最佳採樣方法：

1. MCP SDK 採樣（免費） - 如果你的 MCP 客戶端支持 sampling/createMessage
2. 直接 Anthropic API（付費） - 如果 MCP 採樣不可用，則回退到此模式（需要 ANTHROPIC_API_KEY）

⚠️ Claude Code 限制（截至 2025 年 11 月）： Claude Code 目前 不支持 MCP 採樣（問題 #1785）。使用 Claude Code 時，採樣將回退到直接 API 模式（需要 ANTHROPIC_API_KEY）。

支持 MCP 採樣的兼容客戶端：

• ✅ VS Code（v0.20.0+）
• ✅ GitHub Copilot
• ❌ Claude Code（待解決問題 #1785）

當 Claude Code 增加採樣支持時，無需更改代碼 - 它將自動切換到免費的 MCP 採樣。

文檔

請參閱全面的採樣指南：docs/sampling.md

涵蓋內容：

• 架構圖解釋採樣的原理、原因和方法
• TypeScript 和 Python 的完整 API 參考
• 帶有威脅矩陣的安全模型
• 配置指南（環境變量、配置文件、每次執行）
• 故障排除指南（8 個常見錯誤）
• 性能基準測試（橋接啟動時間 <50ms）
• 常見問題解答（15 個以上問題）

配置

完整示例 (.mcp.json)：

{
  "mcpServers": {
    "code-executor": {
      "command": "npx",
      "args": ["-y", "code-executor-mcp"],
      "env": {
        "MCP_CONFIG_PATH": "/absolute/path/to/.mcp.json",
        "DENO_PATH": "/home/user/.deno/bin/deno",
        "ENABLE_AUDIT_LOG": "true",
        "AUDIT_LOG_PATH": "/home/user/.code-executor/audit.log",
        "ALLOWED_PROJECTS": "/home/user/projects:/tmp"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
    },
    "zen": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/zen-mcp.git", "zen-mcp-server"],
      "env": {
        "GEMINI_API_KEY": "your-key-here"
      }
    }
  }
}

環境變量：

安全注意事項：將 API 密鑰存儲在環境變量中，而不是直接存儲在配置文件中。

多供應商 AI 採樣配置

新增功能：支持 5 個 AI 供應商（Anthropic、OpenAI、Gemini、Grok、Perplexity），並自動選擇特定供應商的模型。

快速設置：

# 1. 複製示例配置
cp .env.example .env

# 2. 編輯 .env 文件並添加你的 API 密鑰
CODE_EXECUTOR_SAMPLING_ENABLED=true
CODE_EXECUTOR_AI_PROVIDER=gemini  # 最便宜的選項！
GEMINI_API_KEY=your-key-here

# 3. 啟動服務器
npm start

供應商比較（2025 年 1 月）：

配置選項：請參閱 .env.example 以獲取完整的採樣配置選項列表，包括：

• 所有供應商的 API 密鑰
• 模型白名單
• 速率限制和配額
• 內容過濾
• 系統提示控制

自動發現（v0.7.3 新增功能）：Code-executor 會自動發現併合並：

• ~/.claude.json（全局/個人 MCP）
• .mcp.json（項目 MCP）
• MCP_CONFIG_PATH（如果設置）（顯式覆蓋，但仍會與全局配置合併）

無需配置 - 只需將 MCP 添加到任一位置，code-executor 就會找到它們！

🔧 技術細節

TypeScript 支持

包含完整的類型定義：

import { MCPClientPool, executeTypescript, type ToolSchema } from 'code-executor-mcp';

const pool = new MCPClientPool();
await pool.initialize('/path/to/.mcp.json');

const result = await executeTypescript({
  code: `const tools = await discoverMCPTools(); console.log(tools.length);`,
  allowedTools: ['mcp__*'],
  timeoutMs: 30000
});

性能

安全（企業級）

Code Executor 不僅能“運行代碼”，還能保障代碼安全：

示例：除 GitHub API 外，阻止所有網絡訪問：

{
  "security": {
    "allowedDomains": ["api.github.com"],
    "allowedProjects": ["/home/user/projects"]
  }
}

沙箱架構：

• Deno（TypeScript）：V8 隔離環境，具有顯式權限（--allow-read=/tmp），無 shell 訪問權限
• Pyodide（Python）：WebAssembly 沙箱，虛擬文件系統，網絡訪問僅限於經過身份驗證的 MCP 代理
• Docker（可選）：非根容器，只讀根文件系統，最小化攻擊面

請參閱 SECURITY.md 以獲取完整的威脅分析和安全模型。

高級用法

白名單（可選安全措施）

限制可執行的工具：

await callMCPTool('mcp__code-executor__run-typescript-code', {
  code: `
    // 此操作可行
    await callMCPTool('mcp__filesystem__read_file', {...});

    // 此操作失敗 - 不在白名單中
    await callMCPTool('mcp__git__push', {...});
  `,
  allowedTools: ['mcp__filesystem__read_file']
});

發現功能

AI 代理可以按需探索可用工具：

// 查找所有工具
const tools = await discoverMCPTools();

// 搜索特定功能
const fileTools = await searchTools('文件讀寫');

// 檢查模式
const schema = await getToolSchema('mcp__filesystem__read_file');

零令牌成本 - 發現功能不會顯示在 AI 代理的工具列表中。

MCP 採樣：循環內大語言模型執行

允許 AI 在沙箱代碼中自主調用其他 AI，以實現迭代問題解決、多智能體協作和複雜工作流。

關鍵特性：

• 多供應商支持：Anthropic、OpenAI、Gemini、Grok、Perplexity
• 混合模式：免費的 MCP 採樣，自動回退到付費 API
• 簡單 API：llm.ask(prompt) 和 llm.think(messages) 輔助函數
• 安全保障：速率限制、內容過濾、僅本地訪問的橋接服務器

設置：

# 1. 創建 .env 文件
cp .env.example .env

# 2. 添加 API 密鑰
echo "CODE_EXECUTOR_SAMPLING_ENABLED=true" >> .env
echo "CODE_EXECUTOR_AI_PROVIDER=gemini" >> .env
echo "GEMINI_API_KEY=your_key_here" >> .env

# 3. 使用包裝腳本（在啟動前加載 .env）
# 更新 .mcp.json：
{
  "code-executor": {
    "command": "/path/to/start-with-env.sh"
  }
}

請參閱 以獲取完整的設置指南。

基本用法：

// 簡單問題
const answer = await llm.ask('2 + 2 等於多少？');
console.log(answer); // "4"

// 多輪推理
const analysis = await llm.think([
  { role: 'system', content: '你是一名代碼審查員' },
  { role: 'user', content: '審查這段代碼：...' }
]);

高級示例 - 多智能體代碼審查： 5 個 AI 智能體協作審查、保障安全、重構、測試和文檔化代碼：

// 智能體 1：代碼審查員
const review = await llm.ask('審查這段代碼並列出 5 個問題...');

// 智能體 2：安全分析師
const security = await llm.ask('分析安全漏洞...');

// 智能體 3：重構專家
const refactored = await llm.ask('使用 ES6+ 進行重構...');

// 智能體 4：測試生成器
const tests = await llm.ask('生成 3 個 Vitest 測試用例...');

// 智能體 5：文檔編寫員
const docs = await llm.ask('編寫 JSDoc 註釋...');

實際結果：

• 5 個 AI 智能體，10 秒，約 2600 個令牌
• 完整的代碼轉換：審查 → 保障安全 → 重構 → 測試 → 文檔化
• 請參閱 以獲取完整的工作示例

用例：

• 🤖 多智能體系統（代碼審查、規劃、執行）
• 🔄 迭代優化（生成 → 驗證 → 改進循環）
• 🧪 自主測試（生成測試用例、運行測試、修復失敗）
• 📚 自動文檔化（分析代碼、編寫文檔、驗證示例）

多動作工作流

在一次工具調用中實現複雜的自動化：

// 啟動瀏覽器 → 導航 → 交互 → 提取數據
await callMCPTool('mcp__code-executor__run-typescript-code', {
  code: `
    await callMCPTool('mcp__playwright__launch', { headless: false });
    await callMCPTool('mcp__playwright__navigate', { url: 'https://example.com' });
    const title = await callMCPTool('mcp__playwright__evaluate', {
      script: 'document.title'
    });
    console.log('頁面標題:', title);
  `,
  allowedTools: ['mcp__playwright__*']
});

狀態在調用之間保持持久 - 無需上下文切換。

Python 執行（Pyodide WebAssembly）

使用 Pyodide 沙箱實現安全的 Python 執行：

啟用 Python：

# 設置環境變量（必需）
export PYTHON_SANDBOX_READY=true

# 在配置中啟用
# .code-executor.json
{
  "executors": {
    "python": {
      "enabled": true
    }
  }
}

示例 - 使用 MCP 工具的 Python 代碼：

import asyncio

async def main():
    # 發現可用工具
    tools = await discover_mcp_tools()
    print(f'找到 {len(tools)} 個工具')

    # 調用 MCP 工具讀取文件
    content = await call_mcp_tool('mcp__filesystem__read_file', {
        'path': '/tmp/data.json'
    })
    print(f'文件內容: {content}')

    # 處理數據
    import json
    data = json.loads(content)
    result = [x * 2 for x in data['numbers']]
    print(f'處理結果: {result}')

asyncio.run(main())

安全保障：

• ✅ WebAssembly 沙箱（與 Deno 具有相同的安全性）
• ✅ 虛擬文件系統（無主機文件訪問）
• ✅ 網絡訪問僅限於經過身份驗證的 MCP 代理
• ✅ 無子進程生成
• ✅ 內存受 V8 堆限制

限制：

• 僅支持純 Python（除非經過 WASM 編譯，否則不支持原生 C 擴展）
• 首次加載約 2 - 3 秒（Pyodide npm 包），緩存後 <100ms
• 不支持多進程/線程（使用 async/await）
• 比原生 Python 慢 10 - 30%（為了安全，WASM 開銷可以接受）

請參閱 SECURITY.md 以獲取完整的安全模型。

📄 許可證

本項目採用 MIT 許可證，請參閱 LICENSE 瞭解詳細信息。

常見問題解答

Q：是否需要為每個 MCP 服務器進行配置？ A：不需要。Code-executor 會自動從 ~/.claude.json（全局）和 .mcp.json（項目）中發現 MCP。只需將 MCP 添加到任一位置即可。

Q：全局配置和項目配置如何合併？ A：Code-executor 會找到併合並兩者：

• 全局 (~/.claude.json)：可在所有項目中使用的個人 MCP
• 項目 (.mcp.json)：版本控制中團隊共享的 MCP
• 結果：所有 MCP 都可用，項目配置會覆蓋全局配置中重複的名稱

Q：驗證是如何工作的？ A：AJV 會根據即時模式驗證所有工具調用。發生錯誤時，你會收到一條詳細的消息，顯示預期的參數。

Q：Python 支持情況如何？ A：通過 Pyodide WebAssembly 提供完整的 Python 沙箱。需要設置 PYTHON_SANDBOX_READY=true 環境變量。與 Deno 具有相同的安全模型（WASM 隔離、虛擬文件系統、網絡受限）。僅支持純 Python - 除非經過 WASM 編譯，否則不支持原生 C 擴展。請參閱 SECURITY.md 瞭解詳細信息。

Q：是否可以在生產環境中使用？ A：可以。有 606 個測試用例，覆蓋率達 95% 以上，支持 Docker，有審計日誌和速率限制。

Q：它是否僅適用於 Claude Code？ A：它是為 Claude Code 構建的。雖然未在其他 MCP 客戶端上進行測試，但根據 MCP 規範應該可以正常工作。

貢獻

歡迎貢獻代碼！請參閱 CONTRIBUTING.md 瞭解貢獻指南。

代碼質量標準：

• ✅ TypeScript 嚴格模式
• ✅ 業務邏輯的測試覆蓋率達 90% 以上
• ✅ ESLint + Prettier
• ✅ 所有拉取請求都必須通過測試

鏈接

• npm：https://www.npmjs.com/package/code-executor-mcp
• Docker Hub：https://hub.docker.com/r/aberemia24/code-executor-mcp
• GitHub：https://github.com/aberemia24/code-executor-MCP
• 問題反饋：https://github.com/aberemia24/code-executor-MCP/issues

使用 Claude Code 構建 | 基於 Anthropic 的 MCP 代碼執行

星標歷史