# Code Execution with MCP - Template Repository

A production-ready template for building AI agents using the **Code Execution with MCP** pattern. This harness enables AI agents to dynamically discover and execute MCP tools through secure, sandboxed code execution.

> **Inspired by**: This template implements the architectural patterns and design philosophy from Anthropic's [Code Execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) engineering blog post and their [Skills Repository](https://github.com/anthropics/skills). We are grateful to Anthropic for openly sharing these patterns.

## 🌟 Key Features

- **Dynamic Tool Discovery** - Tools discovered at runtime using `list_mcp_tools()` and `get_mcp_tool_details()` (no static files)
- **Secure Sandbox Execution** - Docker-based isolation with resource limits, read-only filesystem, and network restrictions
- **PII Protection** - Automatic tokenization/de-tokenization of sensitive data
- **Persistent Skills** - `/skills` directory for reusable agent code
- **Ephemeral Workspace** - `/workspace` directory for temporary task files
- **Multi-Turn Conversations** - Support for complex agent workflows
- **Extensible Architecture** - Easy to customize and extend

## 💡 Why Code Execution?

**The Token Efficiency Problem**: Traditional AI agents must describe every computational step in natural language, consuming valuable context window space. Processing 1,000 records might use 50,000 tokens just to describe the transformations.

**The Solution**: Code execution lets agents write and run code, delegating computation to traditional software while focusing their intelligence on high-level reasoning. The same 1,000-record task uses just ~500 tokens of code.

**Key Benefits**:
- 📊 **Scalability**: Handle tasks of any complexity within token limits
- 🔄 **Reusability**: Save code to `/skills` for future use
- 🔒 **Privacy**: PII tokenized before reaching the LLM
- 🎯 **Reliability**: Deterministic code execution vs. natural language descriptions

> 📖 Read the full philosophy in [`docs/PHILOSOPHY.md`](docs/PHILOSOPHY.md) - explains the "why" behind this architecture based on Anthropic's research.

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    User / Application                        │
└────────────────────┬────────────────────────────────────────┘
                     │ HTTP Request
                     ▼
┌─────────────────────────────────────────────────────────────┐
│                  Agent Orchestrator                          │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────────┐   │
│  │ AgentManager │◄─┤ PII Censor   │◄─┤ MCP Client      │   │
│  └──────┬───────┘  └──────────────┘  └─────────────────┘   │
│         │                                                     │
│         ▼                                                     │
│  ┌──────────────┐                                           │
│  │ LLM Provider │ (OpenAI, Anthropic, etc.)                 │
│  └──────┬───────┘                                           │
│         │                                                     │
│         ▼                                                     │
│  ┌──────────────────────────────────┐                       │
│  │   Sandbox Manager (Docker)       │                       │
│  └──────┬───────────────────────────┘                       │
└─────────┼────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────┐
│              Secure Docker Container                         │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Agent Code Execution                                 │   │
│  │  - Runtime API (callMCPTool, fs, utils)             │   │
│  │  - Dynamic Tool Discovery                            │   │
│  │  - /skills (persistent, mounted)                     │   │
│  │  - /workspace (ephemeral, mounted)                   │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                              │
│  Security: Non-root user, read-only rootfs, resource limits │
└─────────────────────────────────────────────────────────────┘
          │
          │ Authenticated API Call
          ▼
┌─────────────────────────────────────────────────────────────┐
│                    MCP Servers                               │
│  (File System, Databases, APIs, Custom Tools)               │
└─────────────────────────────────────────────────────────────┘
```

## 🚀 Quick Start

### Prerequisites

- Node.js >= 18.0.0
- Docker (for sandbox execution)
- TypeScript knowledge

### Installation

```bash
# Clone the repository
git clone <your-repo-url>
cd code-execution-with-MCP

# Install dependencies
npm install

# Build the project
npm run build

# Build the Docker sandbox image
npm run build-sandbox

# Create required directories
npm run prepare-workspace

# Start the server
npm start
```

### Development

```bash
# Run in development mode with auto-reload
npm run dev

# Type checking only
npm run type-check

# Clean build artifacts
npm run clean
```

## 📁 Project Structure

```
mcp-code-exec-harness/
├── src/
│   ├── agent_orchestrator/     # Main agent logic
│   │   ├── AgentManager.ts     # Agent execution loop
│   │   └── prompt_templates.ts # System prompts
│   │
│   ├── sandbox_manager/        # Secure code execution
│   │   ├── SandboxManager.ts   # Abstract interface
│   │   └── DockerSandbox.ts    # Docker implementation
│   │
│   ├── mcp_client/            # MCP communication
│   │   ├── McpClient.ts       # MCP server client
│   │   └── PiiCensor.ts       # PII tokenization
│   │
│   ├── agent_runtime/         # Sandbox runtime API
│   │   └── runtime_api.ts     # Injected helper functions
│   │
│   ├── tools_interface/       # Dynamic tool discovery
│   │   └── DynamicToolManager.ts
│   │
│   └── index.ts               # Main server entry point
│
├── servers/                   # MCP server collection (NEW!)
│   ├── official/              # Official MCP servers
│   ├── archived/              # Archived reference servers
│   ├── community/             # Community-contributed servers
│   ├── README.md              # Server collection documentation
│   ├── catalog.json           # Structured server index
│   └── QUICKSTART.md          # Quick start guide
│
├── skills/                    # Persistent agent skills (user-specific)
├── workspace/                 # Ephemeral execution workspace
├── Dockerfile.sandbox         # Secure sandbox container
├── package.json
├── tsconfig.json
└── README.md
```

## 🔧 Configuration

### Environment Variables

Create a `.env` file in the root directory:

```env
# Server Configuration
PORT=3000
NODE_ENV=development

# Sandbox Configuration
SANDBOX_IMAGE=sandbox-image-name
SANDBOX_TIMEOUT_MS=30000
SANDBOX_MEMORY_MB=100
SANDBOX_CPU_QUOTA=50000

# LLM Provider (configure for your provider)
LLM_API_KEY=your-api-key-here
LLM_MODEL=your-model-name

# MCP Servers (customize for your setup)
# Add your MCP server configurations here
```

### Customizing the Agent

1. **Implement LLM Integration** - Edit `src/agent_orchestrator/AgentManager.ts`:
   ```typescript
   async function callLLM(prompt: string, tools: any[]): Promise<LLMResponse> {
     // Add your LLM API call here
     // Examples: OpenAI, Anthropic, Google Gemini, etc.
   }
   ```

2. **Connect MCP Servers** - Edit `src/mcp_client/McpClient.ts`:
   ```typescript
   private initializeServers(): void {
     // Add your MCP server connections
     // Use @modelcontextprotocol/sdk
   }
   ```

3. **Customize System Prompts** - Edit `src/agent_orchestrator/prompt_templates.ts`

4. **Adjust Sandbox Security** - Edit `src/sandbox_manager/DockerSandbox.ts`

## 🔐 Security Features

### Sandbox Isolation

- **Non-root execution** - Runs as `sandboxuser`
- **Read-only root filesystem** - Prevents system modifications
- **Resource limits** - CPU and memory constraints
- **Network restrictions** - Configurable network access
- **Capability dropping** - Minimal container privileges

### PII Protection

Automatic detection and tokenization of:
- Email addresses
- Phone numbers
- Social Security Numbers
- Credit card numbers
- IP addresses
- Custom patterns (extensible)

### Authentication

- Session-specific auth tokens for sandbox ↔ host communication
- Validate tokens in production deployment

## 📚 Usage Examples

### Making a Request

```bash
curl -X POST http://localhost:3000/task \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user123",
    "task": "Analyze the latest sales data and create a summary report"
  }'
```

### Agent Code Example

The agent writes code like this (executed in sandbox):

```javascript
// 1. Discover available tools
const tools = await list_mcp_tools();
console.log("Available tools:", tools);

// 2. Get tool details
const dbTool = await get_mcp_tool_details("database__query");
console.log("Tool info:", dbTool.description);

// 3. Execute tools
const salesData = await callMCPTool("database__query", {
  query: "SELECT * FROM sales WHERE date > '2024-01-01'"
});

// 4. Process data in code
const summary = salesData.reduce((acc, sale) => {
  acc.total += sale.amount;
  acc.count += 1;
  return acc;
}, { total: 0, count: 0 });

// 5. Save to skills for reuse
await fs.writeFile('/skills/sales_summary.js', `
  module.exports = async function summarizeSales(data) {
    return data.reduce((acc, sale) => {
      acc.total += sale.amount;
      acc.count += 1;
      return acc;
    }, { total: 0, count: 0 });
  };
`);

// 6. Return results
return { summary, totalSales: summary.total, count: summary.count };
```

## 🛠️ Extending the Template

### MCP Servers Collection

This repository includes a comprehensive collection of **18 MCP servers** organized for progressive discovery:

- **📦 7 Official Servers** - Filesystem, Git, Memory, Fetch, Everything, Time, Sequential Thinking
- **🗄️ 5 Archived Servers** - PostgreSQL, Redis, SQLite, Puppeteer, Sentry
- **🌍 6 Community Servers** - MongoDB, GreptimeDB, Unstructured, Semgrep, MCP Installer, PostgreSQL Community Fork

**Quick Start:**
```bash
# Browse the server collection
cd servers/

# Read the documentation
cat README.md

# Check the quick start guide
cat QUICKSTART.md

# View the structured catalog
cat catalog.json
```

**Documentation:**
- [`servers/README.md`](servers/README.md) - Complete server collection documentation
- [`servers/QUICKSTART.md`](servers/QUICKSTART.md) - Quick start guide with common use cases
- [`servers/catalog.json`](servers/catalog.json) - Structured server index for programmatic discovery
- Category-specific READMEs in `servers/official/`, `servers/archived/`, and `servers/community/`

### Adding New MCP Servers

```typescript
// In src/mcp_client/McpClient.ts
async addServer(config: MCPServerConfig): Promise<void> {
  const client = new Client({
    name: config.name,
    version: '1.0.0'
  }, {
    capabilities: { tools: {} }
  });

  const transport = new StdioClientTransport({
    command: config.command,
    args: config.args
  });

  await client.connect(transport);

  // Discover and register tools
  const tools = await client.listTools();
  tools.forEach(tool => this.registerTool(tool));
}
```

**Example configurations for servers from the collection:**

```typescript
// Filesystem server (official)
await this.addServer({
  name: 'filesystem',
  command: 'npx',
  args: ['@modelcontextprotocol/server-filesystem', '/workspace', '/skills']
});

// MongoDB server (community)
await this.addServer({
  name: 'mongodb',
  command: 'npx',
  args: ['-y', 'mongodb-mcp-server', '--readOnly'],
  env: { MDB_MCP_CONNECTION_STRING: process.env.MONGODB_URI }
});

// Git server (official)
await this.addServer({
  name: 'git',
  command: 'npx',
  args: ['mcp-server-git']
});
```

### Custom PII Patterns

```typescript
// In your code
const piiCensor = new PiiCensor();
piiCensor.addPattern('custom_id', /\bID-\d{6}\b/g);
```

### Alternative Sandbox Implementations

Extend `SandboxManager` to create custom execution environments:
- WebAssembly-based sandboxes
- Cloud function execution
- Process-based isolation

## 🧪 Testing

```bash
# Test the sandbox
curl -X POST http://localhost:3000/task \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "test",
    "task": "Write a simple hello world function and save it to skills"
  }'

# Check health
curl http://localhost:3000/health
```

## 📖 Documentation & References

### Core Documentation

- **[PHILOSOPHY.md](docs/PHILOSOPHY.md)** - ⭐ **Start here!** Explains the "why" behind code execution, token efficiency, and design principles based on Anthropic's research
- **[QUICK_START.md](docs/QUICK_START.md)** - Get running in 5 minutes
- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** - Technical deep dive into system components
- **[SECURITY.md](docs/SECURITY.md)** - Security best practices and hardening checklist
- **[DEPLOYMENT.md](docs/DEPLOYMENT.md)** - Production deployment guides (Docker, K8s, Cloud)
- **[API_EXAMPLES.md](docs/API_EXAMPLES.md)** - Usage examples and patterns

### Skills & Examples

- **[skills/examples/](skills/examples/)** - Example skills following the Anthropic skills pattern
  - `template-skill/` - Template for creating new skills
  - `data-processor/` - Token-efficient data transformation example

### External References

1. **[Code Execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp)** - Anthropic's engineering blog post describing the dynamic execution model and philosophy
2. **[Anthropic Skills Repository](https://github.com/anthropics/skills)** - Open-source examples of skills that extend agent capabilities
3. **[Equipping Agents for the Real World with Agent Skills](https://anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)** - Philosophy behind persistent agent capabilities
4. **[Model Context Protocol Documentation](https://modelcontextprotocol.io)** - MCP specification and guides
5. **[Docker Security Best Practices](https://docs.docker.com/engine/security/)** - Container security hardening

## 🤝 Contributing & Community Collaboration

This is a template repository that represents a **new paradigm** in AI agent development - one where code execution, security, and persistent capabilities work together seamlessly. We believe this approach has the potential to transform how AI agents are built and deployed at scale.

### We're Inviting You to Build This Together

The open-source community is fundamental to advancing this paradigm. We welcome contributions in all forms:

#### **Areas We're Looking For Help**

1. **LLM Integrations** - Add support for more providers (Claude, GPT-4, Gemini, Llama, etc.)
2. **MCP Server Connectors** - Build adapters for popular services (databases, APIs, file systems)
3. **Security Hardening** - Audit the sandbox, propose additional security measures
4. **Performance Optimizations** - Container pooling, caching strategies, resource tuning
5. **Monitoring & Observability** - Prometheus metrics, logging, distributed tracing
6. **Skills Library** - Create reusable, domain-specific skills for the community
7. **Documentation** - Tutorials, deployment guides, best practices
8. **Testing & Examples** - Integration tests, real-world use cases, benchmarks
9. **Alternative Sandboxes** - WebAssembly, cloud functions, process isolation implementations
10. **Frontend UI** - Dashboard, skill explorer, task monitoring interface

#### **How to Contribute**

1. **Fork & Customize** - Start with this template for your specific use case
2. **Share Improvements** - Submit PRs with general-purpose enhancements
3. **Build Skills** - Create reusable skills and submit to the community skills library
4. **Report Issues** - Help us identify bugs and security concerns
5. **Discuss Ideas** - Join conversations about the architecture and design
6. **Write Documentation** - Help others understand and adopt the pattern

#### **The Vision**

We're building toward a future where:
- 🧠 **AI agents scale** beyond token limitations through code execution
- 🔄 **Skills accumulate** over time, making agents continuously smarter
- 🔒 **Privacy is built-in** with automatic PII protection
- 🛡️ **Security is layered** with multiple defense mechanisms
- 🌐 **Tools are discovered dynamically**, not statically configured
- 📚 **Community-driven** with shared skills and best practices

### Customization Guide for Your Organization

Customize this template for your specific needs:

1. **Implement your LLM integration** - Choose your preferred provider
2. **Connect your MCP servers** - Wire up your tools and data sources
3. **Customize security policies** - Adjust for your threat model
4. **Extend PII detection** - Add patterns for your domain
5. **Add monitoring and logging** - Integrate with your observability stack
6. **Build domain-specific skills** - Create your organization's capability library
7. **Share back** - Contribute generic improvements to help the community

### Community Resources

- **Issues & Discussions** - Ask questions, propose features, discuss architecture
- **Skills Repository** - Contribute reusable skills to `skills/examples/`
- **Documentation** - Help improve guides and examples
- **Partnerships** - Collaborate on larger initiatives

### Recognition

Contributors will be recognized in:
- Project README
- Release notes
- Community Hall of Fame
- Speaking opportunities at community events

---

**Together, we can build the next generation of AI agent infrastructure.** Whether you're an AI researcher, DevOps engineer, security expert, or full-stack developer, there's a place for your contributions. Join us in advancing this paradigm!

## 📝 License

MIT License - See LICENSE file for details

## ⚠️ Important Notes

- **TODO Items**: Search for `TODO` comments in the code for areas requiring implementation
- **Security**: Review and harden security settings before production deployment
- **LLM Integration**: The LLM calling function is a placeholder - implement with your provider
- **MCP Servers**: Mock implementations are provided - replace with actual MCP connections
- **Production Ready**: Additional hardening required for production use (monitoring, error handling, scaling)

---

Built with the Code Execution with MCP pattern for dynamic, secure AI agent workflows.