SuperBox-Executor

# 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 ```