terasum-sandbox-code-interpreter-mcp-server 2.2.0
Code Interpreter MCP Server - Secure code execution via E2B on Function Compute
License: Apache-2.0
Requires Python: >=3.10

# Terasum Sandbox Code Interpreter MCP Server

An MCP (Model Context Protocol) Server that provides secure code interpreting capabilities through E2B SDK integration. Supports both local sandbox (via Docker) and AgentRun cloud execution.

**PyPI Package**: `terasum-sandbox-code-interpreter-mcp-server`

## 🚀 Quick Start

### Prerequisites
- Python 3.10+
- UV package manager
- Docker (for local sandbox) OR AgentRun credentials

### Installation

```bash
# Install dependencies
uv install
```

### Option 1: Docker Compose (Recommended)

One-command deployment of both Sandbox and MCP Server:

```bash
# Build and start all services
make docker-up

# Verify services are running
make docker-ps

# View logs
make docker-logs

# Test with MCP Inspector
npx @modelcontextprotocol/inspector http://localhost:3000/sse

# Stop services
make docker-down
```

### Option 2: Local Development (Python)

Run MCP server locally with Docker sandbox:

```bash
# Start local sandbox only
docker-compose up -d sandbox-code-interpreter

# Verify sandbox is running
curl http://localhost:5001/health

# Start MCP server with SSE transport
make run

# Or start with Inspector for debugging
make debug
```

### Option 3: AgentRun Cloud

For production deployment without local sandbox:

Create a `.env` file:

```bash
AGENTRUN_ACCESS_KEY_ID=your_key
AGENTRUN_ACCESS_KEY_SECRET=your_secret
AGENTRUN_ACCOUNT_ID=your_account_id
AGENTRUN_REGION=cn-hangzhou
```

Run the server:

```bash
uv run terasum-sandbox-code-interpreter-mcp-server
```

## 📚 Features

The server exposes 4 MCP tools for secure code execution:

- **`run_code`** - Execute code in isolated contexts (Python/JavaScript)
- **`create_context`** - Create new execution contexts with persistent state
- **`stop_context`** - Stop and cleanup contexts
- **`list_contexts`** - List all active contexts with metadata

## 🔧 Architecture

### Transport Layer
- **SSE (Server-Sent Events)**: HTTP-based streaming for production
- **Stdio**: Process-based for simple integrations

### Execution Layer
- **E2B SDK**: Secure sandbox execution via Docker or AgentRun
- **Code Interpreter**: Isolated environments for Python and JavaScript
- **Context Management**: Persistent execution contexts with state

### Key Components
1. **MCP Server** (`mcp_server/server.py`) - Core MCP protocol handler
2. **E2B Integration** - Sandbox execution via e2b-on-fc SDK
3. **Context Registry** - Manages execution context lifecycle
4. **SSE Transport** - HTTP streaming for remote access

## 🌟 Key Technologies

- **E2B SDK**: Secure sandbox execution (local Docker or AgentRun cloud)
- **MCP Protocol**: Standard AI agent tool integration
- **Starlette + Uvicorn**: High-performance async HTTP server
- **Pydantic**: Type-safe data validation

## 📝 Usage

### Using Make Commands

```bash
# View all available commands
make help

# Start MCP server (SSE mode)
make run

# Start with Inspector for debugging
make debug

# Run tests
make test

# Clean temporary files
make clean
```

### Configuration

Environment variables:

```bash
# Sandbox configuration
SANDBO X_URL=http://localhost:5001  # Local sandbox endpoint

# MCP server configuration
MCP_HOST=0.0.0.0                    # Server bind address
MCP_PORT=3000                       # Server port
LOG_LEVEL=INFO                      # Logging level

# AgentRun cloud (optional)
AGENTRUN_ACCESS_KEY_ID=your_key
AGENTRUN_ACCESS_KEY_SECRET=your_secret
AGENTRUN_ACCOUNT_ID=your_account
AGENTRUN_REGION=cn-hangzhou
```

## 📖 Documentation

- [Quick Start Guide](./QUICK_START.md) - 3-step setup guide
- [Docker Deployment](./DOCKER_DEPLOY.md) - Docker & Docker Compose guide
- [Image Build Guide](./IMAGE_BUILD_GUIDE.md) - Build and push to Aliyun Registry
- [SSE Documentation](./README_SSE.md) - SSE transport details
- [Tools API](./docs/TOOLS_API.md) - Complete API reference
- [Makefile Guide](./MAKEFILE_GUIDE.md) - All available commands
- [WARP Guide](./WARP.md) - Development with WARP AI

## 📦 Publishing

```bash
# Install from PyPI
pip install terasum-sandbox-code-interpreter-mcp-server

# Or with uv
uv pip install terasum-sandbox-code-interpreter-mcp-server
```

### Publishing New Versions

```bash
# Update version in pyproject.toml
# Then publish to PyPI
poetry build
poetry publish
```

Or use automated publishing via Git tags:

```bash
git tag v2.2.1
git push origin v2.2.1
```

## 📄 License

See [LICENSE](./LICENSE) file for details.