framewatch-mcp-server 0.1.0 → 0.2.0

package/dist/tools/save-auth.d.ts

@@ -0,0 +1,263 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare const SAVE_AUTH_TOOL_NAME = "framewatch_save_auth";
+/** One step of the login flow. Same shape as a capture script, with a settle time that suits a form. */
+export declare const saveAuthInteractionSchema: z.ZodEffects<z.ZodObject<{
+    delay_ms: z.ZodDefault<z.ZodNumber>;
+    selector: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodString>;
+    x: z.ZodOptional<z.ZodNumber>;
+    y: z.ZodOptional<z.ZodNumber>;
+    delta_x: z.ZodOptional<z.ZodNumber>;
+    delta_y: z.ZodOptional<z.ZodNumber>;
+    action: z.ZodEnum<["click", "tap", "type", "key", "scroll", "swipe", "hover", "select", "wait", "navigate"]>;
+}, "strip", z.ZodTypeAny, {
+    delay_ms: number;
+    action: "type" | "key" | "click" | "tap" | "scroll" | "swipe" | "hover" | "select" | "wait" | "navigate";
+    value?: string | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+    selector?: string | undefined;
+    delta_x?: number | undefined;
+    delta_y?: number | undefined;
+}, {
+    action: "type" | "key" | "click" | "tap" | "scroll" | "swipe" | "hover" | "select" | "wait" | "navigate";
+    value?: string | undefined;
+    delay_ms?: number | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+    selector?: string | undefined;
+    delta_x?: number | undefined;
+    delta_y?: number | undefined;
+}>, {
+    delay_ms: number;
+    action: "type" | "key" | "click" | "tap" | "scroll" | "swipe" | "hover" | "select" | "wait" | "navigate";
+    value?: string | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+    selector?: string | undefined;
+    delta_x?: number | undefined;
+    delta_y?: number | undefined;
+}, {
+    action: "type" | "key" | "click" | "tap" | "scroll" | "swipe" | "hover" | "select" | "wait" | "navigate";
+    value?: string | undefined;
+    delay_ms?: number | undefined;
+    x?: number | undefined;
+    y?: number | undefined;
+    selector?: string | undefined;
+    delta_x?: number | undefined;
+    delta_y?: number | undefined;
+}>;
+export declare const saveAuthInputShape: {
+    url: z.ZodString;
+    interactions: z.ZodArray<z.ZodEffects<z.ZodObject<{
+        delay_ms: z.ZodDefault<z.ZodNumber>;
+        selector: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        x: z.ZodOptional<z.ZodNumber>;
+        y: z.ZodOptional<z.ZodNumber>;
+        delta_x: z.ZodOptional<z.ZodNumber>;
+        delta_y: z.ZodOptional<z.ZodNumber>;
+        action: z.ZodEnum<["click", "tap", "type", "key", "scroll", "swipe", "hover", "select", "wait", "navigate"]>;
+    }, "strip", z.ZodTypeAny, {
+        delay_ms: number;
+        action: "type" | "key" | "click" | "tap" | "scroll" | "swipe" | "hover" | "select" | "wait" | "navigate";
+        value?: string | undefined;
+        x?: number | undefined;
+        y?: number | undefined;
+        selector?: string | undefined;
+        delta_x?: number | undefined;
+        delta_y?: number | undefined;
+    }, {
+        action: "type" | "key" | "click" | "tap" | "scroll" | "swipe" | "hover" | "select" | "wait" | "navigate";
+        value?: string | undefined;
+        delay_ms?: number | undefined;
+        x?: number | undefined;
+        y?: number | undefined;
+        selector?: string | undefined;
+        delta_x?: number | undefined;
+        delta_y?: number | undefined;
+    }>, {
+        delay_ms: number;
+        action: "type" | "key" | "click" | "tap" | "scroll" | "swipe" | "hover" | "select" | "wait" | "navigate";
+        value?: string | undefined;
+        x?: number | undefined;
+        y?: number | undefined;
+        selector?: string | undefined;
+        delta_x?: number | undefined;
+        delta_y?: number | undefined;
+    }, {
+        action: "type" | "key" | "click" | "tap" | "scroll" | "swipe" | "hover" | "select" | "wait" | "navigate";
+        value?: string | undefined;
+        delay_ms?: number | undefined;
+        x?: number | undefined;
+        y?: number | undefined;
+        selector?: string | undefined;
+        delta_x?: number | undefined;
+        delta_y?: number | undefined;
+    }>, "many">;
+    output_path: z.ZodDefault<z.ZodString>;
+    wait_for: z.ZodOptional<z.ZodString>;
+    wait_for_timeout_ms: z.ZodDefault<z.ZodNumber>;
+    timeout_ms: z.ZodDefault<z.ZodNumber>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodDefault<z.ZodNumber>;
+        height: z.ZodDefault<z.ZodNumber>;
+        is_mobile: z.ZodDefault<z.ZodBoolean>;
+        has_touch: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        width: number;
+        height: number;
+        is_mobile: boolean;
+        has_touch?: boolean | undefined;
+    }, {
+        width?: number | undefined;
+        height?: number | undefined;
+        is_mobile?: boolean | undefined;
+        has_touch?: boolean | undefined;
+    }>>;
+};
+export declare const saveAuthInputSchema: z.ZodObject<{
+    url: z.ZodString;
+    interactions: z.ZodArray<z.ZodEffects<z.ZodObject<{
+        delay_ms: z.ZodDefault<z.ZodNumber>;
+        selector: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        x: z.ZodOptional<z.ZodNumber>;
+        y: z.ZodOptional<z.ZodNumber>;
+        delta_x: z.ZodOptional<z.ZodNumber>;
+        delta_y: z.ZodOptional<z.ZodNumber>;
+        action: z.ZodEnum<["click", "tap", "type", "key", "scroll", "swipe", "hover", "select", "wait", "navigate"]>;
+    }, "strip", z.ZodTypeAny, {
+        delay_ms: number;
+        action: "type" | "key" | "click" | "tap" | "scroll" | "swipe" | "hover" | "select" | "wait" | "navigate";
+        value?: string | undefined;
+        x?: number | undefined;
+        y?: number | undefined;
+        selector?: string | undefined;
+        delta_x?: number | undefined;
+        delta_y?: number | undefined;
+    }, {
+        action: "type" | "key" | "click" | "tap" | "scroll" | "swipe" | "hover" | "select" | "wait" | "navigate";
+        value?: string | undefined;
+        delay_ms?: number | undefined;
+        x?: number | undefined;
+        y?: number | undefined;
+        selector?: string | undefined;
+        delta_x?: number | undefined;
+        delta_y?: number | undefined;
+    }>, {
+        delay_ms: number;
+        action: "type" | "key" | "click" | "tap" | "scroll" | "swipe" | "hover" | "select" | "wait" | "navigate";
+        value?: string | undefined;
+        x?: number | undefined;
+        y?: number | undefined;
+        selector?: string | undefined;
+        delta_x?: number | undefined;
+        delta_y?: number | undefined;
+    }, {
+        action: "type" | "key" | "click" | "tap" | "scroll" | "swipe" | "hover" | "select" | "wait" | "navigate";
+        value?: string | undefined;
+        delay_ms?: number | undefined;
+        x?: number | undefined;
+        y?: number | undefined;
+        selector?: string | undefined;
+        delta_x?: number | undefined;
+        delta_y?: number | undefined;
+    }>, "many">;
+    output_path: z.ZodDefault<z.ZodString>;
+    wait_for: z.ZodOptional<z.ZodString>;
+    wait_for_timeout_ms: z.ZodDefault<z.ZodNumber>;
+    timeout_ms: z.ZodDefault<z.ZodNumber>;
+    viewport: z.ZodOptional<z.ZodObject<{
+        width: z.ZodDefault<z.ZodNumber>;
+        height: z.ZodDefault<z.ZodNumber>;
+        is_mobile: z.ZodDefault<z.ZodBoolean>;
+        has_touch: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        width: number;
+        height: number;
+        is_mobile: boolean;
+        has_touch?: boolean | undefined;
+    }, {
+        width?: number | undefined;
+        height?: number | undefined;
+        is_mobile?: boolean | undefined;
+        has_touch?: boolean | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    wait_for_timeout_ms: number;
+    timeout_ms: number;
+    interactions: {
+        delay_ms: number;
+        action: "type" | "key" | "click" | "tap" | "scroll" | "swipe" | "hover" | "select" | "wait" | "navigate";
+        value?: string | undefined;
+        x?: number | undefined;
+        y?: number | undefined;
+        selector?: string | undefined;
+        delta_x?: number | undefined;
+        delta_y?: number | undefined;
+    }[];
+    output_path: string;
+    viewport?: {
+        width: number;
+        height: number;
+        is_mobile: boolean;
+        has_touch?: boolean | undefined;
+    } | undefined;
+    wait_for?: string | undefined;
+}, {
+    url: string;
+    interactions: {
+        action: "type" | "key" | "click" | "tap" | "scroll" | "swipe" | "hover" | "select" | "wait" | "navigate";
+        value?: string | undefined;
+        delay_ms?: number | undefined;
+        x?: number | undefined;
+        y?: number | undefined;
+        selector?: string | undefined;
+        delta_x?: number | undefined;
+        delta_y?: number | undefined;
+    }[];
+    viewport?: {
+        width?: number | undefined;
+        height?: number | undefined;
+        is_mobile?: boolean | undefined;
+        has_touch?: boolean | undefined;
+    } | undefined;
+    wait_for?: string | undefined;
+    wait_for_timeout_ms?: number | undefined;
+    timeout_ms?: number | undefined;
+    output_path?: string | undefined;
+}>;
+export type SaveAuthInput = z.input<typeof saveAuthInputSchema>;
+/**
+ * Run a login flow once and save what it produced, so no other tool has to
+ * replay it.
+ *
+ * The saved file is Playwright's storage state — cookies plus per-origin
+ * localStorage — which every other FrameWatch tool takes as `storage_state`.
+ * Two rules make it trustworthy:
+ *
+ *   - Nothing is written unless the flow finished, including `wait_for`. A
+ *     state file that is not signed in is worse than no file at all: every
+ *     later call would load it and quietly get the login screen back.
+ *   - The final frame is always returned, success or failure. When a flow
+ *     breaks, the picture of where it stopped is the thing that explains why.
+ *
+ * There is no auto-refresh. When a saved session expires the login screen
+ * simply appears in the next capture, which is the clearest possible signal to
+ * run this tool again.
+ */
+export declare function saveAuth(rawInput: SaveAuthInput): Promise<CallToolResult>;
+/**
+ * One actionable line for a failure that happened outside the flow itself
+ * (launching the browser, opening the URL, writing the file). Mirrors
+ * `describeFailure` in screenshot.ts.
+ */
+export declare function describeSaveAuthFailure(input: {
+    url: string;
+    output_path: string;
+}, error: unknown): string;
+export declare function registerSaveAuthTool(server: McpServer): void;

package/dist/tools/save-auth.js

@@ -0,0 +1,253 @@
+import { z } from "zod";
+import { DEFAULT_AUTH_STATE_PATH, DEFAULT_VIEWPORT, MAX_INTERACTIONS, MAX_VIEWPORT_HEIGHT, MAX_VIEWPORT_WIDTH, NAVIGATION_TIMEOUT_MS, SAVE_AUTH_STEP_DELAY_MS, SAVE_AUTH_WAIT_FOR_TIMEOUT_MS, SELECTOR_TIMEOUT_MS, } from "../constants.js";
+import { withPage } from "../engine/browser.js";
+import { CAPTURE_ACTIONS, describeInteraction, executeInteraction, interactionFieldShape, needsTouch, refineInteraction, } from "../engine/interaction.js";
+import { resizeForOutput, toBase64 } from "../utils/image.js";
+import { storageStateSummary, writeStorageState } from "../utils/storage-state.js";
+export const SAVE_AUTH_TOOL_NAME = "framewatch_save_auth";
+/** One step of the login flow. Same shape as a capture script, with a settle time that suits a form. */
+export const saveAuthInteractionSchema = z
+    .object({
+    action: z
+        .enum(CAPTURE_ACTIONS)
+        .describe("What to do: click, tap, type, key, scroll, swipe, hover, select, wait or navigate"),
+    ...interactionFieldShape,
+    delay_ms: z
+        .number()
+        .int()
+        .min(0)
+        .default(SAVE_AUTH_STEP_DELAY_MS)
+        .describe("Wait this long (ms) before performing this step, so the previous one can settle"),
+})
+    .superRefine(refineInteraction);
+export const saveAuthInputShape = {
+    url: z
+        .string()
+        .url()
+        .describe("Where the flow starts — the login page or the gate, e.g. http://localhost:3000"),
+    interactions: z
+        .array(saveAuthInteractionSchema)
+        .max(MAX_INTERACTIONS)
+        .describe("The login/setup steps to run, in order. Use `key` with `Enter` (or a `\\n` at the end of a typed " +
+        "value) to submit a form."),
+    output_path: z
+        .string()
+        .min(1)
+        .default(DEFAULT_AUTH_STATE_PATH)
+        .describe("Where to write the state file. Relative paths are resolved against the server's working directory."),
+    wait_for: z
+        .string()
+        .optional()
+        .describe("CSS selector that proves the flow worked, e.g. '.feed' or '.dashboard'. Strongly recommended: without " +
+        "it a flow that silently failed still saves a signed-out state."),
+    wait_for_timeout_ms: z
+        .number()
+        .int()
+        .min(1)
+        .default(SAVE_AUTH_WAIT_FOR_TIMEOUT_MS)
+        .describe("Max time (ms) to wait for `wait_for` after the last step (must be > 0)"),
+    timeout_ms: z
+        .number()
+        .int()
+        .min(1)
+        .default(SELECTOR_TIMEOUT_MS)
+        .describe("Max time (ms) one step may spend waiting for its target element"),
+    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),
+        is_mobile: z
+            .boolean()
+            .default(false)
+            .describe("Emulate a phone (mobile viewport meta handling). Set it if the app serves a separate mobile UI."),
+        has_touch: z
+            .boolean()
+            .optional()
+            .describe("Give the page touch events. Defaults to on when the flow taps or swipes, or when `is_mobile` is set."),
+    })
+        .optional()
+        .describe("Viewport for the flow (defaults to 1280x720). A phone-shaped app wants 390x844 with `is_mobile`."),
+};
+export const saveAuthInputSchema = z.object(saveAuthInputShape);
+/**
+ * Run a login flow once and save what it produced, so no other tool has to
+ * replay it.
+ *
+ * The saved file is Playwright's storage state — cookies plus per-origin
+ * localStorage — which every other FrameWatch tool takes as `storage_state`.
+ * Two rules make it trustworthy:
+ *
+ *   - Nothing is written unless the flow finished, including `wait_for`. A
+ *     state file that is not signed in is worse than no file at all: every
+ *     later call would load it and quietly get the login screen back.
+ *   - The final frame is always returned, success or failure. When a flow
+ *     breaks, the picture of where it stopped is the thing that explains why.
+ *
+ * There is no auto-refresh. When a saved session expires the login screen
+ * simply appears in the next capture, which is the clearest possible signal to
+ * run this tool again.
+ */
+export async function saveAuth(rawInput) {
+    const parsed = saveAuthInputSchema.safeParse(rawInput);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "input"}: ${i.message}`).join("; ");
+        return errorResult(`Saving auth state failed: invalid input — ${issues}`);
+    }
+    const input = parsed.data;
+    const viewport = {
+        width: input.viewport?.width ?? DEFAULT_VIEWPORT.width,
+        height: input.viewport?.height ?? DEFAULT_VIEWPORT.height,
+    };
+    // Touch follows the script, as it does in framewatch_capture: `hasTouch`
+    // changes what feature detection sees, so it is not turned on for a flow
+    // that never touches anything.
+    const hasTouch = input.viewport?.has_touch ?? (input.viewport?.is_mobile === true || needsTouch(input.interactions));
+    const contextOptions = {
+        ...(hasTouch ? { hasTouch: true } : {}),
+        ...(input.viewport?.is_mobile ? { isMobile: true } : {}),
+    };
+    try {
+        const outcome = await withPage({ viewport, contextOptions }, async (page, context) => {
+            const completed = [];
+            await page.goto(input.url, { waitUntil: "load", timeout: NAVIGATION_TIMEOUT_MS });
+            for (const step of input.interactions) {
+                try {
+                    await executeInteraction(page, step, { timeout_ms: input.timeout_ms });
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    return { failure: message, completed, png: await safeScreenshot(page), finalUrl: safely(() => page.url()) };
+                }
+                completed.push(describeInteraction(step));
+            }
+            if (input.wait_for) {
+                try {
+                    await page.waitForSelector(input.wait_for, { state: "visible", timeout: input.wait_for_timeout_ms });
+                }
+                catch {
+                    return {
+                        failure: `the flow ran, but "${input.wait_for}" never became visible within ${input.wait_for_timeout_ms}ms, ` +
+                            "so it did not sign in",
+                        completed,
+                        png: await safeScreenshot(page),
+                        finalUrl: safely(() => page.url()),
+                    };
+                }
+            }
+            return {
+                state: await context.storageState(),
+                completed,
+                png: await safeScreenshot(page),
+                finalUrl: safely(() => page.url()),
+            };
+        });
+        return outcome.state
+            ? await succeed(input, outcome, outcome.state)
+            : fail(`Saving auth state failed: ${outcome.failure}`, outcome);
+    }
+    catch (error) {
+        return errorResult(describeSaveAuthFailure(input, error));
+    }
+}
+/** Write the state and describe what is in it — and what to do with it next. */
+async function succeed(input, outcome, state) {
+    await writeStorageState(state, input.output_path);
+    const lines = [`Saved auth state to ${input.output_path} — ${storageStateSummary(state)}.`];
+    if (outcome.completed.length > 0) {
+        lines.push(`Ran ${outcome.completed.length} step${outcome.completed.length === 1 ? "" : "s"}: ${outcome.completed.join("; ")}`);
+    }
+    if (outcome.finalUrl)
+        lines.push(`Ended on ${outcome.finalUrl}`);
+    if (state.cookies.length === 0 && state.origins.every((origin) => origin.localStorage.length === 0)) {
+        lines.push("Nothing was stored, so this file will not keep you signed in. Check that the flow really completed " +
+            "(add `wait_for`), and note that sessions kept only in sessionStorage or in memory cannot be saved.");
+    }
+    else {
+        lines.push(`Pass storage_state: "${input.output_path}" to framewatch_screenshot, framewatch_capture, ` +
+            "framewatch_interact, framewatch_responsive, framewatch_accessibility or framewatch_compare to start " +
+            "past this flow. The file holds live session credentials — keep it out of version control.");
+    }
+    return { content: await withFrame(outcome.png, lines.join("\n")) };
+}
+/** The failure, plus the frame it happened on. */
+function fail(message, outcome) {
+    const lines = [message];
+    if (outcome.completed.length > 0)
+        lines.push(`Completed before it stopped: ${outcome.completed.join("; ")}`);
+    if (outcome.finalUrl)
+        lines.push(`Page at that moment: ${outcome.finalUrl}`);
+    lines.push("Nothing was written — a state file that is not signed in would make every later call fail silently.");
+    const content = [{ type: "text", text: lines.join("\n") }];
+    return { isError: true, content: pushFrame(content, outcome.png) };
+}
+async function withFrame(png, text) {
+    const content = [];
+    if (png) {
+        content.push({ type: "image", data: toBase64(await resizeForOutput(png)), mimeType: "image/png" });
+    }
+    content.push({ type: "text", text });
+    return content;
+}
+/** The failure frame is attached raw-ish: it is evidence, and resizing it can itself fail. */
+function pushFrame(content, png) {
+    if (png)
+        content.push({ type: "image", data: png.toString("base64"), mimeType: "image/png" });
+    return content;
+}
+/** A screenshot is always worth having and never worth failing over. */
+async function safeScreenshot(page) {
+    try {
+        if (page.isClosed())
+            return undefined;
+        return await page.screenshot({ type: "png" });
+    }
+    catch {
+        return undefined;
+    }
+}
+function safely(read) {
+    try {
+        return read();
+    }
+    catch {
+        return undefined;
+    }
+}
+function errorResult(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+/**
+ * One actionable line for a failure that happened outside the flow itself
+ * (launching the browser, opening the URL, writing the file). Mirrors
+ * `describeFailure` in screenshot.ts.
+ */
+export function describeSaveAuthFailure(input, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const firstLine = message.split("\n")[0];
+    const prefix = "Saving auth state 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 (/^page\.goto:/.test(message)) {
+        return `${prefix} could not open ${input.url} — ${firstLine}`;
+    }
+    if (/EACCES|EPERM|ENOTDIR|EISDIR/.test(message)) {
+        return `${prefix} could not write ${input.output_path} — ${firstLine}`;
+    }
+    return `${prefix} ${firstLine}`;
+}
+export function registerSaveAuthTool(server) {
+    server.registerTool(SAVE_AUTH_TOOL_NAME, {
+        title: "Save auth",
+        description: "Run a login or gate flow once and save the browser state it produces (cookies and localStorage) to a " +
+            "file. Every other FrameWatch tool takes that file as `storage_state` and opens the page already signed " +
+            "in, so an app behind a login can be tested without replaying the flow on every call. Give `wait_for` a " +
+            "selector that only exists once signed in: nothing is written unless it appears, so a state file always " +
+            "means a real session. When a saved session expires the login screen shows up in the next capture — run " +
+            "this again then.",
+        inputSchema: saveAuthInputShape,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (args) => saveAuth(args));
+}
+//# sourceMappingURL=save-auth.js.map

package/dist/tools/save-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"save-auth.js","sourceRoot":"","sources":["../../src/tools/save-auth.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\nimport type { BrowserContextOptions, Page } from \"playwright\";\nimport type { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport type { CallToolResult } from \"@modelcontextprotocol/sdk/types.js\";\nimport {\n  DEFAULT_AUTH_STATE_PATH,\n  DEFAULT_VIEWPORT,\n  MAX_INTERACTIONS,\n  MAX_VIEWPORT_HEIGHT,\n  MAX_VIEWPORT_WIDTH,\n  NAVIGATION_TIMEOUT_MS,\n  SAVE_AUTH_STEP_DELAY_MS,\n  SAVE_AUTH_WAIT_FOR_TIMEOUT_MS,\n  SELECTOR_TIMEOUT_MS,\n} from \"../constants.js\";\nimport { withPage } from \"../engine/browser.js\";\nimport {\n  CAPTURE_ACTIONS,\n  describeInteraction,\n  executeInteraction,\n  interactionFieldShape,\n  needsTouch,\n  refineInteraction,\n} from \"../engine/interaction.js\";\nimport { resizeForOutput, toBase64 } from \"../utils/image.js\";\nimport { storageStateSummary, writeStorageState, type StorageState } from \"../utils/storage-state.js\";\n\nexport const SAVE_AUTH_TOOL_NAME = \"framewatch_save_auth\";\n\n/** One step of the login flow. Same shape as a capture script, with a settle time that suits a form. */\nexport const saveAuthInteractionSchema = z\n  .object({\n    action: z\n      .enum(CAPTURE_ACTIONS)\n      .describe(\"What to do: click, tap, type, key, scroll, swipe, hover, select, wait or navigate\"),\n    ...interactionFieldShape,\n    delay_ms: z\n      .number()\n      .int()\n      .min(0)\n      .default(SAVE_AUTH_STEP_DELAY_MS)\n      .describe(\"Wait this long (ms) before performing this step, so the previous one can settle\"),\n  })\n  .superRefine(refineInteraction);\n\nexport const saveAuthInputShape = {\n  url: z\n    .string()\n    .url()\n    .describe(\"Where the flow starts — the login page or the gate, e.g. http://localhost:3000\"),\n  interactions: z\n    .array(saveAuthInteractionSchema)\n    .max(MAX_INTERACTIONS)\n    .describe(\n      \"The login/setup steps to run, in order. Use `key` with `Enter` (or a `\\\\n` at the end of a typed \" +\n        \"value) to submit a form.\",\n    ),\n  output_path: z\n    .string()\n    .min(1)\n    .default(DEFAULT_AUTH_STATE_PATH)\n    .describe(\"Where to write the state file. Relative paths are resolved against the server's working directory.\"),\n  wait_for: z\n    .string()\n    .optional()\n    .describe(\n      \"CSS selector that proves the flow worked, e.g. '.feed' or '.dashboard'. Strongly recommended: without \" +\n        \"it a flow that silently failed still saves a signed-out state.\",\n    ),\n  wait_for_timeout_ms: z\n    .number()\n    .int()\n    .min(1)\n    .default(SAVE_AUTH_WAIT_FOR_TIMEOUT_MS)\n    .describe(\"Max time (ms) to wait for `wait_for` after the last step (must be > 0)\"),\n  timeout_ms: z\n    .number()\n    .int()\n    .min(1)\n    .default(SELECTOR_TIMEOUT_MS)\n    .describe(\"Max time (ms) one step may spend waiting for its target element\"),\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      is_mobile: z\n        .boolean()\n        .default(false)\n        .describe(\"Emulate a phone (mobile viewport meta handling). Set it if the app serves a separate mobile UI.\"),\n      has_touch: z\n        .boolean()\n        .optional()\n        .describe(\"Give the page touch events. Defaults to on when the flow taps or swipes, or when `is_mobile` is set.\"),\n    })\n    .optional()\n    .describe(\"Viewport for the flow (defaults to 1280x720). A phone-shaped app wants 390x844 with `is_mobile`.\"),\n};\n\nexport const saveAuthInputSchema = z.object(saveAuthInputShape);\nexport type SaveAuthInput = z.input<typeof saveAuthInputSchema>;\n\n/** What the browser side of the run produced: either a state, or the step that stopped it. */\ninterface Outcome {\n  png?: Buffer;\n  finalUrl?: string;\n  state?: StorageState;\n  failure?: string;\n  completed: string[];\n}\n\n/**\n * Run a login flow once and save what it produced, so no other tool has to\n * replay it.\n *\n * The saved file is Playwright's storage state — cookies plus per-origin\n * localStorage — which every other FrameWatch tool takes as `storage_state`.\n * Two rules make it trustworthy:\n *\n *   - Nothing is written unless the flow finished, including `wait_for`. A\n *     state file that is not signed in is worse than no file at all: every\n *     later call would load it and quietly get the login screen back.\n *   - The final frame is always returned, success or failure. When a flow\n *     breaks, the picture of where it stopped is the thing that explains why.\n *\n * There is no auto-refresh. When a saved session expires the login screen\n * simply appears in the next capture, which is the clearest possible signal to\n * run this tool again.\n */\nexport async function saveAuth(rawInput: SaveAuthInput): Promise<CallToolResult> {\n  const parsed = saveAuthInputSchema.safeParse(rawInput);\n  if (!parsed.success) {\n    const issues = parsed.error.issues.map((i) => `${i.path.join(\".\") || \"input\"}: ${i.message}`).join(\"; \");\n    return errorResult(`Saving auth state failed: invalid input — ${issues}`);\n  }\n  const input = parsed.data;\n\n  const viewport = {\n    width: input.viewport?.width ?? DEFAULT_VIEWPORT.width,\n    height: input.viewport?.height ?? DEFAULT_VIEWPORT.height,\n  };\n  // Touch follows the script, as it does in framewatch_capture: `hasTouch`\n  // changes what feature detection sees, so it is not turned on for a flow\n  // that never touches anything.\n  const hasTouch = input.viewport?.has_touch ?? (input.viewport?.is_mobile === true || needsTouch(input.interactions));\n  const contextOptions: BrowserContextOptions = {\n    ...(hasTouch ? { hasTouch: true } : {}),\n    ...(input.viewport?.is_mobile ? { isMobile: true } : {}),\n  };\n\n  try {\n    const outcome = await withPage({ viewport, contextOptions }, async (page, context): Promise<Outcome> => {\n      const completed: string[] = [];\n      await page.goto(input.url, { waitUntil: \"load\", timeout: NAVIGATION_TIMEOUT_MS });\n\n      for (const step of input.interactions) {\n        try {\n          await executeInteraction(page, step, { timeout_ms: input.timeout_ms });\n        } catch (error) {\n          const message = error instanceof Error ? error.message : String(error);\n          return { failure: message, completed, png: await safeScreenshot(page), finalUrl: safely(() => page.url()) };\n        }\n        completed.push(describeInteraction(step));\n      }\n\n      if (input.wait_for) {\n        try {\n          await page.waitForSelector(input.wait_for, { state: \"visible\", timeout: input.wait_for_timeout_ms });\n        } catch {\n          return {\n            failure:\n              `the flow ran, but \"${input.wait_for}\" never became visible within ${input.wait_for_timeout_ms}ms, ` +\n              \"so it did not sign in\",\n            completed,\n            png: await safeScreenshot(page),\n            finalUrl: safely(() => page.url()),\n          };\n        }\n      }\n\n      return {\n        state: await context.storageState(),\n        completed,\n        png: await safeScreenshot(page),\n        finalUrl: safely(() => page.url()),\n      };\n    });\n\n    return outcome.state\n      ? await succeed(input, outcome, outcome.state)\n      : fail(`Saving auth state failed: ${outcome.failure}`, outcome);\n  } catch (error) {\n    return errorResult(describeSaveAuthFailure(input, error));\n  }\n}\n\n/** Write the state and describe what is in it — and what to do with it next. */\nasync function succeed(\n  input: z.output<typeof saveAuthInputSchema>,\n  outcome: Outcome,\n  state: StorageState,\n): Promise<CallToolResult> {\n  await writeStorageState(state, input.output_path);\n\n  const lines = [`Saved auth state to ${input.output_path} — ${storageStateSummary(state)}.`];\n  if (outcome.completed.length > 0) {\n    lines.push(`Ran ${outcome.completed.length} step${outcome.completed.length === 1 ? \"\" : \"s\"}: ${outcome.completed.join(\"; \")}`);\n  }\n  if (outcome.finalUrl) lines.push(`Ended on ${outcome.finalUrl}`);\n\n  if (state.cookies.length === 0 && state.origins.every((origin) => origin.localStorage.length === 0)) {\n    lines.push(\n      \"Nothing was stored, so this file will not keep you signed in. Check that the flow really completed \" +\n        \"(add `wait_for`), and note that sessions kept only in sessionStorage or in memory cannot be saved.\",\n    );\n  } else {\n    lines.push(\n      `Pass storage_state: \"${input.output_path}\" to framewatch_screenshot, framewatch_capture, ` +\n        \"framewatch_interact, framewatch_responsive, framewatch_accessibility or framewatch_compare to start \" +\n        \"past this flow. The file holds live session credentials — keep it out of version control.\",\n    );\n  }\n\n  return { content: await withFrame(outcome.png, lines.join(\"\\n\")) };\n}\n\n/** The failure, plus the frame it happened on. */\nfunction fail(message: string, outcome: Outcome): CallToolResult {\n  const lines = [message];\n  if (outcome.completed.length > 0) lines.push(`Completed before it stopped: ${outcome.completed.join(\"; \")}`);\n  if (outcome.finalUrl) lines.push(`Page at that moment: ${outcome.finalUrl}`);\n  lines.push(\"Nothing was written — a state file that is not signed in would make every later call fail silently.\");\n\n  const content: CallToolResult[\"content\"] = [{ type: \"text\", text: lines.join(\"\\n\") }];\n  return { isError: true, content: pushFrame(content, outcome.png) };\n}\n\nasync function withFrame(png: Buffer | undefined, text: string): Promise<CallToolResult[\"content\"]> {\n  const content: CallToolResult[\"content\"] = [];\n  if (png) {\n    content.push({ type: \"image\", data: toBase64(await resizeForOutput(png)), mimeType: \"image/png\" });\n  }\n  content.push({ type: \"text\", text });\n  return content;\n}\n\n/** The failure frame is attached raw-ish: it is evidence, and resizing it can itself fail. */\nfunction pushFrame(content: CallToolResult[\"content\"], png: Buffer | undefined): CallToolResult[\"content\"] {\n  if (png) content.push({ type: \"image\", data: png.toString(\"base64\"), mimeType: \"image/png\" });\n  return content;\n}\n\n/** A screenshot is always worth having and never worth failing over. */\nasync function safeScreenshot(page: Page): Promise<Buffer | undefined> {\n  try {\n    if (page.isClosed()) return undefined;\n    return await page.screenshot({ type: \"png\" });\n  } catch {\n    return undefined;\n  }\n}\n\nfunction safely<T>(read: () => T): T | undefined {\n  try {\n    return read();\n  } catch {\n    return undefined;\n  }\n}\n\nfunction errorResult(text: string): CallToolResult {\n  return { isError: true, content: [{ type: \"text\", text }] };\n}\n\n/**\n * One actionable line for a failure that happened outside the flow itself\n * (launching the browser, opening the URL, writing the file). Mirrors\n * `describeFailure` in screenshot.ts.\n */\nexport function describeSaveAuthFailure(input: { url: string; output_path: string }, error: unknown): string {\n  const message = error instanceof Error ? error.message : String(error);\n  const firstLine = message.split(\"\\n\")[0];\n  const prefix = \"Saving auth state 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 (/^page\\.goto:/.test(message)) {\n    return `${prefix} could not open ${input.url} — ${firstLine}`;\n  }\n  if (/EACCES|EPERM|ENOTDIR|EISDIR/.test(message)) {\n    return `${prefix} could not write ${input.output_path} — ${firstLine}`;\n  }\n  return `${prefix} ${firstLine}`;\n}\n\nexport function registerSaveAuthTool(server: McpServer): void {\n  server.registerTool(\n    SAVE_AUTH_TOOL_NAME,\n    {\n      title: \"Save auth\",\n      description:\n        \"Run a login or gate flow once and save the browser state it produces (cookies and localStorage) to a \" +\n        \"file. Every other FrameWatch tool takes that file as `storage_state` and opens the page already signed \" +\n        \"in, so an app behind a login can be tested without replaying the flow on every call. Give `wait_for` a \" +\n        \"selector that only exists once signed in: nothing is written unless it appears, so a state file always \" +\n        \"means a real session. When a saved session expires the login screen shows up in the next capture — run \" +\n        \"this again then.\",\n      inputSchema: saveAuthInputShape,\n      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },\n    },\n    async (args) => saveAuth(args),\n  );\n}\n"]}

package/dist/tools/screenshot.d.ts

@@ -18,6 +18,7 @@ export declare const screenshotInputShape: {
     selector: z.ZodOptional<z.ZodString>;
     wait_for: z.ZodOptional<z.ZodString>;
     wait_for_timeout_ms: z.ZodDefault<z.ZodNumber>;
+    storage_state: z.ZodOptional<z.ZodString>;
 };
 export declare const screenshotInputSchema: z.ZodObject<{
     url: z.ZodString;
@@ -35,6 +36,7 @@ export declare const screenshotInputSchema: z.ZodObject<{
     selector: z.ZodOptional<z.ZodString>;
     wait_for: z.ZodOptional<z.ZodString>;
     wait_for_timeout_ms: z.ZodDefault<z.ZodNumber>;
+    storage_state: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     url: string;
     wait_ms: number;
@@ -44,6 +46,7 @@ export declare const screenshotInputSchema: z.ZodObject<{
         height: number;
     } | undefined;
     wait_for?: string | undefined;
+    storage_state?: string | undefined;
     selector?: string | undefined;
 }, {
     url: string;
@@ -54,6 +57,7 @@ export declare const screenshotInputSchema: z.ZodObject<{
     wait_ms?: number | undefined;
     wait_for?: string | undefined;
     wait_for_timeout_ms?: number | undefined;
+    storage_state?: string | undefined;
     selector?: string | undefined;
 }>;
 export type ScreenshotInput = z.input<typeof screenshotInputSchema>;

package/dist/tools/screenshot.js

@@ -2,6 +2,7 @@ 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";
+import { loginFormVisible, resolveStorageState, storageStateField, withAuthNote } from "../utils/storage-state.js";
 export const SCREENSHOT_TOOL_NAME = "framewatch_screenshot";
 export const screenshotInputShape = {
     url: z
@@ -29,6 +30,7 @@ export const screenshotInputShape = {
         .min(1)
         .default(SELECTOR_TIMEOUT_MS)
         .describe("Max time (ms) to wait for `wait_for` / `selector` to appear (must be > 0)"),
+    storage_state: storageStateField,
 };
 export const screenshotInputSchema = z.object(screenshotInputShape);
 /**
@@ -46,7 +48,9 @@ export async function takeScreenshot(rawInput) {
     const input = parsed.data;
     const viewport = input.viewport ?? { ...DEFAULT_VIEWPORT };
     try {
-        const shot = await withPage({ viewport }, async (page) => {
+        const auth = await resolveStorageState(input.storage_state);
+        const contextOptions = auth ? { storageState: auth.state } : {};
+        const shot = await withPage({ viewport, contextOptions }, 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 });
@@ -57,7 +61,14 @@ export async function takeScreenshot(rawInput) {
             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 };
+            return {
+                png,
+                title: await page.title(),
+                finalUrl: page.url(),
+                status: response?.status() ?? null,
+                // A login form on the page after restoring a session is the expiry signal.
+                loginVisible: auth ? await loginFormVisible(page) : false,
+            };
         });
         const resized = await resizeForOutput(shot.png);
         const { width, height } = await getDimensions(resized);
@@ -69,12 +80,12 @@ export async function takeScreenshot(rawInput) {
             `viewport ${viewport.width}x${viewport.height}`,
             input.selector ? `element ${input.selector}` : null,
         ].filter((p) => p !== null);
-        return {
+        return withAuthNote({
             content: [
                 { type: "image", data: toBase64(resized), mimeType: "image/png" },
                 { type: "text", text: summaryParts.join(" — ") },
             ],
-        };
+        }, auth, shot.loginVisible);
     }
     catch (error) {
         return errorResult(describeFailure(input, error));