playwright-checkpoint 0.1.0-beta.0

package/dist/mcp/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * playwright-checkpoint MCP proxy server.
+ *
+ * Proxies all tools from an upstream Playwright MCP server while adding
+ * the browser_checkpoint, browser_checkpoint_report, and
+ * browser_checkpoint_compare tools handled locally.
+ *
+ * The StdioServerTransport is inlined locally. The SDK is loaded at runtime
+ * (not bundled) so this module works even when the SDK is not installed,
+ * with a clear error message when startMcpProxy() is actually called.
+ */
+type McpProxyOptions = {
+    /** Explicit upstream package to proxy (e.g. "@playwright/mcp"). */
+    upstream?: string;
+    /** Run in standalone mode — no upstream proxying. */
+    standalone?: boolean;
+    /** CDP endpoint to connect to the browser directly (overrides auto-detection). */
+    cdpEndpoint?: string;
+    /** Directory for checkpoint output files (default: ./checkpoints). */
+    outputDir?: string;
+    /** Arguments to pass through to the upstream server (everything after --). */
+    passthrough?: string[];
+};
+declare function startMcpProxy(options?: McpProxyOptions): Promise<void>;
+
+export { type McpProxyOptions, startMcpProxy };

package/dist/mcp/index.js

@@ -0,0 +1,586 @@
+import {
+  captureCheckpoint,
+  sanitizeSegment
+} from "../chunk-KG37WSYS.js";
+import {
+  runReporters
+} from "../chunk-X5IPL32H.js";
+import {
+  __require
+} from "../chunk-DGUM43GV.js";
+
+// src/mcp/transport.ts
+function serializeMessage(message) {
+  return JSON.stringify(message) + "\n";
+}
+var ReadBuffer = class {
+  _buffer;
+  append(chunk) {
+    this._buffer = this._buffer ? Buffer.concat([this._buffer, chunk]) : chunk;
+  }
+  readMessage() {
+    if (!this._buffer) return null;
+    const index = this._buffer.indexOf("\n");
+    if (index === -1) return null;
+    const line = this._buffer.toString("utf8", 0, index).replace(/\r$/, "");
+    this._buffer = this._buffer.subarray(index + 1);
+    try {
+      return JSON.parse(line);
+    } catch {
+      return null;
+    }
+  }
+  clear() {
+    this._buffer = void 0;
+  }
+};
+var StdioServerTransport = class {
+  _stdin;
+  _stdout;
+  _readBuffer = new ReadBuffer();
+  _started = false;
+  constructor(stdin, stdout) {
+    this._stdin = stdin ?? process.stdin;
+    this._stdout = stdout ?? process.stdout;
+  }
+  onclose;
+  onerror;
+  onmessage;
+  async start() {
+    if (this._started) {
+      throw new Error("StdioServerTransport already started!");
+    }
+    this._started = true;
+    this._stdin.on("data", (chunk) => {
+      this._readBuffer.append(chunk);
+      this.#processReadBuffer();
+    });
+    this._stdin.on("error", (error) => {
+      this.onerror?.(error);
+    });
+  }
+  #processReadBuffer() {
+    while (true) {
+      try {
+        const message = this._readBuffer.readMessage();
+        if (message === null) break;
+        this.onmessage?.(message);
+      } catch (error) {
+        this.onerror?.(error instanceof Error ? error : new Error(String(error)));
+      }
+    }
+  }
+  async close() {
+    this._stdin.pause?.();
+    this._readBuffer.clear();
+    this.onclose?.();
+  }
+  async send(message) {
+    const json = serializeMessage(message);
+    if (this._stdout.write(json)) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      this._stdout.once("drain", resolve);
+    });
+  }
+};
+
+// src/mcp/upstream.ts
+import { spawn } from "child_process";
+function getNodeModuleCreateRequire() {
+  const { createRequire } = __require("module");
+  return createRequire(process.cwd() + "/noop.js");
+}
+function resolvePackageJson(pkg) {
+  try {
+    const req = getNodeModuleCreateRequire();
+    return req.resolve(`${pkg}/package.json`);
+  } catch {
+    return null;
+  }
+}
+function resolveUpstream(options) {
+  if (options.upstream) {
+    return options.upstream;
+  }
+  if (resolvePackageJson("@playwright/mcp")) {
+    return "@playwright/mcp";
+  }
+  if (resolvePackageJson("playwright-mcp-advanced")) {
+    return "playwright-mcp-advanced";
+  }
+  return null;
+}
+var ChildProcessTransport = class {
+  constructor(stdin, stdout, stderr, onMessage, onClose) {
+    this.stdin = stdin;
+    this.stdout = stdout;
+    this.stderr = stderr;
+    this.onMessage = onMessage;
+    this.onClose = onClose;
+  }
+  stdin;
+  stdout;
+  stderr;
+  onMessage;
+  onClose;
+  pendingRequests = /* @__PURE__ */ new Map();
+  id = 0;
+  start() {
+    let buffer = "";
+    this.stdout.on("data", (chunk) => {
+      buffer += chunk.toString();
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (line.trim()) {
+          try {
+            const msg = JSON.parse(line);
+            this.handleMessage(msg);
+          } catch {
+          }
+        }
+      }
+    });
+    this.stdout.on("end", () => {
+      this.onClose?.();
+    });
+    this.stderr?.on("data", (chunk) => {
+      process.stderr.write(chunk);
+    });
+  }
+  handleMessage(msg) {
+    if (msg.id !== void 0) {
+      const pending = this.pendingRequests.get(String(msg.id));
+      if (pending) {
+        this.pendingRequests.delete(String(msg.id));
+        if (msg.error) {
+          pending.reject(new Error(String(msg.error)));
+        } else {
+          pending.resolve(msg.result);
+        }
+      }
+      return;
+    }
+    if (msg.method) {
+      this.onMessage(msg);
+    }
+  }
+  send(message) {
+    const json = JSON.stringify(message) + "\n";
+    this.stdin.write(json);
+  }
+  request(method, params) {
+    const id = String(++this.id);
+    const promise = new Promise((resolve, reject) => {
+      this.pendingRequests.set(id, { resolve, reject });
+    });
+    this.send({ method, params, id });
+    return promise;
+  }
+  close() {
+    this.stdin.end();
+  }
+};
+function injectDebugPort(args) {
+  const hasDebugFlag = args.some(
+    (a) => a.startsWith("--remote-debugging-port") || a.startsWith("--cdp-endpoint")
+  );
+  if (hasDebugFlag) {
+    return args;
+  }
+  return ["--remote-debugging-port=9222", ...args];
+}
+function spawnUpstream(pkg, passthroughArgs) {
+  const npxBin = process.platform === "win32" ? "npx.cmd" : "npx";
+  const npxArgs = [pkg, ...passthroughArgs];
+  const child = spawn(npxBin, npxArgs, {
+    stdio: ["pipe", "pipe", "pipe"],
+    env: {
+      ...process.env,
+      // Prevent npx from prompting or caching in CI
+      NPM_CONFIG_YES: "true",
+      NPM_CONFIG_INTERACTIVE: "false"
+    },
+    shell: false,
+    windowsHide: true
+  });
+  const transport = new ChildProcessTransport(
+    child.stdin,
+    child.stdout,
+    child.stderr,
+    (_msg) => {
+    },
+    () => {
+    }
+  );
+  transport.start();
+  const connection = {
+    process: child,
+    async listTools() {
+      const result = await transport.request("tools/list");
+      return result;
+    },
+    async callTool(name, args) {
+      const result = await transport.request("tools/call", { name, arguments: args ?? {} });
+      return result;
+    },
+    close() {
+      transport.close();
+    }
+  };
+  return connection;
+}
+
+// src/mcp/browser-connect.ts
+var CDP_WS_REGEX = /DevTools listening on (ws:\/\/[^\s]+)/;
+var cachedConnection = null;
+function extractCdpUrlFromStderr(data) {
+  const match = CDP_WS_REGEX.exec(data);
+  return match ? match[1] ?? null : null;
+}
+async function getUpstreamPage(upstreamProcess, options) {
+  if (cachedConnection) {
+    return cachedConnection;
+  }
+  let cdpEndpoint = options.cdpEndpoint;
+  if (!cdpEndpoint) {
+    if (upstreamProcess?.stderr) {
+      const stderrLines = [];
+      upstreamProcess.stderr.on("data", (chunk) => {
+        stderrLines.push(chunk.toString());
+      });
+      await new Promise((resolve) => setTimeout(resolve, 500));
+      for (const line of stderrLines) {
+        const url = extractCdpUrlFromStderr(line);
+        if (url) {
+          cdpEndpoint = url;
+          break;
+        }
+      }
+    }
+  }
+  if (!cdpEndpoint) {
+    const port = options.debugPort ?? 9222;
+    cdpEndpoint = `http://localhost:${port}`;
+  }
+  const browser = await chromiumConnect(cdpEndpoint);
+  const pages = await browser.contexts()[0]?.pages() ?? [];
+  const page = pages[0] ?? await browser.newPage();
+  cachedConnection = { browser, page };
+  return cachedConnection;
+}
+function getNodeModuleCreateRequire2() {
+  const { createRequire } = __require("module");
+  return createRequire(import.meta.url);
+}
+async function chromiumConnect(endpoint) {
+  const req = getNodeModuleCreateRequire2();
+  const pw = req("playwright-core");
+  return pw.chromium.connectOverCDP(endpoint);
+}
+function resetCachedConnection() {
+  cachedConnection = null;
+}
+
+// src/mcp/tools.ts
+var browserCheckpointSchema = {
+  type: "object",
+  properties: {
+    name: { type: "string", description: 'Unique name for this checkpoint (e.g. "homepage", "after-login").' },
+    description: {
+      type: "string",
+      description: "Long-form description of what this checkpoint captures."
+    },
+    highlightSelector: {
+      type: "string",
+      description: "CSS selector for a region to highlight in the annotated screenshot."
+    },
+    fullPage: {
+      type: "boolean",
+      description: "Capture the full page (default: true). Set false for viewport-only."
+    },
+    collectors: {
+      type: "object",
+      description: "Per-collector overrides. Set to false to disable, or an options object to configure.",
+      additionalProperties: true
+    }
+  },
+  required: ["name"]
+};
+var browserCheckpointReportSchema = {
+  type: "object",
+  properties: {
+    outputDir: {
+      type: "string",
+      description: "Directory to write report files (default: ./report)."
+    },
+    format: {
+      type: "string",
+      enum: ["html", "markdown", "mdx"],
+      description: "Report format(s) to generate."
+    }
+  }
+};
+var browserCheckpointCompareSchema = {
+  type: "object",
+  properties: {
+    baseline: { type: "string", description: "Path or name of the baseline checkpoint manifest." },
+    current: { type: "string", description: "Path or name of the current checkpoint manifest." }
+  },
+  required: ["baseline", "current"]
+};
+var CHECKPOINT_TOOL_NAME = "browser_checkpoint";
+var REPORT_TOOL_NAME = "browser_checkpoint_report";
+var COMPARE_TOOL_NAME = "browser_checkpoint_compare";
+var CHECKPOINT_TOOLS = [
+  {
+    name: CHECKPOINT_TOOL_NAME,
+    description: "Capture a structured snapshot of the current browser page: screenshot, accessibility violations, Web Vitals, console errors, and network failures. Returns an LLM-friendly summary plus artifact paths.",
+    inputSchema: browserCheckpointSchema
+  },
+  {
+    name: REPORT_TOOL_NAME,
+    description: "Generate an HTML, Markdown, or MDX report from all checkpoint manifests in a directory.",
+    inputSchema: browserCheckpointReportSchema
+  },
+  {
+    name: COMPARE_TOOL_NAME,
+    description: "Compare two checkpoint runs to surface differences (not yet implemented).",
+    inputSchema: browserCheckpointCompareSchema
+  }
+];
+async function handleBrowserCheckpoint(args, ctx) {
+  const slug = sanitizeSegment(args.name);
+  const record = await captureCheckpoint(ctx.page, args.name, {
+    outputDir: ctx.outputDir,
+    highlightSelector: args.highlightSelector,
+    fullPage: args.fullPage ?? true,
+    description: args.description,
+    collectors: args.collectors
+  });
+  void slug;
+  return formatCheckpointSummary(record);
+}
+async function handleBrowserCheckpointReport(args, testResultsDir = "test-results") {
+  const outputDir = args.outputDir ?? "report";
+  const config = {
+    reporters: {
+      html: args.format === void 0 || args.format === "html",
+      markdown: args.format === "markdown",
+      mdx: args.format === "mdx"
+    }
+  };
+  const { resolve } = await import("path");
+  const results = await runReporters(
+    config,
+    resolve(process.cwd(), testResultsDir),
+    resolve(process.cwd(), outputDir)
+  );
+  const lines = Object.entries(results).map(([name, result]) => `- ${name}: ${result.summary}`);
+  if (lines.length === 0) {
+    return "No reports generated.";
+  }
+  return `Report generation complete:
+${lines.join("\n")}`;
+}
+function handleBrowserCheckpointCompare(_args) {
+  return "browser_checkpoint_compare is not yet implemented.";
+}
+function formatCheckpointSummary(record) {
+  const lines = [];
+  lines.push(`Checkpoint "${record.name}" captured.`);
+  lines.push(`URL: ${record.url}`);
+  lines.push(`Title: ${record.title}`);
+  lines.push("");
+  const axeData = record.collectors["axe"];
+  if (axeData?.data) {
+    const axe = axeData.data;
+    if (axe.skipped) {
+      lines.push(`Accessibility: skipped (${axe.reason ?? "unknown reason"})`);
+    } else {
+      const violations = axe.violations ?? 0;
+      lines.push(`Accessibility: ${violations} violation${violations !== 1 ? "s" : ""}`);
+    }
+  }
+  const wvData = record.collectors["web-vitals"];
+  if (wvData?.data) {
+    const wv = wvData.data;
+    lines.push("Web Vitals:");
+    const metricLines = [];
+    for (const [key, metric] of Object.entries(wv)) {
+      if (!metric || typeof metric !== "object") continue;
+      const m = metric;
+      if (m.value === null) continue;
+      const ratingIcon = m.rating === "good" ? "\u2705" : m.rating === "needs-improvement" ? "\u26A0\uFE0F" : m.rating === "poor" ? "\u274C" : "";
+      const label = key.replace(/Ms$/, "").toUpperCase();
+      const formatted = key.endsWith("Ms") ? `${Math.round(m.value)}ms` : m.value.toFixed ? m.value.toFixed(3) : String(m.value);
+      metricLines.push(`  ${label}: ${formatted} (${m.rating} ${ratingIcon})`.trim());
+    }
+    if (metricLines.length > 0) {
+      lines.push(metricLines.join("\n"));
+    }
+  }
+  const consoleData = record.collectors["console"];
+  if (consoleData?.data) {
+    const entries = consoleData.data;
+    const errors = entries.filter((e) => e.type === "error" || e.type === "pageerror");
+    if (errors.length > 0) {
+      lines.push(`Console: ${errors.length} error${errors.length !== 1 ? "s" : ""}`);
+      for (const err of errors.slice(0, 3)) {
+        lines.push(`  ${err.text}`);
+      }
+      if (errors.length > 3) {
+        lines.push(`  ... and ${errors.length - 3} more`);
+      }
+    } else {
+      lines.push("Console: no errors");
+    }
+  }
+  const netData = record.collectors["network"];
+  if (netData?.data) {
+    const requests = netData.data;
+    const failed = requests.filter((r) => r.status === null || r.status >= 400 || r.failureText);
+    if (failed.length > 0) {
+      lines.push(`Network: ${failed.length} failed request${failed.length !== 1 ? "s" : ""}`);
+      for (const req of failed.slice(0, 3)) {
+        const reason = req.failureText ?? `${req.status} ${req.url}`;
+        lines.push(`  ${req.url} \u2192 ${reason}`);
+      }
+      if (failed.length > 3) {
+        lines.push(`  ... and ${failed.length - 3} more`);
+      }
+    } else {
+      lines.push("Network: 0 failed requests");
+    }
+  }
+  const ssData = record.collectors["screenshot"];
+  if (ssData?.summary) {
+    const ss = ssData.summary;
+    if (ss.screenshotPath) {
+      lines.push(`Screenshot: ${ss.screenshotPath}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+// src/mcp/index.ts
+function ensureMcpSdk() {
+  try {
+    __require("@modelcontextprotocol/sdk");
+  } catch {
+    throw new Error(
+      "playwright-checkpoint MCP mode requires @modelcontextprotocol/sdk.\nInstall it: npm install @modelcontextprotocol/sdk"
+    );
+  }
+}
+function getNodeModuleCreateRequire3() {
+  const { createRequire } = __require("module");
+  return createRequire(import.meta.url);
+}
+async function startMcpProxy(options = {}) {
+  ensureMcpSdk();
+  const req = getNodeModuleCreateRequire3();
+  const sdk = req("@modelcontextprotocol/sdk");
+  const sdkServer = req("@modelcontextprotocol/sdk/server");
+  const ListToolsRequestSchema = sdk.ListToolsRequestSchema;
+  const CallToolRequestSchema = sdk.CallToolRequestSchema;
+  const Server = sdkServer.Server;
+  const outputDir = options.outputDir ?? "./checkpoints";
+  let upstreamConnection = null;
+  const upstreamTools = [];
+  const upstreamPkg = options.standalone ? null : resolveUpstream({ upstream: options.upstream });
+  if (upstreamPkg) {
+    console.error(`[playwright-checkpoint MCP] Proxying upstream: ${upstreamPkg}`);
+    let passthroughArgs = options.passthrough ?? [];
+    if (!options.cdpEndpoint) {
+      passthroughArgs = injectDebugPort(passthroughArgs);
+    }
+    upstreamConnection = spawnUpstream(upstreamPkg, passthroughArgs);
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    try {
+      const result = await upstreamConnection.listTools();
+      for (const tool of result.tools) {
+        upstreamTools.push({
+          name: tool.name,
+          description: tool.description,
+          inputSchema: tool.inputSchema
+        });
+      }
+    } catch (err) {
+      console.error("[playwright-checkpoint MCP] Warning: could not list upstream tools:", err);
+    }
+  } else {
+    console.error("[playwright-checkpoint MCP] Running in standalone mode (no upstream).");
+  }
+  const checkpointTools = CHECKPOINT_TOOLS.map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: t.inputSchema
+  }));
+  const allTools = [...checkpointTools, ...upstreamTools];
+  const server = new Server({ name: "playwright-checkpoint", version: "0.1.0-beta.0" }, { capabilities: { tools: {} } });
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: allTools };
+  });
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+    if (name === CHECKPOINT_TOOL_NAME) {
+      const { page } = await getUpstreamPage(upstreamConnection?.process ?? null, {
+        cdpEndpoint: options.cdpEndpoint,
+        debugPort: 9222
+      });
+      const result = await handleBrowserCheckpoint(
+        args,
+        { page, outputDir }
+      );
+      return { content: [{ type: "text", text: result }] };
+    }
+    if (name === REPORT_TOOL_NAME) {
+      const result = await handleBrowserCheckpointReport(
+        args
+      );
+      return { content: [{ type: "text", text: result }] };
+    }
+    if (name === COMPARE_TOOL_NAME) {
+      const result = handleBrowserCheckpointCompare(
+        args
+      );
+      return { content: [{ type: "text", text: result }], isError: true };
+    }
+    if (upstreamConnection) {
+      try {
+        const result = await upstreamConnection.callTool(name, args);
+        return {
+          content: result.content,
+          isError: result.isError,
+          structuredContent: result.structuredContent
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Upstream tool "${name}" failed: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ],
+          isError: true
+        };
+      }
+    }
+    return { content: [{ type: "text", text: `Tool "${name}" is not available.` }], isError: true };
+  });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  const cleanup = () => {
+    resetCachedConnection();
+    upstreamConnection?.close();
+  };
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+}
+export {
+  startMcpProxy
+};
+//# sourceMappingURL=index.js.map