MCP Code Execution - Enhanced Edition

99.6% Token Reduction through CLI-based scripts and progressive tool discovery for Model Context Protocol (MCP) servers.

Note: This project is optimized for Claude Code with native Skills support. The core runtime works with any AI agent. Scripts with CLI arguments achieve 99.6% token reduction.

---

🎯 What This Is

An enhanced implementation of Anthropic's Code Execution with MCP pattern, optimized for Claude Code, combining the best ideas from the MCP community and adding significant improvements:

• Scripts with CLI Args: Reusable Python workflows with command-line parameters (99.6% token reduction)
• Multi-Transport: Full support for stdio, SSE, and HTTP MCP servers
• Container Sandboxing: Optional rootless isolation with security controls
• Type Safety: Pydantic models throughout with full validation
• Production-Ready: 129 passing tests, comprehensive error handling

🤖 Claude Code Integration

Native Skills Support: This project includes proper Claude Code Skills integration:

• .claude/skills/ - Skills in Claude Code's native format (SKILL.md + workflow.py)
• Auto-discovery - Claude Code automatically finds and validates Skills
• 2 Generic Examples - simple-fetch, multi-tool-pipeline (templates for custom workflows)
• Format Compliant - YAML frontmatter, validation rules, progressive disclosure

Dual-layer architecture:

• Layer 1: Claude Code Skills (.claude/skills/) - Native discovery and format
• Layer 2: Scripts (./scripts/) - CLI-based Python workflows with argparse

Token efficiency:

• Core runtime: 98.7% reduction (Anthropic's filesystem pattern)
• Scripts with CLI args: 99.6% reduction (no file editing needed)

Note: Scripts work with any AI agent. Claude Code Skills provide native auto-discovery for Claude Code users.

---

🙏 Acknowledgments

This project builds upon and merges ideas from:

1. ipdelete/mcp-code-execution - Original implementation of Anthropic's PRIMARY pattern

   • Filesystem-based progressive disclosure
   • Type-safe Pydantic wrappers
   • Schema discovery system
   • Lazy server connections

2. elusznik/mcp-server-code-execution-mode - Production security patterns

   • Container sandboxing architecture
   • Comprehensive security controls
   • Production deployment patterns

Our contribution: Merged the best of both, added CLI-based scripts pattern, implemented multi-transport support, and refined the architecture for maximum efficiency.

---

✨ Key Enhancements

1. Claude Code Skills Integration (NEW)

Native Skills format in .claude/skills/ directory:

.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

How it works:

1. Claude Code auto-discovers Skills in .claude/skills/
2. Reads SKILL.md (follows Claude Code's format spec)
3. Executes workflow.py (which is a script) with CLI arguments
4. Returns results

Benefits:

• ✅ Native Claude Code discovery
• ✅ Standard SKILL.md format (YAML + markdown)
• ✅ Validation compliant (name, description rules)
• ✅ Progressive disclosure compatible
• ✅ Generic examples as templates

Documentation: See .claude/skills/README.md for details

2. Scripts with CLI Arguments (99.6% Token Reduction)

CLI-based Python workflows that agents execute with parameters:

# 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

Benefits over writing scripts from scratch:

• 18x better tokens: 110 vs 2,000
• 24x faster: 5 seconds vs 2 minutes
• Immutable templates: No file editing
• Reusable workflows: Same logic, different parameters

What's included:

• 2 generic template scripts (simple_fetch.py, multi_tool_pipeline.py)
• Complete pattern documentation

2. Multi-Transport Support (NEW)

Full support for all MCP transport types:

{
  "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. Container Sandboxing (Enhanced)

Optional rootless container execution with comprehensive security:

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

Security features:

• Rootless execution (UID 65534:65534)
• Network isolation (--network none)
• Read-only root filesystem
• Memory/CPU/PID limits
• Capability dropping (--cap-drop ALL)
• Timeout enforcement

---

🚀 Installation

System Requirements

• Python 3.11 or 3.12 (3.14 not recommended due to anyio compatibility issues)
• uv package manager (v0.5.0+)
• Claude Code (optional, for Skills auto-discovery)
• Git (for cloning repository)
• Docker or Podman (optional, for sandbox mode)

Step 1: Install uv

If you don't have uv installed:

# 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

Step 2: Clone and Install

# 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')"

Step 3: Create MCP Configuration

Important for Claude Code Users: This project uses its own mcp_config.json for MCP server configuration, separate from Claude Code's global configuration (~/.claude.json). To avoid conflicts, use different servers in each configuration or disable overlapping servers in ~/.claude.json while using this project.

Create mcp_config.json from the example:

# Copy example config (includes git + fetch for examples)
cp mcp_config.example.json mcp_config.json

This config works out of the box:

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

To add more servers: Edit mcp_config.json and add your own MCP servers. See docs/TRANSPORTS.md for examples of stdio, SSE, and HTTP transports.

Step 4: Generate Tool Wrappers

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

# This creates ./servers/<server_name>/<tool>.py files
# Example: servers/git/git_log.py, servers/fetch/fetch.py

Step 5: Test the Installation

# 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

Step 6 (Optional): Setup Sandbox Mode

If you want to use container sandboxing:

# 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

Step 7 (Optional): Claude Code Skills Setup

If using Claude Code, the Skills are already configured in .claude/skills/ and will be auto-discovered. No additional setup needed!

To use:

• Claude Code will automatically find Skills in .claude/skills/
• Just ask Claude to use them naturally
• Example: "Fetch https://example.com" → Claude discovers and uses simple-fetch Skill

---

📖 How It Works

PREFERRED: Scripts with CLI Args (99.6% reduction)

For multi-step workflows (research, data processing, synthesis):

1. Discover scripts: ls ./scripts/ → see available script templates
2. Read documentation: cat ./scripts/simple_fetch.py → see CLI args and pattern
3. Execute with parameters:

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

Generic template scripts (scripts/):

• simple_fetch.py - Basic single-tool execution pattern
• multi_tool_pipeline.py - Multi-tool chaining pattern

Note: These are templates - use them as examples to create workflows for you