pursor 0.2.0

package/src/interact.js

@@ -0,0 +1,138 @@
+// click, type, wait, seq — interaction primitives.
+
+import { launch, newPage } from "./runway.js";
+import { DEFAULT_VIEWPORT } from "./viewport.js";
+import { gotoOrThrow, settle, CLICK_TIMEOUT_MS, WAIT_DEFAULT_TIMEOUT_MS } from "./overlays.js";
+import { resolveLocator } from "./selector.js";
+import { requireArg } from "./util.js";
+
+export async function runClick(url, selector, out) {
+  requireArg("url", url, "string");
+  requireArg("selector", selector, "string");
+  const browser = await launch();
+  try {
+    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    const r = await gotoOrThrow(page, url); await settle(page);
+    const loc = await resolveLocator(page, selector);
+    await loc.first().waitFor({ state: "visible", timeout: CLICK_TIMEOUT_MS });
+    await loc.first().click({ timeout: CLICK_TIMEOUT_MS });
+    await settle(page);
+    if (out) await page.screenshot({ path: out, fullPage: false });
+    return { ...r, url, out, selector, clicked: true };
+  } finally { try { await browser.close(); } catch {} }
+}
+
+export async function runType(url, selector, text, out) {
+  requireArg("url", url, "string");
+  requireArg("selector", selector, "string");
+  const browser = await launch();
+  try {
+    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    const r = await gotoOrThrow(page, url); await settle(page);
+    const loc = await resolveLocator(page, selector);
+    await loc.first().waitFor({ state: "visible", timeout: CLICK_TIMEOUT_MS });
+    await loc.first().click({ timeout: CLICK_TIMEOUT_MS });
+    await page.keyboard.type(String(text ?? ""), { delay: 10 });
+    await settle(page);
+    if (out) await page.screenshot({ path: out, fullPage: false });
+    return { ...r, url, out, selector, text, typed: true };
+  } finally { try { await browser.close(); } catch {} }
+}
+
+export async function runWait(url, selector, timeoutMs) {
+  requireArg("url", url, "string");
+  requireArg("selector", selector, "string");
+  const browser = await launch();
+  try {
+    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    const r = await gotoOrThrow(page, url);
+    const loc = await resolveLocator(page, selector);
+    const t = timeoutMs || WAIT_DEFAULT_TIMEOUT_MS;
+    try {
+      await loc.first().waitFor({ state: "visible", timeout: t });
+      return { ...r, url, selector, found: true, timeoutMs: t };
+    } catch {
+      return { ...r, url, selector, found: false, timeoutMs: t };
+    }
+  } finally { try { await browser.close(); } catch {} }
+}
+
+export async function runSeq(url, actionsJson, out) {
+  requireArg("url", url, "string");
+  let actions;
+  try { actions = JSON.parse(actionsJson); }
+  catch (e) { throw new Error(`invalid actions JSON: ${e.message}`, { cause: e }); }
+  if (!Array.isArray(actions)) throw new Error("actions must be a JSON array");
+  if (!actions.length) throw new Error("actions array is empty");
+  const browser = await launch();
+  try {
+    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    const r = await gotoOrThrow(page, url); await settle(page);
+    const trace = [];
+    let failed = false;
+    for (let i = 0; i < actions.length; i++) {
+      const a = actions[i] || {};
+      const step = { i, op: a.op };
+      try {
+        switch (a.op) {
+          case "click": {
+            const loc = await resolveLocator(page, a.selector);
+            await loc.first().waitFor({ state: "visible", timeout: CLICK_TIMEOUT_MS });
+            await loc.first().click({ timeout: CLICK_TIMEOUT_MS });
+            step.selector = a.selector; break;
+          }
+          case "type": {
+            const loc = await resolveLocator(page, a.selector);
+            await loc.first().waitFor({ state: "visible", timeout: CLICK_TIMEOUT_MS });
+            await loc.first().click({ timeout: CLICK_TIMEOUT_MS });
+            await page.keyboard.type(String(a.text ?? ""), { delay: 10 });
+            step.selector = a.selector; step.text = a.text; break;
+          }
+          case "wait": {
+            const t = a.timeoutMs ? Number(a.timeoutMs) : WAIT_DEFAULT_TIMEOUT_MS;
+            const loc = await resolveLocator(page, a.selector);
+            await loc.first().waitFor({ state: "visible", timeout: t });
+            step.selector = a.selector; step.timeoutMs = t; break;
+          }
+          case "eval": { step.result = await page.evaluate(String(a.js ?? "")); break; }
+          case "shot": {
+            await page.screenshot({ path: a.out, fullPage: !!a.fullPage });
+            step.out = a.out; step.fullPage = !!a.fullPage; break;
+          }
+          case "scroll": {
+            const vp = page.viewportSize();
+            await page.mouse.move((vp?.width || 640) / 2, (vp?.height || 400) / 2);
+            await page.mouse.wheel(a.deltaX || 0, a.deltaY || 0);
+            step.deltaX = a.deltaX; step.deltaY = a.deltaY; break;
+          }
+          case "navigate": { await gotoOrThrow(page, a.url); step.url = a.url; break; }
+          case "press": {
+            // a.key can be a single key ("Escape") or comma-separated ("Tab,Enter")
+            const raw = String(a.key ?? "").trim();
+            if (!raw) throw new Error("press: missing key");
+            const keys = raw.split(",").map(k => k.trim()).filter(Boolean);
+            for (const k of keys) await page.keyboard.press(k);
+            step.key = raw; step.count = keys.length; break;
+          }
+          case "sleep": { await page.waitForTimeout(Number(a.ms ?? 1000)); step.ms = a.ms; break; }
+          case "hover": {
+            const loc = await resolveLocator(page, a.selector);
+            await loc.first().waitFor({ state: "visible", timeout: CLICK_TIMEOUT_MS });
+            await loc.first().hover({ timeout: CLICK_TIMEOUT_MS });
+            step.selector = a.selector; break;
+          }
+          default: throw new Error(`unknown op: ${a.op}`);
+        }
+        if (a.settleMs !== undefined) await page.waitForTimeout(Number(a.settleMs));
+        else await settle(page);
+        step.ok = true;
+      } catch (e) {
+        step.ok = false; step.error = e.message; failed = true;
+      }
+      trace.push(step);
+      if (failed) break;
+    }
+    if (out) await page.screenshot({ path: out, fullPage: false });
+    return { ...r, url, out, steps: trace, failed };
+  } finally { try { await browser.close(); } catch {} }
+}

package/src/mcp-resources.js

@@ -0,0 +1,111 @@
+// pursor — MCP resources adapter.
+//
+// Exposes run results as MCP resources so hosts (Claude Code, Cursor, etc.)
+// can browse, preview, and re-read captures without re-running captures.
+//
+// Resource shape (per MCP spec):
+//   uri:        pursor://<kind>/<id>
+//   name:       <human label>
+//   description: <what it is>
+//   mimeType:   image/png | application/json | text/html
+//
+// We track "recent" sweep outputs in-memory + persist an index at
+// $PURSOR_MCP_STATE/mcp-index.json so resources survive restarts.
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import { join, basename, dirname } from "node:path";
+import { homedir } from "node:os";
+import { nowIso } from "./util.js";
+
+function stateDir() {
+  const root = process.env.PURSOR_MCP_STATE || join(homedir(), ".pursor", "mcp");
+  mkdirSync(root, { recursive: true });
+  return root;
+}
+
+function indexPath() { return join(stateDir(), "mcp-index.json"); }
+
+function loadIndex() {
+  const p = indexPath();
+  if (!existsSync(p)) return { resources: [] };
+  try { return JSON.parse(readFileSync(p, "utf8")); } catch { return { resources: [] }; }
+}
+
+function saveIndex(idx) {
+  writeFileSync(indexPath(), JSON.stringify(idx, null, 2), "utf8");
+}
+
+export function recordResource({ kind, id, name, description, uri, mimeType, file, meta }) {
+  const idx = loadIndex();
+  // De-dup by uri
+  idx.resources = idx.resources.filter(r => r.uri !== uri);
+  idx.resources.unshift({
+    kind, id, name, description, uri, mimeType, file, meta: meta || null, ts: nowIso(),
+  });
+  // Cap index size
+  if (idx.resources.length > 200) idx.resources = idx.resources.slice(0, 200);
+  saveIndex(idx);
+  return idx.resources[0];
+}
+
+export function listResources() {
+  // Combine persisted index + any in-memory scan of recent sweep dirs
+  const idx = loadIndex();
+  // Also include sidecars sitting next to a sweep.json under cwd
+  try {
+    const cwd = process.cwd();
+    for (const f of readdirSync(cwd)) {
+      if (f === "sweep.json") {
+        const sweepPath = join(cwd, f);
+        try {
+          const s = JSON.parse(readFileSync(sweepPath, "utf8"));
+          const dirUri = `pursor://sweep/${encodeURIComponent(s.name || basename(cwd))}`;
+          if (!idx.resources.some(r => r.uri === dirUri)) {
+            idx.resources.push({
+              kind: "sweep", id: s.name || basename(cwd),
+              name: `sweep: ${s.name || basename(cwd)}`,
+              description: `Sweep summary: ${(s.steps || []).length} steps`,
+              uri: dirUri, mimeType: "application/json",
+              file: sweepPath, meta: { steps: (s.steps || []).length, ts: s.ts }, ts: s.ts || nowIso(),
+            });
+          }
+        } catch {}
+      }
+    }
+  } catch {}
+  return idx.resources;
+}
+
+export function readResource(uri) {
+  if (typeof uri !== "string") return null;
+  if (!uri.startsWith("pursor://")) return null;
+  // Parse kind/id
+  const rest = uri.slice("pursor://".length);
+  const [kind, ...restParts] = rest.split("/");
+  const id = restParts.join("/");
+  const idx = loadIndex();
+  const r = idx.resources.find(x => x.uri === uri);
+  if (r) {
+    return readResourceFile(r);
+  }
+  // Resolve by kind/id from filesystem fallback
+  if (kind === "sweep") {
+    const file = join(process.cwd(), decodeURIComponent(id), "sweep.json");
+    if (existsSync(file)) {
+      return { uri, mimeType: "application/json", text: readFileSync(file, "utf8") };
+    }
+  }
+  return null;
+}
+
+function readResourceFile(r) {
+  if (!r.file || !existsSync(r.file)) return { uri: r.uri, mimeType: r.mimeType, error: "file not found" };
+  const data = readFileSync(r.file);
+  if (r.mimeType && r.mimeType.startsWith("image/")) {
+    return { uri: r.uri, mimeType: r.mimeType, blob: data.toString("base64") };
+  }
+  if (r.mimeType === "application/json" || r.mimeType === "text/html") {
+    return { uri: r.uri, mimeType: r.mimeType, text: data.toString("utf8") };
+  }
+  return { uri: r.uri, mimeType: r.mimeType || "application/octet-stream", blob: data.toString("base64") };
+}

package/src/mcp.js

@@ -0,0 +1,436 @@
+// pursor — MCP stdio server (Model Context Protocol).
+//
+// Implements JSON-RPC 2.0 over stdio with Content-Length framing.
+// Exposes every pursor capability as an MCP tool for use by
+// Claude Code, Cursor, Continue, and any other MCP host.
+//
+// Config via PURSOR_MCP_CONFIG env or ~/.pursor/mcp-config.json:
+//   { "plugins": ["./my-plugin.js"], "defaultOutDir": "./mcp-output" }
+
+import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { runProbe } from "./probe.js";
+import { runShoot } from "./shoot.js";
+import { runDiff } from "./diff.js";
+import { runSweep } from "./sweep.js";
+import { runFrames } from "./frames.js";
+import { runShootWithSidecar } from "./shoot.js";
+import { captureDomSnapshot } from "./dom-snapshot.js";
+import { runAudit } from "./plugin-audit.js";
+import { loadPlugins, listPlugins } from "./plugin.js";
+import { makeOut, nowIso } from "./util.js";
+import { listResources, readResource, recordResource } from "./mcp-resources.js";
+import { createRequire } from "node:module";
+
+const __require = createRequire(import.meta.url);
+let _pkg = { version: "0.1.0" };
+try { _pkg = __require("../package.json"); } catch {}
+
+const MCP_VERSION = "0.1.0";
+
+// ─── Config ──────────────────────────────────────────────────────────────
+
+function loadConfig() {
+  const envRaw = process.env.PURSOR_MCP_CONFIG;
+  if (envRaw) {
+    try { return JSON.parse(envRaw); } catch { /* not JSON, treat as path */ }
+    try { return JSON.parse(readFileSync(envRaw, "utf8")); } catch {}
+  }
+  const configDir = join(homedir(), ".pursor");
+  const configPath = join(configDir, "mcp-config.json");
+  if (existsSync(configPath)) {
+    try { return JSON.parse(readFileSync(configPath, "utf8")); } catch {}
+  }
+  return {};
+}
+
+// ─── MCP Error ───────────────────────────────────────────────────────────
+
+class McpError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "McpError";
+  }
+}
+
+// ─── Server ──────────────────────────────────────────────────────────────
+
+class PursorMCPServer {
+  constructor(config = {}) {
+    this.config = config;
+    this._buffer = Buffer.alloc(0);
+    this._contentLength = -1;
+    this._initialized = false;
+    this._verbose = !!config.verbose;
+  }
+
+  log(...args) {
+    if (this._verbose) console.error("[pursor-mcp]", ...args);
+  }
+
+  async start() {
+    if (this.config.plugins?.length) {
+      await loadPlugins(this.config.plugins);
+    }
+    this.log("server started, plugins:", listPlugins());
+
+    process.stdin.on("data", (chunk) => {
+      this._buffer = Buffer.concat([this._buffer, chunk]);
+      this._processBuffer();
+    });
+    process.stdin.on("end", () => {
+      this.log("stdin closed");
+    });
+
+    process.on("uncaughtException", (err) => {
+      console.error("[pursor-mcp] uncaught:", err.message);
+    });
+  }
+
+  // ── Buffer framing ──────────────────────────────────────────────────
+
+  _processBuffer() {
+    while (true) {
+      if (this._contentLength < 0) {
+        const idx = this._buffer.indexOf(Buffer.from("\r\n\r\n"));
+        if (idx === -1) break;
+        const header = this._buffer.slice(0, idx).toString("utf8");
+        const m = header.match(/Content-Length:\s*(\d+)/i);
+        if (m) this._contentLength = parseInt(m[1], 10);
+        this._buffer = this._buffer.slice(idx + 4);
+      }
+      if (this._contentLength > 0 && this._buffer.length >= this._contentLength) {
+        const raw = this._buffer.slice(0, this._contentLength).toString("utf8");
+        this._buffer = this._buffer.slice(this._contentLength);
+        this._contentLength = -1;
+        try {
+          const msg = JSON.parse(raw);
+          this._handleMessage(msg);
+        } catch (e) {
+          console.error("[pursor-mcp] invalid JSON:", e.message);
+        }
+      } else break;
+    }
+  }
+
+  _send(msg) {
+    const json = JSON.stringify(msg);
+    const bytes = Buffer.from(json, "utf8");
+    const header = `Content-Length: ${bytes.length}\r\n\r\n`;
+    process.stdout.write(header);
+    process.stdout.write(bytes);
+  }
+
+  // ── JSON-RPC dispatcher ─────────────────────────────────────────────
+
+  async _handleMessage(msg) {
+    if (!msg || msg.jsonrpc !== "2.0" || !msg.method) {
+      console.error("[pursor-mcp] skipping non-JSON-RPC message");
+      return;
+    }
+    const { method, id } = msg;
+
+    // Notifications — no id → no response
+    if (method === "notifications/initialized" || method === "notifications/cancelled") {
+      if (method === "notifications/initialized") this._initialized = true;
+      return;
+    }
+    if (id === undefined || id === null) return; // unnamed notification
+
+    try {
+      switch (method) {
+        case "initialize":
+          this._initialized = true;
+          this._send({
+            jsonrpc: "2.0", id,
+            result: {
+              protocolVersion: msg.params?.protocolVersion || "2024-11-05",
+              capabilities: { tools: {} },
+              serverInfo: { name: "pursor", version: MCP_VERSION },
+            },
+          });
+          break;
+
+        case "tools/list":
+          this._send({ jsonrpc: "2.0", id, result: { tools: this._toolDefs() } });
+          break;
+
+        case "resources/list":
+          this._send({ jsonrpc: "2.0", id, result: { resources: listResources().map(this._toMcpResource, this) } });
+          break;
+
+        case "resources/read":
+          if (!msg.params?.uri) throw new McpError(-32602, "Missing uri");
+          const data = readResource(msg.params.uri);
+          if (!data) throw new McpError(-32602, "Resource not found: " + msg.params.uri);
+          this._send({ jsonrpc: "2.0", id, result: { contents: [data] } });
+          break;
+
+        case "tools/call":
+          if (!msg.params?.name) throw new McpError(-32602, "Missing tool name");
+          const result = await this._callTool(msg.params.name, msg.params.arguments || {});
+          this._send({ jsonrpc: "2.0", id, result: { content: result } });
+          break;
+
+        default:
+          this._send({
+            jsonrpc: "2.0", id,
+            error: { code: -32601, message: `Unknown method: ${method}` },
+          });
+      }
+    } catch (e) {
+      if (e instanceof McpError) {
+        this._send({ jsonrpc: "2.0", id, error: { code: e.code, message: e.message } });
+      } else {
+        console.error("[pursor-mcp] handler error:", e.stack || e.message);
+        this._send({ jsonrpc: "2.0", id, error: { code: -32603, message: e.message } });
+      }
+    }
+  }
+
+  // ── Resource shape adapter ─────────────────────────────────────────
+
+  _toMcpResource(r) {
+    return {
+      uri: r.uri,
+      name: r.name,
+      description: r.description || (r.kind + ": " + r.id),
+      mimeType: r.mimeType || "application/octet-stream",
+    };
+  }
+
+  // ── Tool definitions ────────────────────────────────────────────────
+
+  _toolDefs() {
+    return [
+      {
+        name: "pursor_shoot",
+        description: "Capture a screenshot of a URL with full feature control (viewport, grid, layer, cursor, camera, animation freeze). Returns PNG path and sidecar metadata.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            url:              { type: "string", description: "Target URL" },
+            out:              { type: "string", description: "Output PNG path (auto-gen if omitted)" },
+            preset:           { type: "string", description: "Viewport preset: desktop-1280, desktop-1440, desktop-1920, mobile-375, etc." },
+            width:            { type: "number", description: "Viewport width (custom)" },
+            height:           { type: "number", description: "Viewport height (custom)" },
+            dpr:              { type: "number", description: "Device pixel ratio" },
+            full:             { type: "boolean", description: "Full-page screenshot" },
+            cursor:           { type: "string", description: "Cursor: default|pointer|grab|grabbing|crosshair|none" },
+            grid:             { type: "boolean", description: "Overlay grid" },
+            "grid-tile":     { type: "number", description: "Grid tile size (px)" },
+            "grid-color":    { type: "string", description: "Grid line color" },
+            layer:            { type: "string", description: "Layer isolation: all|entity|terrain|hud|ui" },
+            zoom:             { type: "number", description: "Camera zoom factor" },
+            panX:             { type: "number", description: "Camera pan X (px)" },
+            panY:             { type: "number", description: "Camera pan Y (px)" },
+            "no-animation":  { type: "boolean", description: "Freeze CSS animations" },
+            "wait-frame":    { type: "number", description: "Wait for stable canvas frame (ms)" },
+            "no-hud":        { type: "boolean", description: "Hide header/footer/nav elements" },
+          },
+          required: ["url"],
+        },
+      },
+      {
+        name: "pursor_diff",
+        description: "Pixel-diff a URL against a reference PNG. Returns diff stats and writes diff overlay image.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            url:       { type: "string", description: "URL to capture" },
+            ref:       { type: "string", description: "Reference PNG path" },
+            out:       { type: "string", description: "Diff output PNG (auto-gen if omitted)" },
+            threshold: { type: "number", description: "Pixelmatch threshold 0-1 (default 0.1)" },
+          },
+          required: ["url", "ref"],
+        },
+      },
+      {
+        name: "pursor_sweep",
+        description: "Execute a batch sweep plan (JSON file). Runs multiple capture steps sequentially, returns summary + HTML report.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            plan:   { type: "string", description: "Path to sweep plan JSON" },
+            outDir: { type: "string", description: "Output directory (default from plan)" },
+          },
+          required: ["plan"],
+        },
+      },
+      {
+        name: "pursor_frames",
+        description: "Capture an animation frame timeline — N screenshots at a given interval.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            url:         { type: "string", description: "Target URL" },
+            count:       { type: "number", description: "Number of frames 1-120 (default 8)" },
+            intervalMs:  { type: "number", description: "Interval between frames in ms (default 250)" },
+            outDir:      { type: "string", description: "Output directory (auto-gen if omitted)" },
+          },
+          required: ["url"],
+        },
+      },
+      {
+        name: "pursor_probe",
+        description: "Health-check a URL: returns HTTP status, page title, nav errors. No screenshot.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            url: { type: "string", description: "URL to probe" },
+          },
+          required: ["url"],
+        },
+      },
+      {
+        name: "pursor_audit",
+        description: "Run axe-core WCAG accessibility audit on a URL. Returns violation summary, saves full report + highlighted screenshot.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            url:        { type: "string", description: "Target URL" },
+            tags:       { type: "string", description: "Comma-separated WCAG tags: wcag2a,wcag2aa,wcag21a,wcag21aa" },
+            outDir:     { type: "string", description: "Output directory (auto-gen if omitted)" },
+            screenshot: { type: "boolean", description: "Capture highlighted screenshot (default true)" },
+          },
+          required: ["url"],
+        },
+      },
+      {
+        name: "pursor_dom_snapshot",
+        description: "Full DOM snapshot: serialized HTML, computed styles per visible element, selector map (id/role/text/xpath), bounding rects. Stored as .dom.json sidecar.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            url: { type: "string", description: "Target URL" },
+            out: { type: "string", description: "Output .dom.json path (auto-gen if omitted)" },
+          },
+          required: ["url"],
+        },
+      },
+    ];
+  }
+
+  // ── Tool dispatcher ─────────────────────────────────────────────────
+
+  async _callTool(name, args) {
+    switch (name) {
+      case "pursor_shoot":        return await this._shoot(args);
+      case "pursor_diff":         return await this._diff(args);
+      case "pursor_sweep":        return await this._sweep(args);
+      case "pursor_frames":       return await this._frames(args);
+      case "pursor_probe":        return await this._probe(args);
+      case "pursor_audit":        return await this._audit(args);
+      case "pursor_dom_snapshot": return await this._domSnapshot(args);
+      default: throw new McpError(-32602, `Unknown tool: ${name}`);
+    }
+  }
+
+  // ── Tool implementations ────────────────────────────────────────────
+
+  async _shoot(args) {
+    const url = args.url;
+    if (!url) throw new McpError(-32602, "Missing required: url");
+
+    const defDir = this.config.defaultOutDir || process.cwd();
+    const out = args.out || join(defDir, `mcp-shoot-${Date.now()}.png`);
+    if (out) mkdirSync(dirname(out), { recursive: true });
+
+    const flags = {};
+    for (const [k, v] of Object.entries(args)) {
+      if (k !== "url" && k !== "out") flags[k] = v;
+    }
+
+    const meta = await runShootWithSidecar({ url, out, flags });
+    const sidecar = meta.out && existsSync(meta.out.replace(/\.png$/i, ".json"))
+      ? JSON.parse(readFileSync(meta.out.replace(/\.png$/i, ".json"), "utf8"))
+      : meta;
+
+    recordResource({
+      kind: "shoot", id: Date.now().toString(36),
+      name: "shoot: " + (flags.preset || "default") + " " + url,
+      description: "Screenshot capture",
+      uri: "pursor://shoot/" + encodeURIComponent(url + "|" + (flags.preset || "default")),
+      mimeType: "image/png",
+      file: out, meta: { url, flags, ts: sidecar?.ts },
+    });
+
+    return [{ type: "text", text: JSON.stringify({ out, meta: sidecar }, null, 2) }];
+  }
+
+  async _diff(args) {
+    const { url, ref } = args;
+    if (!url) throw new McpError(-32602, "Missing required: url");
+    if (!ref) throw new McpError(-32602, "Missing required: ref");
+    if (!existsSync(ref)) throw new McpError(-32602, `Reference file not found: ${ref}`);
+
+    const out = args.out || ref.replace(/\.png$/i, "-diff.png");
+    if (out) mkdirSync(dirname(out), { recursive: true });
+    const threshold = args.threshold ?? 0.1;
+    const result = await runDiff(url, ref, out, threshold);
+    return [{ type: "text", text: JSON.stringify(result, null, 2) }];
+  }
+
+  async _sweep(args) {
+    if (!args.plan) throw new McpError(-32602, "Missing required: plan");
+    if (!existsSync(args.plan)) throw new McpError(-32602, `Plan file not found: ${args.plan}`);
+    const summary = await runSweep(args.plan, args.outDir);
+    recordResource({
+      kind: "sweep", id: summary.name || "sweep",
+      name: "sweep: " + (summary.name || "(unnamed)"),
+      description: "Sweep plan: " + (summary.steps?.length || 0) + " steps",
+      uri: "pursor://sweep/" + encodeURIComponent(summary.name || "sweep"),
+      mimeType: "application/json",
+      file: (summary.outDir ? join(summary.outDir, "sweep.json") : null),
+      meta: { steps: summary.steps?.length || 0, ts: summary.ts },
+    });
+    return [{ type: "text", text: JSON.stringify(summary, null, 2) }];
+  }
+
+  async _frames(args) {
+    if (!args.url) throw new McpError(-32602, "Missing required: url");
+    const defDir = this.config.defaultOutDir || process.cwd();
+    const outDir = args.outDir || join(defDir, `mcp-frames-${Date.now()}`);
+    mkdirSync(outDir, { recursive: true });
+    const result = await runFrames({
+      url: args.url,
+      count: args.count,
+      intervalMs: args.intervalMs,
+      outDir,
+    });
+    return [{ type: "text", text: JSON.stringify(result, null, 2) }];
+  }
+
+  async _probe(args) {
+    if (!args.url) throw new McpError(-32602, "Missing required: url");
+    const result = await runProbe(args.url);
+    return [{ type: "text", text: JSON.stringify(result, null, 2) }];
+  }
+
+  async _audit(args) {
+    if (!args.url) throw new McpError(-32602, "Missing required: url");
+    const tags = args.tags ? args.tags.split(",").map(t => t.trim()).filter(Boolean) : undefined;
+    const defDir = this.config.defaultOutDir || process.cwd();
+    const outDir = args.outDir || join(defDir, `mcp-audit-${Date.now()}`);
+    const result = await runAudit({
+      url: args.url,
+      tags,
+      outDir,
+      screenshot: args.screenshot !== false,
+    });
+    return [{ type: "text", text: JSON.stringify(result, null, 2) }];
+  }
+
+  async _domSnapshot(args) {
+    if (!args.url) throw new McpError(-32602, "Missing required: url");
+    const defDir = this.config.defaultOutDir || process.cwd();
+    const out = args.out || join(defDir, `dom-snapshot-${Date.now()}.dom.json`);
+    mkdirSync(dirname(out), { recursive: true });
+    const result = await captureDomSnapshot({ url: args.url, out });
+    return [{ type: "text", text: JSON.stringify({ out, ...result }, null, 2) }];
+  }
+}
+
+export { PursorMCPServer, McpError, loadConfig, MCP_VERSION };