framewatch-mcp-server 0.1.0

package/dist/tools/screenshot.js

@@ -0,0 +1,117 @@
+import { z } from "zod";
+import { DEFAULT_SCREENSHOT_WAIT_MS, DEFAULT_VIEWPORT, NAVIGATION_TIMEOUT_MS, SELECTOR_TIMEOUT_MS } from "../constants.js";
+import { withPage } from "../engine/browser.js";
+import { getDimensions, resizeForOutput, toBase64 } from "../utils/image.js";
+export const SCREENSHOT_TOOL_NAME = "framewatch_screenshot";
+export const screenshotInputShape = {
+    url: z
+        .string()
+        .url()
+        .describe("URL to screenshot, e.g. http://localhost:3000 (http, https and file URLs are accepted)"),
+    wait_ms: z
+        .number()
+        .int()
+        .min(0)
+        .default(DEFAULT_SCREENSHOT_WAIT_MS)
+        .describe("Wait time (ms) after page load before screenshot"),
+    viewport: z
+        .object({
+        width: z.number().int().min(1).default(DEFAULT_VIEWPORT.width),
+        height: z.number().int().min(1).default(DEFAULT_VIEWPORT.height),
+    })
+        .optional()
+        .describe("Viewport size (defaults to 1280x720)"),
+    selector: z.string().optional().describe("CSS selector to screenshot a specific element instead of the viewport"),
+    wait_for: z.string().optional().describe("CSS selector to wait for (visible) before taking the screenshot"),
+    wait_for_timeout_ms: z
+        .number()
+        .int()
+        .min(1)
+        .default(SELECTOR_TIMEOUT_MS)
+        .describe("Max time (ms) to wait for `wait_for` / `selector` to appear (must be > 0)"),
+};
+export const screenshotInputSchema = z.object(screenshotInputShape);
+/**
+ * Take a single screenshot of a page and return it as an MCP image content
+ * block (base64 PNG, resized to max OUTPUT_MAX_WIDTH wide) plus a one-line
+ * text summary. All failures — including invalid input — are reported as
+ * `isError` results rather than thrown so the MCP client sees a useful message.
+ */
+export async function takeScreenshot(rawInput) {
+    const parsed = screenshotInputSchema.safeParse(rawInput);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "input"}: ${i.message}`).join("; ");
+        return errorResult(`Screenshot failed: invalid input — ${issues}`);
+    }
+    const input = parsed.data;
+    const viewport = input.viewport ?? { ...DEFAULT_VIEWPORT };
+    try {
+        const shot = await withPage({ viewport }, async (page) => {
+            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 png = input.selector
+                ? await page.locator(input.selector).first().screenshot({ type: "png", timeout: input.wait_for_timeout_ms })
+                : await page.screenshot({ type: "png" });
+            return { png, title: await page.title(), finalUrl: page.url(), status: response?.status() ?? null };
+        });
+        const resized = await resizeForOutput(shot.png);
+        const { width, height } = await getDimensions(resized);
+        const summaryParts = [
+            `Screenshot of ${shot.finalUrl}`,
+            shot.status !== null && shot.status >= 400 ? `HTTP ${shot.status}` : null,
+            shot.title ? `"${shot.title}"` : null,
+            `${width}x${height}`,
+            `viewport ${viewport.width}x${viewport.height}`,
+            input.selector ? `element ${input.selector}` : null,
+        ].filter((p) => p !== null);
+        return {
+            content: [
+                { type: "image", data: toBase64(resized), mimeType: "image/png" },
+                { type: "text", text: summaryParts.join(" — ") },
+            ],
+        };
+    }
+    catch (error) {
+        return errorResult(describeFailure(input, error));
+    }
+}
+function errorResult(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+/**
+ * Turn a Playwright/Node error into a one-line, actionable message. Matches on
+ * the failing Playwright call (the message prefix) rather than on substrings
+ * of user-supplied selectors, so a navigation failure is never blamed on an
+ * element.
+ */
+export function describeFailure(input, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const firstLine = message.split("\n")[0];
+    const prefix = `Screenshot 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 (input.selector && /^locator\.screenshot:/.test(message)) {
+        return `${prefix} element "${input.selector}" not found or not visible within ${input.wait_for_timeout_ms}ms. ${firstLine}`;
+    }
+    return `${prefix} ${firstLine}`;
+}
+export function registerScreenshotTool(server) {
+    server.registerTool(SCREENSHOT_TOOL_NAME, {
+        title: "Screenshot",
+        description: "Take a single screenshot of a web page (or one element on it) and return it as a PNG image. " +
+            "Good for checking the current visual state of a running app.",
+        inputSchema: screenshotInputShape,
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (args) => takeScreenshot(args));
+}
+//# sourceMappingURL=screenshot.js.map

package/dist/tools/screenshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenshot.js","sourceRoot":"","sources":["../../src/tools/screenshot.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\nimport type { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport type { CallToolResult } from \"@modelcontextprotocol/sdk/types.js\";\nimport { DEFAULT_SCREENSHOT_WAIT_MS, DEFAULT_VIEWPORT, NAVIGATION_TIMEOUT_MS, SELECTOR_TIMEOUT_MS } from \"../constants.js\";\nimport { withPage } from \"../engine/browser.js\";\nimport { getDimensions, resizeForOutput, toBase64 } from \"../utils/image.js\";\n\nexport const SCREENSHOT_TOOL_NAME = \"framewatch_screenshot\";\n\nexport const screenshotInputShape = {\n  url: z\n    .string()\n    .url()\n    .describe(\"URL to screenshot, 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_SCREENSHOT_WAIT_MS)\n    .describe(\"Wait time (ms) after page load before screenshot\"),\n  viewport: z\n    .object({\n      width: z.number().int().min(1).default(DEFAULT_VIEWPORT.width),\n      height: z.number().int().min(1).default(DEFAULT_VIEWPORT.height),\n    })\n    .optional()\n    .describe(\"Viewport size (defaults to 1280x720)\"),\n  selector: z.string().optional().describe(\"CSS selector to screenshot a specific element instead of the viewport\"),\n  wait_for: z.string().optional().describe(\"CSS selector to wait for (visible) before taking the screenshot\"),\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` / `selector` to appear (must be > 0)\"),\n};\n\nexport const screenshotInputSchema = z.object(screenshotInputShape);\nexport type ScreenshotInput = z.input<typeof screenshotInputSchema>;\ntype ParsedScreenshotInput = z.output<typeof screenshotInputSchema>;\n\n/**\n * Take a single screenshot of a page and return it as an MCP image content\n * block (base64 PNG, resized to max OUTPUT_MAX_WIDTH wide) plus a one-line\n * text summary. All failures — including invalid input — are reported as\n * `isError` results rather than thrown so the MCP client sees a useful message.\n */\nexport async function takeScreenshot(rawInput: ScreenshotInput): Promise<CallToolResult> {\n  const parsed = screenshotInputSchema.safeParse(rawInput);\n  if (!parsed.success) {\n    const issues = parsed.error.issues.map((i) => `${i.path.join(\".\") || \"input\"}: ${i.message}`).join(\"; \");\n    return errorResult(`Screenshot failed: invalid input — ${issues}`);\n  }\n  const input = parsed.data;\n  const viewport = input.viewport ?? { ...DEFAULT_VIEWPORT };\n\n  try {\n    const shot = await withPage({ viewport }, async (page) => {\n      const response = await page.goto(input.url, { waitUntil: \"load\", timeout: NAVIGATION_TIMEOUT_MS });\n\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 png = input.selector\n        ? await page.locator(input.selector).first().screenshot({ type: \"png\", timeout: input.wait_for_timeout_ms })\n        : await page.screenshot({ type: \"png\" });\n\n      return { png, title: await page.title(), finalUrl: page.url(), status: response?.status() ?? null };\n    });\n\n    const resized = await resizeForOutput(shot.png);\n    const { width, height } = await getDimensions(resized);\n\n    const summaryParts = [\n      `Screenshot of ${shot.finalUrl}`,\n      shot.status !== null && shot.status >= 400 ? `HTTP ${shot.status}` : null,\n      shot.title ? `\"${shot.title}\"` : null,\n      `${width}x${height}`,\n      `viewport ${viewport.width}x${viewport.height}`,\n      input.selector ? `element ${input.selector}` : null,\n    ].filter((p): p is string => p !== null);\n\n    return {\n      content: [\n        { type: \"image\", data: toBase64(resized), mimeType: \"image/png\" },\n        { type: \"text\", text: summaryParts.join(\" — \") },\n      ],\n    };\n  } catch (error) {\n    return errorResult(describeFailure(input, error));\n  }\n}\n\nfunction errorResult(text: string): CallToolResult {\n  return { isError: true, content: [{ type: \"text\", text }] };\n}\n\n/**\n * Turn a Playwright/Node error into a one-line, actionable message. Matches on\n * the failing Playwright call (the message prefix) rather than on substrings\n * of user-supplied selectors, so a navigation failure is never blamed on an\n * element.\n */\nexport function describeFailure(\n  input: Pick<ParsedScreenshotInput, \"url\" | \"wait_for\" | \"selector\" | \"wait_for_timeout_ms\">,\n  error: unknown,\n): string {\n  const message = error instanceof Error ? error.message : String(error);\n  const firstLine = message.split(\"\\n\")[0];\n  const prefix = `Screenshot 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. (${firstLine})`\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 (input.selector && /^locator\\.screenshot:/.test(message)) {\n    return `${prefix} element \"${input.selector}\" not found or not visible within ${input.wait_for_timeout_ms}ms. ${firstLine}`;\n  }\n  return `${prefix} ${firstLine}`;\n}\n\nexport function registerScreenshotTool(server: McpServer): void {\n  server.registerTool(\n    SCREENSHOT_TOOL_NAME,\n    {\n      title: \"Screenshot\",\n      description:\n        \"Take a single screenshot of a web page (or one element on it) and return it as a PNG image. \" +\n        \"Good for checking the current visual state of a running app.\",\n      inputSchema: screenshotInputShape,\n      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },\n    },\n    async (args) => takeScreenshot(args),\n  );\n}\n"]}

package/dist/tools/server.d.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare const START_SERVER_TOOL_NAME = "framewatch_start_server";
+export declare const STOP_SERVER_TOOL_NAME = "framewatch_stop_server";
+export declare const startServerInputShape: {
+    command: z.ZodString;
+    port: z.ZodNumber;
+    ready_pattern: z.ZodDefault<z.ZodString>;
+    cwd: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    timeout_ms: z.ZodDefault<z.ZodNumber>;
+};
+export declare const startServerInputSchema: z.ZodObject<{
+    command: z.ZodString;
+    port: z.ZodNumber;
+    ready_pattern: z.ZodDefault<z.ZodString>;
+    cwd: z.ZodOptional<z.ZodString>;
+    env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    timeout_ms: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    timeout_ms: number;
+    command: string;
+    port: number;
+    ready_pattern: string;
+    cwd?: string | undefined;
+    env?: Record<string, string> | undefined;
+}, {
+    command: string;
+    port: number;
+    timeout_ms?: number | undefined;
+    cwd?: string | undefined;
+    ready_pattern?: string | undefined;
+    env?: Record<string, string> | undefined;
+}>;
+export type StartServerInput = z.input<typeof startServerInputSchema>;
+/** Structured result of `framewatch_start_server`. */
+export declare const startServerOutputShape: {
+    status: z.ZodLiteral<"running">;
+    port: z.ZodNumber;
+    pid: z.ZodNumber;
+    url: z.ZodString;
+    command: z.ZodString;
+    cwd: z.ZodString;
+    ready_ms: z.ZodNumber;
+    ready_line: z.ZodOptional<z.ZodString>;
+};
+/** Structured result of `framewatch_stop_server`. */
+export declare const stopServerOutputShape: {
+    status: z.ZodEnum<["stopped", "not_running"]>;
+    port: z.ZodOptional<z.ZodNumber>;
+    pid: z.ZodOptional<z.ZodNumber>;
+    command: z.ZodOptional<z.ZodString>;
+    uptime_ms: z.ZodOptional<z.ZodNumber>;
+    exit_code: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    exit_signal: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    /** True when the server ignored SIGTERM and had to be killed. */
+    forced: z.ZodOptional<z.ZodBoolean>;
+};
+/**
+ * Start the app's dev server so the rest of FrameWatch has something to look
+ * at.
+ *
+ * One server runs at a time. Asking for the one that is already running is a
+ * no-op that reports its status (the tool is idempotent); asking for a
+ * different one while it is up is an error naming what to stop first, because
+ * silently replacing a running server is not something a tool should decide.
+ */
+export declare function startServer(rawInput: StartServerInput): Promise<CallToolResult>;
+/**
+ * Stop the dev server FrameWatch started.
+ *
+ * Never an error: there being nothing to stop is a normal answer, and a caller
+ * cleaning up after itself should not have to know whether the earlier start
+ * succeeded.
+ */
+export declare function stopServer(): Promise<CallToolResult>;
+/**
+ * Explain a failed start, with the server's own output underneath.
+ *
+ * That output is the whole point: "exit code 1" says nothing, while the three
+ * lines above it are usually a missing script, a syntax error or a port
+ * clash — the actual answer.
+ */
+export declare function describeStartFailure(input: {
+    command: string;
+    port: number;
+}, error: unknown): string;
+export declare function registerServerTools(server: McpServer): void;

package/dist/tools/server.js

@@ -0,0 +1,201 @@
+import { z } from "zod";
+import { DEFAULT_READY_PATTERN, DEFAULT_SERVER_TIMEOUT_MS, MAX_SERVER_TIMEOUT_MS, MIN_SERVER_TIMEOUT_MS, SERVER_OUTPUT_TAIL, } from "../constants.js";
+import { DevServerError, devServerOutput, getDevServer, startDevServer, stopDevServer, } from "../utils/server-process.js";
+export const START_SERVER_TOOL_NAME = "framewatch_start_server";
+export const STOP_SERVER_TOOL_NAME = "framewatch_stop_server";
+export const startServerInputShape = {
+    command: z.string().min(1).describe("Shell command to start the server, e.g. 'npm run dev'"),
+    port: z.number().int().min(1).max(65535).describe("Port the server will listen on"),
+    ready_pattern: z
+        .string()
+        .default(DEFAULT_READY_PATTERN)
+        .describe("Regex matched against the server's output. The matching line is reported back (dev servers print the URL " +
+        "they actually bound to), but readiness itself is decided by the port answering."),
+    cwd: z.string().optional().describe("Working directory to run the command in (defaults to the current one)"),
+    env: z.record(z.string()).optional().describe("Extra environment variables for the server process"),
+    timeout_ms: z
+        .number()
+        .int()
+        .min(MIN_SERVER_TIMEOUT_MS)
+        .max(MAX_SERVER_TIMEOUT_MS)
+        .default(DEFAULT_SERVER_TIMEOUT_MS)
+        .describe("Max time (ms) to wait for the port to start answering"),
+};
+export const startServerInputSchema = z.object(startServerInputShape);
+/** Structured result of `framewatch_start_server`. */
+export const startServerOutputShape = {
+    status: z.literal("running"),
+    port: z.number().int(),
+    pid: z.number().int(),
+    url: z.string(),
+    command: z.string(),
+    cwd: z.string(),
+    ready_ms: z.number().int(),
+    ready_line: z.string().optional(),
+};
+/** Structured result of `framewatch_stop_server`. */
+export const stopServerOutputShape = {
+    status: z.enum(["stopped", "not_running"]),
+    port: z.number().int().optional(),
+    pid: z.number().int().optional(),
+    command: z.string().optional(),
+    uptime_ms: z.number().int().optional(),
+    exit_code: z.number().int().nullable().optional(),
+    exit_signal: z.string().nullable().optional(),
+    /** True when the server ignored SIGTERM and had to be killed. */
+    forced: z.boolean().optional(),
+};
+/**
+ * Start the app's dev server so the rest of FrameWatch has something to look
+ * at.
+ *
+ * One server runs at a time. Asking for the one that is already running is a
+ * no-op that reports its status (the tool is idempotent); asking for a
+ * different one while it is up is an error naming what to stop first, because
+ * silently replacing a running server is not something a tool should decide.
+ */
+export async function startServer(rawInput) {
+    const parsed = startServerInputSchema.safeParse(rawInput);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "input"}: ${i.message}`).join("; ");
+        return errorResult(`Start server failed: invalid input — ${issues}`);
+    }
+    const input = parsed.data;
+    const running = getDevServer();
+    if (running && running.command === input.command && running.port === input.port) {
+        return runningResult(running, `Dev server is already running — ${describeRunning(running)}`);
+    }
+    try {
+        const started = await startDevServer({
+            command: input.command,
+            port: input.port,
+            ready_pattern: input.ready_pattern,
+            timeout_ms: input.timeout_ms,
+            ...(input.cwd !== undefined ? { cwd: input.cwd } : {}),
+            ...(input.env !== undefined ? { env: input.env } : {}),
+        });
+        return runningResult(started, `Dev server running — ${describeRunning(started)}`);
+    }
+    catch (error) {
+        return errorResult(describeStartFailure(input, error));
+    }
+}
+/**
+ * Stop the dev server FrameWatch started.
+ *
+ * Never an error: there being nothing to stop is a normal answer, and a caller
+ * cleaning up after itself should not have to know whether the earlier start
+ * succeeded.
+ */
+export async function stopServer() {
+    let stopped;
+    try {
+        stopped = await stopDevServer();
+    }
+    catch (error) {
+        return errorResult(`Stop server failed: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}`);
+    }
+    if (!stopped) {
+        return {
+            content: [{ type: "text", text: "No dev server is running (FrameWatch did not start one, or it has already been stopped)." }],
+            structuredContent: { status: "not_running" },
+        };
+    }
+    const how = stopped.forced
+        ? "killed (it did not exit on SIGTERM)"
+        : stopped.exit_signal
+            ? `stopped by ${stopped.exit_signal}`
+            : `stopped with exit code ${stopped.exit_code ?? "unknown"}`;
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Dev server ${how} — pid ${stopped.pid}, port ${stopped.port}, up for ${seconds(stopped.uptime_ms)}s: ${stopped.command}`,
+            },
+        ],
+        structuredContent: {
+            status: "stopped",
+            port: stopped.port,
+            pid: stopped.pid,
+            command: stopped.command,
+            uptime_ms: stopped.uptime_ms,
+            exit_code: stopped.exit_code,
+            exit_signal: stopped.exit_signal,
+            forced: stopped.forced,
+        },
+    };
+}
+function runningResult(server, text) {
+    return {
+        content: [{ type: "text", text }],
+        structuredContent: {
+            status: "running",
+            port: server.port,
+            pid: server.pid,
+            url: server.url,
+            command: server.command,
+            cwd: server.cwd,
+            ready_ms: server.ready_ms,
+            ...(server.ready_line !== undefined ? { ready_line: server.ready_line } : {}),
+        },
+    };
+}
+function describeRunning(server) {
+    const parts = [
+        `pid ${server.pid}`,
+        `port ${server.port}`,
+        server.url,
+        `ready in ${seconds(server.ready_ms)}s`,
+        `command: ${server.command}`,
+    ];
+    const text = parts.join(", ");
+    return server.ready_line !== undefined ? `${text}\nIt said: ${server.ready_line}` : text;
+}
+function seconds(ms) {
+    return (ms / 1000).toFixed(1);
+}
+function errorResult(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+/**
+ * Explain a failed start, with the server's own output underneath.
+ *
+ * That output is the whole point: "exit code 1" says nothing, while the three
+ * lines above it are usually a missing script, a syntax error or a port
+ * clash — the actual answer.
+ */
+export function describeStartFailure(input, error) {
+    const message = error instanceof Error ? error.message.split("\n")[0] : String(error);
+    const lines = [`Start server failed: \`${input.command}\` on port ${input.port} — ${message}`];
+    const output = error instanceof DevServerError ? error.output : devServerOutput(SERVER_OUTPUT_TAIL);
+    const tail = output.slice(Math.max(0, output.length - SERVER_OUTPUT_TAIL));
+    if (tail.length > 0) {
+        lines.push("Last output from the server:");
+        for (const line of tail)
+            lines.push(`  ${line}`);
+    }
+    else if (error instanceof DevServerError) {
+        lines.push("The server produced no output.");
+    }
+    return lines.join("\n");
+}
+export function registerServerTools(server) {
+    server.registerTool(START_SERVER_TOOL_NAME, {
+        title: "Start dev server",
+        description: "Start the app's dev server (e.g. `npm run dev`) and wait until its port answers, so the other FrameWatch " +
+            "tools have something to point at. One server runs at a time and FrameWatch stops it when it shuts down. " +
+            "If the command fails or the port never opens, the server's own output comes back with the error.",
+        inputSchema: startServerInputShape,
+        outputSchema: startServerOutputShape,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (args) => startServer(args));
+    server.registerTool(STOP_SERVER_TOOL_NAME, {
+        title: "Stop dev server",
+        description: "Stop the dev server FrameWatch started, along with everything it spawned. Reports `not_running` rather " +
+            "than failing when there is nothing to stop.",
+        inputSchema: {},
+        outputSchema: stopServerOutputShape,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async () => stopServer());
+}
+//# sourceMappingURL=server.js.map

package/dist/tools/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/tools/server.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\nimport type { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport type { CallToolResult } from \"@modelcontextprotocol/sdk/types.js\";\nimport {\n  DEFAULT_READY_PATTERN,\n  DEFAULT_SERVER_TIMEOUT_MS,\n  MAX_SERVER_TIMEOUT_MS,\n  MIN_SERVER_TIMEOUT_MS,\n  SERVER_OUTPUT_TAIL,\n} from \"../constants.js\";\nimport {\n  DevServerError,\n  devServerOutput,\n  getDevServer,\n  startDevServer,\n  stopDevServer,\n  type RunningServer,\n  type StoppedServer,\n} from \"../utils/server-process.js\";\n\nexport const START_SERVER_TOOL_NAME = \"framewatch_start_server\";\nexport const STOP_SERVER_TOOL_NAME = \"framewatch_stop_server\";\n\nexport const startServerInputShape = {\n  command: z.string().min(1).describe(\"Shell command to start the server, e.g. 'npm run dev'\"),\n  port: z.number().int().min(1).max(65535).describe(\"Port the server will listen on\"),\n  ready_pattern: z\n    .string()\n    .default(DEFAULT_READY_PATTERN)\n    .describe(\n      \"Regex matched against the server's output. The matching line is reported back (dev servers print the URL \" +\n        \"they actually bound to), but readiness itself is decided by the port answering.\",\n    ),\n  cwd: z.string().optional().describe(\"Working directory to run the command in (defaults to the current one)\"),\n  env: z.record(z.string()).optional().describe(\"Extra environment variables for the server process\"),\n  timeout_ms: z\n    .number()\n    .int()\n    .min(MIN_SERVER_TIMEOUT_MS)\n    .max(MAX_SERVER_TIMEOUT_MS)\n    .default(DEFAULT_SERVER_TIMEOUT_MS)\n    .describe(\"Max time (ms) to wait for the port to start answering\"),\n};\n\nexport const startServerInputSchema = z.object(startServerInputShape);\nexport type StartServerInput = z.input<typeof startServerInputSchema>;\n\n/** Structured result of `framewatch_start_server`. */\nexport const startServerOutputShape = {\n  status: z.literal(\"running\"),\n  port: z.number().int(),\n  pid: z.number().int(),\n  url: z.string(),\n  command: z.string(),\n  cwd: z.string(),\n  ready_ms: z.number().int(),\n  ready_line: z.string().optional(),\n};\n\n/** Structured result of `framewatch_stop_server`. */\nexport const stopServerOutputShape = {\n  status: z.enum([\"stopped\", \"not_running\"]),\n  port: z.number().int().optional(),\n  pid: z.number().int().optional(),\n  command: z.string().optional(),\n  uptime_ms: z.number().int().optional(),\n  exit_code: z.number().int().nullable().optional(),\n  exit_signal: z.string().nullable().optional(),\n  /** True when the server ignored SIGTERM and had to be killed. */\n  forced: z.boolean().optional(),\n};\n\n/**\n * Start the app's dev server so the rest of FrameWatch has something to look\n * at.\n *\n * One server runs at a time. Asking for the one that is already running is a\n * no-op that reports its status (the tool is idempotent); asking for a\n * different one while it is up is an error naming what to stop first, because\n * silently replacing a running server is not something a tool should decide.\n */\nexport async function startServer(rawInput: StartServerInput): Promise<CallToolResult> {\n  const parsed = startServerInputSchema.safeParse(rawInput);\n  if (!parsed.success) {\n    const issues = parsed.error.issues.map((i) => `${i.path.join(\".\") || \"input\"}: ${i.message}`).join(\"; \");\n    return errorResult(`Start server failed: invalid input — ${issues}`);\n  }\n  const input = parsed.data;\n\n  const running = getDevServer();\n  if (running && running.command === input.command && running.port === input.port) {\n    return runningResult(running, `Dev server is already running — ${describeRunning(running)}`);\n  }\n\n  try {\n    const started = await startDevServer({\n      command: input.command,\n      port: input.port,\n      ready_pattern: input.ready_pattern,\n      timeout_ms: input.timeout_ms,\n      ...(input.cwd !== undefined ? { cwd: input.cwd } : {}),\n      ...(input.env !== undefined ? { env: input.env } : {}),\n    });\n    return runningResult(started, `Dev server running — ${describeRunning(started)}`);\n  } catch (error) {\n    return errorResult(describeStartFailure(input, error));\n  }\n}\n\n/**\n * Stop the dev server FrameWatch started.\n *\n * Never an error: there being nothing to stop is a normal answer, and a caller\n * cleaning up after itself should not have to know whether the earlier start\n * succeeded.\n */\nexport async function stopServer(): Promise<CallToolResult> {\n  let stopped: StoppedServer | null;\n  try {\n    stopped = await stopDevServer();\n  } catch (error) {\n    return errorResult(`Stop server failed: ${error instanceof Error ? error.message.split(\"\\n\")[0] : String(error)}`);\n  }\n\n  if (!stopped) {\n    return {\n      content: [{ type: \"text\", text: \"No dev server is running (FrameWatch did not start one, or it has already been stopped).\" }],\n      structuredContent: { status: \"not_running\" },\n    };\n  }\n\n  const how = stopped.forced\n    ? \"killed (it did not exit on SIGTERM)\"\n    : stopped.exit_signal\n      ? `stopped by ${stopped.exit_signal}`\n      : `stopped with exit code ${stopped.exit_code ?? \"unknown\"}`;\n\n  return {\n    content: [\n      {\n        type: \"text\",\n        text: `Dev server ${how} — pid ${stopped.pid}, port ${stopped.port}, up for ${seconds(stopped.uptime_ms)}s: ${stopped.command}`,\n      },\n    ],\n    structuredContent: {\n      status: \"stopped\",\n      port: stopped.port,\n      pid: stopped.pid,\n      command: stopped.command,\n      uptime_ms: stopped.uptime_ms,\n      exit_code: stopped.exit_code,\n      exit_signal: stopped.exit_signal,\n      forced: stopped.forced,\n    },\n  };\n}\n\nfunction runningResult(server: RunningServer, text: string): CallToolResult {\n  return {\n    content: [{ type: \"text\", text }],\n    structuredContent: {\n      status: \"running\",\n      port: server.port,\n      pid: server.pid,\n      url: server.url,\n      command: server.command,\n      cwd: server.cwd,\n      ready_ms: server.ready_ms,\n      ...(server.ready_line !== undefined ? { ready_line: server.ready_line } : {}),\n    },\n  };\n}\n\nfunction describeRunning(server: RunningServer): string {\n  const parts = [\n    `pid ${server.pid}`,\n    `port ${server.port}`,\n    server.url,\n    `ready in ${seconds(server.ready_ms)}s`,\n    `command: ${server.command}`,\n  ];\n  const text = parts.join(\", \");\n  return server.ready_line !== undefined ? `${text}\\nIt said: ${server.ready_line}` : text;\n}\n\nfunction seconds(ms: number): string {\n  return (ms / 1000).toFixed(1);\n}\n\nfunction errorResult(text: string): CallToolResult {\n  return { isError: true, content: [{ type: \"text\", text }] };\n}\n\n/**\n * Explain a failed start, with the server's own output underneath.\n *\n * That output is the whole point: \"exit code 1\" says nothing, while the three\n * lines above it are usually a missing script, a syntax error or a port\n * clash — the actual answer.\n */\nexport function describeStartFailure(input: { command: string; port: number }, error: unknown): string {\n  const message = error instanceof Error ? error.message.split(\"\\n\")[0] : String(error);\n  const lines = [`Start server failed: \\`${input.command}\\` on port ${input.port} — ${message}`];\n\n  const output = error instanceof DevServerError ? error.output : devServerOutput(SERVER_OUTPUT_TAIL);\n  const tail = output.slice(Math.max(0, output.length - SERVER_OUTPUT_TAIL));\n  if (tail.length > 0) {\n    lines.push(\"Last output from the server:\");\n    for (const line of tail) lines.push(`  ${line}`);\n  } else if (error instanceof DevServerError) {\n    lines.push(\"The server produced no output.\");\n  }\n\n  return lines.join(\"\\n\");\n}\n\nexport function registerServerTools(server: McpServer): void {\n  server.registerTool(\n    START_SERVER_TOOL_NAME,\n    {\n      title: \"Start dev server\",\n      description:\n        \"Start the app's dev server (e.g. `npm run dev`) and wait until its port answers, so the other FrameWatch \" +\n        \"tools have something to point at. One server runs at a time and FrameWatch stops it when it shuts down. \" +\n        \"If the command fails or the port never opens, the server's own output comes back with the error.\",\n      inputSchema: startServerInputShape,\n      outputSchema: startServerOutputShape,\n      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },\n    },\n    async (args) => startServer(args),\n  );\n\n  server.registerTool(\n    STOP_SERVER_TOOL_NAME,\n    {\n      title: \"Stop dev server\",\n      description:\n        \"Stop the dev server FrameWatch started, along with everything it spawned. Reports `not_running` rather \" +\n        \"than failing when there is nothing to stop.\",\n      inputSchema: {},\n      outputSchema: stopServerOutputShape,\n      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },\n    },\n    async () => stopServer(),\n  );\n}\n"]}

package/dist/types.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Shared TypeScript interfaces for FrameWatch.
+ *
+ * Phase 1 only needs a handful of these, but the full DiffCard shape is
+ * declared up front so later phases (recorder, differ, context layers) share
+ * one vocabulary.
+ */
+export type FrameTrigger = "initial" | "animation" | "navigation" | "interaction" | "network" | "dom_change" | "error";
+export interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface ConsoleEntry {
+    level: "log" | "warn" | "error" | "info";
+    text: string;
+    timestamp_ms: number;
+}
+export interface NetworkEvent {
+    method: string;
+    url: string;
+    /** HTTP status, or 0 when the request never got a response (see `error`). */
+    status: number;
+    duration_ms: number;
+    /** Relative to recording start, at the moment the request settled. */
+    timestamp_ms: number;
+    /**
+     * Why the request never completed — Chromium's error text
+     * (e.g. "net::ERR_CONNECTION_REFUSED"), or "pending" for a request still in
+     * flight when the recording ended. Absent for requests that got a response.
+     */
+    error?: string;
+}
+export interface PerformanceInfo {
+    /** First Contentful Paint, ms since this document's navigation start. */
+    paint_time_ms?: number;
+    /** Layout shifts observed since the previous card. */
+    layout_shifts?: number;
+    /**
+     * Summed `value` of those shifts. This is the total for the window, not
+     * Chrome's CLS metric (which is the largest shift *session* over the whole
+     * page life), so it is comparable between cards but not with a Lighthouse score.
+     */
+    layout_shift_score?: number;
+    /** Largest Contentful Paint, ms since this document's navigation start. */
+    lcp_ms?: number;
+}
+export interface ChangeRegion {
+    /**
+     * Base64 PNG cropped to the bounding box of the change. Omitted when the
+     * padded bounding box already covers nearly the whole frame (the full frame
+     * image shows the same thing).
+     */
+    crop?: string;
+    bbox: BoundingBox;
+    /** Percentage (0–100) of total pixels that changed. */
+    change_percent: number;
+}
+export interface DiffCard {
+    index: number;
+    timestamp_ms: number;
+    trigger: FrameTrigger;
+    /** Base64 PNG — full frame, resized to max OUTPUT_MAX_WIDTH wide. */
+    full_frame: string;
+    change_region?: ChangeRegion;
+    dom_snapshot?: string;
+    console_entries?: ConsoleEntry[];
+    network_events?: NetworkEvent[];
+    performance?: PerformanceInfo;
+    component_state?: object;
+}
+/** One raw screenshot taken by the frame recorder. */
+export interface RawFrame {
+    /** Encoded PNG of the full viewport. */
+    buffer: Buffer;
+    /** Milliseconds since recording start. */
+    timestamp_ms: number;
+    /** True for frames captured immediately after a replayed interaction. */
+    is_interaction: boolean;
+    /**
+     * Set on frames the recorder captured because of an event (navigation,
+     * interaction, error). These frames are always kept by the differ.
+     * Undefined for ordinary interval frames, which the differ classifies as
+     * "initial" (first frame) or "animation".
+     */
+    trigger?: FrameTrigger;
+}
+/** Result of the low-res grid comparison between two frames. */
+export interface GridDiffResult {
+    changedCells: number;
+    totalCells: number;
+    /** changedCells / totalCells, 0..1 */
+    changeRatio: number;
+    /** Union of changed cells, in the coordinates of the compared buffers. null when nothing changed. */
+    bbox: BoundingBox | null;
+}
+/** Result of a full-resolution per-pixel comparison between two frames. */
+export interface PixelDiffResult {
+    /** Pixels whose absolute grayscale difference exceeds PIXEL_THRESHOLD. */
+    changedPixels: number;
+    totalPixels: number;
+    /** 0..100 */
+    changePercent: number;
+    /** Tight bounding box of all changed pixels (no padding). null when nothing changed. */
+    bbox: BoundingBox | null;
+}
+/** A per-pixel change mask alongside the counts, for rendering a diff overlay. */
+export interface PixelMaskResult extends PixelDiffResult {
+    /** One byte per pixel, row-major: 1 where the pixel changed, 0 where it did not. */
+    mask: Uint8Array;
+}
+export interface Viewport {
+    width: number;
+    height: number;
+}
+export interface DevServerConfig {
+    command: string;
+    port: number;
+    ready_pattern: string;
+    cwd?: string;
+    env?: Record<string, string>;
+}

package/dist/types.js

@@ -0,0 +1,9 @@
+/**
+ * Shared TypeScript interfaces for FrameWatch.
+ *
+ * Phase 1 only needs a handful of these, but the full DiffCard shape is
+ * declared up front so later phases (recorder, differ, context layers) share
+ * one vocabulary.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG","sourcesContent":["/**\n * Shared TypeScript interfaces for FrameWatch.\n *\n * Phase 1 only needs a handful of these, but the full DiffCard shape is\n * declared up front so later phases (recorder, differ, context layers) share\n * one vocabulary.\n */\n\nexport type FrameTrigger =\n  | \"initial\"\n  | \"animation\"\n  | \"navigation\"\n  | \"interaction\"\n  | \"network\"\n  | \"dom_change\"\n  | \"error\";\n\nexport interface BoundingBox {\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n}\n\nexport interface ConsoleEntry {\n  level: \"log\" | \"warn\" | \"error\" | \"info\";\n  text: string;\n  timestamp_ms: number;\n}\n\nexport interface NetworkEvent {\n  method: string;\n  url: string;\n  /** HTTP status, or 0 when the request never got a response (see `error`). */\n  status: number;\n  duration_ms: number;\n  /** Relative to recording start, at the moment the request settled. */\n  timestamp_ms: number;\n  /**\n   * Why the request never completed — Chromium's error text\n   * (e.g. \"net::ERR_CONNECTION_REFUSED\"), or \"pending\" for a request still in\n   * flight when the recording ended. Absent for requests that got a response.\n   */\n  error?: string;\n}\n\nexport interface PerformanceInfo {\n  /** First Contentful Paint, ms since this document's navigation start. */\n  paint_time_ms?: number;\n  /** Layout shifts observed since the previous card. */\n  layout_shifts?: number;\n  /**\n   * Summed `value` of those shifts. This is the total for the window, not\n   * Chrome's CLS metric (which is the largest shift *session* over the whole\n   * page life), so it is comparable between cards but not with a Lighthouse score.\n   */\n  layout_shift_score?: number;\n  /** Largest Contentful Paint, ms since this document's navigation start. */\n  lcp_ms?: number;\n}\n\nexport interface ChangeRegion {\n  /**\n   * Base64 PNG cropped to the bounding box of the change. Omitted when the\n   * padded bounding box already covers nearly the whole frame (the full frame\n   * image shows the same thing).\n   */\n  crop?: string;\n  bbox: BoundingBox;\n  /** Percentage (0–100) of total pixels that changed. */\n  change_percent: number;\n}\n\nexport interface DiffCard {\n  index: number;\n  timestamp_ms: number;\n  trigger: FrameTrigger;\n  /** Base64 PNG — full frame, resized to max OUTPUT_MAX_WIDTH wide. */\n  full_frame: string;\n  change_region?: ChangeRegion;\n  dom_snapshot?: string;\n  console_entries?: ConsoleEntry[];\n  network_events?: NetworkEvent[];\n  performance?: PerformanceInfo;\n  component_state?: object;\n}\n\n/** One raw screenshot taken by the frame recorder. */\nexport interface RawFrame {\n  /** Encoded PNG of the full viewport. */\n  buffer: Buffer;\n  /** Milliseconds since recording start. */\n  timestamp_ms: number;\n  /** True for frames captured immediately after a replayed interaction. */\n  is_interaction: boolean;\n  /**\n   * Set on frames the recorder captured because of an event (navigation,\n   * interaction, error). These frames are always kept by the differ.\n   * Undefined for ordinary interval frames, which the differ classifies as\n   * \"initial\" (first frame) or \"animation\".\n   */\n  trigger?: FrameTrigger;\n}\n\n/** Result of the low-res grid comparison between two frames. */\nexport interface GridDiffResult {\n  changedCells: number;\n  totalCells: number;\n  /** changedCells / totalCells, 0..1 */\n  changeRatio: number;\n  /** Union of changed cells, in the coordinates of the compared buffers. null when nothing changed. */\n  bbox: BoundingBox | null;\n}\n\n/** Result of a full-resolution per-pixel comparison between two frames. */\nexport interface PixelDiffResult {\n  /** Pixels whose absolute grayscale difference exceeds PIXEL_THRESHOLD. */\n  changedPixels: number;\n  totalPixels: number;\n  /** 0..100 */\n  changePercent: number;\n  /** Tight bounding box of all changed pixels (no padding). null when nothing changed. */\n  bbox: BoundingBox | null;\n}\n\n/** A per-pixel change mask alongside the counts, for rendering a diff overlay. */\nexport interface PixelMaskResult extends PixelDiffResult {\n  /** One byte per pixel, row-major: 1 where the pixel changed, 0 where it did not. */\n  mask: Uint8Array;\n}\n\nexport interface Viewport {\n  width: number;\n  height: number;\n}\n\nexport interface DevServerConfig {\n  command: string;\n  port: number;\n  ready_pattern: string;\n  cwd?: string;\n  env?: Record<string, string>;\n}\n"]}

package/dist/utils/bounded-log.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A fixed-size log that gives priority to interesting entries.
+ *
+ * The context layers watch things a page can produce without limit — console
+ * output, network requests — so every collector needs a cap. A plain cap has
+ * the wrong failure mode: a page that logs in a render loop fills the budget
+ * with noise in the first second, and the console error thrown at second four
+ * (the one thing worth capturing) is dropped.
+ *
+ * So the log keeps `limit` entries, and once it is full an *important* entry
+ * still gets in by evicting the oldest unimportant one. Important entries are
+ * only ever dropped when the log holds nothing but important entries — at
+ * which point the page is genuinely producing more signal than the cap allows.
+ * `dropped` counts everything that did not make it, so the caller can say so.
+ */
+export declare class BoundedLog<T> {
+    #private;
+    /**
+     * @param limit Maximum entries kept. Values below 1 are treated as 1.
+     * @param isImportant Entries worth evicting an ordinary entry for. Defaults to "nothing is".
+     */
+    constructor(limit: number, isImportant?: (item: T) => boolean);
+    /** Entries kept, oldest first. */
+    get items(): readonly T[];
+    get size(): number;
+    /** How many entries were refused or evicted. */
+    get dropped(): number;
+    add(item: T): void;
+    /**
+     * Forget everything, including the dropped count.
+     *
+     * A capture builds a log and throws it away, but `framewatch_interact` keeps
+     * one page — and so one set of collectors — alive across many calls, and
+     * each call reports only what its own action caused. Without this, call
+     * twenty would repeat the console output of calls one to nineteen and then
+     * start dropping the entries that actually mattered.
+     */
+    clear(): void;
+    /** A plain copy of the entries (safe to hand out and mutate). */
+    toArray(): T[];
+}