dtc-mcp 0.2.0 → 1.0.0

package/dist/sandbox/sandbox-helpers.js

@@ -0,0 +1,98 @@
+/**
+ * JS source for the output-discipline helpers that get injected into the
+ * sandbox global scope. Same code runs in both runners (node:vm and
+ * isolated-vm) — keeping this as a single string source-of-truth means the
+ * behavior the LLM observes is identical regardless of which runner is
+ * actually executing.
+ *
+ * Why these helpers exist: Stainless's published benchmark caps factuality
+ * at 53% across all code-mode MCPs, with the model "tending toward verbose
+ * responses beyond what's strictly necessary." These helpers give the LLM
+ * a vocabulary to project / aggregate / trim raw API responses before
+ * returning, and the docs explicitly point at them.
+ */
+export const SANDBOX_HELPERS_SOURCE = `
+/**
+ * pick(value, schema) — projection over deep objects + arrays.
+ *
+ * schema is a partial mirror of value's shape; truthy leaves are kept.
+ *   pick({a:1,b:2,c:{x:3,y:4}}, {a:true, c:{x:true}}) → {a:1, c:{x:3}}
+ *
+ * Arrays inherit the schema for each element:
+ *   pick([{a:1,b:2}, {a:3,b:4}], {a:true}) → [{a:1}, {a:3}]
+ */
+globalThis.pick = function pick(value, schema) {
+  if (value === null || value === undefined) return value;
+  if (Array.isArray(value)) return value.map((item) => pick(item, schema));
+  if (typeof value !== 'object') return value;
+  if (schema === true) return value;
+  if (!schema || typeof schema !== 'object') return undefined;
+  const out = {};
+  for (const key of Object.keys(schema)) {
+    if (!(key in value)) continue;
+    const subSchema = schema[key];
+    if (subSchema === true) {
+      out[key] = value[key];
+    } else if (subSchema && typeof subSchema === 'object') {
+      out[key] = pick(value[key], subSchema);
+    }
+  }
+  return out;
+};
+
+/**
+ * topN(arr, n, by) — top N items by a numeric key (descending).
+ *   topN([{revenue: 10}, {revenue: 30}, {revenue: 20}], 2, 'revenue')
+ *     → [{revenue: 30}, {revenue: 20}]
+ *
+ * by can be a string (property name) or a function (custom comparator value).
+ */
+globalThis.topN = function topN(arr, n, by) {
+  if (!Array.isArray(arr)) return [];
+  const keyFn = typeof by === 'function' ? by : (item) => (item == null ? 0 : item[by] ?? 0);
+  return [...arr]
+    .map((item) => ({ item, key: Number(keyFn(item)) || 0 }))
+    .sort((a, b) => b.key - a.key)
+    .slice(0, n)
+    .map((entry) => entry.item);
+};
+
+/**
+ * summarize(arr, opts) — auto-summarize an array. Returns:
+ *   { count, top?, total?, avg?, min?, max? }
+ *
+ * Options:
+ *   - by: string | (item) => number — the numeric field to aggregate
+ *   - topN: number — also return the top N items by 'by' (default: omitted)
+ *   - total: boolean — include sum (default: true when 'by' is set)
+ *   - stats: boolean — include avg/min/max (default: true when 'by' is set)
+ */
+globalThis.summarize = function summarize(arr, opts) {
+  opts = opts || {};
+  if (!Array.isArray(arr)) {
+    return { count: 0 };
+  }
+  const result = { count: arr.length };
+  if (opts.by !== undefined) {
+    const keyFn = typeof opts.by === 'function' ? opts.by : (item) => (item == null ? 0 : item[opts.by] ?? 0);
+    const values = arr.map((item) => Number(keyFn(item)) || 0);
+    const wantTotal = opts.total !== false;
+    const wantStats = opts.stats !== false;
+    if (wantTotal) {
+      result.total = values.reduce((s, v) => s + v, 0);
+    }
+    if (wantStats && values.length > 0) {
+      result.min = Math.min(...values);
+      result.max = Math.max(...values);
+      result.avg = result.total !== undefined
+        ? result.total / values.length
+        : values.reduce((s, v) => s + v, 0) / values.length;
+    }
+    if (opts.topN && opts.topN > 0) {
+      result.top = topN(arr, opts.topN, opts.by);
+    }
+  }
+  return result;
+};
+`.trim();
+//# sourceMappingURL=sandbox-helpers.js.map

package/dist/sandbox/sandbox-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-helpers.js","sourceRoot":"","sources":["../../src/sandbox/sandbox-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmFrC,CAAC,IAAI,EAAE,CAAC"}

package/dist/sandbox/sidecar/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Sidecar entrypoint — spawned by the main MCP server as a child Node process.
+ *
+ * Why it exists: Claude Desktop is Electron with hardened runtime + Library
+ * Validation, which refuses to dlopen native modules whose code signature
+ * doesn't share Anthropic's Team ID. `isolated-vm` therefore can't be loaded
+ * directly inside the main MCP server. A child process spawned from the
+ * user's system `node` binary has no such restriction, so we load
+ * isolated-vm here and proxy execute requests to/from main via stdio.
+ *
+ * Protocol: newline-delimited JSON, see ../protocol.ts.
+ *   stdin  ← MainToSidecar messages
+ *   stdout → SidecarToMain messages
+ *   stderr → diagnostic logs only (not protocol)
+ */
+export {};

package/dist/sandbox/sidecar/index.js

@@ -0,0 +1,346 @@
+/**
+ * Sidecar entrypoint — spawned by the main MCP server as a child Node process.
+ *
+ * Why it exists: Claude Desktop is Electron with hardened runtime + Library
+ * Validation, which refuses to dlopen native modules whose code signature
+ * doesn't share Anthropic's Team ID. `isolated-vm` therefore can't be loaded
+ * directly inside the main MCP server. A child process spawned from the
+ * user's system `node` binary has no such restriction, so we load
+ * isolated-vm here and proxy execute requests to/from main via stdio.
+ *
+ * Protocol: newline-delimited JSON, see ../protocol.ts.
+ *   stdin  ← MainToSidecar messages
+ *   stdout → SidecarToMain messages
+ *   stderr → diagnostic logs only (not protocol)
+ */
+import { createInterface } from "node:readline";
+import { SANDBOX_HELPERS_SOURCE } from "../sandbox-helpers.js";
+function send(msg) {
+    process.stdout.write(JSON.stringify(msg) + "\n");
+}
+function logErr(line) {
+    process.stderr.write(`[sidecar] ${line}\n`);
+}
+// Step 1: try to load isolated-vm. If this throws, we tell main and exit so it
+// can fall back to the in-process node:vm runner.
+let ivmModule;
+try {
+    ivmModule = await import("isolated-vm").then((m) => m.default ?? m);
+}
+catch (e) {
+    send({
+        type: "fatal",
+        reason: `isolated-vm load failed: ${e instanceof Error ? e.message : String(e)}`,
+    });
+    process.exit(1);
+}
+const ivm = ivmModule;
+const ivmVersion = ivmModule.version ?? "unknown";
+// Step 2: emit ready. Main will follow with an `init` message giving us the
+// method-path registry to mirror into the isolate's globals.
+send({ type: "ready", ivmVersion });
+let methodPaths = [];
+let proxyScript = null;
+// Track host-call resolves per (execId, callId). Each isolate execute can fan
+// out many host calls in parallel (Promise.all in user code), so we need
+// per-call resolution rather than per-execute.
+const pendingHostCalls = new Map();
+// ---- Stateful session ----
+//
+// One isolate per sidecar process = one MCP connection. Bootstrap runs once;
+// each execute reuses the same context so user variables (`globalThis.x =
+// ...`) persist across calls. After 30 min idle the isolate is disposed and
+// the next execute recreates it with `sessionReset: true` in the result.
+const IDLE_TTL_MS = 30 * 60_000;
+const HEAP_LIMIT_MB = 256;
+let session = null;
+let idleTimer = null;
+// Pulls the current execute's id so the host-call bridge can tag outbound
+// messages. Set in handleExecute before user code runs.
+let currentExecId = null;
+const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+rl.on("line", (line) => {
+    if (!line.trim())
+        return;
+    let msg;
+    try {
+        msg = JSON.parse(line);
+    }
+    catch (e) {
+        logErr(`bad JSON from main: ${e instanceof Error ? e.message : String(e)}`);
+        return;
+    }
+    switch (msg.type) {
+        case "init":
+            handleInit(msg);
+            break;
+        case "execute":
+            void handleExecute(msg);
+            break;
+        case "host-result":
+            handleHostResult(msg);
+            break;
+        case "shutdown":
+            process.exit(0);
+            break;
+        default:
+            logErr(`unknown msg type: ${msg.type}`);
+    }
+});
+rl.on("close", () => {
+    // Stdin closed → main process is gone or shutting us down. Exit cleanly.
+    process.exit(0);
+});
+function handleInit(msg) {
+    methodPaths = msg.methodPaths;
+    proxyScript = buildIsolateProxyScript(methodPaths);
+}
+function handleHostResult(msg) {
+    const key = `${msg.execId}:${msg.callId}`;
+    const resolver = pendingHostCalls.get(key);
+    if (!resolver) {
+        logErr(`stale host-result for ${key}`);
+        return;
+    }
+    pendingHostCalls.delete(key);
+    resolver(msg.resultJson);
+}
+async function ensureSession() {
+    if (session && !session.isolate.isDisposed) {
+        refreshIdleTimer();
+        return { wasReset: false };
+    }
+    if (!proxyScript) {
+        throw new Error("Sidecar not initialized (missing init message)");
+    }
+    logErr("creating new isolate session");
+    const isolate = new ivm.Isolate({ memoryLimit: HEAP_LIMIT_MB });
+    const context = await isolate.createContext();
+    const jail = context.global;
+    await jail.set("global", jail.derefInto());
+    // The host-bridge Reference is installed ONCE on the persistent context.
+    // It reads currentExecId at call time so calls across executes get tagged
+    // with their owning execute's id.
+    const invokeRef = new ivm.Reference(async (path, argsJson) => {
+        const execId = currentExecId;
+        if (!execId) {
+            return `__ERROR__host call made outside of an execute context`;
+        }
+        const s = session;
+        if (!s) {
+            return `__ERROR__session unavailable`;
+        }
+        const callId = `c${s.callCounter++}`;
+        const key = `${execId}:${callId}`;
+        const promise = new Promise((resolveCall) => {
+            pendingHostCalls.set(key, resolveCall);
+        });
+        send({
+            type: "host-call",
+            execId,
+            callId,
+            path,
+            argsJson,
+        });
+        return promise;
+    });
+    await jail.set("__host_invoke", invokeRef);
+    // Bootstrap: install proxy + console capture + sandbox helpers. Runs once.
+    const bootstrap = await isolate.compileScript(proxyScript);
+    await bootstrap.run(context);
+    session = { isolate, context, callCounter: 0 };
+    refreshIdleTimer();
+    return { wasReset: true };
+}
+function refreshIdleTimer() {
+    if (idleTimer)
+        clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => {
+        logErr("idle TTL hit; disposing isolate");
+        disposeSession();
+    }, IDLE_TTL_MS);
+    idleTimer.unref?.();
+}
+function disposeSession() {
+    if (idleTimer) {
+        clearTimeout(idleTimer);
+        idleTimer = null;
+    }
+    if (session) {
+        try {
+            session.isolate.dispose();
+        }
+        catch {
+            // already disposed
+        }
+        session = null;
+    }
+}
+async function handleExecute(msg) {
+    const start = Date.now();
+    let wasReset = false;
+    try {
+        ({ wasReset } = await ensureSession());
+    }
+    catch (e) {
+        send({
+            type: "execute-result",
+            id: msg.id,
+            ok: false,
+            error: e instanceof Error ? e.message : String(e),
+            stdout: [],
+            durationMs: Date.now() - start,
+        });
+        return;
+    }
+    const s = session;
+    if (!s) {
+        send({
+            type: "execute-result",
+            id: msg.id,
+            ok: false,
+            error: "session disposed before execute could run",
+            stdout: [],
+            durationMs: Date.now() - start,
+        });
+        return;
+    }
+    currentExecId = msg.id;
+    try {
+        // Reset stdout for this call; user-declared globals on `globalThis`
+        // persist across calls (the whole point of stateful sessions).
+        // Strip TS in the main process before sending — we don't ship sucrase
+        // to the sidecar (see sidecar-runner.ts).
+        const wrapped = `
+(async () => {
+  __resetStdout();
+  const __result = await (async () => {
+${msg.code}
+  })();
+  return JSON.stringify({
+    result: __result === undefined ? null : __result,
+    stdout: __getStdout(),
+  });
+})();
+`;
+        const userScript = await s.isolate.compileScript(wrapped);
+        const resultJson = (await userScript.run(s.context, {
+            timeout: msg.timeoutMs,
+            promise: true,
+        }));
+        const parsed = JSON.parse(resultJson);
+        send({
+            type: "execute-result",
+            id: msg.id,
+            ok: true,
+            resultJson: JSON.stringify(parsed.result ?? null),
+            stdout: parsed.stdout,
+            durationMs: Date.now() - start,
+            ...(wasReset ? { sessionReset: true } : {}),
+        });
+    }
+    catch (e) {
+        const msgStr = e instanceof Error ? e.message : String(e);
+        const isTimeout = msgStr.includes("Script execution timed out");
+        const isOOM = msgStr.includes("memory") || msgStr.includes("Array buffer allocation");
+        // Memory limit kills the isolate. Drop the session so the next call
+        // builds a fresh one (the LLM will see sessionReset on it).
+        if (isOOM) {
+            disposeSession();
+        }
+        send({
+            type: "execute-result",
+            id: msg.id,
+            ok: false,
+            error: isTimeout
+                ? `Code timed out after ${msg.timeoutMs}ms. Add \`// @timeout 2m\` (max 5m) at the top of your code to extend.`
+                : msgStr,
+            stdout: [],
+            durationMs: Date.now() - start,
+            ...(wasReset ? { sessionReset: true } : {}),
+        });
+    }
+    finally {
+        currentExecId = null;
+        // Don't dispose the isolate — that's the whole point of stateful sessions.
+        // Clean up any orphaned pending host calls for this execute.
+        for (const key of pendingHostCalls.keys()) {
+            if (key.startsWith(`${msg.id}:`))
+                pendingHostCalls.delete(key);
+        }
+        refreshIdleTimer();
+    }
+}
+/**
+ * Build the JS that runs INSIDE the isolated-vm isolate. Different from the
+ * node:vm proxy template because isolated-vm requires Reference.apply with
+ * explicit `arguments.copy` / `result.promise` options to cross the isolate
+ * boundary. Args travel as JSON strings to avoid prototype-chain leaks.
+ */
+function buildIsolateProxyScript(paths) {
+    const tree = {};
+    for (const path of paths) {
+        const segments = path.split(".");
+        let cursor = tree;
+        for (let i = 0; i < segments.length - 1; i++) {
+            const key = segments[i];
+            if (typeof cursor[key] !== "object")
+                cursor[key] = {};
+            cursor = cursor[key];
+        }
+        cursor[segments[segments.length - 1]] = path;
+    }
+    function emit(node) {
+        const parts = [];
+        for (const [key, value] of Object.entries(node)) {
+            if (typeof value === "string") {
+                parts.push(`${JSON.stringify(key)}: (...args) => __invoke(${JSON.stringify(value)}, args)`);
+            }
+            else {
+                parts.push(`${JSON.stringify(key)}: ${emit(value)}`);
+            }
+        }
+        return `{${parts.join(",")}}`;
+    }
+    return `
+(function () {
+  const __invoke = async function (path, args) {
+    const argsJson = JSON.stringify(args);
+    const resultJson = await __host_invoke.apply(undefined, [path, argsJson], {
+      arguments: { copy: false },
+      result: { promise: true }
+    });
+    if (typeof resultJson === 'string' && resultJson.startsWith('__ERROR__')) {
+      throw new Error(resultJson.slice(9));
+    }
+    return resultJson ? JSON.parse(resultJson) : undefined;
+  };
+
+  const __stdout = [];
+  globalThis.console = {
+    log: (...args) => {
+      __stdout.push(args.map((a) => typeof a === 'string' ? a : JSON.stringify(a)).join(' '));
+    },
+    error: (...args) => {
+      __stdout.push('[err] ' + args.map((a) => typeof a === 'string' ? a : JSON.stringify(a)).join(' '));
+    },
+    warn: (...args) => {
+      __stdout.push('[warn] ' + args.map((a) => typeof a === 'string' ? a : JSON.stringify(a)).join(' '));
+    },
+    info: (...args) => {
+      __stdout.push(args.map((a) => typeof a === 'string' ? a : JSON.stringify(a)).join(' '));
+    },
+  };
+  globalThis.__getStdout = () => __stdout;
+  globalThis.__resetStdout = () => { __stdout.length = 0; };
+
+  const __sdk = ${emit(tree)};
+  for (const k of Object.keys(__sdk)) {
+    globalThis[k] = __sdk[k];
+  }
+})();
+
+${SANDBOX_HELPERS_SOURCE}
+`;
+}
+//# sourceMappingURL=index.js.map

package/dist/sandbox/sidecar/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sandbox/sidecar/index.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/sidecar-runner.d.ts

@@ -0,0 +1,32 @@
+import { type DiscoveredNode } from "./node-discovery.js";
+import type { RunResult } from "./vm-runner.js";
+/**
+ * Sidecar runner: spawns a system-Node child process that hosts `isolated-vm`
+ * and proxies execute_code calls to it. The sidecar exists because Claude
+ * Desktop's Electron hardened runtime blocks loading native modules into the
+ * main MCP server process. See ./sidecar/index.ts for the child side.
+ *
+ * Lifecycle (lazy):
+ *   - First call to runSandboxSidecar triggers discovery + spawn.
+ *   - Sidecar emits `ready` → we send `init` with the method registry.
+ *   - Subsequent calls reuse the same process for low per-call latency.
+ *   - On unexpected exit we mark the runner unavailable; runner.ts falls
+ *     back to the vm-runner for the current and future calls.
+ *
+ * Why not fork() a worker thread instead: workers run in the SAME process
+ * (still bound by Electron's hardened runtime). A separately-spawned `node`
+ * binary is the actual escape hatch.
+ */
+export interface SidecarAvailability {
+    available: true;
+    node: DiscoveredNode;
+}
+export interface SidecarUnavailable {
+    available: false;
+    reason: string;
+}
+export type SidecarStatus = SidecarAvailability | SidecarUnavailable;
+export declare function getSidecarStatus(): Promise<SidecarStatus>;
+export declare function runSandboxSidecar(code: string, options: {
+    timeoutMs: number;
+}): Promise<RunResult>;