@scratchrun/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,68 @@
+# @scratchrun/mcp-server
+
+MCP server for [ScratchRun](https://scratchrun.dev) — ephemeral, MicroVM-isolated code execution for AI agents.
+
+Each call runs in a fresh hardware-isolated MicroVM. The VM is hard-purged after execution. No state, no files, nothing persists between calls.
+
+## Install
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "scratchrun": {
+      "command": "npx",
+      "args": ["-y", "@scratchrun/mcp-server"],
+      "env": {
+        "SCRATCHRUN_API_KEY": "sr_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+Get an API key at [scratchrun.dev](https://scratchrun.dev).
+
+## Tool: `scratchrun_exec`
+
+Executes code in an ephemeral sandbox and returns stdout, stderr, exit code, and any output files.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `runtime` | `python3.12` \| `python3.11` \| `node20` \| `bash` | yes | Runtime to use |
+| `code` | string | yes | Code to execute |
+| `timeout_ms` | integer | no | Timeout in ms (default 10000, max 30000) |
+| `memory_mb` | integer | no | Memory limit in MB (default 256, max 512) |
+| `env` | object | no | Environment variables — use for secrets, not code strings |
+| `files` | object | no | Files to write before execution (path → content) |
+| `return_files` | string[] | no | File paths to capture after execution (returned as base64) |
+
+**Example — run Python and return a chart:**
+
+```json
+{
+  "runtime": "python3.12",
+  "code": "import matplotlib.pyplot as plt\nimport numpy as np\nx = np.linspace(0, 10, 100)\nplt.plot(x, np.sin(x))\nplt.savefig('/tmp/plot.png')",
+  "return_files": ["/tmp/plot.png"]
+}
+```
+
+Output files are returned as base64. Image files (PNG, JPG, SVG) are returned as MCP image content blocks and render inline in Claude.
+
+## Isolation
+
+- Hardware-virtualized MicroVM per execution (own kernel, not a shared-kernel container)
+- `TerminateMicroVM` called unconditionally after every run — VM destroyed, never reused
+- RFC 1918 + cloud metadata (`169.254.x.x`) always blocked at the network layer
+- Read-only system filesystem via OverlayFS; `/tmp` is RAM-backed and gone with the VM
+
+## Latency
+
+~400ms median (warm pool). 2–8s cold start if the pool is empty.
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+const API_BASE = "https://api.scratchrun.dev";
+const API_KEY = process.env.SCRATCHRUN_API_KEY;
+if (!API_KEY) {
+    process.stderr.write("Error: SCRATCHRUN_API_KEY environment variable is required.\n");
+    process.exit(1);
+}
+const server = new Server({ name: "scratchrun", version: "0.1.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "scratchrun_exec",
+            description: "Execute code in an ephemeral, MicroVM-isolated sandbox. " +
+                "The VM is hard-purged after execution — no state, no files, nothing persists between calls. " +
+                "Full internet egress (RFC 1918 + cloud metadata always blocked). " +
+                "Use return_files to capture output artifacts (charts, CSVs, data files) as base64. " +
+                "Keep secrets out of code strings — pass them via env instead.",
+            inputSchema: {
+                type: "object",
+                required: ["runtime", "code"],
+                properties: {
+                    runtime: {
+                        type: "string",
+                        enum: ["python3.12", "python3.11", "node20", "bash"],
+                        description: "Runtime. python3.12 includes numpy, pandas, matplotlib, requests, and more.",
+                    },
+                    code: {
+                        type: "string",
+                        description: "Code to execute.",
+                    },
+                    timeout_ms: {
+                        type: "integer",
+                        minimum: 1000,
+                        maximum: 30000,
+                        default: 10000,
+                        description: "Execution timeout in milliseconds. Exit code 124 signals timeout.",
+                    },
+                    memory_mb: {
+                        type: "integer",
+                        minimum: 64,
+                        maximum: 512,
+                        default: 256,
+                        description: "Memory limit in MB.",
+                    },
+                    env: {
+                        type: "object",
+                        additionalProperties: { type: "string" },
+                        description: "Environment variables injected into the sandbox. Use for secrets and config.",
+                    },
+                    files: {
+                        type: "object",
+                        additionalProperties: { type: "string" },
+                        description: "Files to write before execution. Keys are absolute paths, values are file contents.",
+                    },
+                    return_files: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "File paths to capture after execution and return as base64. Use for charts, CSVs, or any output artifact.",
+                    },
+                },
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (request.params.name !== "scratchrun_exec") {
+        throw new Error(`Unknown tool: ${request.params.name}`);
+    }
+    const args = request.params.arguments;
+    const body = {
+        runtime: args.runtime,
+        code: args.code,
+        limits: {
+            timeout_ms: args.timeout_ms ?? 10000,
+            memory_mb: args.memory_mb ?? 256,
+        },
+    };
+    if (args.env)
+        body.env = args.env;
+    if (args.files)
+        body.files = args.files;
+    if (args.return_files)
+        body.return_files = args.return_files;
+    let res;
+    try {
+        res = await fetch(`${API_BASE}/v1/exec`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${API_KEY}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Network error: ${String(err)}` }],
+            isError: true,
+        };
+    }
+    if (res.status === 401) {
+        return {
+            content: [{ type: "text", text: "Error: Invalid API key. Check SCRATCHRUN_API_KEY." }],
+            isError: true,
+        };
+    }
+    if (res.status === 429) {
+        const retryAfter = res.headers.get("Retry-After") ?? "10";
+        return {
+            content: [{ type: "text", text: `Sandbox capacity temporarily unavailable. Retry after ${retryAfter}s.` }],
+            isError: true,
+        };
+    }
+    if (!res.ok) {
+        const text = await res.text();
+        return {
+            content: [{ type: "text", text: `Error ${res.status}: ${text}` }],
+            isError: true,
+        };
+    }
+    const result = await res.json();
+    const summary = [
+        `exit_code: ${result.exit_code}`,
+        `execution_ms: ${result.execution_ms}`,
+        `state_purged: ${result.state_purged}`,
+    ];
+    if (result.stdout)
+        summary.push(`\nstdout:\n${result.stdout}`);
+    if (result.stderr)
+        summary.push(`\nstderr:\n${result.stderr}`);
+    if (result.note)
+        summary.push(`\nnote: ${result.note}`);
+    const content = [{ type: "text", text: summary.join("\n") }];
+    if (result.files) {
+        const imageTypes = {
+            png: "image/png",
+            jpg: "image/jpeg",
+            jpeg: "image/jpeg",
+            gif: "image/gif",
+            svg: "image/svg+xml",
+            webp: "image/webp",
+        };
+        for (const [path, b64] of Object.entries(result.files)) {
+            const ext = path.split(".").pop()?.toLowerCase() ?? "";
+            if (ext in imageTypes) {
+                content.push({ type: "image", data: b64, mimeType: imageTypes[ext] });
+            }
+            else {
+                const decoded = Buffer.from(b64, "base64").toString("utf-8");
+                content.push({ type: "text", text: `\n--- ${path} ---\n${decoded}` });
+            }
+        }
+    }
+    return { content };
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@scratchrun/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for ScratchRun — ephemeral MicroVM code execution for AI agents",
+  "type": "module",
+  "bin": {
+    "scratchrun-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "node --loader ts-node/esm src/index.ts"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.2",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "scratchrun",
+    "code-execution",
+    "sandbox",
+    "microvm",
+    "ai-agents"
+  ],
+  "license": "MIT"
+}