webperf-snippets 1.0.0 → 1.1.0

package/src/bin.js

@@ -4,29 +4,25 @@ import { parseArgs } from "node:util";
 import { loadSnippet } from "./load-snippet.js";
 import { resolveSnippetName } from "./snippet-names.js";
 import { runSnippets, runMeasurement, VIEWPORT_PRESETS } from "./runner.js";
-import { cwvWorkflow } from "./workflows/cwv.js";
-import { auditWorkflow } from "./workflows/audit.js";
-import { loadingWorkflow } from "./workflows/loading.js";
-import { interactionWorkflow } from "./workflows/interaction.js";
+import { WORKFLOWS } from "./workflows/index.js";
 import { RULES } from "./decision-tree.js";
 import { reportHuman } from "./reporters/human.js";
 import { reportJson } from "./reporters/json.js";
 import { reportMarkdown } from "./reporters/markdown.js";
 import { cliVersion, reportTo, validateReportUrl } from "./report-to.js";
 import { fetchCrux, formFactorFor } from "./crux.js";
-
-const WORKFLOWS = {
-  "core-web-vitals": cwvWorkflow,
-  audit: auditWorkflow,
-  loading: loadingWorkflow,
-  interaction: interactionWorkflow,
-};
+import { MissingBrowserError } from "./browser.js";
 
 
 const USAGE = `webperf-snippets <url> [options]
+webperf-snippets mcp
 
 Run curated WebPerf Snippets headlessly via Playwright.
 
+Commands:
+  mcp                   Start the MCP server over stdio, for AI agents
+                        (claude mcp add webperf -- npx -y webperf-snippets mcp)
+
 Options:
   --workflow <name>     Workflow to run (default: core-web-vitals)
                         Workflows: core-web-vitals, audit, loading, interaction
@@ -59,15 +55,15 @@ Options:
   -h, --help            Show this help
 
 Examples:
-  npx webperf-snippets https://web.dev
-  npx webperf-snippets https://web.dev --workflow audit
-  npx webperf-snippets https://web.dev --json
-  npx webperf-snippets https://web.dev --snippet LCP-Subparts
-  npx webperf-snippets https://web.dev --snippet render-blocking
-  npx webperf-snippets https://web.dev --snippet fonts
-  npx webperf-snippets https://web.dev --snippet Compression-Audit
-  npx webperf-snippets https://web.dev --budget-lcp 2500
-  npx webperf-snippets https://web.dev --snippet INP --interact-script interactions.json
+  npx webperf-snippets https://example.com
+  npx webperf-snippets https://example.com --workflow audit
+  npx webperf-snippets https://example.com --json
+  npx webperf-snippets https://example.com --snippet LCP-Subparts
+  npx webperf-snippets https://example.com --snippet render-blocking
+  npx webperf-snippets https://example.com --snippet fonts
+  npx webperf-snippets https://example.com --snippet Compression-Audit
+  npx webperf-snippets https://example.com --budget-lcp 2500
+  npx webperf-snippets https://example.com --snippet INP --interact-script interactions.json
   npx webperf-snippets https://example.com/dashboard --storage-state auth.json
 `;
 
@@ -104,6 +100,13 @@ function checkBudgets(results, values) {
 }
 
 async function main() {
+  // The MCP server only loads its SDK when it is asked for
+  if (process.argv[2] === "mcp") {
+    const { startStdioServer } = await import("./mcp/stdio.js");
+    await startStdioServer();
+    return;
+  }
+
   let parsed;
   try {
     parsed = parseArgs({
@@ -228,6 +231,7 @@ async function main() {
 }
 
 main().catch((err) => {
-  process.stderr.write(`Error: ${err.stack ?? err.message}\n`);
+  // A missing Chromium is a step of the setup, not a bug: the message says what to run, without a stack
+  process.stderr.write(err instanceof MissingBrowserError ? `${err.message}\n` : `Error: ${err.stack ?? err.message}\n`);
   process.exit(1);
 });

package/src/browser.js

@@ -0,0 +1,22 @@
+import { chromium } from "playwright";
+
+// Chromium for Playwright is a download of its own: npx installs this package and its peer playwright,
+// not the browser. Without it, Playwright fails with the path of the missing executable, and its advice
+// (npx playwright install) downloads every browser; this message names the only one the CLI uses.
+export const MISSING_BROWSER = "Chromium for Playwright is not installed. Install it once with: npx playwright install chromium";
+
+export class MissingBrowserError extends Error {
+  constructor() {
+    super(MISSING_BROWSER);
+  }
+}
+
+export const isMissingBrowser = (err) => err instanceof MissingBrowserError || /Executable doesn't exist/.test(err?.message ?? "");
+
+export async function launchChromium(options) {
+  try {
+    return await chromium.launch(options);
+  } catch (err) {
+    throw isMissingBrowser(err) ? new MissingBrowserError() : err;
+  }
+}

package/src/crux.js

@@ -40,7 +40,9 @@ async function query({ endpoint, apiKey, body, timeoutMs }) {
 }
 
 // Never throws, and no message it returns contains the key (it travels in the
-// query string, so the request URL is never logged or put in an error).
+// query string, so the request URL is never logged or put in an error). A page
+// with no field data is an answer ({ unavailable }); an API error or no answer is
+// a failure ({ unavailable, failed: true }).
 export async function fetchCrux({
   url,
   apiKey,
@@ -56,13 +58,13 @@ export async function fetchCrux({
       answer = await query({ endpoint, apiKey, body: { origin: new URL(url).origin, formFactor }, timeoutMs });
     }
     if (answer.notFound) return { unavailable: "not in the CrUX dataset" };
-    if (answer.status) return { unavailable: `the CrUX API answered ${answer.status}` };
+    if (answer.status) return { unavailable: `the CrUX API answered ${answer.status}`, failed: true };
     const metrics = parseMetrics(answer.record);
     if (Object.keys(metrics).length === 0) return { unavailable: "no Core Web Vitals in the CrUX record" };
     return { scope, formFactor, metrics };
   } catch (err) {
     const reason = err.name === "TimeoutError" ? `no answer within ${timeoutMs}ms` : (err.cause?.code ?? "request failed");
-    return { unavailable: reason };
+    return { unavailable: reason, failed: true };
   }
 }
 

package/src/mcp/documents.js

@@ -0,0 +1,111 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ResourceTemplate, ResourceNotFoundError } from "@modelcontextprotocol/server";
+import { SNIPPET_DIRS } from "../load-snippet.js";
+import { CATEGORIES } from "../snippet-names.js";
+
+const MARKDOWN = "text/markdown";
+
+// A document of snippets/, from the copy bundled with the package or from the repository
+function readDocument(relativePath) {
+  for (const dir of SNIPPET_DIRS) {
+    try {
+      return readFileSync(join(dir, relativePath), "utf8");
+    } catch {
+      // try the next directory
+    }
+  }
+  return null;
+}
+
+// Splits SCHEMA.md into the general contract and the section of each snippet ("#### LCP" up to the next
+// heading of that level or above). The general contract is everything outside "## Script-Specific Schemas".
+export function splitSchema(markdown) {
+  const lines = markdown.split("\n");
+  const start = lines.findIndex((l) => l.startsWith("## Script-Specific Schemas"));
+  const end = lines.findIndex((l, i) => i > start && l.startsWith("## "));
+  const general = [...lines.slice(0, start), ...lines.slice(end)].join("\n");
+
+  const sections = new Map();
+  let name = null;
+  let current = [];
+  const flush = () => name && sections.set(name, current.join("\n").trim());
+  for (const line of lines.slice(start, end)) {
+    if (line.startsWith("#### ")) {
+      flush();
+      name = line.slice(5).split(" ")[0];
+      current = [line];
+    } else if (/^#{1,3} /.test(line)) {
+      flush();
+      name = null;
+    } else if (name) {
+      current.push(line);
+    }
+  }
+  flush();
+  return { general, sections };
+}
+
+let schema = null;
+export function schemaSection(snippet) {
+  schema ??= splitSchema(readDocument("SCHEMA.md") ?? "");
+  return snippet === undefined ? schema.general : schema.sections.get(snippet);
+}
+
+function schemaSnippets() {
+  schemaSection();
+  return [...schema.sections.keys()];
+}
+
+const markdown = (uri, text) => ({ contents: [{ uri: uri.href, mimeType: MARKDOWN, text }] });
+
+export function registerResources(server) {
+  server.registerResource(
+    "schema",
+    "webperf://schema",
+    {
+      title: "Snippet result contract",
+      description: "What every snippet returns: the base shape, the statuses, the execution patterns and how to read a result. The fields of each snippet are in webperf://schema/{snippet}.",
+      mimeType: MARKDOWN,
+    },
+    async (uri) => markdown(uri, schemaSection())
+  );
+
+  server.registerResource(
+    "snippet-schema",
+    new ResourceTemplate("webperf://schema/{snippet}", {
+      list: async () => ({
+        resources: schemaSnippets().map((snippet) => ({ uri: `webperf://schema/${snippet}`, name: `${snippet} result`, mimeType: MARKDOWN })),
+      }),
+    }),
+    {
+      title: "Result of one snippet",
+      description: "The fields one snippet returns, with an example, from snippets/SCHEMA.md.",
+      mimeType: MARKDOWN,
+    },
+    async (uri, { snippet }) => {
+      const section = schemaSection(snippet);
+      if (!section) throw new ResourceNotFoundError(uri.href);
+      return markdown(uri, section);
+    }
+  );
+
+  server.registerResource(
+    "workflows",
+    new ResourceTemplate("webperf://workflows/{category}", {
+      list: async () => ({
+        resources: CATEGORIES.map((category) => ({ uri: `webperf://workflows/${category}`, name: `${category} workflows`, mimeType: MARKDOWN })),
+      }),
+    }),
+    {
+      title: "Workflows and decision tree",
+      description: "The snippets to run for common questions of a category, and what to run next after each one depending on its result.",
+      mimeType: MARKDOWN,
+    },
+    async (uri, { category }) => {
+      const text = CATEGORIES.includes(category) ? readDocument(`${category}/WORKFLOWS.md`) : null;
+      if (!text) throw new ResourceNotFoundError(uri.href);
+      return markdown(uri, text);
+    }
+  );
+}

package/src/mcp/prompts.js

@@ -0,0 +1,101 @@
+import * as z from "zod/v4";
+import { schemaSection } from "./documents.js";
+
+// Prompts are templates the user picks (in Claude Code, as /mcp__webperf__audit_lcp). Each one says
+// which tools to chain and in what order, and embeds the schema sections the answer needs, so the model
+// reads the results with the same reference the skills use.
+const text = (value) => ({ role: "user", content: { type: "text", text: value } });
+const schemaOf = (snippet) => ({
+  role: "user",
+  content: { type: "resource", resource: { uri: `webperf://schema/${snippet}`, mimeType: "text/markdown", text: schemaSection(snippet) } },
+});
+
+const Url = z.string().describe("The page to audit");
+const Viewport = z.enum(["mobile", "desktop"]).optional().describe("mobile by default");
+const QUOTE = "Quote the values the tools return; do not estimate or round them up.";
+
+export function registerPrompts(server) {
+  server.registerPrompt(
+    "audit_lcp",
+    {
+      title: "Audit LCP",
+      description: "Measures the Largest Contentful Paint of a page in the lab and in the field, finds its slowest sub-part and proposes fixes.",
+      argsSchema: z.object({ url: Url, viewport: Viewport }),
+    },
+    ({ url, viewport = "mobile" }) => ({
+      messages: [
+        text(
+          [
+            `Audit the Largest Contentful Paint of ${url} on ${viewport}.`,
+            "",
+            `1. Call run_workflow with url "${url}", workflow "core-web-vitals" and viewport "${viewport}". It returns LCP and CLS, and adds LCP-Subparts with the reason when LCP is over 2.5 s.`,
+            `2. Call get_crux for the same URL with formFactor "${viewport === "desktop" ? "desktop" : "phone"}", to compare the lab with what real users get. If it answers that there is no key, say so and go on with the lab data.`,
+            '3. If LCP-Subparts did not run, call run_snippet with snippet "LCP-Subparts".',
+            "4. Report the LCP value and rating in the lab and in the field, the LCP element, the slowest sub-part and what it means, and the fixes for that sub-part, the most effective first.",
+            "",
+            `${QUOTE} The result of each snippet is described below.`,
+          ].join("\n")
+        ),
+        schemaOf("LCP"),
+        schemaOf("LCP-Subparts"),
+      ],
+    })
+  );
+
+  server.registerPrompt(
+    "debug_inp",
+    {
+      title: "Debug INP",
+      description: "Opens a page, clicks on it like a user and finds the slowest interaction, its target and the phase that makes it slow.",
+      argsSchema: z.object({
+        url: Url,
+        selector: z.string().optional().describe("A CSS selector of the element to click, such as #buy"),
+        viewport: Viewport,
+      }),
+    },
+    ({ url, selector, viewport = "mobile" }) => ({
+      messages: [
+        text(
+          [
+            `Find what makes the interactions slow on ${url} (${viewport}).`,
+            "",
+            `1. Call open_page with url "${url}", viewport "${viewport}" and track ["INP", "Interactions", "Input-Latency-Breakdown"].`,
+            selector
+              ? `2. Call interact with a click on "${selector}". Add a few more clicks or key presses if the page has other controls a user would use.`
+              : "2. Call interact with clicks on the controls a user would use first: main buttons, links that open menus, form fields. If you cannot tell which ones, ask me.",
+            "3. Call read_results. INP gives the worst interaction and its phases (input delay, processing, presentation); Input-Latency-Breakdown says which phase dominates for each type of event.",
+            "4. Call close_page.",
+            "5. Report the worst interaction, its target, the dominant phase and the fixes for that phase.",
+            "",
+            `${QUOTE} The result of INP is described below.`,
+          ].join("\n")
+        ),
+        schemaOf("INP"),
+      ],
+    })
+  );
+
+  server.registerPrompt(
+    "audit_page",
+    {
+      title: "Audit a page",
+      description: "Runs the audit and loading workflows on a page and summarizes the issues by severity, with fixes.",
+      argsSchema: z.object({ url: Url, viewport: Viewport }),
+    },
+    ({ url, viewport = "mobile" }) => ({
+      messages: [
+        text(
+          [
+            `Audit the loading performance of ${url} on ${viewport}.`,
+            "",
+            `1. Call run_workflow with url "${url}", workflow "audit" and viewport "${viewport}".`,
+            '2. Call run_workflow with the same URL and workflow "loading".',
+            "3. Summarize the issues the snippets report, errors first, then warnings, each with the snippet that found it and the fix. Leave out the checks that passed.",
+            "",
+            `${QUOTE} If a result is unclear, read the resource webperf://schema/{snippet} of that snippet.`,
+          ].join("\n")
+        ),
+      ],
+    })
+  );
+}