MCP代码执行增强服务器

Name: MCP代码执行增强服务器
Author: yoloshii

作者：yoloshii16 星标更新：2025-11-21

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

项目介绍

MCP代码执行 - 增强版

通过基于CLI的脚本和逐步发现工具，实现对模型上下文协议（MCP）服务器的99.6%令牌减少。

注意： 该项目针对Claude Code进行了优化，支持原生技能。核心运行时与任何AI代理兼容。带有CLI参数的脚本实现了99.6%的令牌减少。

🎯 这是什么

这是一个增强版的Anthropic 代码执行与MCP模式的实现，针对Claude Code进行了优化，结合了MCP社区的最佳想法并增加了显著改进：

带CLI参数的脚本：可重用的Python工作流，具有命令行参数（99.6%令牌减少）
多传输：完全支持stdio、SSE和HTTP MCP服务器
容器沙箱：可选的无根隔离，带有安全控制
类型安全性：整个流程中使用Pydantic模型进行完整验证
生产就绪：129个通过测试，全面的错误处理

🤖 Claude Code集成

原生技能支持：此项目包括适当的Claude Code技能集成：

.claude/skills/ - 使用Claude Code原生格式的技能（SKILL.md + workflow.py）
自动发现 - Claude Code会自动找到并验证技能
两个通用示例 - 简单获取、多工具流水线（自定义工作流模板）
格式合规 - YAML前言，验证规则，逐步披露

双层架构：

第一层：Claude Code技能（.claude/skills/） - 原生发现和格式
第二层：脚本（./scripts/） - 带有argparse的CLI基础Python工作流

令牌效率：

核心运行时：98.7%减少（Anthropic的文件系统模式）
带CLI参数的脚本：99.6%减少（无需编辑文件）

注意：脚本与任何AI代理兼容。Claude Code技能为Claude Code用户提供原生自动发现。

🙏 致谢

这个项目建立并融合了以下想法：

ipdelete/mcp-code-execution - Anthropic PRIMARY模式的原始实现
- 基于文件系统的逐步披露
- 类型安全的Pydantic包装器
- 模式发现系统
- 惰性服务器连接
elusznik/mcp-server-code-execution-mode - 生产安全模式
- 容器沙箱架构
- 全面的安全控制
- 生产部署模式

我们的贡献：合并了两者最佳部分，添加了CLI基础脚本模式，实现了多传输支持，并优化了架构以达到最大效率。

✨ 关键增强

1. Claude Code技能集成（新）

原生技能格式在.claude/skills/目录中：

.claude/skills/
├── simple-fetch/
│   ├── SKILL.md        # YAML前言 + Markdown指令
│   └── workflow.py     # → 符号链接到../../scripts/simple_fetch.py
└── multi-tool-pipeline/
    ├── SKILL.md        # 多工具编排示例
    └── workflow.py     # → 符号链接到../../scripts/multi_tool_pipeline.py

如何工作：

Claude Code自动发现.claude/skills/中的技能
读取SKILL.md（遵循Claude Code的格式规范）
执行workflow.py（这是一个脚本），带有CLI参数
返回结果

优点：

✅ 原生Claude Code发现
✅ 标准SKILL.md格式（YAML + Markdown）
✅ 验证合规（名称、描述规则）
✅ 兼容逐步披露
✅ 通用示例作为模板

文档：请参阅.claude/skills/README.md了解详情

2. 带CLI参数的脚本（99.6%令牌减少）

基于CLI的Python工作流，代理使用参数执行：

# 简单示例（通用模板）
uv run python -m runtime.harness scripts/simple_fetch.py \
    --url "https://example.com"

# 流水线示例（通用模板）
uv run python -m runtime.harness scripts/multi_tool_pipeline.py \
    --repo-path "." \
    --max-commits  5

相比于从头编写脚本的优点：

18倍更好的令牌：110 vs 2,000
24倍更快：5秒 vs 2分钟
不可变模板：无需编辑文件
可重用的工作流：相同逻辑，不同参数

包含内容：

2个通用模板脚本（simple_fetch.py，multi_tool_pipeline.py）
完整模式文档

2. 多传输支持（新）

完全支持所有MCP传输类型：

{
  "mcpServers": {
    "local-tool": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-git"]
    },
    "jina": {
      "type": "sse",
      "url": "https://mcp.jina.ai/sse",
      "headers": {"Authorization": "Bearer YOUR_KEY"}
    },
    "exa": {
      "type": "http",
      "url": "https://mcp.exa.ai/mcp",
      "headers": {"x-api-key": "YOUR_KEY"}
    }
  }
}

3. 容器沙箱（增强）

可选的无根容器执行，带有全面的安全控制：

# 带有安全控制的沙箱模式
uv run python -m runtime.harness workspace/script.py --sandbox

安全特性：

无根执行（UID 65534:65534）
网络隔离（--network none）
只读根文件系统
内存/CPU/PID限制
能力下放（--cap-drop ALL）
超时强制执行

🚀 安装

系统需求

Python 3.11或3.12（不推荐3.14，因为anyio兼容性问题）
uv 包管理器（v0.5.0+）
Claude Code（可选，用于技能自动发现）
Git（用于克隆仓库）
Docker或Podman（可选，用于沙箱模式）

第一步：安装uv

如果你还没有安装uv：

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows（PowerShell）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 验证安装
uv --version

第二步：克隆并安装

# 克隆仓库
git clone https://github.com/yourusername/mcp-code-execution-enhanced.git
cd mcp-code-execution-enhanced

# 安装依赖项（自动创建.venv）
uv sync

# 验证安装
uv run python -c "from runtime.mcp_client import get_mcp_client_manager; print('✓ 安装成功')"

第三步：创建MCP配置

重要提示：Claude Code用户：此项目使用自己的mcp_config.json进行MCP服务器配置，独立于Claude Code的全局配置（~/.claude.json）。为了避免冲突，请在每个配置中使用不同的服务器，或者在使用此项目时禁用~/.claude.json中的重叠服务器。

从示例创建mcp_config.json：

# 复制示例配置（包括git + 获取示例）
cp mcp_config.example.json mcp_config.json

此配置开箱即用：

{
  "mcpServers": {
    "git": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "."]
    },
    "fetch": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  },
  "sandbox": {
    "enabled": false
  }
}

要添加更多服务器：编辑mcp_config.json并添加您自己的MCP服务器。请参阅docs/TRANSPORTS.md了解stdio、SSE和HTTP传输的示例。

第四步：生成工具包装器

# 自动从您的MCP服务器生成类型化的Python包装器
uv run mcp-generate

# 这会在./servers/<server_name>/<tool>.py文件中创建
# 示例：servers/git/git_log.py，servers/fetch/fetch.py

第五步：测试安装

# 使用简单脚本测试
uv run python -m runtime.harness scripts/simple_fetch.py --url "https://example.com"

# 如果您配置了一个git服务器，测试流水线
uv run python -m runtime.harness scripts/multi_tool_pipeline.py --repo-path "." --max-commits 5

第六步（可选）：设置沙箱模式

如果您想使用容器沙箱：

# 安装Podman（推荐，无根）
sudo apt-get install -y podman  # Ubuntu/Debian
brew install podman             # macOS

# 或者安装Docker
curl -fsSL https://get.docker.com | sh

# 验证
podman --version  # 或docker --version

# 测试沙箱模式
uv run python -m runtime.harness scripts/simple_fetch.py --url "https://example.com" --sandbox

第七步（可选）：Claude Code技能设置

如果使用Claude Code，技能已经在.claude/skills/中配置好，并且会被自动发现。不需要额外设置！

使用方法：

Claude Code会自动找到.claude/skills/中的技能
直接请求Claude使用它们
示例："获取https://example.com" → Claude发现并使用simple-fetch技能

📖 工作原理

推荐：带CLI参数的脚本（99.6%减少）

对于多步骤工作流（研究、数据处理、综合）：

发现脚本：ls ./scripts/ → 查看可用脚本模板
阅读文档：cat ./scripts/simple_fetch.py → 查看CLI参数和模式

使用参数执行：

uv run python -m runtime.harness scripts/simple_fetch.py \
    --url "https://example.com"

通用模板脚本（scripts/）：

simple_fetch.py - 基本单工具执行模式
multi_tool_pipeline.py - 多工具链模式

注意：这些是模板 - 将它们用作示例来创建适用于您特定MCP服务器和使用场景的工作流。

替代方案：直接编写脚本（98.7%减少）

对于简单的任务或新颖的工作流：

探索工具：ls ./servers/ → 发现可用的MCP工具
编写脚本：使用工具导入创建Python脚本
执行：uv run python -m runtime.harness workspace/script.py

示例脚本：

import asyncio
from runtime.mcp_client import call_mcp_tool

async def main():
    result = await call_mcp_tool(
        "git__git_log",
        {"repo_path": ".", "max_count": 10}
    )
    print(f"获取了{len(result)}条提交记录")
    return result

if __name__ == "__main__":
    asyncio.run(main())

🏗️ 架构

逐步披露模式

传统方法（高令牌使用量）：

代理 → MCP服务器 → [完整工具模式 27,300令牌] → 代理

带CLI参数的脚本（99.6%减少 - 推荐）：

代理 → 发现脚本 → 阅读脚本文档 → 使用CLI参数执行
脚本 → 多服务器编排 → 返回结果
令牌：约110（脚本发现 + 文档）
时间：约5秒

编写脚本（98.7%减少 - 替代方案）：

代理 → 发现工具 → 编写脚本
脚本 → MCP服务器 → 返回数据
代理 → 处理/总结
令牌：约2,000（工具发现 + 脚本编写）
时间：约2分钟

关键组件

runtime/mcp_client.py：支持多传输的懒加载MCP客户端管理器
runtime/harness.py：双模式脚本执行（直接/沙箱）
runtime/generate_wrappers.py：从MCP模式自动生成类型化包装器
runtime/sandbox/：带有安全控制的容器沙箱
scripts/：带有2个通用示例的CLI基础工作流模板

🎓 脚本系统

哲学

不要：每次从头开始编写脚本要：使用带有CLI参数的预编写脚本

创建自定义脚本

"""
脚本：您的脚本名称

描述：它做什么

CLI参数：
    --query    研究查询（必需）
    --limit    最大结果数（默认：10）

用法：
    uv run python -m runtime.harness scripts/your_script.py \
        --query "您的问题" \
        --limit 5
"""

import argparse
import asyncio
import sys

def parse_args():
    parser = argparse.ArgumentParser()
    parser.add_argument("--query", required=True)
    parser.add_argument("--limit", type=int, default=10)

    # 过滤脚本路径参数
    args_to_parse = [arg for arg in sys.argv[1:] if not arg.endswith(".py")]
    return parser.parse_args(args_to_parse)

async def main():
    args = parse_args()
    # 您的工作流逻辑在这里
    return result

if __name__ == "__main__":
    asyncio.run(main())

请参阅scripts/README.md了解完整文档。

🔌 多传输支持

stdio（基于子进程）

{
  "type": "stdio",
  "command": "uvx",
  "args": ["mcp-server-name"],
  "env": {"API_KEY": "your-key"}
}

SSE（服务器发送事件）

{
  "type": "sse",
  "url": "https://mcp.example.com/sse",
  "headers": {"Authorization": "Bearer YOUR_KEY"}
}

HTTP（可流式传输的HTTP）

{
  "type": "http",
  "url": "https://mcp.example.com/mcp",
  "headers": {"x-api-key": "YOUR_KEY"}
}

请参阅docs/TRANSPORTS.md了解详细信息。

🔐 沙箱模式

配置

{
  "sandbox": {
    "enabled": true,
    "runtime": "auto",
    "image": "python:3.11-slim",
    "memory_limit": "512m",
    "timeout": 30
  }
}

安全控制

无根执行：UID 65534:65534（nobody）
网络隔离：--network none
文件系统：只读根，可写的tmpfs
资源限制：内存、CPU、PID约束
能力：全部下放（--cap-drop ALL）
安全：no-new-privileges，SELinux标签

请参阅SECURITY.md了解完整的安全文档。

🧪 测试

# 运行所有测试（共129个）
uv run pytest

# 单元测试
uv run pytest tests/unit/

# 集成测试（需要Docker/Podman进行沙箱测试）
uv run pytest tests/integration/

# 带覆盖率
uv run pytest --cov=src/runtime

📚 文档

README.md（此文件） - 概述和快速入门
CLAUDE.md - Claude Code快速参考
AGENTS.md.template - 适应其他AI框架的模板
scripts/README.md - 脚本系统指南
scripts/SKILLS.md - 完整脚本文档
docs/USAGE.md - 综合用户指南
docs/ARCHITECTURE.md - 技术架构
**`docs/CONFIGURATION