framewatch-mcp-server 0.1.1 → 0.2.0

package/dist/tools/seo.js

@@ -0,0 +1,281 @@
+import { z } from "zod";
+import { DEFAULT_SEO_WAIT_MS, DEFAULT_VIEWPORT, MAX_SEO_HEADINGS, MAX_VIEWPORT_HEIGHT, MAX_VIEWPORT_WIDTH, NAVIGATION_TIMEOUT_MS, SELECTOR_TIMEOUT_MS, } from "../constants.js";
+import { withPage } from "../engine/browser.js";
+import { PERF_INIT_SCRIPT, extractSeo, fetchRobots, probeImage, readPerformance, } from "../engine/seo.js";
+import { resizeForOutput, toBase64 } from "../utils/image.js";
+import { SEO_AREAS, judgeSeo, metaValues, } from "../utils/seo-rules.js";
+import { resolveStorageState, storageStateField, withAuthNote } from "../utils/storage-state.js";
+export const SEO_TOOL_NAME = "framewatch_seo";
+export const seoInputShape = {
+    url: z.string().url().describe("URL to audit, e.g. http://localhost:3000 (http, https and file URLs are accepted)"),
+    wait_ms: z
+        .number()
+        .int()
+        .min(0)
+        .default(DEFAULT_SEO_WAIT_MS)
+        .describe("Wait time (ms) after page load before reading the page, so a client-rendered app can finish"),
+    wait_for: z.string().optional().describe("CSS selector to wait for (visible) before reading the page"),
+    wait_for_timeout_ms: z
+        .number()
+        .int()
+        .min(1)
+        .default(SELECTOR_TIMEOUT_MS)
+        .describe("Max time (ms) to wait for `wait_for` to appear (must be > 0)"),
+    check_robots: z
+        .boolean()
+        .default(true)
+        .describe("Fetch /robots.txt and work out whether this page's own path is crawlable"),
+    robots_user_agent: z
+        .string()
+        .min(1)
+        .default("Googlebot")
+        .describe("Which crawler to answer the robots.txt question for. A named group beats the `*` group, as it does for the real thing."),
+    check_og_image: z
+        .boolean()
+        .default(true)
+        .describe("Fetch the og:image and measure it — a share image that 404s or is too small is invisible from the page itself"),
+    include_performance: z
+        .boolean()
+        .default(false)
+        .describe("Also measure this load: LCP, CLS, TTFB, page weight and DOM size. Lab numbers from one headless load, " +
+        "useful for finding the slow element, not a prediction of field data."),
+    viewport: z
+        .object({
+        width: z.number().int().min(1).max(MAX_VIEWPORT_WIDTH).default(DEFAULT_VIEWPORT.width),
+        height: z.number().int().min(1).max(MAX_VIEWPORT_HEIGHT).default(DEFAULT_VIEWPORT.height),
+    })
+        .optional()
+        .describe("Viewport size (defaults to 1280x720)"),
+    storage_state: storageStateField,
+};
+export const seoInputSchema = z.object(seoInputShape);
+/**
+ * Audit what a search engine — and a link preview — would make of a page.
+ *
+ * Everything is read from the *rendered* document rather than the HTML source.
+ * A single-page app ships an empty `<div id="app">` and fills in the title,
+ * the description and the structured data afterwards, so reading the source
+ * would report every client-rendered page as having no SEO at all, which is
+ * both wrong and the opposite of useful.
+ *
+ * Three things are checked that are not on the page and cannot be seen from
+ * it: the response headers (an `X-Robots-Tag: noindex` is invisible in the
+ * DOM), robots.txt (a page can be perfect and simply not crawlable), and the
+ * share image itself, which is fetched and measured — an `og:image` pointing
+ * at a 404 looks exactly like a working one until somebody shares the link.
+ */
+export async function auditSeo(rawInput) {
+    const parsed = seoInputSchema.safeParse(rawInput);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "input"}: ${i.message}`).join("; ");
+        return errorResult(`SEO audit failed: invalid input — ${issues}`);
+    }
+    const input = parsed.data;
+    const viewport = input.viewport ?? { ...DEFAULT_VIEWPORT };
+    let contextOptions = {};
+    let auth = null;
+    try {
+        auth = await resolveStorageState(input.storage_state);
+        if (auth)
+            contextOptions = { storageState: auth.state };
+    }
+    catch (error) {
+        return errorResult(`SEO audit of ${input.url} failed: ${firstLine(error)}`);
+    }
+    let gathered;
+    try {
+        gathered = await withPage({ viewport, contextOptions }, (page, context) => gather(input, page, context));
+    }
+    catch (error) {
+        return errorResult(describeSeoFailure(input, error));
+    }
+    const report = judgeSeo({
+        requested_url: input.url,
+        page: gathered.page,
+        robots_user_agent: input.robots_user_agent,
+        ...(gathered.response ? { response: gathered.response } : {}),
+        ...(gathered.robots ? { robots: gathered.robots } : {}),
+        ...(gathered.og_image ? { og_image: gathered.og_image } : {}),
+        ...(gathered.performance ? { performance: gathered.performance } : {}),
+    });
+    return withAuthNote(await render(gathered, report), auth);
+}
+/** Open the page and collect everything the audit needs from it. */
+async function gather(input, page, context) {
+    // The observers have to exist before the navigation: LCP, CLS and long
+    // tasks are only observable as they happen.
+    if (input.include_performance)
+        await page.addInitScript(PERF_INIT_SCRIPT);
+    const response = await page.goto(input.url, { waitUntil: "load", timeout: NAVIGATION_TIMEOUT_MS });
+    if (input.wait_for) {
+        await page.waitForSelector(input.wait_for, { state: "visible", timeout: input.wait_for_timeout_ms });
+    }
+    if (input.wait_ms > 0) {
+        await page.waitForTimeout(input.wait_ms);
+    }
+    const seo = await extractSeo(page);
+    const gathered = { page: seo };
+    if (response) {
+        gathered.response = { status: response.status(), headers: response.headers() };
+    }
+    if (input.include_performance) {
+        const metrics = await readPerformance(page);
+        if (metrics)
+            gathered.performance = metrics;
+    }
+    if (input.check_robots) {
+        gathered.robots = await fetchRobots(context, seo.url);
+    }
+    if (input.check_og_image) {
+        const target = resolveUrl(metaValues(seo, "og:image")[0], seo.url);
+        if (target)
+            gathered.og_image = await probeImage(context, target);
+    }
+    return gathered;
+}
+/* ── Rendering ────────────────────────────────────────────────────────── */
+const AREA_TITLES = {
+    indexing: "Indexing",
+    content: "Title & description",
+    headings: "Headings",
+    social: "Social (Open Graph)",
+    images: "Images",
+    structured_data: "Structured data",
+    performance: "Performance (lab)",
+};
+const MARKS = {
+    problem: "✗",
+    warning: "!",
+    pass: "✓",
+    info: "·",
+};
+async function render(gathered, report) {
+    const content = [{ type: "text", text: formatSeoReport(gathered.page, report) }];
+    // The share image is worth looking at, not only measuring: whether the logo
+    // is cropped or the text unreadable at card size is not a thing any header
+    // can answer.
+    const probe = gathered.og_image;
+    if (probe?.data) {
+        try {
+            const resized = await resizeForOutput(probe.data);
+            content.push({ type: "image", data: toBase64(resized), mimeType: "image/png" });
+            content.push({
+                type: "text",
+                text: `og:image — ${probe.url} (${probe.width}x${probe.height}${probe.content_type ? `, ${probe.content_type}` : ""}), as it will appear when the page is shared.`,
+            });
+        }
+        catch {
+            // Measured already; failing to re-encode it is not worth failing the audit for.
+        }
+    }
+    return { content };
+}
+/**
+ * The report as text: a verdict line, the problems up front, then every check
+ * in the order it was run.
+ *
+ * Passing checks are printed rather than counted. A report of four lines with
+ * nothing else in it is otherwise indistinguishable from an audit that only
+ * looked at four things.
+ */
+export function formatSeoReport(page, report) {
+    const lines = [];
+    lines.push(`SEO audit of ${page.url} — ${count(report.problems, "problem")}, ${count(report.warnings, "warning")}, ` +
+        `${report.passes} ${report.passes === 1 ? "check" : "checks"} passed.`);
+    const problems = report.findings.filter((finding) => finding.level === "problem");
+    if (problems.length > 0) {
+        lines.push(`Problems: ${problems.map((finding) => `${finding.label} (${headline(finding)})`).join("; ")}`);
+    }
+    else {
+        lines.push("Nothing here would keep this page out of an index or break its share card.");
+    }
+    for (const area of SEO_AREAS) {
+        const findings = report.findings.filter((finding) => finding.area === area);
+        if (findings.length === 0)
+            continue;
+        lines.push("");
+        lines.push(AREA_TITLES[area]);
+        for (const finding of findings) {
+            lines.push(`  ${MARKS[finding.level]} ${finding.label} — ${finding.detail}`);
+            if (finding.fix)
+                lines.push(`      → ${finding.fix}`);
+        }
+        if (area === "headings" && page.headings.length > 0) {
+            lines.push("  Outline:");
+            for (const heading of page.headings) {
+                const indent = "  ".repeat(Math.max(0, heading.level - 1));
+                const text = heading.empty ? "(empty)" : heading.text;
+                lines.push(`    ${indent}h${heading.level} ${text}${heading.hidden ? " (hidden)" : ""}`);
+            }
+            if (page.heading_total > page.headings.length) {
+                lines.push(`    … and ${page.heading_total - page.headings.length} more headings (the first ${MAX_SEO_HEADINGS} are listed)`);
+            }
+        }
+    }
+    return lines.join("\n");
+}
+/** The short form of a finding, for the problems line at the top. */
+function headline(finding) {
+    const [first] = finding.detail.split(" — ");
+    return first.length > 90 ? `${first.slice(0, 90)}…` : first;
+}
+function count(n, noun) {
+    return `${n} ${noun}${n === 1 ? "" : "s"}`;
+}
+/* ── Helpers ──────────────────────────────────────────────────────────── */
+/** Resolve a possibly relative URL against the page. Returns undefined for anything unusable. */
+function resolveUrl(href, base) {
+    if (!href)
+        return undefined;
+    try {
+        const resolved = new URL(href, base);
+        // A data: URI is already the image; there is nothing to fetch and nothing
+        // a network could fail to load.
+        return resolved.protocol === "http:" || resolved.protocol === "https:" ? resolved.href : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function firstLine(error) {
+    return (error instanceof Error ? error.message : String(error)).split("\n")[0];
+}
+function errorResult(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+/**
+ * One actionable line for an audit that could not run. Mirrors
+ * `describeFailure` in screenshot.ts: match on the failing Playwright call,
+ * never on substrings of a user-supplied selector.
+ */
+export function describeSeoFailure(input, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const line = message.split("\n")[0];
+    const prefix = `SEO audit of ${input.url} failed:`;
+    if (/Executable doesn't exist|browserType\.launch/i.test(message)) {
+        return (`${prefix} Playwright's Chromium browser is not installed. ` +
+            `Run \`npx playwright install chromium\` and try again. (${line})`);
+    }
+    if (input.wait_for && /^page\.waitForSelector:/.test(message)) {
+        return `${prefix} selector "${input.wait_for}" did not become visible within ${input.wait_for_timeout_ms}ms.`;
+    }
+    if (/^page\.goto:/.test(message)) {
+        return `${prefix} the page could not be opened — ${line}`;
+    }
+    return `${prefix} ${line}`;
+}
+export function registerSeoTool(server) {
+    server.registerTool(SEO_TOOL_NAME, {
+        title: "SEO",
+        description: "Audit what a search engine and a link preview would make of a page: title and meta description (with " +
+            "lengths), canonical, robots directives and robots.txt, Open Graph and Twitter card tags, the heading " +
+            "outline, images with no alt text, and JSON-LD structured data checked against what Google's rich " +
+            "results require. Everything is read from the rendered DOM, so a client-rendered app is measured " +
+            "properly rather than reported as empty. The og:image is fetched and measured — a share image that " +
+            "404s or is too small is invisible from the page itself — and comes back as an image to look at. " +
+            "Set `include_performance: true` to add LCP, CLS, TTFB, page weight and DOM size from the same load.",
+        inputSchema: seoInputShape,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (args) => auditSeo(args));
+}
+//# sourceMappingURL=seo.js.map

package/dist/tools/seo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo.js","sourceRoot":"","sources":["../../src/tools/seo.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\nimport type { BrowserContext, Page } from \"playwright\";\nimport type { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport type { CallToolResult } from \"@modelcontextprotocol/sdk/types.js\";\nimport {\n  DEFAULT_SEO_WAIT_MS,\n  DEFAULT_VIEWPORT,\n  MAX_SEO_HEADINGS,\n  MAX_VIEWPORT_HEIGHT,\n  MAX_VIEWPORT_WIDTH,\n  NAVIGATION_TIMEOUT_MS,\n  SELECTOR_TIMEOUT_MS,\n} from \"../constants.js\";\nimport { withPage } from \"../engine/browser.js\";\nimport {\n  PERF_INIT_SCRIPT,\n  extractSeo,\n  fetchRobots,\n  probeImage,\n  readPerformance,\n  type ImageProbe,\n  type PageSeo,\n  type PerfMetrics,\n  type RobotsFetch,\n} from \"../engine/seo.js\";\nimport { resizeForOutput, toBase64 } from \"../utils/image.js\";\nimport {\n  SEO_AREAS,\n  judgeSeo,\n  metaValues,\n  type SeoArea,\n  type SeoFinding,\n  type SeoLevel,\n  type SeoReport,\n  type SeoResponseInfo,\n} from \"../utils/seo-rules.js\";\nimport { resolveStorageState, storageStateField, withAuthNote } from \"../utils/storage-state.js\";\n\nexport const SEO_TOOL_NAME = \"framewatch_seo\";\n\nexport const seoInputShape = {\n  url: z.string().url().describe(\"URL to audit, e.g. http://localhost:3000 (http, https and file URLs are accepted)\"),\n  wait_ms: z\n    .number()\n    .int()\n    .min(0)\n    .default(DEFAULT_SEO_WAIT_MS)\n    .describe(\"Wait time (ms) after page load before reading the page, so a client-rendered app can finish\"),\n  wait_for: z.string().optional().describe(\"CSS selector to wait for (visible) before reading the page\"),\n  wait_for_timeout_ms: z\n    .number()\n    .int()\n    .min(1)\n    .default(SELECTOR_TIMEOUT_MS)\n    .describe(\"Max time (ms) to wait for `wait_for` to appear (must be > 0)\"),\n  check_robots: z\n    .boolean()\n    .default(true)\n    .describe(\"Fetch /robots.txt and work out whether this page's own path is crawlable\"),\n  robots_user_agent: z\n    .string()\n    .min(1)\n    .default(\"Googlebot\")\n    .describe(\"Which crawler to answer the robots.txt question for. A named group beats the `*` group, as it does for the real thing.\"),\n  check_og_image: z\n    .boolean()\n    .default(true)\n    .describe(\"Fetch the og:image and measure it — a share image that 404s or is too small is invisible from the page itself\"),\n  include_performance: z\n    .boolean()\n    .default(false)\n    .describe(\n      \"Also measure this load: LCP, CLS, TTFB, page weight and DOM size. Lab numbers from one headless load, \" +\n        \"useful for finding the slow element, not a prediction of field data.\",\n    ),\n  viewport: z\n    .object({\n      width: z.number().int().min(1).max(MAX_VIEWPORT_WIDTH).default(DEFAULT_VIEWPORT.width),\n      height: z.number().int().min(1).max(MAX_VIEWPORT_HEIGHT).default(DEFAULT_VIEWPORT.height),\n    })\n    .optional()\n    .describe(\"Viewport size (defaults to 1280x720)\"),\n  storage_state: storageStateField,\n};\n\nexport const seoInputSchema = z.object(seoInputShape);\nexport type SeoInput = z.input<typeof seoInputSchema>;\ntype ParsedSeoInput = z.output<typeof seoInputSchema>;\n\n/** Everything one audit gathered, before anything judges it. */\ninterface Gathered {\n  page: PageSeo;\n  response?: SeoResponseInfo;\n  robots?: RobotsFetch;\n  og_image?: ImageProbe;\n  performance?: PerfMetrics;\n}\n\n/**\n * Audit what a search engine — and a link preview — would make of a page.\n *\n * Everything is read from the *rendered* document rather than the HTML source.\n * A single-page app ships an empty `<div id=\"app\">` and fills in the title,\n * the description and the structured data afterwards, so reading the source\n * would report every client-rendered page as having no SEO at all, which is\n * both wrong and the opposite of useful.\n *\n * Three things are checked that are not on the page and cannot be seen from\n * it: the response headers (an `X-Robots-Tag: noindex` is invisible in the\n * DOM), robots.txt (a page can be perfect and simply not crawlable), and the\n * share image itself, which is fetched and measured — an `og:image` pointing\n * at a 404 looks exactly like a working one until somebody shares the link.\n */\nexport async function auditSeo(rawInput: SeoInput): Promise<CallToolResult> {\n  const parsed = seoInputSchema.safeParse(rawInput);\n  if (!parsed.success) {\n    const issues = parsed.error.issues.map((i) => `${i.path.join(\".\") || \"input\"}: ${i.message}`).join(\"; \");\n    return errorResult(`SEO audit failed: invalid input — ${issues}`);\n  }\n  const input = parsed.data;\n  const viewport = input.viewport ?? { ...DEFAULT_VIEWPORT };\n\n  let contextOptions = {};\n  let auth = null;\n  try {\n    auth = await resolveStorageState(input.storage_state);\n    if (auth) contextOptions = { storageState: auth.state };\n  } catch (error) {\n    return errorResult(`SEO audit of ${input.url} failed: ${firstLine(error)}`);\n  }\n\n  let gathered: Gathered;\n  try {\n    gathered = await withPage({ viewport, contextOptions }, (page, context) => gather(input, page, context));\n  } catch (error) {\n    return errorResult(describeSeoFailure(input, error));\n  }\n\n  const report = judgeSeo({\n    requested_url: input.url,\n    page: gathered.page,\n    robots_user_agent: input.robots_user_agent,\n    ...(gathered.response ? { response: gathered.response } : {}),\n    ...(gathered.robots ? { robots: gathered.robots } : {}),\n    ...(gathered.og_image ? { og_image: gathered.og_image } : {}),\n    ...(gathered.performance ? { performance: gathered.performance } : {}),\n  });\n\n  return withAuthNote(await render(gathered, report), auth);\n}\n\n/** Open the page and collect everything the audit needs from it. */\nasync function gather(input: ParsedSeoInput, page: Page, context: BrowserContext): Promise<Gathered> {\n  // The observers have to exist before the navigation: LCP, CLS and long\n  // tasks are only observable as they happen.\n  if (input.include_performance) await page.addInitScript(PERF_INIT_SCRIPT);\n\n  const response = await page.goto(input.url, { waitUntil: \"load\", timeout: NAVIGATION_TIMEOUT_MS });\n  if (input.wait_for) {\n    await page.waitForSelector(input.wait_for, { state: \"visible\", timeout: input.wait_for_timeout_ms });\n  }\n  if (input.wait_ms > 0) {\n    await page.waitForTimeout(input.wait_ms);\n  }\n\n  const seo = await extractSeo(page);\n  const gathered: Gathered = { page: seo };\n\n  if (response) {\n    gathered.response = { status: response.status(), headers: response.headers() };\n  }\n  if (input.include_performance) {\n    const metrics = await readPerformance(page);\n    if (metrics) gathered.performance = metrics;\n  }\n  if (input.check_robots) {\n    gathered.robots = await fetchRobots(context, seo.url);\n  }\n  if (input.check_og_image) {\n    const target = resolveUrl(metaValues(seo, \"og:image\")[0], seo.url);\n    if (target) gathered.og_image = await probeImage(context, target);\n  }\n\n  return gathered;\n}\n\n/* ── Rendering ────────────────────────────────────────────────────────── */\n\nconst AREA_TITLES: Readonly<Record<SeoArea, string>> = {\n  indexing: \"Indexing\",\n  content: \"Title & description\",\n  headings: \"Headings\",\n  social: \"Social (Open Graph)\",\n  images: \"Images\",\n  structured_data: \"Structured data\",\n  performance: \"Performance (lab)\",\n};\n\nconst MARKS: Readonly<Record<SeoLevel, string>> = {\n  problem: \"✗\",\n  warning: \"!\",\n  pass: \"✓\",\n  info: \"·\",\n};\n\nasync function render(gathered: Gathered, report: SeoReport): Promise<CallToolResult> {\n  const content: CallToolResult[\"content\"] = [{ type: \"text\", text: formatSeoReport(gathered.page, report) }];\n\n  // The share image is worth looking at, not only measuring: whether the logo\n  // is cropped or the text unreadable at card size is not a thing any header\n  // can answer.\n  const probe = gathered.og_image;\n  if (probe?.data) {\n    try {\n      const resized = await resizeForOutput(probe.data);\n      content.push({ type: \"image\", data: toBase64(resized), mimeType: \"image/png\" });\n      content.push({\n        type: \"text\",\n        text: `og:image — ${probe.url} (${probe.width}x${probe.height}${probe.content_type ? `, ${probe.content_type}` : \"\"}), as it will appear when the page is shared.`,\n      });\n    } catch {\n      // Measured already; failing to re-encode it is not worth failing the audit for.\n    }\n  }\n\n  return { content };\n}\n\n/**\n * The report as text: a verdict line, the problems up front, then every check\n * in the order it was run.\n *\n * Passing checks are printed rather than counted. A report of four lines with\n * nothing else in it is otherwise indistinguishable from an audit that only\n * looked at four things.\n */\nexport function formatSeoReport(page: PageSeo, report: SeoReport): string {\n  const lines: string[] = [];\n\n  lines.push(\n    `SEO audit of ${page.url} — ${count(report.problems, \"problem\")}, ${count(report.warnings, \"warning\")}, ` +\n      `${report.passes} ${report.passes === 1 ? \"check\" : \"checks\"} passed.`,\n  );\n\n  const problems = report.findings.filter((finding) => finding.level === \"problem\");\n  if (problems.length > 0) {\n    lines.push(`Problems: ${problems.map((finding) => `${finding.label} (${headline(finding)})`).join(\"; \")}`);\n  } else {\n    lines.push(\"Nothing here would keep this page out of an index or break its share card.\");\n  }\n\n  for (const area of SEO_AREAS) {\n    const findings = report.findings.filter((finding) => finding.area === area);\n    if (findings.length === 0) continue;\n    lines.push(\"\");\n    lines.push(AREA_TITLES[area]);\n    for (const finding of findings) {\n      lines.push(`  ${MARKS[finding.level]} ${finding.label} — ${finding.detail}`);\n      if (finding.fix) lines.push(`      → ${finding.fix}`);\n    }\n    if (area === \"headings\" && page.headings.length > 0) {\n      lines.push(\"  Outline:\");\n      for (const heading of page.headings) {\n        const indent = \"  \".repeat(Math.max(0, heading.level - 1));\n        const text = heading.empty ? \"(empty)\" : heading.text;\n        lines.push(`    ${indent}h${heading.level} ${text}${heading.hidden ? \" (hidden)\" : \"\"}`);\n      }\n      if (page.heading_total > page.headings.length) {\n        lines.push(`    … and ${page.heading_total - page.headings.length} more headings (the first ${MAX_SEO_HEADINGS} are listed)`);\n      }\n    }\n  }\n\n  return lines.join(\"\\n\");\n}\n\n/** The short form of a finding, for the problems line at the top. */\nfunction headline(finding: SeoFinding): string {\n  const [first] = finding.detail.split(\" — \");\n  return first.length > 90 ? `${first.slice(0, 90)}…` : first;\n}\n\nfunction count(n: number, noun: string): string {\n  return `${n} ${noun}${n === 1 ? \"\" : \"s\"}`;\n}\n\n/* ── Helpers ──────────────────────────────────────────────────────────── */\n\n/** Resolve a possibly relative URL against the page. Returns undefined for anything unusable. */\nfunction resolveUrl(href: string | undefined, base: string): string | undefined {\n  if (!href) return undefined;\n  try {\n    const resolved = new URL(href, base);\n    // A data: URI is already the image; there is nothing to fetch and nothing\n    // a network could fail to load.\n    return resolved.protocol === \"http:\" || resolved.protocol === \"https:\" ? resolved.href : undefined;\n  } catch {\n    return undefined;\n  }\n}\n\nfunction firstLine(error: unknown): string {\n  return (error instanceof Error ? error.message : String(error)).split(\"\\n\")[0];\n}\n\nfunction errorResult(text: string): CallToolResult {\n  return { isError: true, content: [{ type: \"text\", text }] };\n}\n\n/**\n * One actionable line for an audit that could not run. Mirrors\n * `describeFailure` in screenshot.ts: match on the failing Playwright call,\n * never on substrings of a user-supplied selector.\n */\nexport function describeSeoFailure(\n  input: { url: string; wait_for?: string; wait_for_timeout_ms: number },\n  error: unknown,\n): string {\n  const message = error instanceof Error ? error.message : String(error);\n  const line = message.split(\"\\n\")[0];\n  const prefix = `SEO audit of ${input.url} failed:`;\n\n  if (/Executable doesn't exist|browserType\\.launch/i.test(message)) {\n    return (\n      `${prefix} Playwright's Chromium browser is not installed. ` +\n      `Run \\`npx playwright install chromium\\` and try again. (${line})`\n    );\n  }\n  if (input.wait_for && /^page\\.waitForSelector:/.test(message)) {\n    return `${prefix} selector \"${input.wait_for}\" did not become visible within ${input.wait_for_timeout_ms}ms.`;\n  }\n  if (/^page\\.goto:/.test(message)) {\n    return `${prefix} the page could not be opened — ${line}`;\n  }\n  return `${prefix} ${line}`;\n}\n\nexport function registerSeoTool(server: McpServer): void {\n  server.registerTool(\n    SEO_TOOL_NAME,\n    {\n      title: \"SEO\",\n      description:\n        \"Audit what a search engine and a link preview would make of a page: title and meta description (with \" +\n        \"lengths), canonical, robots directives and robots.txt, Open Graph and Twitter card tags, the heading \" +\n        \"outline, images with no alt text, and JSON-LD structured data checked against what Google's rich \" +\n        \"results require. Everything is read from the rendered DOM, so a client-rendered app is measured \" +\n        \"properly rather than reported as empty. The og:image is fetched and measured — a share image that \" +\n        \"404s or is too small is invisible from the page itself — and comes back as an image to look at. \" +\n        \"Set `include_performance: true` to add LCP, CLS, TTFB, page weight and DOM size from the same load.\",\n      inputSchema: seoInputShape,\n      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },\n    },\n    async (args) => auditSeo(args),\n  );\n}\n"]}

package/dist/tools/snapshot.d.ts

@@ -0,0 +1,122 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { getSessionPage } from "../engine/browser.js";
+import { type PageSnapshot } from "../engine/snapshot.js";
+import { type VueInfo } from "../utils/vue-rules.js";
+import { type ResolvedAuth } from "../utils/storage-state.js";
+import type { Viewport } from "../types.js";
+export declare const SNAPSHOT_TOOL_NAME = "framewatch_snapshot";
+export declare const snapshotInputShape: {
+    url: z.ZodOptional<z.ZodString>;
+    selector: z.ZodOptional<z.ZodString>;
+    mode: z.ZodDefault<z.ZodEnum<["full", "interactive"]>>;
+    max_chars: z.ZodDefault<z.ZodNumber>;
+    include_screenshot: z.ZodDefault<z.ZodBoolean>;
+    include_components: z.ZodDefault<z.ZodBoolean>;
+    wait_ms: z.ZodDefault<z.ZodNumber>;
+    wait_for: z.ZodOptional<z.ZodString>;
+    wait_for_timeout_ms: z.ZodDefault<z.ZodNumber>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        width: number;
+        height: number;
+    }, {
+        width: number;
+        height: number;
+    }>>;
+    storage_state: z.ZodOptional<z.ZodString>;
+};
+export declare const snapshotInputSchema: z.ZodObject<{
+    url: z.ZodOptional<z.ZodString>;
+    selector: z.ZodOptional<z.ZodString>;
+    mode: z.ZodDefault<z.ZodEnum<["full", "interactive"]>>;
+    max_chars: z.ZodDefault<z.ZodNumber>;
+    include_screenshot: z.ZodDefault<z.ZodBoolean>;
+    include_components: z.ZodDefault<z.ZodBoolean>;
+    wait_ms: z.ZodDefault<z.ZodNumber>;
+    wait_for: z.ZodOptional<z.ZodString>;
+    wait_for_timeout_ms: z.ZodDefault<z.ZodNumber>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        width: number;
+        height: number;
+    }, {
+        width: number;
+        height: number;
+    }>>;
+    storage_state: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    wait_ms: number;
+    wait_for_timeout_ms: number;
+    mode: "full" | "interactive";
+    max_chars: number;
+    include_screenshot: boolean;
+    include_components: boolean;
+    url?: string | undefined;
+    viewport?: {
+        width: number;
+        height: number;
+    } | undefined;
+    wait_for?: string | undefined;
+    storage_state?: string | undefined;
+    selector?: string | undefined;
+}, {
+    url?: string | undefined;
+    viewport?: {
+        width: number;
+        height: number;
+    } | undefined;
+    wait_ms?: number | undefined;
+    wait_for?: string | undefined;
+    wait_for_timeout_ms?: number | undefined;
+    storage_state?: string | undefined;
+    selector?: string | undefined;
+    mode?: "full" | "interactive" | undefined;
+    max_chars?: number | undefined;
+    include_screenshot?: boolean | undefined;
+    include_components?: boolean | undefined;
+}>;
+export type SnapshotInput = z.input<typeof snapshotInputSchema>;
+/**
+ * Read the page as a tree of named elements, on the interact session's page so
+ * the refs it hands out are the ones the next `framewatch_interact` or
+ * `framewatch_inspect` can use.
+ */
+export declare function snapshotPage(rawInput: SnapshotInput): Promise<CallToolResult>;
+export declare function describeCounts(snapshot: Pick<PageSnapshot, "elements" | "interactive">): string;
+/** Input the session-page tools share: where to open, how long to wait, what size. */
+export interface SessionPageInput {
+    url?: string;
+    wait_ms?: number;
+    wait_for?: string;
+    wait_for_timeout_ms?: number;
+    viewport?: Viewport;
+    storage_state?: string;
+}
+/**
+ * The session page, opened at `url` when one is given. Shared by snapshot and
+ * inspect, which both read the page interact drives; `toolName` is only for
+ * the error wording.
+ */
+export interface OpenedSessionPage {
+    page: Awaited<ReturnType<typeof getSessionPage>>["page"];
+    vue: VueInfo | null;
+    /** The saved auth in force for this call, if any. */
+    auth: ResolvedAuth | null;
+    /** Whether the page showed a login form after opening — only checked when `url` was given. */
+    login_visible: boolean;
+}
+export declare function openSessionPage(input: SessionPageInput, toolName: string): Promise<OpenedSessionPage | {
+    error: string;
+}>;
+export declare function describeSessionFailure(toolName: string, input: {
+    url?: string;
+    wait_for?: string;
+    wait_for_timeout_ms?: number;
+}, error: unknown): string;
+export declare function registerSnapshotTool(server: McpServer): void;

package/dist/tools/snapshot.js

@@ -0,0 +1,183 @@
+import { z } from "zod";
+import { DEFAULT_SNAPSHOT_MAX_CHARS, DEFAULT_SNAPSHOT_WAIT_MS, MAX_SNAPSHOT_MAX_CHARS, MAX_VIEWPORT_HEIGHT, MAX_VIEWPORT_WIDTH, NAVIGATION_TIMEOUT_MS, SELECTOR_TIMEOUT_MS, VUE_READY_TIMEOUT_MS, } from "../constants.js";
+import { getSessionPage, withSessionLock } from "../engine/browser.js";
+import { hmrFor } from "../engine/hmr.js";
+import { takeSnapshot } from "../engine/snapshot.js";
+import { componentTree, detectVue, waitForVueReady } from "../engine/vue.js";
+import { describeVue, formatComponentTree } from "../utils/vue-rules.js";
+import { describeScale } from "../utils/format.js";
+import { resizeForOutput, toBase64 } from "../utils/image.js";
+import { loginFormVisible, resolveStorageState, storageStateField, withAuthNote } from "../utils/storage-state.js";
+export const SNAPSHOT_TOOL_NAME = "framewatch_snapshot";
+export const snapshotInputShape = {
+    url: z
+        .string()
+        .url()
+        .optional()
+        .describe("Open this URL first. Omit to read the page left open by framewatch_interact / framewatch_inspect."),
+    selector: z.string().optional().describe("Only this container, e.g. `main` or `#checkout`"),
+    mode: z
+        .enum(["full", "interactive"])
+        .default("full")
+        .describe("`full` is the whole tree with headings and text; `interactive` is a flat list of what can be clicked, typed into or chosen"),
+    max_chars: z
+        .number()
+        .int()
+        .min(200)
+        .max(MAX_SNAPSHOT_MAX_CHARS)
+        .default(DEFAULT_SNAPSHOT_MAX_CHARS)
+        .describe("Cut the tree past this many characters (a note says how many lines went)"),
+    include_screenshot: z.boolean().default(false).describe("Also return a screenshot of the page as it was read"),
+    include_components: z
+        .boolean()
+        .default(false)
+        .describe("On a Vue app: also return the component tree (names and nesting) from the root"),
+    wait_ms: z
+        .number()
+        .int()
+        .min(0)
+        .default(DEFAULT_SNAPSHOT_WAIT_MS)
+        .describe("Settle time (ms) after opening `url`. On a Vue app this is a ceiling: the page is read as soon as the app " +
+        "is mounted and its router ready"),
+    wait_for: z.string().optional().describe("CSS selector to wait for (visible) before reading"),
+    wait_for_timeout_ms: z.number().int().min(1).default(SELECTOR_TIMEOUT_MS).describe("Max time (ms) to wait for `wait_for`"),
+    viewport: z
+        .object({
+        width: z.number().int().min(1).max(MAX_VIEWPORT_WIDTH),
+        height: z.number().int().min(1).max(MAX_VIEWPORT_HEIGHT),
+    })
+        .optional()
+        .describe("Resize the page to this first (defaults to leaving it as it is)"),
+    storage_state: storageStateField,
+};
+export const snapshotInputSchema = z.object(snapshotInputShape);
+/**
+ * Read the page as a tree of named elements, on the interact session's page so
+ * the refs it hands out are the ones the next `framewatch_interact` or
+ * `framewatch_inspect` can use.
+ */
+export function snapshotPage(rawInput) {
+    return withSessionLock(() => runSnapshot(rawInput));
+}
+async function runSnapshot(rawInput) {
+    const parsed = snapshotInputSchema.safeParse(rawInput);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "input"}: ${i.message}`).join("; ");
+        return errorResult(`Snapshot failed: invalid input — ${issues}`);
+    }
+    const input = parsed.data;
+    try {
+        const opened = await openSessionPage(input, "Snapshot");
+        if ("error" in opened)
+            return errorResult(opened.error);
+        const { page, vue, auth, login_visible } = opened;
+        const snapshot = await takeSnapshot(page, {
+            ...(input.selector ? { selector: input.selector } : {}),
+            mode: input.mode,
+            max_chars: input.max_chars,
+        });
+        const viewport = page.viewportSize() ?? { width: 0, height: 0 };
+        const title = await page.title().catch(() => "");
+        const lines = [
+            `Snapshot of ${page.url()}${title ? ` — "${title}"` : ""} — ${describeScale(viewport).replace(/, images.*$/, "")} — ${describeCounts(snapshot)}${vue ? ` — ${describeVue(vue)}` : ""}`,
+            ...(input.include_screenshot ? [describeScale(viewport)] : []),
+            ...(input.selector ? [`Scope: ${input.selector}`] : []),
+            REF_HINT,
+            "",
+            snapshot.text,
+            ...(snapshot.cut_lines > 0
+                ? [`… ${snapshot.cut_lines} more lines cut — raise \`max_chars\`, pass \`selector\`, or use mode "interactive".`]
+                : []),
+        ];
+        if (input.include_components) {
+            lines.push("", ...(await describeComponents(page, vue)));
+        }
+        const content = [{ type: "text", text: lines.join("\n") }];
+        if (input.include_screenshot) {
+            const png = await page.screenshot({ type: "png" });
+            content.unshift({ type: "image", data: toBase64(await resizeForOutput(png)), mimeType: "image/png" });
+        }
+        hmrFor(page).markSeen();
+        return withAuthNote({ content }, auth, login_visible);
+    }
+    catch (error) {
+        return errorResult(describeSessionFailure("Snapshot", input, error));
+    }
+}
+const REF_HINT = "Refs: pass one as `ref` to framewatch_interact (to act on it) or framewatch_inspect (to measure it). " +
+    "They stay valid until the page changes — snapshot again after an action that re-rendered. " +
+    'In a framewatch_capture script, target the same element with a selector such as role=button[name="Sign in"].';
+export function describeCounts(snapshot) {
+    return `${snapshot.elements} elements, ${snapshot.interactive} interactive`;
+}
+/** The component tree, or why there is none. */
+async function describeComponents(page, vue) {
+    if (!vue)
+        return ["Components: no Vue app on this page"];
+    if (vue.major < 3)
+        return ["Components: Vue 2 — component details need Vue 3"];
+    if (vue.production)
+        return ["Components: production build — no component data on elements"];
+    const tree = await componentTree(page);
+    if (!tree)
+        return ["Components: could not be read"];
+    return formatComponentTree(tree.root, tree.total);
+}
+export async function openSessionPage(input, toolName) {
+    const options = {};
+    if (input.viewport)
+        options.viewport = input.viewport;
+    const auth = await resolveStorageState(input.storage_state);
+    if (auth)
+        options.storageState = { path: auth.path, state: auth.state };
+    const { page, previousUrl } = await getSessionPage(options);
+    const target = input.url ?? previousUrl;
+    if (target !== undefined) {
+        await page.goto(target, { waitUntil: "load", timeout: NAVIGATION_TIMEOUT_MS });
+        if (input.wait_for) {
+            await page.waitForSelector(input.wait_for, { state: "visible", timeout: input.wait_for_timeout_ms ?? SELECTOR_TIMEOUT_MS });
+        }
+        // `wait_ms` is a ceiling, not a sleep: a Vue app is read the moment it is
+        // mounted and its router has resolved; a page without one gets the full wait.
+        const { vue } = await waitForVueReady(page, { detect_ms: input.wait_ms ?? 0, ready_ms: VUE_READY_TIMEOUT_MS });
+        if (page.url() === "about:blank")
+            return { error: noPage(toolName) };
+        return { page, vue, auth, login_visible: auth && input.url !== undefined ? await loginFormVisible(page) : false };
+    }
+    if (page.url() === "about:blank")
+        return { error: noPage(toolName) };
+    return { page, vue: await detectVue(page), auth, login_visible: false };
+}
+function noPage(toolName) {
+    return `${toolName} failed: no page is open yet — pass \`url\` to open one (e.g. http://localhost:3000).`;
+}
+export function describeSessionFailure(toolName, input, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const firstLine = message.split("\n")[0];
+    if (/Executable doesn't exist|browserType\.launch/i.test(message)) {
+        return `${toolName} failed: Playwright's Chromium browser is not installed. Run \`npx playwright install chromium\` and try again. (${firstLine})`;
+    }
+    if (/^page\.goto:/.test(message)) {
+        return `${toolName} failed: could not open ${input.url ?? "the page"} — ${firstLine}`;
+    }
+    if (input.wait_for && /^page\.waitForSelector:/.test(message)) {
+        return `${toolName} failed: selector "${input.wait_for}" did not become visible within ${input.wait_for_timeout_ms ?? SELECTOR_TIMEOUT_MS}ms.`;
+    }
+    return `${toolName} failed: ${firstLine}`;
+}
+function errorResult(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+export function registerSnapshotTool(server) {
+    server.registerTool(SNAPSHOT_TOOL_NAME, {
+        title: "Snapshot",
+        description: "Read the page as a tree of named elements — every heading, field, button and link with its accessible name " +
+            "and a short ref like `e8` — so you know what is on the page and what to call it instead of guessing selectors " +
+            "from a screenshot. Pass a ref as `ref` to framewatch_interact to act on that element, or to framewatch_inspect " +
+            "to measure it. Works on the page framewatch_interact keeps open; pass `url` to open one. " +
+            "Use mode `interactive` for a short list of only what can be acted on.",
+        inputSchema: snapshotInputShape,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (args) => snapshotPage(args));
+}
+//# sourceMappingURL=snapshot.js.map