# SuperBox Executor

Remote MCP server executor built on **Cloudflare Workers + Durable Objects**.

## Architecture

```
MCP Client (VS Code / Cursor / Antigravity / Claude Desktop / ChatGPT)
    |
    |  POST /mcp?name=<server>
    v
Cloudflare Worker  (superbox-executor.workers.dev)
    |  validates name in R2 registry, routes to Durable Object by session ID
    v
McpSession Durable Object  (one per session)
    |  fetches source from GitHub, detects language, parses tools, runs on request
    |
    +-- Python (lang: "python")  ->  interpreter/python.ts
    |       outbound HTTP via fetch (requests.get/post/put/patch/delete)
    |       JSON processing, dict/list ops, f-strings, common builtins
    |
    +-- JS/TS  (lang: "javascript" | "typescript")  ->  interpreter/javascript.ts
            outbound HTTP via fetch(), template literals, URL/URLSearchParams
            const/let, arrow functions, Zod schema parsing, common builtins
```

## Setup

### Prerequisites

- [Node.js 22+](https://nodejs.org)
- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler) (`npm i -g wrangler`)
- Cloudflare account (`wrangler login`)

### 1. Install dependencies

```bash
cd cloudflare
npm install
```

### 2. Create R2 bucket

```bash
wrangler r2 bucket create superbox-mcp-registry
```

For local dev, the preview bucket is `superbox-mcp-registry-dev`:

```bash
wrangler r2 bucket create superbox-mcp-registry-dev
```

### 3. Local development

```bash
npm run dev
# Worker available at http://localhost:8787
```

### 4. Deploy to production

```bash
npm run deploy
# URL: https://superbox-executor.<your-account>.workers.dev
```

Copy the deployed URL and set it in your backend `.env`:

```env
CLOUDFLARE_WORKER_URL=https://superbox-executor.<your-account>.workers.dev
```

## API

### Health check

```
GET /health
```

### MCP endpoint (Streamable HTTP, spec 2025-11-25)

```
POST /mcp?name=<server-name>
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"test","version":"0.0.1"}}}
```

### Test mode (skip registry, provide repo directly)

```
POST /mcp?name=my-test&test_mode=true&repo_url=https://github.com/user/repo&entrypoint=main.py
```

## Execution model

Tools are executed by a lightweight TypeScript interpreter built into the Worker. Cloudflare Workers cannot run Pyodide (WASM bundle exceeds the 10 MB script limit, and `eval()` / `new Function()` are blocked at the V8 level), so the interpreter handles the patterns that cover the vast majority of published MCP servers.

The language is detected automatically from the registry entry's `lang` field (`"python"`, `"javascript"`, or `"typescript"`). Two interpreter modules live under `src/interpreter/`:

- **`python.ts`**: parses and executes Python MCP tools
- **`javascript.ts`**: parses and executes JS/TS MCP tools
- **`parsing.ts`**: shared string-parsing utilities

### Supported (Python)

- `requests.get/post/put/patch/delete` (mapped to native `fetch`)
- Dict, list, string, and numeric operations
- f-strings, `if/elif/else`, `for` loops, `try/except`
- Common builtins: `int`, `float`, `str`, `bool`, `len`, `min`, `max`, `range`, `enumerate`, `zip`
- JSON serialization / deserialization

### Supported (JS/TS)

- `fetch()` with `URL`, `URLSearchParams`, custom headers
- Template literals, `const`/`let`, arrow functions
- `JSON.parse` / `JSON.stringify`
- Zod schema parsing (tool input schemas)
- Common builtins: `parseInt`, `parseFloat`, `String`, `Boolean`, `Array`, `Object`, `Math`

### Not supported

- `httpx`, `aiohttp`, or any HTTP library other than `requests`
- Packages with C extensions (`pandas`, `numpy`, `cryptography`, etc.)
- `async def` / `await`
- List/dict/set comprehensions
- Class definitions
- Complex stdlib usage (`os`, `subprocess`, `socket`, etc.)

uv, pip, and poetry are package managers; what matters is what they install. Python servers that install `requests`-based packages work. Servers that install `httpx`, C-extension packages, or rely on async patterns do not. For JS/TS servers, standard `fetch()` patterns work; servers that rely on Node-specific APIs (`fs`, `child_process`, etc.) do not.

## Real-time logs

```bash
wrangler tail superbox-executor --format pretty
```