@triscope/mcp 0.4.0

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@triscope/mcp",
+  "version": "0.4.0",
+  "description": "MCP server for Triscope: live read_telemetry, set_knob, list_elements, capture_views, run_smoke. Lets Claude Code drive a running triscope dev server.",
+  "type": "module",
+  "bin": {
+    "triscope-mcp": "./bin/triscope-mcp.mjs",
+    "triscope-mcp-supervised": "./bin/triscope-mcp-supervised.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "src"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "pngjs": "^7.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.41",
+    "@types/pngjs": "^6.0.5",
+    "@vitest/coverage-v8": "^2.1.9",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.9"
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "node test/e2e/mcp-tools.e2e.mjs",
+    "test:e2e:all": "node test/e2e/mcp-all.e2e.mjs",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text --coverage.reporter=html"
+  },
+  "keywords": [
+    "triscope",
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "three.js"
+  ]
+}

package/src/browser.ts

@@ -0,0 +1,461 @@
+// Persistent Chromium pool. The MCP server keeps one Chromium child +
+// one CDP websocket alive across capture_views / diff_reference calls so
+// subsequent captures skip the 3-5 s cold start. First call lazy-spawns;
+// later calls navigate the existing page if the URL changed, otherwise reuse.
+//
+// One pool per MCP process. Disposed on process exit (kill -9 also clears
+// the user-data-dir via the OS, since /tmp is volatile).
+
+import type { ChildProcessWithoutNullStreams } from 'node:child_process';
+import { spawn } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { Logger } from './logger.js';
+
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+
+const DEFAULT_CHROME_ARGS = [
+  '--enable-unsafe-webgpu',
+  '--ignore-gpu-blocklist',
+  // Suppress the first-run wizard and the default-browser banner: both
+  // can block the new window from rendering or trigger a different code
+  // path that ignores --remote-debugging-port until dismissed. Both have
+  // been seen to leave Chromium "running" but with no CDP endpoint open,
+  // which manifests as a "DevTools endpoint did not become ready" error.
+  '--no-first-run',
+  '--no-default-browser-check',
+];
+
+export function parseExtraChromeArgs(): string[] {
+  const raw = process.env.TRISCOPE_CHROME_ARGS ?? '';
+  if (!raw.trim()) return [];
+  // Keep this intentionally simple: env-configured args are whitespace split.
+  // Flags containing spaces should be wrapped in a tiny launcher script and
+  // provided via CHROME_BIN instead.
+  return raw.trim().split(/\s+/).filter(Boolean);
+}
+
+export function tailLines(text: string, maxLines = 24): string {
+  const lines = text.trim().split(/\r?\n/).filter(Boolean);
+  return lines.slice(-maxLines).join('\n');
+}
+
+async function readDevtoolsPages(port: number): Promise<any[] | null> {
+  try {
+    const pages = await fetch(`http://127.0.0.1:${port}/json`, {
+      signal: AbortSignal.timeout(1000),
+    }).then((r) => r.json());
+    return Array.isArray(pages) && pages.length > 0 ? pages : null;
+  } catch {
+    return null;
+  }
+}
+
+export function cdpClient(ws) {
+  const pending = new Map();
+  let nextId = 0;
+  ws.onmessage = (event) => {
+    const msg = JSON.parse(event.data);
+    if (msg.id && pending.has(msg.id)) {
+      pending.get(msg.id)(msg);
+      pending.delete(msg.id);
+    }
+  };
+  // When the socket closes or errors mid-call, every pending request would
+  // otherwise sit until its 20s timeout, blocking the next tool call for up to
+  // 20s × N. Drain them immediately with a synthetic error so the failing tool
+  // call rejects fast (and health() can report a sick pool).
+  const drain = (reason: string) => {
+    for (const cb of pending.values()) cb({ error: { message: reason } });
+    pending.clear();
+  };
+  ws.onclose = (event) =>
+    drain(`CDP WebSocket closed (code ${event?.code ?? '?'}) before the response arrived`);
+  ws.onerror = (event) =>
+    drain(`CDP WebSocket error (${event?.message ?? 'unknown'}) before the response arrived`);
+  const call = (method, params = {}) =>
+    new Promise((resolve, reject) => {
+      const id = ++nextId;
+      ws.send(JSON.stringify({ id, method, params }));
+      const t = setTimeout(() => {
+        pending.delete(id);
+        reject(new Error(`CDP timeout for ${method}`));
+      }, 20000);
+      pending.set(id, (msg) => {
+        clearTimeout(t);
+        if (msg.error) reject(new Error(`${method}: ${msg.error.message}`));
+        else resolve(msg);
+      });
+    });
+  return call;
+}
+
+/**
+ * Locate a Chromium-family browser on disk. Resolution order matches
+ * puppeteer/playwright so users who already set one of these for their
+ * existing tooling don't have to duplicate config:
+ *   1. explicit arg
+ *   2. CHROME_BIN
+ *   3. PUPPETEER_EXECUTABLE_PATH
+ *   4. OS-typical defaults (Windows: Program Files\Google\Chrome; macOS:
+ *      /Applications/Google Chrome.app; Linux: PATH-relative `chromium`)
+ */
+
+export function inferGraphicalEnv(): NodeJS.ProcessEnv {
+  if (process.platform !== 'linux') return process.env;
+
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  const uid = typeof process.getuid === 'function' ? process.getuid() : undefined;
+  const runtimeDir = env.XDG_RUNTIME_DIR || (uid !== undefined ? `/run/user/${uid}` : undefined);
+
+  if (runtimeDir && existsSync(runtimeDir)) {
+    env.XDG_RUNTIME_DIR = runtimeDir;
+    if (!env.WAYLAND_DISPLAY) {
+      try {
+        const waylandSocket = readdirSync(runtimeDir).find((name) => /^wayland-\d+$/.test(name));
+        if (waylandSocket) env.WAYLAND_DISPLAY = waylandSocket;
+      } catch {
+        /* best-effort */
+      }
+    }
+  }
+
+  if (!env.DISPLAY && existsSync('/tmp/.X11-unix/X0')) env.DISPLAY = ':0';
+  return env;
+}
+
+export function defaultChromeBinary(): string {
+  if (process.platform === 'win32') {
+    // Windows users normally install Chrome under Program Files. We don't
+    // touch the filesystem to verify — Chrome's own startup will surface
+    // an ENOENT clearly enough — but we pick the typical 64-bit path so
+    // most installs Just Work without setting CHROME_BIN.
+    return 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe';
+  }
+  if (process.platform === 'darwin') {
+    return '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+  }
+  return 'chromium';
+}
+
+export function createBrowserPool({
+  chromeBin = process.env.CHROME_BIN ??
+    process.env.PUPPETEER_EXECUTABLE_PATH ??
+    defaultChromeBinary(),
+  port = Number(process.env.TRISCOPE_DEBUG_PORT ?? 9230),
+  logger = undefined as Logger | undefined,
+} = {}) {
+  let chrome: ChildProcessWithoutNullStreams | null = null;
+  let chromeExit: { code: number | null; signal: NodeJS.Signals | null } | null = null;
+  let chromeStderr = '';
+  let ws = null;
+  let call = null;
+  let currentUrl = null;
+  // URL last confirmed to have rendered ≥1 real frame. Lets getPage skip the
+  // warm-frame wait for an already-warm page (so e.g. auto_tune's capture loop
+  // isn't slowed); reset whenever we navigate or force a reload.
+  let lastWarmUrl: string | null = null;
+
+  async function connectToPage(initialUrl: string, pages: any[]) {
+    const page =
+      pages.find((p) => p.url === initialUrl || p.url?.startsWith(initialUrl)) ?? pages[0];
+    ws = new WebSocket(page.webSocketDebuggerUrl);
+    await new Promise((res, rej) => {
+      ws.onopen = res;
+      ws.onerror = (e) => rej(new Error(`ws error: ${e?.message ?? 'unknown'}`));
+    });
+    call = cdpClient(ws);
+    await call('Runtime.enable');
+    await call('Page.enable');
+    currentUrl = page.url ?? initialUrl;
+    if (currentUrl !== initialUrl) await navigateIfNeeded(initialUrl);
+  }
+
+  function chromeLaunchArgs(profile: string, initialUrl: string): string[] {
+    return [
+      ...DEFAULT_CHROME_ARGS,
+      ...parseExtraChromeArgs(),
+      `--user-data-dir=${profile}`,
+      `--remote-debugging-port=${port}`,
+      '--window-size=1600,900',
+      initialUrl,
+    ];
+  }
+
+  async function ensureBrowser(initialUrl: string) {
+    if (chrome && !chrome.killed && ws && ws.readyState === 1) return;
+
+    // First attach to an already-running browser on the configured port. This
+    // is the reliable path in sandboxed agents where opening a headed GUI may
+    // require a user-approved launcher outside the MCP process.
+    const existingPages = await readDevtoolsPages(port);
+    if (existingPages) {
+      logger?.info('browser', 'attaching to existing DevTools endpoint', {
+        port,
+        pages: existingPages.length,
+      });
+      await connectToPage(initialUrl, existingPages);
+      return;
+    }
+
+    // Profile dir: pid + monotonic timestamp + random suffix → unique per
+    // spawn so two concurrent MCP servers (or one that respawned after a
+    // crash, leaving SingletonLock pointing at a dead PID) can never share
+    // the same dir. Chromium's singleton check is path-based — same dir =
+    // forwards URL to the "running" instance and exits without binding
+    // --remote-debugging-port, which is the silent-fail mode that's hard
+    // to diagnose.
+    const profile = join(
+      tmpdir(),
+      `triscope-mcp-profile-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    );
+    const args = chromeLaunchArgs(profile, initialUrl);
+    chromeExit = null;
+    chromeStderr = '';
+    const browserEnv = inferGraphicalEnv();
+    logger?.info('browser', 'spawning chromium', {
+      chromeBin,
+      port,
+      profile,
+      args,
+      env: {
+        DISPLAY: browserEnv.DISPLAY,
+        WAYLAND_DISPLAY: browserEnv.WAYLAND_DISPLAY,
+        XDG_RUNTIME_DIR: browserEnv.XDG_RUNTIME_DIR,
+      },
+    });
+    chrome = spawn(chromeBin, args, { stdio: ['ignore', 'ignore', 'pipe'], env: browserEnv });
+    chrome.stderr.on('data', (d) => {
+      chromeStderr += String(d);
+      if (chromeStderr.length > 12000) chromeStderr = chromeStderr.slice(-12000);
+    });
+    chrome.on('exit', (code, signal) => {
+      chromeExit = { code, signal };
+      logger?.warn('browser', 'chromium exited', { code, signal, stderr: tailLines(chromeStderr) });
+    });
+    chrome.on('error', (err) => {
+      chromeExit = { code: 1, signal: null };
+      chromeStderr += `\nspawn error: ${(err as any)?.message ?? String(err)}`;
+      logger?.error('browser', 'chromium spawn error', {
+        message: (err as any)?.message ?? String(err),
+      });
+    });
+
+    let pages: any[] | null = null;
+    const start = Date.now();
+    while (Date.now() - start < 10000) {
+      pages = await readDevtoolsPages(port);
+      if (pages) break;
+      if (chromeExit) break;
+      await wait(250);
+    }
+    if (!pages) {
+      const stderr = tailLines(chromeStderr);
+      const exit = chromeExit ? ` chromiumExit=${JSON.stringify(chromeExit)}` : '';
+      // Silent-exit pattern: chromiumExit is null (process didn't die) but
+      // port stayed closed. Almost always: sandboxed Chromium can't bind
+      // network ports, or the singleton check forwarded the URL to a
+      // (non-debuggable) sibling instance.
+      const silentExit = !chromeExit && !pages;
+      const hint = silentExit
+        ? 'Chromium process is alive but DevTools never opened — usually the host sandbox is blocking the bind on TRISCOPE_DEBUG_PORT, or another Chromium instance is reusing the same profile dir. Workarounds: (1) pre-launch Chrome yourself with --remote-debugging-port=' +
+          port +
+          ' --enable-unsafe-webgpu — the MCP server auto-attaches to an existing endpoint when present; (2) set TRISCOPE_DEBUG_PORT to a port the sandbox permits.'
+        : 'If this runs under Codex/Claude and headed launch still fails, pre-launch Chrome with --remote-debugging-port=' +
+          port +
+          ' or set TRISCOPE_CHROME_ARGS=--headless=new for non-interactive capture.';
+      throw new Error(
+        `DevTools endpoint did not become ready on 127.0.0.1:${port}.${exit}${stderr ? `\nstderr:\n${stderr}` : ''}\n${hint}`,
+      );
+    }
+    await connectToPage(initialUrl, pages);
+  }
+
+  function harnessNotMountedError(url: string) {
+    return new Error(
+      `window.__TRISCOPE__ did not mount within 10s on ${url}. ` +
+        `Common causes: ` +
+        `(1) the page never loaded — confirm the dev server is up and the URL is right (open it in a real browser tab); ` +
+        `(2) WebGPU init failed — Linux Chrome needs --enable-unsafe-webgpu and either xvfb or a real display; ` +
+        `(3) runLab() threw before mounting — check the #boot overlay text or the page console; ` +
+        `(4) the lab page doesn't call runLab() at all — verify its entry script imports @triscope/core.`,
+    );
+  }
+
+  // When the harness never mounts, check whether runLab() recorded a precise
+  // mount failure (bad element / mount() threw) and surface THAT instead of the
+  // generic timeout — turns "not mounted within 10s" into "element X failed to
+  // mount: <real error at line N>".
+  async function mountErrorOrTimeout(url: string): Promise<Error> {
+    try {
+      const r = await call('Runtime.evaluate', {
+        expression: 'JSON.stringify(window.__TRISCOPE_MOUNT_ERROR__ ?? null)',
+        returnByValue: true,
+      });
+      const me = JSON.parse(r.result.result.value);
+      if (me?.message) {
+        const probs = me.problems?.length
+          ? `\nContract problems:\n - ${me.problems.join('\n - ')}`
+          : '';
+        return new Error(`element "${me.element ?? '?'}" failed to mount: ${me.message}${probs}`);
+      }
+    } catch {
+      /* fall through to the generic message */
+    }
+    return harnessNotMountedError(url);
+  }
+
+  async function navigateIfNeeded(url) {
+    if (url === currentUrl) return;
+    await call('Page.navigate', { url });
+    lastWarmUrl = null; // new document → not warm until a frame renders
+    // Wait for the harness to remount on the new page.
+    const start = Date.now();
+    while (Date.now() - start < 10000) {
+      try {
+        const probe = await call('Runtime.evaluate', {
+          expression:
+            '!!window.__TRISCOPE__ && (Object.keys(window.__TRISCOPE__.cameras || {}).length > 0 || typeof window.__TRISCOPE__.availableElements === "function")',
+          returnByValue: true,
+        });
+        if (probe.result.result.value) {
+          currentUrl = url;
+          return;
+        }
+      } catch {}
+      await wait(200);
+    }
+    throw await mountErrorOrTimeout(url);
+  }
+
+  async function waitForHarness() {
+    for (let i = 0; i < 40; i++) {
+      try {
+        const probe = await call('Runtime.evaluate', {
+          expression:
+            '!!window.__TRISCOPE__ && (Object.keys(window.__TRISCOPE__.cameras || {}).length > 0 || typeof window.__TRISCOPE__.availableElements === "function")',
+          returnByValue: true,
+        });
+        if (probe.result.result.value) return;
+      } catch {
+        // Transient "execution context destroyed" while a reload tears down the
+        // old document — retry (mirrors navigateIfNeeded). Without this a probe
+        // landing mid-teardown throws raw out of a fresh:true call.
+      }
+      await wait(250);
+    }
+    throw await mountErrorOrTimeout(currentUrl ?? '(initial page)');
+  }
+
+  // Wait for the harness to render a REAL frame before a capture. The mount
+  // probe (waitForHarness/navigateIfNeeded) only proves window.__TRISCOPE__
+  // exists — not that anything was drawn. Capturing in that gap yields a black
+  // pre-render frame (observed: diff_reference came back black right after a
+  // fresh navigate while a warmed capture_views rendered fine). Polls the
+  // harness's monotonic framesRendered() (true on the first RAF), falling back
+  // to fps>0 for older labs. Skips entirely when the page is already warm.
+  async function waitForWarmFrame() {
+    if (currentUrl && currentUrl === lastWarmUrl) return;
+    for (let i = 0; i < 20; i++) {
+      try {
+        const probe = await call('Runtime.evaluate', {
+          expression:
+            '(function(){var t=window.__TRISCOPE__;if(!t)return 0;if(typeof t.framesRendered==="function")return t.framesRendered();try{return (t.sampleTelemetry&&t.sampleTelemetry().perf&&t.sampleTelemetry().perf.fps>0)?2:0;}catch(e){return 0;}})()',
+          returnByValue: true,
+        });
+        if ((probe.result.result.value ?? 0) >= 2) {
+          lastWarmUrl = currentUrl;
+          return;
+        }
+      } catch {
+        /* transient eval failure — retry */
+      }
+      await wait(100);
+    }
+    // Timed out without a confirmed frame — proceed anyway; per-camera
+    // blackFrames detection in capture_views is the backstop. Cache as "warm"
+    // so a perpetually-slow page doesn't re-block every capture.
+    lastWarmUrl = currentUrl;
+  }
+
+  async function isAlive() {
+    if (!chrome || chrome.killed || !ws || ws.readyState !== 1) return false;
+    // Even with WS open, the page may be hung. Probe with a fast no-op
+    // CDP call and short timeout so a stalled Chromium is detected here
+    // rather than at the much heavier Page.navigate that follows.
+    try {
+      await Promise.race([
+        call('Runtime.evaluate', { expression: '1', returnByValue: true }),
+        new Promise((_, rej) => setTimeout(() => rej(new Error('alive probe timeout')), 1500)),
+      ]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  function disposeQuiet() {
+    try {
+      ws?.close();
+    } catch {}
+    try {
+      if (chrome && !chrome.killed) chrome.kill();
+    } catch {}
+    ws = null;
+    chrome = null;
+    call = null;
+    currentUrl = null;
+    lastWarmUrl = null;
+    chromeExit = null;
+    chromeStderr = '';
+  }
+
+  return {
+    /** Lazy-spawn Chromium (first call) or reuse it (subsequent). Always
+     *  guarantees the page is sitting on `url` with the harness mounted.
+     *  Self-heals: if the previous Chromium died externally (manual kill,
+     *  crash) the next call disposes the stale state and respawns. */
+    async getPage(url, opts: { reload?: boolean } = {}) {
+      const reload = opts?.reload === true;
+      if (chrome && !(await isAlive())) {
+        disposeQuiet();
+      }
+      if (!chrome) {
+        await ensureBrowser(url);
+        await waitForHarness();
+        lastWarmUrl = null;
+      } else if (reload && url === currentUrl) {
+        // Force a fresh load of the SAME url to pick up source edits the pool's
+        // cached page would otherwise miss (e.g. a *.lab.ts edit that doesn't
+        // match the dev plugin's forceReloadOn regex).
+        //
+        // Page.reload resolves on *initiation*, not load — the old execution
+        // context stays scriptable briefly, so waitForHarness/waitForWarmFrame
+        // would otherwise confirm the STALE page (its __TRISCOPE__ + monotonic
+        // framesRendered both still satisfy the probes) and we'd capture the
+        // pre-edit content. Invalidate the old global first so the probes only
+        // pass once the NEW document has mounted a fresh harness.
+        try {
+          await call('Runtime.evaluate', {
+            expression: 'try { window.__TRISCOPE__ = undefined; } catch (e) {}',
+            returnByValue: true,
+          });
+        } catch {
+          /* old context already gone — fine */
+        }
+        lastWarmUrl = null;
+        await call('Page.reload', { ignoreCache: true });
+        await waitForHarness();
+      } else {
+        await navigateIfNeeded(url); // navigates only when url changed
+      }
+      await waitForWarmFrame();
+      return { call };
+    },
+    /** Synchronous teardown. Safe to call multiple times. */
+    dispose() {
+      disposeQuiet();
+    },
+  };
+}

package/src/logger.ts

@@ -0,0 +1,94 @@
+/**
+ * Structured logger for the MCP server.
+ *
+ * Two output sinks:
+ *   - console.error (the existing convention — readable when run under
+ *     Claude Code, doesn't pollute stdout which is the MCP transport)
+ *   - /tmp/<project>-mcp.log with naive 1 MB rotation (rename to .1 then
+ *     truncate), so a long-running server keeps a persistent error trail
+ *     without leaking disk.
+ *
+ * Each entry is one JSON line:
+ *   {"ts":"2026-05-17T15:00:00.000Z","level":"error","scope":"capture",
+ *    "msg":"…","meta":{…}}
+ *
+ * Designed for grep / jq, not for fancy log libraries.
+ */
+import { appendFileSync, existsSync, renameSync, statSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+export type LogLevel = 'info' | 'warn' | 'error' | 'debug';
+
+export interface LogEntry {
+  ts: string;
+  level: LogLevel;
+  scope: string;
+  msg: string;
+  meta?: Record<string, unknown>;
+}
+
+export interface Logger {
+  info(scope: string, msg: string, meta?: Record<string, unknown>): void;
+  warn(scope: string, msg: string, meta?: Record<string, unknown>): void;
+  error(scope: string, msg: string, meta?: Record<string, unknown>): void;
+  debug(scope: string, msg: string, meta?: Record<string, unknown>): void;
+  readonly logPath: string;
+}
+
+const MAX_LOG_BYTES = 1024 * 1024; // 1 MB
+
+export function createLogger(project: string): Logger {
+  const logPath = join(tmpdir(), `${project}-mcp.log`);
+
+  function rotateIfNeeded(): void {
+    try {
+      if (!existsSync(logPath)) return;
+      const size = statSync(logPath).size;
+      if (size < MAX_LOG_BYTES) return;
+      const rolled = `${logPath}.1`;
+      if (existsSync(rolled)) {
+        try {
+          unlinkSync(rolled);
+        } catch {
+          /* best-effort */
+        }
+      }
+      renameSync(logPath, rolled);
+    } catch {
+      /* never let logging crash the server */
+    }
+  }
+
+  function write(entry: LogEntry): void {
+    // console (stderr — stdout is taken by MCP stdio transport)
+    const tag = `[triscope-mcp:${entry.level}:${entry.scope}]`;
+    if (entry.level === 'error' || entry.level === 'warn') {
+      // eslint-disable-next-line no-console
+      console.error(tag, entry.msg, entry.meta ?? '');
+    } else if (process.env.TRISCOPE_MCP_DEBUG) {
+      // eslint-disable-next-line no-console
+      console.error(tag, entry.msg, entry.meta ?? '');
+    }
+    // file
+    try {
+      rotateIfNeeded();
+      appendFileSync(logPath, JSON.stringify(entry) + '\n');
+    } catch {
+      /* swallow */
+    }
+  }
+
+  function make(level: LogLevel) {
+    return (scope: string, msg: string, meta?: Record<string, unknown>) =>
+      write({ ts: new Date().toISOString(), level, scope, msg, meta });
+  }
+
+  return {
+    info: make('info'),
+    warn: make('warn'),
+    error: make('error'),
+    debug: make('debug'),
+    logPath,
+  };
+}