webperf-snippets 1.0.0 → 1.2.0

package/src/bin.js

@@ -4,29 +4,28 @@ 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";
+import { parseHeader } from "./headers.js";
+import { NETWORK_PRESETS, parseCpuFactor } from "./throttling.js";
+import { parseOwnDomains } from "./own-domains.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
@@ -41,6 +40,8 @@ Options:
   --markdown            Output GitHub-renderable markdown (for PR comments)
   --viewport <preset>   Viewport preset: mobile (default), tablet, desktop
   --wait <ms>           Post-load wait before evaluating (default: 3000)
+  --cpu <factor>        Slow the CPU down by this factor, such as 4 (no throttling by default)
+  --network <preset>    Throttle the network as DevTools does: fast-4g, slow-4g, 3g
   --budget-lcp <ms>     Exit 1 if LCP exceeds this value
   --budget-cls <score>  Exit 1 if CLS exceeds this value
   --interact-script <path>  JSON file with interactions to run after the load; the
@@ -48,6 +49,10 @@ Options:
                             Actions: scroll, click, hover, type, wait
   --storage-state <path>    Playwright storage state (cookies + localStorage) to
                             measure pages that require authentication
+  --header "Name: value"    Request header for the origin of the URL only, such as
+                            the token of an access proxy. Repeat it for more headers
+  --own-domains <list>      Domains of the site to count as first party, such as its
+                            own CDN, comma-separated or repeated
   --crux-key <key>          Add CrUX field data (p75) next to the measured values.
                             Also read from the CRUX_API_KEY environment variable
   --report-to <url>         POST the results to this https URL after the run
@@ -59,16 +64,19 @@ 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 --cpu 4 --network slow-4g
+  npx webperf-snippets https://example.com --workflow loading --own-domains cdn.example.net
+  npx webperf-snippets https://example.com --snippet INP --interact-script interactions.json
   npx webperf-snippets https://example.com/dashboard --storage-state auth.json
+  npx webperf-snippets https://review.example.com --header "CF-Access-Client-Id: $CF_ID" --header "CF-Access-Client-Secret: $CF_SECRET"
 `;
 
 function fail(message, code = 2) {
@@ -104,6 +112,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({
@@ -116,8 +131,12 @@ async function main() {
         "budget-lcp": { type: "string" },
         "budget-cls": { type: "string" },
         viewport: { type: "string" },
+        cpu: { type: "string" },
+        network: { type: "string" },
         "interact-script": { type: "string" },
         "storage-state": { type: "string" },
+        header: { type: "string", multiple: true },
+        "own-domains": { type: "string", multiple: true },
         "crux-key": { type: "string" },
         "report-to": { type: "string" },
         "api-key": { type: "string" },
@@ -151,6 +170,13 @@ async function main() {
     fail(`Unknown viewport preset: "${viewportName}". Choose from: ${Object.keys(VIEWPORT_PRESETS).join(", ")}`);
   }
 
+  const cpu = values.cpu != null ? parseCpuFactor(values.cpu) : undefined;
+  if (cpu === null) fail(`Invalid CPU factor "${values.cpu}". Use a number of at least 1, such as 4`);
+  const network = values.network;
+  if (network != null && !NETWORK_PRESETS[network]) {
+    fail(`Unknown network preset: "${network}". Choose from: ${Object.keys(NETWORK_PRESETS).join(", ")}`);
+  }
+
   const reportUrl = values["report-to"];
   if (reportUrl) {
     const problem = validateReportUrl(reportUrl);
@@ -163,15 +189,28 @@ async function main() {
     fail(`Storage state file not found: ${storageState}`);
   }
 
+  const headers = {};
+  for (const raw of values.header ?? []) {
+    const header = parseHeader(raw);
+    if (!header) fail(`Invalid header "${raw}". Use --header "Name: value"`);
+    headers[header[0]] = header[1];
+  }
+
+  const invalidOwnDomains = (values["own-domains"] ?? []).find((raw) => !parseOwnDomains([raw]));
+  if (invalidOwnDomains != null) {
+    fail(`Invalid --own-domains "${invalidOwnDomains}". Use domains separated by commas, such as cdn.example.net,static.example.org`);
+  }
+  const ownDomains = values["own-domains"] && parseOwnDomains(values["own-domains"]);
+
   let payload;
   if (values.snippet) {
     const items = buildSnippetItem(values);
-    payload = await runSnippets({ url, items, waitMs, headless: !values.headed, viewport, interactScript, storageState });
+    payload = await runSnippets({ url, items, waitMs, headless: !values.headed, viewport, interactScript, storageState, headers, cpu, network, ownDomains });
   } else {
     const workflowName = values.workflow ?? "core-web-vitals";
     const workflow = WORKFLOWS[workflowName];
     if (!workflow) fail(`Unknown workflow: ${workflowName}`);
-    payload = await runMeasurement({ url, workflow, rules: RULES, waitMs, headless: !values.headed, viewport, interactScript, storageState });
+    payload = await runMeasurement({ url, workflow, rules: RULES, waitMs, headless: !values.headed, viewport, interactScript, storageState, headers, cpu, network, ownDomains });
   }
 
   const cruxKey = values["crux-key"] || process.env.CRUX_API_KEY;
@@ -199,7 +238,7 @@ async function main() {
         timestamp: new Date().toISOString(),
         navMs: payload.navMs,
         results: payload.results,
-        meta: { viewport: viewportName, waitMs, cli_version: cliVersion },
+        meta: { viewport: viewportName, waitMs, ...(payload.throttling ? { throttling: payload.throttling } : {}), cli_version: cliVersion },
       },
     });
     if (!outcome.ok) {
@@ -228,6 +267,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/headers.js

@@ -0,0 +1,35 @@
+// Extra request headers, for pages behind an access proxy that reads a token from each request.
+// They go only to the origin of the measured URL: sent to every origin, as Playwright's
+// extraHTTPHeaders does, they would hand the token to third parties, and a custom header on a
+// cross-origin fetch needs a CORS preflight that most third parties do not answer.
+//
+// The Fetch domain of CDP pauses only the requests that match the pattern, inside the browser,
+// so third-party requests are not intercepted and keep their timings. Each request to the origin
+// waits for the round trip to Node, which adds a few milliseconds to its timing.
+
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+
+// "Name: value" as given to --header, or null when it is not a valid header
+export function parseHeader(raw) {
+  const colon = raw.indexOf(":");
+  if (colon === -1) return null;
+  const name = raw.slice(0, colon).trim();
+  if (!HEADER_NAME.test(name)) return null;
+  return [name, raw.slice(colon + 1).trim()];
+}
+
+export async function sendHeadersToOrigin(context, page, url, headers) {
+  if (!headers || Object.keys(headers).length === 0) return;
+  const extra = Object.entries(headers);
+  const replaced = new Set(extra.map(([name]) => name.toLowerCase()));
+  const cdp = await context.newCDPSession(page);
+  cdp.on("Fetch.requestPaused", ({ requestId, request }) => {
+    const kept = Object.entries(request.headers).filter(([name]) => !replaced.has(name.toLowerCase()));
+    const all = [...kept, ...extra].map(([name, value]) => ({ name, value }));
+    // The request is gone when the page navigates away while it is paused
+    cdp.send("Fetch.continueRequest", { requestId, headers: all }).catch(() => {});
+  });
+  await cdp.send("Fetch.enable", {
+    patterns: [{ urlPattern: `${new URL(url).origin}/*`, requestStage: "Request" }],
+  });
+}

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")
+        ),
+      ],
+    })
+  );
+}