@scratchrun/mcp-server 0.1.0 → 0.1.2

package/README.md

@@ -56,12 +56,15 @@ Output files are returned as base64. Image files (PNG, JPG, SVG) are returned as
 
 - 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
+- RFC 1918 private ranges are blocked. Link-local `169.254.x.x` is **not**: an
+  instance-metadata service is reachable. It exposes no credentials (no IAM
+  role is attached), only placement data and a per-VM key.
+- No in-guest hardening: code runs as root on a writable filesystem, and `/tmp`
+  is ordinary disk inside the VM. All of it is destroyed with the VM.
 
 ## Latency
 
-~400ms median (warm pool). 2–8s cold start if the pool is empty.
+~3.4s median end to end, ~4.2s p95 for trivial code (measured over 100 sequential runs). Every call boots a fresh hardware-isolated MicroVM and destroys it afterwards; real workloads take as long as the work takes.
 
 ## License
 

package/dist/index.js

@@ -15,7 +15,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             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). " +
+                "Full internet egress; RFC 1918 private ranges are blocked, link-local 169.254.x.x is not. " +
                 "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: {
@@ -84,22 +84,79 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         body.files = args.files;
     if (args.return_files)
         body.return_files = args.return_files;
+    // Capacity retry.
+    //
+    // ScratchRun is currently limited to roughly one execution per second across
+    // the service, so a 429 under load is expected rather than exceptional. The
+    // agent should not have to handle that, so we absorb it here.
+    //
+    // Three deliberate choices:
+    //   BOUNDED  — an unbounded silent retry is worse than a clear error, because
+    //              the caller has its own timeout and token budget and cannot tell
+    //              "waiting" apart from "hung". We stop at RETRY_BUDGET_MS and
+    //              return a structured error it can act on.
+    //   JITTERED — full jitter, not fixed backoff. Without it, callers that
+    //              collide once collide again on every retry, and the unlucky one
+    //              starves. Jitter dissolves that without needing a queue.
+    //   QUIET    — no output for short waits. One progress line once the wait gets
+    //              long, which is for the human watching the agent, not the agent.
+    const RETRY_BUDGET_MS = 45_000;
+    const BASE_DELAY_MS = 500;
+    const MAX_DELAY_MS = 8_000;
+    const NOTIFY_AFTER_MS = 2_000;
+    const started = Date.now();
+    let attempt = 0;
+    let waited = 0;
+    let notified = false;
     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,
-        };
+    for (;;) {
+        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,
+            };
+        }
+        // 429 = capacity. 503 = service-wide daily ceiling; retrying will not help.
+        if (res.status !== 429)
+            break;
+        const elapsed = Date.now() - started;
+        // Full jitter: pick uniformly from [0, capped exponential backoff].
+        const ceiling = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * 2 ** attempt);
+        let delay = Math.random() * ceiling;
+        // Honour a server Retry-After when it asks for longer than our own backoff.
+        const ra = Number(res.headers.get("Retry-After"));
+        if (Number.isFinite(ra) && ra * 1000 > delay)
+            delay = ra * 1000;
+        if (elapsed + delay > RETRY_BUDGET_MS) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `Sandbox capacity unavailable after ${Math.round(elapsed / 1000)}s of retrying. ` +
+                            `ScratchRun serves roughly one execution per second across all users, so this ` +
+                            `means sustained contention rather than an outage. Retry in a minute, or reduce ` +
+                            `how many executions you issue in parallel.`,
+                    }],
+                isError: true,
+            };
+        }
+        if (!notified && elapsed + delay > NOTIFY_AFTER_MS) {
+            notified = true;
+            // stderr, not the tool result — visible to the operator, invisible to the model
+            console.error(`[scratchrun] waiting for sandbox capacity (~${Math.round(delay / 1000)}s)...`);
+        }
+        await new Promise((r) => setTimeout(r, delay));
+        waited += delay;
+        attempt++;
     }
     if (res.status === 401) {
         return {

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@scratchrun/mcp-server",
-  "version": "0.1.0",
+  "version": "0.1.2",
+  "mcpName": "dev.scratchrun/mcp",
   "description": "MCP server for ScratchRun — ephemeral MicroVM code execution for AI agents",
   "type": "module",
   "bin": {