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+
• Wrangler CLI (npm i -g wrangler)
• Cloudflare account (wrangler login)

1. Install dependencies

cd cloudflare
npm install

2. Create R2 bucket

wrangler r2 bucket create superbox-mcp-registry

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

wrangler r2 bucket create superbox-mcp-registry-dev

3. Local development

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

4. Deploy to production

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

Copy the deployed URL and set it in your backend .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

wrangler tail superbox-executor --format pretty