MCP Code Execution Enhanced

MCP代码执行-增强版

代币减少99.6% 通过基于CLI的脚本和模型上下文协议（MCP）服务器的渐进式工具发现。

  

注： 该项目针对以下方面进行了优化 克劳德代码 在本土技能支持下。核心运行时适用于任何AI代理。带有CLI参数的脚本实现了99.6%的令牌减少。

______________________________________________________________________

🎯 这是什么

一 加强执行 Anthropic的 使用MCP执行代码 图案， 针对Claude代码进行了优化，结合MCP社区的最佳想法，并做出重大改进：

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

🤖 Claude代码集成

本地技能支持： 本项目包括 Claude代码技能 集成：

• .claude/skills/ -Claude Code原生格式的技能（SKILL.md+workflow.py）
• 自动发现 -Claude Code自动查找并验证技能
• 2通用示例 -简单获取，多工具管道（自定义工作流模板）
• 符合格式 -YAML frontmatter、验证规则、渐进式披露

双层架构：

• 层1：克劳德代码技能(.claude/skills/)-本地发现和格式
• 层2：脚本(./scripts/)-基于CLI的Python工作流，带argparse

代币效率：

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

注： 脚本适用于任何AI代理。Claude Code Skills为Claude Code用户提供本机自动发现功能。

______________________________________________________________________

🙏 致谢

本项目基于并融合了以下方面的想法：

1. ipdelete/mcp代码执行 -Anthropic的PRIMARY模式的原始实现

- 基于文件系统的渐进式披露 - 类型安全的Pydantic包装 - 模式发现系统 - 懒惰的服务器连接

1. elusznik/mcp服务器代码执行模式 -生产安全模式

- 容器沙盒架构 - 全面的安全控制 - 生产部署模式

我们的贡献： 融合了两者的优点，添加了基于CLI的脚本模式，实现了多传输支持，并优化了架构以实现最高效率。

______________________________________________________________________

✨ 关键增强功能

1.克劳德代码技能集成（新）

本地技能格式 在 .claude/skills/ 目录：

.claude/skills/
├── simple-fetch/
│   ├── SKILL.md        # YAML frontmatter + markdown instructions
│   └── workflow.py     # → symlink to ../../scripts/simple_fetch.py
└── multi-tool-pipeline/
    ├── SKILL.md        # Multi-tool orchestration example
    └── workflow.py     # → symlink to ../../scripts/multi_tool_pipeline.py

它是如何工作的：

1. Claude Code自动发现技能 .claude/skills/
2. 读取SKILL.md（遵循Claude Code的格式规范）
3. 使用CLI参数执行workflow.py（一个脚本）
4. 返回结果

优点：

• ✅ 本地克劳德代码发现
• ✅ 标准SKILL.md格式（YAML+markdown）
• ✅ 符合验证（名称、描述规则）
• ✅ 渐进式披露兼容
• ✅ 通用示例作为模板

文档： 看 .claude/skills/README.md 详情

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

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

# Simple example (generic template)
uv run python -m runtime.harness scripts/simple_fetch.py \
    --url "https://example.com"

# Pipeline example (generic template)
uv run python -m runtime.harness scripts/multi_tool_pipeline.py \
    --repo-path "." \
    --max-commits 5

与从头开始编写脚本相比的好处：

• 18倍更好的代币110对2000
• 快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.集装箱沙盒（增强型）

可选的无根容器执行，具有全面的安全性：

# Sandbox mode with security controls
uv run python -m runtime.harness workspace/script.py --sandbox

安全功能：

• 无根执行（UID 65534:65534）
• 网络隔离（--网络无）
• 只读根文件系统
• 内存/CPU/PID限制
• 能力下降（--盖帽下降全部）
• 超时执行

______________________________________________________________________

🚀 安装

系统要求

• Python 3.11或3.12 （由于anyio兼容性问题，不建议使用3.14）
• 紫外线 包管理器（v0.5.0+）
• 克劳德代码 （可选，用于技能自动发现）
• Git （用于克隆存储库）
• Docker或Podman （可选，适用于沙盒模式）

第一步：安装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"

# Verify installation
uv --version

步骤2：克隆并安装

# Clone repository
git clone https://github.com/yourusername/mcp-code-execution-enhanced.git
cd mcp-code-execution-enhanced

# Install dependencies (creates .venv automatically)
uv sync

# Verify installation
uv run python -c "from runtime.mcp_client import get_mcp_client_manager; print('✓ Installation successful')"

步骤3：创建MCP配置

对Claude Code用户来说很重要： 此项目使用自己的 mcp_config.json 对于MCP服务器配置， 分开 来自Claude Code的全局配置(~/.claude.json).为避免冲突，请在每种配置中使用不同的服务器，或在中禁用重叠的服务器 ~/.claude.json 在使用此项目时。

创建 mcp_config.json 从示例中可以看出：

# Copy example config (includes git + fetch for examples)
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传输。

步骤4：生成工具包装

# Auto-generate typed Python wrappers from your MCP servers
uv run mcp-generate

# This creates ./servers//.py files
# Example: servers/git/git_log.py, servers/fetch/fetch.py

步骤5：测试安装

# Test with a simple script
uv run python -m runtime.harness scripts/simple_fetch.py --url "https://example.com"

# If you configured a git server, test the pipeline
uv run python -m runtime.harness scripts/multi_tool_pipeline.py --repo-path "." --max-commits 5

步骤6（可选）：设置沙盒模式

如果你想使用容器沙盒：

# Install Podman (recommended, rootless)
sudo apt-get install -y podman  # Ubuntu/Debian
brew install podman             # macOS

# OR install Docker
curl -fsSL https://get.docker.com | sh

# Verify
podman --version  # or docker --version

# Test sandbox mode
uv run python -m runtime.harness scripts/simple_fetch.py --url "https://example.com" --sandbox

步骤7（可选）：Claude代码技能设置

如果使用Claude Code，则技能已在中配置 .claude/skills/ 并且将被自动发现。无需额外设置！

要使用：

• Claude Code将自动在以下位置找到技能 .claude/skills/
• 让克劳德自然地使用它们
• 示例：“提取https://example.com" → 克劳德发现并使用简单的取回技能

______________________________________________________________________

📖 运作原理

首选：带有CLI参数的脚本（减少99.6%）

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

1. 发现脚本: ls ./scripts/ → 查看可用的脚本模板
2. 阅读文档: cat ./scripts/simple_fetch.py → 请参阅CLI参数和模式
3. 使用参数执行:

   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%）

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

1. 探索工具: ls ./servers/ → 发现可用的MCP工具
2. 编写脚本：使用工具导入创建Python脚本
3. 执行: 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"Fetched {len(result)} commits")
    return result

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

______________________________________________________________________

🏗️ 建筑

渐进式披露模式

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

Agent → MCP Server → [Full Tool Schemas 27,300 tokens] → Agent

带有CLI参数的脚本 （减少99.6%-首选）：

Agent → Discovers scripts → Reads script docs → Executes with CLI args
Script → Multi-server orchestration → Returns results
Tokens: ~110 (script discovery + documentation)
Time: ~5 seconds

剧本创作 （减少98.7%-备选方案）：

Agent → Discovers tools → Writes script
Script → MCP Server → Returns data
Agent → Processes/summarizes
Tokens: ~2,000 (tool discovery + script writing)
Time: ~2 minutes

关键组件

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

______________________________________________________________________

🎓 脚本系统

哲学

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

创建自定义脚本

"""
SCRIPT: Your Script Name

DESCRIPTION: What it does

CLI ARGUMENTS:
    --query    Research query (required)
    --limit    Max results (default: 10)

USAGE:
    uv run python -m runtime.harness scripts/your_script.py \
        --query "your question" \
        --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)

    # Filter script path from args
    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()
    # Your workflow logic here
    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（无人）
• 网络隔离: --network none
• 文件系统：只读根，可写tmpfs
• 资源限制：内存、CPU、PID约束
• 能力：全部掉落(--cap-drop ALL)
• 安全: no-new-privileges，SELinux标签

看 SECURITY.md 获取完整的安全文档。

______________________________________________________________________

🧪 测试

# Run all tests (129 total)
uv run pytest

# Unit tests only
uv run pytest tests/unit/

# Integration tests (requires Docker/Podman for sandbox tests)
uv run pytest tests/integration/

# With coverage
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.md -MCP服务器配置管理（克劳德代码vs项目）
• docs/TRANSPORTS.md -运输具体细节
• SECURITY.md -安全架构和最佳实践

______________________________________________________________________

🛠️ 发展

代码质量

# Type checking
uv run mypy src/

# Formatting
uv run black src/ tests/

# Linting
uv run ruff check src/ tests/

项目脚本

# Generate wrappers from tool definitions
uv run mcp-generate

# (Optional) Generate discovery config with LLM parameter generation
uv run mcp-generate-discovery

# (Optional) Execute safe tools and infer schemas
uv run mcp-discover

# Execute a script with MCP tools available
uv run mcp-exec workspace/script.py

# Execute in sandbox mode
uv run mcp-exec workspace/script.py --sandbox

______________________________________________________________________

📊 效率比较

带有CLI参数的脚本减少了99.6% -超过了Anthropic的98.7%目标！

______________________________________________________________________

🎨 是什么让它得到了增强

超越原创项目

从ipdelete/mcp代码执行开始：

• ✅ 基于文件系统的渐进式披露
• ✅ 类型安全的Pydantic包装
• ✅ 懒惰的服务器连接
• ✅ 模式发现系统

从elusznik/mcp服务器代码执行模式：

• ✅ 容器沙盒架构
• ✅ 安全控制和政策
• ✅ 生产部署模式

本项目增强：

• ⭐ 基于CLI的脚本：基于CLI的不可变模板（减少99.6%）
• ⭐ 多运输：stdio+SSE+HTTP支持（100%服务器覆盖率）
• ⭐ 双模式执行：直接（快速）+沙盒（安全）
• ⭐ Python 3.11稳定版：避免3.14 anyio兼容性问题
• ⭐ 综合测试：涵盖所有功能的129个测试
• ⭐ 增强文档：所有功能的完整指南

建筑创新

带有CLI参数的脚本：

• 脚本是 不可变模板 使用CLI参数执行
• 无需编辑文件（参数通过 --query, --num-urls等等）
• 可在不同的查询和上下文中重用
• 预先测试和记录的工作流程

多运输：

• 单个代码库支持所有传输类型
• 自动运输检测
• 统一配置格式
• 无缝服务器连接

双模式执行：

• 直接模式：快速、完全访问（开发）
• 沙盒模式：安全、隔离（生产）
• 相同的代码，不同的安全态势
• 通过标志或配置选择运行时

______________________________________________________________________

🔧 配置参考

最小配置

{
  "mcpServers": {
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "."]
    }
  }
}

完整配置

{
  "mcpServers": {
    "local-stdio": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-name"],
      "env": {"API_KEY": "key"},
      "disabled": false
    },
    "remote-sse": {
      "type": "sse",
      "url": "https://mcp.example.com/sse",
      "headers": {"Authorization": "Bearer KEY"},
      "disabled": false
    },
    "remote-http": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {"x-api-key": "KEY"},
      "disabled": false
    }
  },
  "sandbox": {
    "enabled": false,
    "runtime": "auto",
    "image": "python:3.11-slim",
    "memory_limit": "512m",
    "cpu_limit": "1.0",
    "timeout": 30,
    "max_timeout": 120
  }
}

______________________________________________________________________

📦 特性

核心功能

• 🦥 延迟加载：服务器仅在调用工具时连接
• 🔒 类型安全：所有工具输入/输出的Pydantic模型
• 🔄 防御性编码：处理可变MCP响应结构
• 📦 自动生成的包装：从MCP模式中键入Python函数
• 🛠️ 现场标准化：处理不一致的API套管

增强功能

• 🎯 脚本模式：基于CLI的可重用工作流模式
• 🔌 多运输：stdio、SSE和HTTP支持
• 🔐 集装箱装箱：可选无根隔离
• 🧪 综合测试：129次全覆盖测试
• 📖 完整的文件：每个功能的指南

______________________________________________________________________

🎓 示例

请参阅 examples/ 目录：

• example_progressive_disclosure.py -经典代币缩减模式
• example_tool_chaining.py -LLM编排模式
• example_sandbox_usage.py -容器沙盒演示
• example_sandbox_simple.py -基本沙盒使用

请参阅 scripts/ 生产就绪工作流目录。

______________________________________________________________________

🐛 故障排除

常见问题

“未配置MCP服务器”

• 检查 mcp_config.json 服务器名称与您的呼叫匹配

“连接已关闭”

• 验证服务器命令： which
• 检查服务器日志中的启动错误

“找不到模块”

• 跑 uv run mcp-generate 再生包装纸
• 确保 src/ 是在巨蟒（安全带处理这个）

技能导入错误

• 技能必须通过安全带运行（设置PYTHONPATH）
• 不要直接运行技能： python scripts/script.py ❌
• 对的： uv run python -m runtime.harness scripts/script.py ✅

Python版本问题

Python 3.14兼容性：

• 由于anyio\<4.9.0的破坏性更改，不建议使用
• 使用Python 3.11或3.12以获得稳定性
• 请参阅问题跟踪器以获取更新

______________________________________________________________________

🤝 贡献

我们欢迎捐款！感兴趣的领域：

• 新技能：添加更多工作流模板
• MCP服务器支持：使用不同的服务器进行测试
• 文档：改进指南和示例
• 测试：扩大测试覆盖范围
• 演出：进一步优化代币使用

开发设置

# Install with dev dependencies
uv sync --all-extras

# Run quality checks
uv run black src/ tests/
uv run mypy src/
uv run ruff check src/ tests/
uv run pytest

______________________________________________________________________

📄 许可证

MIT许可证-有关详细信息，请参阅许可证文件

______________________________________________________________________

🔗 参考文献

原创项目

• ipdelete/mcp代码执行 -人类学的主要模式
• elusznik/mcp服务器代码执行模式 -生产安全

MCP资源

• 模型上下文协议
• Anthropic：使用MCP执行代码
• MCP Python SDK
• MCP服务器列表

Python资源

• Pydantic文档
• uv包管理器

______________________________________________________________________

🌟 功能比较

______________________________________________________________________

💡 用例

非常适合

• ✅ 需要编排多个MCP工具的AI代理
• ✅ 研究工作流程（网络搜索→ read → 合成）
• ✅ 数据处理管道（fetch→ 变换→ 输出）
• ✅ 代码发现（搜索→ 分析→ 推荐）
• ✅ 需要安全隔离的生产部署
• ✅ 需要可重复研究工作流程的团队

不适合

• ❌ 单个工具调用（直接使用MCP）
• ❌ 实时交互工具（更适合直接集成）
• ❌ GUI应用程序（以命令行为中心）

______________________________________________________________________

🚦 入门检查表

• \[\]安装Python 3.11+和uv
• \[\]克隆存储库
• \[\]运行 uv sync
• \[\]创建 mcp_config.json 使用您的MCP服务器
• \[\]运行 uv run mcp-generate 创建包装
• \[\]尝试一项技能： uv run python -m runtime.harness scripts/simple_fetch.py --url "https://example.com"
• \[\]阅读 AGENTS.md 用于操作指南
• \[\]探索 scripts/ 对于可用工作流
• \[\]审查 docs/ 获取详细文档

______________________________________________________________________

❓ 常见问题解答

Q： 为什么是技能而不是写剧本？ A： 技能减少了99.6%的令牌，而脚本减少了98.7%，执行速度提高了24倍（5秒对2分钟）。它们经过预先测试、记录和不可变。

Q： 我可以在没有Claude Code的情况下使用它吗？ A： 是的，但有局限性。核心运行时（脚本编写，减少98.7%）适用于任何AI代理。带有CLI参数的脚本（减少99.6%）适用于Claude Code的操作智能。

Q： 我还可以编写自定义脚本吗？ A： 是的！对于常见的工作流（使用克劳德代码），首选带有CLI参数的脚本，但对于新的用例和其他AI代理，完全支持自定义脚本。

Q： 与最初的项目有什么不同？ A： 我们融合了两者的优点（渐进式披露+安全性），添加了基于CLI的脚本模式、多传输支持，并完善了架构。

Q： 为什么是Python 3.11而不是3.14？ A： anyio\<4.9.0与Python 3.14的asyncio更改存在兼容性问题。3.11稳定且经过良好测试。

Q： 是否需要沙盒？ A： 不，这是可选的。使用直接模式进行开发（快速），使用沙盒模式进行生产（安全）。

Q： 如何添加我自己的MCP服务器？ A： 将它们添加到 mcp_config.json，跑 uv run mcp-generate，它们已经准备好使用了！

______________________________________________________________________

🎯 后续步骤

1. 探索脚本: ls scripts/ 和 cat scripts/simple_fetch.py
2. 尝试示例：运行示例技能或创建自己的技能
3. 阅读CLAUDE.md：快速操作指南（适用于Claude Code用户）
4. 审阅文档/：深入建筑
5. 创建自定义技能：遵循用例模板