framewatch-mcp-server 0.1.0

package/dist/index.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { closeBrowser } from "./engine/browser.js";
+import { registerAllTools } from "./tools/index.js";
+import { shutdownDevServer } from "./utils/server-process.js";
+export const SERVER_NAME = "framewatch";
+export const SERVER_VERSION = readPackageVersion();
+/**
+ * Build a fully configured FrameWatch McpServer (not yet connected to a
+ * transport). Exported so tests and embedders can wire their own transport;
+ * importing this module has no side effects — the stdio server only starts
+ * when this file is executed directly (`node dist/index.js` / the npm bin).
+ */
+export function createServer() {
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, {
+        instructions: "FrameWatch gives you visual eyes on running web apps. Use framewatch_screenshot to see the " +
+            "current state of a page. Pass a `selector` to zoom in on one element, or `wait_for` to wait " +
+            "for an element before capturing. Use framewatch_capture to record a page for a few seconds " +
+            "and get back only the frames where something meaningful changed (animations, splash screens, " +
+            "transitions, anything that changes over time), each with a crop of the changed region and its " +
+            "position. Lower `sensitivity` to keep more frames, raise `max_frames` for longer sequences. " +
+            "Pass `interactions` to replay a click/type/scroll/tap/swipe script while it records — that is how you " +
+            "test a flow such as a login. Use framewatch_interact for one action at a time: it keeps the page open " +
+            "between calls, so you can click, look at the result, type, and look again without replaying the flow. " +
+            "Both capture and interact can attach the context behind a frame — console output and uncaught errors " +
+            "(on by default), plus network requests, DOM mutations and paint timing via `include_network`, " +
+            "`include_dom` and `include_performance` — which is how you find out why a frame looks wrong. " +
+            "Use framewatch_responsive to see one page at mobile, tablet and desktop widths at once (it also " +
+            "reports content that overflows its viewport), framewatch_accessibility to run an axe-core WCAG audit, " +
+            "and framewatch_compare to diff two URLs — or the page interact has open against a URL — with an " +
+            "overlay of every pixel that differs. If the app is not running yet, framewatch_start_server runs its " +
+            "dev server (e.g. `npm run dev`) and waits for the port; framewatch_stop_server stops it again.",
+    });
+    registerAllTools(server);
+    return server;
+}
+/** Run the server on stdio until the client disconnects or the process is signalled. */
+export async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    // stderr may be closed by the host (e.g. parent died); never let a log write
+    // turn into an uncaught 'error' event that re-enters the handlers below.
+    process.stderr.on("error", () => { });
+    let shuttingDown = false;
+    const shutdown = async (reason, exitCode = 0) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        log(`shutting down (${reason})`);
+        try {
+            // The dev server is a child process of this one; leaving it behind would
+            // hold its port and outlive the client that asked for it.
+            await shutdownDevServer();
+            await closeBrowser();
+        }
+        finally {
+            await server.close().catch(() => { });
+            process.exit(exitCode);
+        }
+    };
+    // Client went away. The SDK transport only fires onclose on protocol errors,
+    // so watch stdin EOF directly — once Chromium is running it would otherwise
+    // keep the event loop (and a headless browser) alive forever.
+    process.stdin.on("end", () => void shutdown("stdin closed"));
+    process.stdin.on("close", () => void shutdown("stdin closed"));
+    transport.onclose = () => void shutdown("transport closed");
+    process.on("SIGINT", () => void shutdown("SIGINT"));
+    process.on("SIGTERM", () => void shutdown("SIGTERM"));
+    process.on("SIGHUP", () => void shutdown("SIGHUP"));
+    process.on("uncaughtException", (err) => {
+        log(`uncaught exception: ${formatError(err)}`);
+        void shutdown("uncaught exception", 1);
+    });
+    process.on("unhandledRejection", (err) => {
+        log(`unhandled rejection: ${formatError(err)}`);
+    });
+    await server.connect(transport);
+    log(`${SERVER_NAME} v${SERVER_VERSION} ready on stdio`);
+}
+/** stdout is the MCP channel — all diagnostics go to stderr, and never throw. */
+function log(message) {
+    try {
+        process.stderr.write(`[framewatch] ${message}\n`);
+    }
+    catch {
+        // stderr is gone; nothing sensible to do.
+    }
+}
+function formatError(err) {
+    return err instanceof Error ? (err.stack ?? err.message) : String(err);
+}
+function readPackageVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+/**
+ * True when this file is the process entry point. npm's bin shim is a symlink,
+ * so compare real paths: import.meta.url is already resolved, argv[1] is not.
+ */
+function isRunDirectly() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return import.meta.url === pathToFileURL(realpathSync(entry)).href;
+    }
+    catch {
+        return false;
+    }
+}
+if (isRunDirectly()) {
+    main().catch((err) => {
+        log(`fatal: ${formatError(err)}`);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE9D,MAAM,CAAC,MAAM,WAAW,GAAG,YAAY,CAAC;AACxC,MAAM,CAAC,MAAM,cAAc,GAAW,kBAAkB,EAAE,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,EAAE,EAC9C;QACE,YAAY,EACV,6FAA6F;YAC7F,8FAA8F;YAC9F,6FAA6F;YAC7F,+FAA+F;YAC/F,gGAAgG;YAChG,8FAA8F;YAC9F,wGAAwG;YACxG,wGAAwG;YACxG,wGAAwG;YACxG,uGAAuG;YACvG,gGAAgG;YAChG,+FAA+F;YAC/F,kGAAkG;YAClG,wGAAwG;YACxG,kGAAkG;YAClG,uGAAuG;YACvG,gGAAgG;KACnG,CACF,CAAC;IACF,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,wFAAwF;AACxF,MAAM,CAAC,KAAK,UAAU,IAAI;IACxB,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAE7C,6EAA6E;IAC7E,yEAAyE;IACzE,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAErC,IAAI,YAAY,GAAG,KAAK,CAAC;IACzB,MAAM,QAAQ,GAAG,KAAK,EAAE,MAAc,EAAE,QAAQ,GAAG,CAAC,EAAiB,EAAE;QACrE,IAAI,YAAY;YAAE,OAAO;QACzB,YAAY,GAAG,IAAI,CAAC;QACpB,GAAG,CAAC,kBAAkB,MAAM,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC;YACH,yEAAyE;YACzE,0DAA0D;YAC1D,MAAM,iBAAiB,EAAE,CAAC;YAC1B,MAAM,YAAY,EAAE,CAAC;QACvB,CAAC;gBAAS,CAAC;YACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YACrC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzB,CAAC;IACH,CAAC,CAAC;IAEF,6EAA6E;IAC7E,4EAA4E;IAC5E,8DAA8D;IAC9D,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC;IAC7D,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC;IAC/D,SAAS,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC,KAAK,QAAQ,CAAC,kBAAkB,CAAC,CAAC;IAE5D,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;IACpD,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;IACtD,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;IACpD,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,GAAG,EAAE,EAAE;QACtC,GAAG,CAAC,uBAAuB,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC/C,KAAK,QAAQ,CAAC,oBAAoB,EAAE,CAAC,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,GAAG,EAAE,EAAE;QACvC,GAAG,CAAC,wBAAwB,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;IAEH,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,GAAG,CAAC,GAAG,WAAW,KAAK,cAAc,iBAAiB,CAAC,CAAC;AAC1D,CAAC;AAED,iFAAiF;AACjF,SAAS,GAAG,CAAC,OAAe;IAC1B,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,OAAO,IAAI,CAAC,CAAC;IACpD,CAAC;IAAC,MAAM,CAAC;QACP,0CAA0C;IAC5C,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,GAAY;IAC/B,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AACzE,CAAC;AAED,SAAS,kBAAkB;IACzB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAyB,CAAC;QAClH,OAAO,GAAG,CAAC,OAAO,IAAI,OAAO,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,aAAa;IACpB,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9B,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,aAAa,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,IAAI,aAAa,EAAE,EAAE,CAAC;IACpB,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QACnB,GAAG,CAAC,UAAU,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["#!/usr/bin/env node\nimport { readFileSync, realpathSync } from \"node:fs\";\nimport { pathToFileURL } from \"node:url\";\nimport { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport { closeBrowser } from \"./engine/browser.js\";\nimport { registerAllTools } from \"./tools/index.js\";\nimport { shutdownDevServer } from \"./utils/server-process.js\";\n\nexport const SERVER_NAME = \"framewatch\";\nexport const SERVER_VERSION: string = readPackageVersion();\n\n/**\n * Build a fully configured FrameWatch McpServer (not yet connected to a\n * transport). Exported so tests and embedders can wire their own transport;\n * importing this module has no side effects — the stdio server only starts\n * when this file is executed directly (`node dist/index.js` / the npm bin).\n */\nexport function createServer(): McpServer {\n  const server = new McpServer(\n    { name: SERVER_NAME, version: SERVER_VERSION },\n    {\n      instructions:\n        \"FrameWatch gives you visual eyes on running web apps. Use framewatch_screenshot to see the \" +\n        \"current state of a page. Pass a `selector` to zoom in on one element, or `wait_for` to wait \" +\n        \"for an element before capturing. Use framewatch_capture to record a page for a few seconds \" +\n        \"and get back only the frames where something meaningful changed (animations, splash screens, \" +\n        \"transitions, anything that changes over time), each with a crop of the changed region and its \" +\n        \"position. Lower `sensitivity` to keep more frames, raise `max_frames` for longer sequences. \" +\n        \"Pass `interactions` to replay a click/type/scroll/tap/swipe script while it records — that is how you \" +\n        \"test a flow such as a login. Use framewatch_interact for one action at a time: it keeps the page open \" +\n        \"between calls, so you can click, look at the result, type, and look again without replaying the flow. \" +\n        \"Both capture and interact can attach the context behind a frame — console output and uncaught errors \" +\n        \"(on by default), plus network requests, DOM mutations and paint timing via `include_network`, \" +\n        \"`include_dom` and `include_performance` — which is how you find out why a frame looks wrong. \" +\n        \"Use framewatch_responsive to see one page at mobile, tablet and desktop widths at once (it also \" +\n        \"reports content that overflows its viewport), framewatch_accessibility to run an axe-core WCAG audit, \" +\n        \"and framewatch_compare to diff two URLs — or the page interact has open against a URL — with an \" +\n        \"overlay of every pixel that differs. If the app is not running yet, framewatch_start_server runs its \" +\n        \"dev server (e.g. `npm run dev`) and waits for the port; framewatch_stop_server stops it again.\",\n    },\n  );\n  registerAllTools(server);\n  return server;\n}\n\n/** Run the server on stdio until the client disconnects or the process is signalled. */\nexport async function main(): Promise<void> {\n  const server = createServer();\n  const transport = new StdioServerTransport();\n\n  // stderr may be closed by the host (e.g. parent died); never let a log write\n  // turn into an uncaught 'error' event that re-enters the handlers below.\n  process.stderr.on(\"error\", () => {});\n\n  let shuttingDown = false;\n  const shutdown = async (reason: string, exitCode = 0): Promise<void> => {\n    if (shuttingDown) return;\n    shuttingDown = true;\n    log(`shutting down (${reason})`);\n    try {\n      // The dev server is a child process of this one; leaving it behind would\n      // hold its port and outlive the client that asked for it.\n      await shutdownDevServer();\n      await closeBrowser();\n    } finally {\n      await server.close().catch(() => {});\n      process.exit(exitCode);\n    }\n  };\n\n  // Client went away. The SDK transport only fires onclose on protocol errors,\n  // so watch stdin EOF directly — once Chromium is running it would otherwise\n  // keep the event loop (and a headless browser) alive forever.\n  process.stdin.on(\"end\", () => void shutdown(\"stdin closed\"));\n  process.stdin.on(\"close\", () => void shutdown(\"stdin closed\"));\n  transport.onclose = () => void shutdown(\"transport closed\");\n\n  process.on(\"SIGINT\", () => void shutdown(\"SIGINT\"));\n  process.on(\"SIGTERM\", () => void shutdown(\"SIGTERM\"));\n  process.on(\"SIGHUP\", () => void shutdown(\"SIGHUP\"));\n  process.on(\"uncaughtException\", (err) => {\n    log(`uncaught exception: ${formatError(err)}`);\n    void shutdown(\"uncaught exception\", 1);\n  });\n  process.on(\"unhandledRejection\", (err) => {\n    log(`unhandled rejection: ${formatError(err)}`);\n  });\n\n  await server.connect(transport);\n  log(`${SERVER_NAME} v${SERVER_VERSION} ready on stdio`);\n}\n\n/** stdout is the MCP channel — all diagnostics go to stderr, and never throw. */\nfunction log(message: string): void {\n  try {\n    process.stderr.write(`[framewatch] ${message}\\n`);\n  } catch {\n    // stderr is gone; nothing sensible to do.\n  }\n}\n\nfunction formatError(err: unknown): string {\n  return err instanceof Error ? (err.stack ?? err.message) : String(err);\n}\n\nfunction readPackageVersion(): string {\n  try {\n    const pkg = JSON.parse(readFileSync(new URL(\"../package.json\", import.meta.url), \"utf8\")) as { version?: string };\n    return pkg.version ?? \"0.0.0\";\n  } catch {\n    return \"0.0.0\";\n  }\n}\n\n/**\n * True when this file is the process entry point. npm's bin shim is a symlink,\n * so compare real paths: import.meta.url is already resolved, argv[1] is not.\n */\nfunction isRunDirectly(): boolean {\n  const entry = process.argv[1];\n  if (!entry) return false;\n  try {\n    return import.meta.url === pathToFileURL(realpathSync(entry)).href;\n  } catch {\n    return false;\n  }\n}\n\nif (isRunDirectly()) {\n  main().catch((err) => {\n    log(`fatal: ${formatError(err)}`);\n    process.exit(1);\n  });\n}\n"]}

package/dist/tools/accessibility.d.ts

@@ -0,0 +1,140 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare const ACCESSIBILITY_TOOL_NAME = "framewatch_accessibility";
+/** WCAG conformance levels, and the axe-core tags each one runs. */
+declare const STANDARDS: {
+    readonly wcag2a: readonly ["wcag2a"];
+    readonly wcag2aa: readonly ["wcag2a", "wcag2aa"];
+    readonly wcag21aa: readonly ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"];
+};
+export type A11yStandard = keyof typeof STANDARDS;
+export declare const accessibilityInputShape: {
+    url: z.ZodString;
+    standard: z.ZodDefault<z.ZodEnum<["wcag2a", "wcag2aa", "wcag21aa"]>>;
+    wait_ms: z.ZodDefault<z.ZodNumber>;
+    wait_for: z.ZodOptional<z.ZodString>;
+    wait_for_timeout_ms: z.ZodDefault<z.ZodNumber>;
+    max_violations: z.ZodDefault<z.ZodNumber>;
+    max_elements: z.ZodDefault<z.ZodNumber>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodDefault<z.ZodNumber>;
+        height: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        width: number;
+        height: number;
+    }, {
+        width?: number | undefined;
+        height?: number | undefined;
+    }>>;
+};
+export declare const accessibilityInputSchema: z.ZodObject<{
+    url: z.ZodString;
+    standard: z.ZodDefault<z.ZodEnum<["wcag2a", "wcag2aa", "wcag21aa"]>>;
+    wait_ms: z.ZodDefault<z.ZodNumber>;
+    wait_for: z.ZodOptional<z.ZodString>;
+    wait_for_timeout_ms: z.ZodDefault<z.ZodNumber>;
+    max_violations: z.ZodDefault<z.ZodNumber>;
+    max_elements: z.ZodDefault<z.ZodNumber>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodDefault<z.ZodNumber>;
+        height: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        width: number;
+        height: number;
+    }, {
+        width?: number | undefined;
+        height?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    standard: "wcag2a" | "wcag2aa" | "wcag21aa";
+    wait_ms: number;
+    wait_for_timeout_ms: number;
+    max_violations: number;
+    max_elements: number;
+    viewport?: {
+        width: number;
+        height: number;
+    } | undefined;
+    wait_for?: string | undefined;
+}, {
+    url: string;
+    viewport?: {
+        width?: number | undefined;
+        height?: number | undefined;
+    } | undefined;
+    standard?: "wcag2a" | "wcag2aa" | "wcag21aa" | undefined;
+    wait_ms?: number | undefined;
+    wait_for?: string | undefined;
+    wait_for_timeout_ms?: number | undefined;
+    max_violations?: number | undefined;
+    max_elements?: number | undefined;
+}>;
+export type AccessibilityInput = z.input<typeof accessibilityInputSchema>;
+/** The trimmed shape the in-page script sends back — never raw axe results. */
+interface AxeNode {
+    target: string;
+    html: string;
+    summary: string;
+}
+interface AxeViolation {
+    id: string;
+    impact: string;
+    help: string;
+    description: string;
+    help_url: string;
+    tags: string[];
+    node_count: number;
+    nodes: AxeNode[];
+}
+interface AxeReport {
+    violations: AxeViolation[];
+    /** Rules that passed, that found nothing to test, and that need a human. */
+    passes: number;
+    inapplicable: number;
+    incomplete: number;
+    /** Total violation types found, before `max_violations` trimmed the list. */
+    total_violations: number;
+    /** Offending elements across every violation, including those not listed. */
+    total_nodes: number;
+    url: string;
+    axe_version: string;
+}
+/**
+ * Run an axe-core accessibility audit and report what it found.
+ *
+ * axe is injected into the page rather than reimplemented: it is the engine
+ * behind most commercial accessibility tooling, so a violation reported here
+ * is one an auditor would also raise. It is injected as a script through
+ * `evaluate`, into a context created with CSP bypassed, so a page with a
+ * strict Content-Security-Policy can still be audited.
+ *
+ * Only violations come back. Passing rules are counted, not listed — a list of
+ * two hundred rules that did not fire is noise, but the count is what tells
+ * you the audit actually ran.
+ */
+export declare function auditAccessibility(rawInput: AccessibilityInput): Promise<CallToolResult>;
+/**
+ * Render the report as text.
+ *
+ * Each violation gets its impact, the rule that failed, what to do about it,
+ * the elements at fault and the URL of Deque's write-up — everything needed to
+ * fix it without a second lookup.
+ */
+export declare function formatReport(report: AxeReport, standard: A11yStandard): string;
+export declare function axeSource(): string;
+/**
+ * One actionable line for a failed audit. Mirrors `describeFailure` in
+ * screenshot.ts: match on the failing Playwright call, never on substrings of
+ * a user-supplied selector.
+ */
+export declare function describeAuditFailure(input: {
+    url: string;
+    wait_for?: string;
+    wait_for_timeout_ms: number;
+}, error: unknown): string;
+export declare function registerAccessibilityTool(server: McpServer): void;
+/** Exported for tests: the axe tag list each standard maps to. */
+export declare const A11Y_STANDARD_TAGS: Readonly<Record<A11yStandard, readonly string[]>>;
+export {};

package/dist/tools/accessibility.js

@@ -0,0 +1,357 @@
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+import { A11Y_FRAME_WAIT_MS, A11Y_RUN_TIMEOUT_MS, DEFAULT_A11Y_WAIT_MS, DEFAULT_VIEWPORT, MAX_A11Y_HTML_LENGTH, MAX_A11Y_NODES_PER_VIOLATION, MAX_A11Y_VIOLATIONS, MAX_VIEWPORT_HEIGHT, MAX_VIEWPORT_WIDTH, NAVIGATION_TIMEOUT_MS, SELECTOR_TIMEOUT_MS, } from "../constants.js";
+import { withPage } from "../engine/browser.js";
+export const ACCESSIBILITY_TOOL_NAME = "framewatch_accessibility";
+/** WCAG conformance levels, and the axe-core tags each one runs. */
+const STANDARDS = {
+    wcag2a: ["wcag2a"],
+    wcag2aa: ["wcag2a", "wcag2aa"],
+    wcag21aa: ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"],
+};
+/** Worst first — this is the order violations are reported in. */
+const IMPACT_ORDER = ["critical", "serious", "moderate", "minor"];
+export const accessibilityInputShape = {
+    url: z.string().url().describe("URL to audit, e.g. http://localhost:3000 (http, https and file URLs are accepted)"),
+    standard: z
+        .enum(["wcag2a", "wcag2aa", "wcag21aa"])
+        .default("wcag2aa")
+        .describe("Conformance level to test against. wcag2aa is the usual legal baseline; wcag21aa adds WCAG 2.1."),
+    wait_ms: z
+        .number()
+        .int()
+        .min(0)
+        .default(DEFAULT_A11Y_WAIT_MS)
+        .describe("Wait time (ms) after page load before auditing, so the app can finish rendering"),
+    wait_for: z.string().optional().describe("CSS selector to wait for (visible) before auditing"),
+    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)"),
+    max_violations: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_A11Y_VIOLATIONS)
+        .default(MAX_A11Y_VIOLATIONS)
+        .describe("Maximum violation types to report (they are reported worst-impact first)"),
+    max_elements: z
+        .number()
+        .int()
+        .min(1)
+        .max(20)
+        .default(MAX_A11Y_NODES_PER_VIOLATION)
+        .describe("Maximum offending elements listed under each violation"),
+    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). Some rules — reflow, target size — depend on it."),
+};
+export const accessibilityInputSchema = z.object(accessibilityInputShape);
+/**
+ * Run an axe-core accessibility audit and report what it found.
+ *
+ * axe is injected into the page rather than reimplemented: it is the engine
+ * behind most commercial accessibility tooling, so a violation reported here
+ * is one an auditor would also raise. It is injected as a script through
+ * `evaluate`, into a context created with CSP bypassed, so a page with a
+ * strict Content-Security-Policy can still be audited.
+ *
+ * Only violations come back. Passing rules are counted, not listed — a list of
+ * two hundred rules that did not fire is noise, but the count is what tells
+ * you the audit actually ran.
+ */
+export async function auditAccessibility(rawInput) {
+    const parsed = accessibilityInputSchema.safeParse(rawInput);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "input"}: ${i.message}`).join("; ");
+        return errorResult(`Accessibility audit failed: invalid input — ${issues}`);
+    }
+    const input = parsed.data;
+    const viewport = input.viewport ?? { ...DEFAULT_VIEWPORT };
+    let source;
+    try {
+        source = axeSource();
+    }
+    catch (error) {
+        return errorResult("Accessibility audit failed: the axe-core library could not be loaded from this installation " +
+            `(${error instanceof Error ? error.message : String(error)}). Reinstall dependencies and try again.`);
+    }
+    try {
+        // `bypassCSP` so the audit can be injected into an app that forbids
+        // inline script and eval. The page's own CSP has no bearing on what axe
+        // measures, and without this a strictly configured app could not be
+        // audited at all.
+        const report = await withPage({ viewport, contextOptions: { bypassCSP: true } }, async (page) => {
+            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);
+            }
+            await injectAxe(page, source);
+            // axe walks the whole DOM; on a big enough app that takes a while, and
+            // `page.evaluate` has no timeout of its own — a page that wedges
+            // mid-audit would otherwise hang the tool call forever.
+            return withTimeout(runAxe(page, {
+                tags: [...STANDARDS[input.standard]],
+                max_violations: input.max_violations,
+                max_elements: input.max_elements,
+                max_html: MAX_A11Y_HTML_LENGTH,
+                frame_wait_ms: A11Y_FRAME_WAIT_MS,
+            }), A11Y_RUN_TIMEOUT_MS, `axe-core did not finish within ${A11Y_RUN_TIMEOUT_MS}ms`);
+        });
+        return { content: [{ type: "text", text: formatReport(report, input.standard) }] };
+    }
+    catch (error) {
+        return errorResult(describeAuditFailure(input, error));
+    }
+}
+/**
+ * Put axe in the main frame and in every child frame.
+ *
+ * axe audits iframes by talking to a copy of itself inside each one, so a page
+ * that embeds anything (a preview pane, an embedded checkout) needs it
+ * everywhere. Child frames are best-effort: one that refuses injection — it
+ * may be mid-navigation, or gone by the time we reach it — must not stop the
+ * audit of the page around it.
+ */
+async function injectAxe(page, source) {
+    await evaluateSource(page.mainFrame(), source);
+    for (const frame of page.frames()) {
+        if (frame === page.mainFrame())
+            continue;
+        await evaluateSource(frame, source).catch(() => { });
+    }
+}
+/**
+ * Evaluate the axe bundle as a script in `frame`.
+ *
+ * The source goes in as a *string*, which Playwright evaluates as a script in
+ * the frame — no script tag to be blocked, and the audit context is created
+ * with CSP bypassed so injection works on strictly configured apps too.
+ *
+ * `allowedOrigins` is widened because axe defaults to same-origin frame
+ * messaging only, and a cross-origin iframe would otherwise never answer.
+ */
+async function evaluateSource(frame, source) {
+    await frame.evaluate(source);
+    await frame.evaluate(() => {
+        const axe = globalThis.axe;
+        if (axe?.configure)
+            axe.configure({ allowedOrigins: ["<unsafe_all_origins>"] });
+    });
+}
+/**
+ * Run axe in the page and bring back only what gets printed.
+ *
+ * The trimming happens in the page on purpose: a full axe result carries every
+ * passing rule with every element it checked, which on a real app is megabytes
+ * of JSON to serialise across the protocol and then throw away.
+ */
+async function runAxe(page, options) {
+    return page.evaluate(async (opts) => {
+        const g = globalThis;
+        const axe = g.axe;
+        if (!axe?.run)
+            throw new Error("axe-core did not load in the page");
+        const results = await axe.run(g.document, {
+            runOnly: { type: "tag", values: opts.tags },
+            // Only violations are reported, so this is the only result type whose
+            // element details need collecting.
+            resultTypes: ["violations"],
+            frameWaitTime: opts.frame_wait_ms,
+        });
+        const order = ["critical", "serious", "moderate", "minor"];
+        const rank = (impact) => {
+            const at = order.indexOf(impact);
+            return at === -1 ? order.length : at;
+        };
+        const all = (results.violations ?? []).slice().sort((a, b) => {
+            const byImpact = rank(String(a.impact)) - rank(String(b.impact));
+            if (byImpact !== 0)
+                return byImpact;
+            // Then by blast radius: the rule breaking twenty elements first.
+            return (b.nodes?.length ?? 0) - (a.nodes?.length ?? 0);
+        });
+        const elide = (text) => {
+            const flat = String(text ?? "")
+                .replace(/\s+/g, " ")
+                .trim();
+            return flat.length > opts.max_html ? `${flat.slice(0, opts.max_html)}…` : flat;
+        };
+        return {
+            violations: all.slice(0, opts.max_violations).map((violation) => ({
+                id: String(violation.id ?? "unknown"),
+                impact: String(violation.impact ?? "unknown"),
+                help: String(violation.help ?? ""),
+                description: String(violation.description ?? ""),
+                help_url: String(violation.helpUrl ?? ""),
+                tags: (violation.tags ?? []).map((tag) => String(tag)),
+                node_count: violation.nodes?.length ?? 0,
+                nodes: (violation.nodes ?? []).slice(0, opts.max_elements).map((node) => ({
+                    target: (node.target ?? []).map((part) => String(part)).join(" "),
+                    html: elide(node.html),
+                    // The first line is the rule that failed for this element; the rest
+                    // repeats the violation's own help text.
+                    summary: elide(String(node.failureSummary ?? "").split("\n").slice(1).join(" ")),
+                })),
+            })),
+            passes: results.passes?.length ?? 0,
+            inapplicable: results.inapplicable?.length ?? 0,
+            incomplete: results.incomplete?.length ?? 0,
+            total_violations: all.length,
+            total_nodes: all.reduce((sum, violation) => sum + (violation.nodes?.length ?? 0), 0),
+            url: String(results.url ?? ""),
+            axe_version: String(results.testEngine?.version ?? ""),
+        };
+    }, options);
+}
+/**
+ * Render the report as text.
+ *
+ * Each violation gets its impact, the rule that failed, what to do about it,
+ * the elements at fault and the URL of Deque's write-up — everything needed to
+ * fix it without a second lookup.
+ */
+export function formatReport(report, standard) {
+    const scope = `${standard.toUpperCase()} (axe-core ${report.axe_version || "?"})`;
+    const lines = [];
+    if (report.total_violations === 0) {
+        lines.push(`No ${scope} violations on ${report.url}.`);
+        lines.push(auditFooter(report));
+        return lines.join("\n");
+    }
+    lines.push(`${report.total_violations} ${scope} violation ${report.total_violations === 1 ? "type" : "types"} on ${report.url}, ` +
+        `affecting ${report.total_nodes} ${report.total_nodes === 1 ? "element" : "elements"} — ${countByImpact(report)}.`);
+    lines.push(auditFooter(report));
+    lines.push("");
+    report.violations.forEach((violation, index) => {
+        lines.push(`${index + 1}. [${violation.impact}] ${violation.help} (${violation.id}) — ` +
+            `${violation.node_count} ${violation.node_count === 1 ? "element" : "elements"}`);
+        lines.push(`   ${violation.description}`);
+        for (const node of violation.nodes) {
+            lines.push(`   • ${node.target || "?"}`);
+            if (node.html)
+                lines.push(`     ${node.html}`);
+            if (node.summary)
+                lines.push(`     ${node.summary}`);
+        }
+        if (violation.node_count > violation.nodes.length) {
+            lines.push(`   … and ${violation.node_count - violation.nodes.length} more elements`);
+        }
+        if (violation.help_url)
+            lines.push(`   ${violation.help_url}`);
+    });
+    if (report.total_violations > report.violations.length) {
+        lines.push("");
+        lines.push(`… and ${report.total_violations - report.violations.length} more violation types not shown ` +
+            "(raise `max_violations` to see them).");
+    }
+    return lines.join("\n");
+}
+/**
+ * The counts that say how much of the page was actually judged. `incomplete`
+ * is the important one: those are the checks axe could not decide on its own
+ * (typically colour contrast over an image) and they are the rules a human
+ * still has to look at.
+ */
+function auditFooter(report) {
+    return `${report.passes} rules passed, ${report.incomplete} need a human to check, ${report.inapplicable} did not apply.`;
+}
+function countByImpact(report) {
+    const counts = new Map();
+    for (const violation of report.violations) {
+        counts.set(violation.impact, (counts.get(violation.impact) ?? 0) + 1);
+    }
+    const known = IMPACT_ORDER.filter((impact) => counts.has(impact)).map((impact) => `${counts.get(impact)} ${impact}`);
+    const other = [...counts.keys()]
+        .filter((impact) => !IMPACT_ORDER.includes(impact))
+        .map((impact) => `${counts.get(impact)} ${impact}`);
+    return [...known, ...other].join(", ");
+}
+/**
+ * The axe-core bundle as source text, read once and cached.
+ *
+ * The minified build is preferred purely for injection size; the readable one
+ * is an equivalent fallback for installations that ship only it.
+ */
+let cachedSource = null;
+export function axeSource() {
+    if (cachedSource !== null)
+        return cachedSource;
+    const require = createRequire(import.meta.url);
+    const candidates = ["axe-core/axe.min.js", "axe-core/axe.js", "axe-core"];
+    const problems = [];
+    for (const candidate of candidates) {
+        try {
+            cachedSource = readFileSync(require.resolve(candidate), "utf8");
+            return cachedSource;
+        }
+        catch (error) {
+            problems.push(`${candidate}: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}`);
+        }
+    }
+    throw new Error(problems.join("; "));
+}
+/** Reject with `message` if `work` has not settled within `ms`. */
+async function withTimeout(work, ms, message) {
+    let timer;
+    const expire = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(message)), ms);
+    });
+    try {
+        return await Promise.race([work, expire]);
+    }
+    finally {
+        clearTimeout(timer);
+        // The losing side has to be settled too: the audit outlives a timeout and
+        // would otherwise reject unobserved once the context is torn down.
+        void work.catch(() => { });
+    }
+}
+function errorResult(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+/**
+ * One actionable line for a failed audit. Mirrors `describeFailure` in
+ * screenshot.ts: match on the failing Playwright call, never on substrings of
+ * a user-supplied selector.
+ */
+export function describeAuditFailure(input, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const firstLine = message.split("\n")[0];
+    const prefix = `Accessibility 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. (${firstLine})`);
+    }
+    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 — ${firstLine}`;
+    }
+    return `${prefix} ${firstLine}`;
+}
+export function registerAccessibilityTool(server) {
+    server.registerTool(ACCESSIBILITY_TOOL_NAME, {
+        title: "Accessibility",
+        description: "Run an axe-core accessibility audit on a page and report the violations: impact level, the rule that " +
+            "failed, the elements at fault and a link to how to fix each one. Choose the conformance level with " +
+            "`standard` (wcag2a, wcag2aa, wcag21aa). Rules that passed are counted rather than listed, and the " +
+            "'needs review' count tells you what axe could not decide on its own.",
+        inputSchema: accessibilityInputShape,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (args) => auditAccessibility(args));
+}
+/** Exported for tests: the axe tag list each standard maps to. */
+export const A11Y_STANDARD_TAGS = STANDARDS;
+//# sourceMappingURL=accessibility.js.map