playwright-e2e-mcp 0.1.0

package/dist/http.js

@@ -0,0 +1,156 @@
+/**
+ * Streamable HTTP bridge for the MCP server.
+ *
+ * `createMcpHandler` (MCP SDK) is fetch-shaped: it answers the 2025
+ * streamable-HTTP transport *statelessly* — a fresh server per request, which
+ * is exactly what a serverless function wants — and the modern envelope
+ * transport on the same URL. This module adds the thin adapter for runtimes
+ * that hand you Node's `IncomingMessage`/`ServerResponse` pair (Vercel
+ * functions, a plain `node:http` server), so the very same code path can be
+ * verified locally before it is deployed.
+ *
+ * The stdio transport in server.ts is untouched; this is an additional way to
+ * reach the same eight tools.
+ */
+import { createMcpHandler } from '@modelcontextprotocol/server';
+import { createServer } from './server.js';
+import { logger } from './utils/logger.js';
+/** Mirrors the SDK's default POST body bound, so oversized bodies die early. */
+export const MAX_BODY_BYTES = 4 * 1024 * 1024;
+/** Build the fetch-shaped MCP handler backed by a fresh server per request. */
+export function createMcpHttpHandler() {
+    return createMcpHandler(() => createServer(), {
+        legacy: 'stateless',
+        onerror: (error) => logger.error('mcp http handler error', { error }),
+    });
+}
+/** A failure that maps onto an HTTP status before any response is written. */
+class RequestError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+function firstHeader(value) {
+    if (Array.isArray(value))
+        return value[0];
+    return value;
+}
+function toHeaders(raw) {
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(raw)) {
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                headers.append(key, item);
+        }
+        else {
+            headers.set(key, value);
+        }
+    }
+    return headers;
+}
+async function readBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buf.byteLength;
+        if (size > MAX_BODY_BYTES) {
+            req.destroy();
+            throw new RequestError(413, 'request body too large');
+        }
+        chunks.push(buf);
+    }
+    return Buffer.concat(chunks, size);
+}
+function buildRequest(req, method, body) {
+    const protocol = (firstHeader(req.headers['x-forwarded-proto']) ?? 'http').split(',')[0].trim();
+    const host = firstHeader(req.headers.host) ?? 'localhost';
+    const init = { method, headers: toHeaders(req.headers) };
+    if (body && body.byteLength > 0)
+        init.body = body;
+    return new Request(`${protocol}://${host}${req.url ?? '/'}`, init);
+}
+/** Resolve when the socket drains or closes, so a dead client cannot hang us. */
+function waitDrain(res) {
+    return new Promise((resolve) => {
+        const done = () => {
+            res.off('drain', done);
+            res.off('close', done);
+            resolve();
+        };
+        res.once('drain', done);
+        res.once('close', done);
+    });
+}
+/**
+ * Serve one Node request through the MCP handler.
+ *
+ * Always settles: a transport failure becomes a JSON error response, and a
+ * mid-stream failure closes the socket so the client stops waiting.
+ */
+export async function handleNodeRequest(handler, req, res) {
+    let response;
+    try {
+        const method = (req.method ?? 'GET').toUpperCase();
+        const body = method === 'GET' || method === 'HEAD' ? undefined : await readBody(req);
+        response = await handler.fetch(buildRequest(req, method, body));
+    }
+    catch (err) {
+        const status = err instanceof RequestError ? err.status : 500;
+        if (status !== 413 && !(err instanceof RequestError)) {
+            logger.error('mcp http request failed', { error: err });
+        }
+        if (!res.headersSent && !res.writableEnded) {
+            res.statusCode = status;
+            res.setHeader('content-type', 'application/json');
+            res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+        }
+        else if (!res.writableEnded) {
+            res.destroy();
+        }
+        return;
+    }
+    res.statusCode = response.status;
+    response.headers.forEach((value, key) => {
+        // Let Node choose chunked framing for streamed bodies.
+        if (key.toLowerCase() === 'content-length' && response.body)
+            return;
+        res.setHeader(key, value);
+    });
+    const body = response.body;
+    if (!body) {
+        res.end();
+        return;
+    }
+    const reader = body.getReader();
+    try {
+        for (;;) {
+            if (res.destroyed || res.writableEnded) {
+                await reader.cancel().catch(() => undefined);
+                break;
+            }
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value && value.byteLength > 0 && !res.write(Buffer.from(value))) {
+                await waitDrain(res);
+            }
+        }
+    }
+    catch (err) {
+        logger.warn('mcp http response stream failed', { error: err });
+        if (!res.writableEnded)
+            res.destroy();
+        return;
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+    if (!res.writableEnded)
+        res.end();
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * playwright-e2e-mcp entry point.
+ *
+ * When executed (npx playwright-e2e-mcp / the `bin` shim) it connects
+ * the MCP server over stdio. When imported it only exposes the API, so
+ * tests and tooling can construct a server without side effects.
+ */
+import { logger } from './utils/logger.js';
+export { createServer, startServer, SERVER_NAME, SERVER_VERSION } from './server.js';
+export { createMcpHttpHandler, handleNodeRequest, MAX_BODY_BYTES } from './http.js';
+export { logger };

package/dist/index.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * playwright-e2e-mcp entry point.
+ *
+ * When executed (npx playwright-e2e-mcp / the `bin` shim) it connects
+ * the MCP server over stdio. When imported it only exposes the API, so
+ * tests and tooling can construct a server without side effects.
+ */
+import { realpathSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { logger, createLogger } from './utils/logger.js';
+import { SERVER_VERSION } from './server.js';
+function isMainModule() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return import.meta.url === pathToFileURL(realpathSync(entry)).href;
+    }
+    catch {
+        return false;
+    }
+}
+async function main() {
+    if (process.argv.includes('--version') || process.argv.includes('-v')) {
+        process.stdout.write(`${SERVER_VERSION}\n`);
+        return;
+    }
+    if (process.argv.includes('--help') || process.argv.includes('-h')) {
+        process.stdout.write([
+            'playwright-e2e-mcp — MCP server for running and debugging Playwright tests',
+            '',
+            'Usage: playwright-e2e-mcp [--version] [--help]',
+            '',
+            'Connects over stdio (MCP). Configuration via environment:',
+            '  PW_MCP_PROJECT_ROOT   default project root (default: cwd)',
+            '  LOG_LEVEL             debug | info | warn | error | silent (default: info)',
+            '  LOG_FORMAT            text | json (default: text)',
+            '',
+        ].join('\n'));
+        return;
+    }
+    const { startServer } = await import('./server.js');
+    await startServer();
+}
+if (isMainModule()) {
+    main().catch((err) => {
+        const log = createLogger({ bindings: { name: 'playwright-e2e-mcp' } });
+        log.error('server failed to start', { error: err });
+        process.exit(1);
+    });
+}
+export { createServer, startServer, SERVER_NAME, SERVER_VERSION } from './server.js';
+export { createMcpHttpHandler, handleNodeRequest, MAX_BODY_BYTES } from './http.js';
+export { logger };
+//# 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;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,SAAS,YAAY;IACnB,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,KAAK,UAAU,IAAI;IACjB,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACtE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,cAAc,IAAI,CAAC,CAAC;QAC5C,OAAO;IACT,CAAC;IACD,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACnE,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB;YACE,4EAA4E;YAC5E,EAAE;YACF,gDAAgD;YAChD,EAAE;YACF,2DAA2D;YAC3D,6DAA6D;YAC7D,8EAA8E;YAC9E,qDAAqD;YACrD,EAAE;SACH,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;QACF,OAAO;IACT,CAAC;IAED,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IACpD,MAAM,WAAW,EAAE,CAAC;AACtB,CAAC;AAED,IAAI,YAAY,EAAE,EAAE,CAAC;IACnB,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;QAC5B,MAAM,GAAG,GAAG,YAAY,CAAC,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,oBAAoB,EAAE,EAAE,CAAC,CAAC;QACvE,GAAG,CAAC,KAAK,CAAC,wBAAwB,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;QACpD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACpF,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,23 @@
+/**
+ * MCP server setup: creates the McpServer instance, registers the eight
+ * tools (with spec tool annotations), and wires each invocation to a ToolContext (per-tool logger,
+ * abort signal, shared store, default project root).
+ *
+ * Logs go to stderr only — stdout belongs to the MCP protocol.
+ */
+import { McpServer } from '@modelcontextprotocol/server';
+import type { ToolStore } from './types/index.js';
+export declare const SERVER_NAME = "playwright-e2e-mcp";
+export declare const SERVER_VERSION: string;
+export interface CreateServerOptions {
+    /** Default project root for tool calls (defaults to cwd / env var). */
+    projectRoot?: string;
+    /** Share a store across servers (tests). */
+    store?: ToolStore;
+}
+export declare function resolveDefaultProjectRoot(): string;
+export declare function createServer(options?: CreateServerOptions): McpServer;
+/** Close the server, kill orphaned children, and exit. */
+export declare function shutdown(server: McpServer, code: number, reason: string): Promise<void>;
+/** Connect the server over stdio and install shutdown handlers. */
+export declare function startServer(): Promise<void>;

package/dist/server.js

@@ -0,0 +1,225 @@
+/**
+ * MCP server setup: creates the McpServer instance, registers the eight
+ * tools (with spec tool annotations), and wires each invocation to a ToolContext (per-tool logger,
+ * abort signal, shared store, default project root).
+ *
+ * Logs go to stderr only — stdout belongs to the MCP protocol.
+ */
+import { createRequire } from 'node:module';
+import { statSync } from 'node:fs';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+import { McpServer } from '@modelcontextprotocol/server';
+import { toPlaywrightMcpError } from './types/index.js';
+import { logger } from './utils/logger.js';
+import { killActiveChildren } from './utils/playwright-runner.js';
+import { createToolStore, toolError } from './tools/shared.js';
+import { runTestTool } from './tools/run-test.js';
+import { getFailureTool } from './tools/get-failure.js';
+import { inspectPageTool } from './tools/inspect-page.js';
+import { listTestsTool } from './tools/list-tests.js';
+import { validateSelectorTool } from './tools/validate-selector.js';
+import { generateE2ETestTool } from './tools/generate-e2e-test.js';
+import { compareVisualStateTool } from './tools/compare-visual-state.js';
+import { diagnoseFlakyTool } from './tools/diagnose-flaky.js';
+const require = createRequire(import.meta.url);
+function readVersion() {
+    try {
+        const pkg = require('../package.json');
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+export const SERVER_NAME = 'playwright-e2e-mcp';
+export const SERVER_VERSION = readVersion();
+const TOOLS = [
+    {
+        ...runTestTool,
+        title: 'Run E2E tests',
+        // Spawns Playwright, hits live apps, writes test-results/ artifacts.
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        handler: runTestTool.handler,
+    },
+    {
+        ...getFailureTool,
+        title: 'Analyze a test failure',
+        // Pure reads: JSON report, trace.zip, generated failure summaries.
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        handler: getFailureTool.handler,
+    },
+    {
+        ...inspectPageTool,
+        title: 'Inspect live page DOM',
+        // Navigates and evaluates read-only DOM queries; never clicks or types.
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        handler: inspectPageTool.handler,
+    },
+    {
+        ...listTestsTool,
+        title: 'List available tests',
+        // Parses test files and config without modifying them.
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+        handler: listTestsTool.handler,
+    },
+    {
+        ...validateSelectorTool,
+        title: 'Validate CSS selector',
+        // Opens a page and queries the selector; no state-changing actions.
+        annotations: {
+            readOnlyHint: true,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        handler: validateSelectorTool.handler,
+    },
+    {
+        ...generateE2ETestTool,
+        title: 'Generate an E2E test',
+        // Writes a new spec under tests/generated/ (never edits existing files).
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        handler: generateE2ETestTool.handler,
+    },
+    {
+        ...compareVisualStateTool,
+        title: 'Compare visual state',
+        // Navigates the app; baseline action overwrites only the stored baseline.
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        handler: compareVisualStateTool.handler,
+    },
+    {
+        ...diagnoseFlakyTool,
+        title: 'Diagnose flaky test',
+        // Spawns Playwright repeatedly; writes test-results/ artifacts only.
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+        handler: diagnoseFlakyTool.handler,
+    },
+];
+export function resolveDefaultProjectRoot() {
+    const fromEnv = process.env.PW_MCP_PROJECT_ROOT;
+    // A host that collects PW_MCP_PROJECT_ROOT via MCPB user_config but does
+    // not substitute `${user_config.project_root}` would pass the placeholder
+    // through verbatim; that can never be a real path, so fall back to cwd.
+    if (fromEnv && fromEnv.includes('${')) {
+        logger.warn('PW_MCP_PROJECT_ROOT contains an unsubstituted ${...} placeholder; using cwd', {
+            value: fromEnv,
+        });
+        return process.cwd();
+    }
+    const root = fromEnv && fromEnv.trim() !== '' ? fromEnv : process.cwd();
+    if (fromEnv) {
+        try {
+            statSync(root);
+        }
+        catch {
+            logger.warn('PW_MCP_PROJECT_ROOT does not exist; tool calls will fail until it does', { root });
+        }
+    }
+    return root;
+}
+export function createServer(options = {}) {
+    const projectRoot = options.projectRoot ?? resolveDefaultProjectRoot();
+    const store = options.store ?? createToolStore();
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+    for (const tool of TOOLS) {
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            annotations: tool.annotations,
+        }, async (args, reqCtx) => {
+            const ctx = {
+                logger: logger.child({ tool: tool.name }),
+                // v2: the request abort signal lives under ctx.mcpReq.
+                signal: reqCtx.mcpReq.signal,
+                store,
+                projectRoot,
+            };
+            try {
+                return await tool.handler(args, ctx);
+            }
+            catch (err) {
+                // Backstop: tools already convert their own errors via guard().
+                const error = toPlaywrightMcpError(err);
+                ctx.logger.error('tool threw unexpectedly', { error, kind: error.kind });
+                return toolError(error.kind, error.message, error.hint, error.details);
+            }
+        });
+    }
+    logger.debug('server created', { version: SERVER_VERSION, projectRoot, tools: TOOLS.length });
+    return server;
+}
+let shuttingDown = false;
+/** Close the server, kill orphaned children, and exit. */
+export async function shutdown(server, code, reason) {
+    if (shuttingDown)
+        return;
+    shuttingDown = true;
+    const killed = killActiveChildren();
+    logger.info('shutting down', { reason, killedProcesses: killed });
+    try {
+        await server.close();
+    }
+    catch (err) {
+        logger.warn('error while closing server', { error: err });
+    }
+    process.exit(code);
+}
+/** Connect the server over stdio and install shutdown handlers. */
+export async function startServer() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    process.on('SIGINT', () => void shutdown(server, 0, 'SIGINT'));
+    process.on('SIGTERM', () => void shutdown(server, 0, 'SIGTERM'));
+    // The client went away: stdin ends, and we must not leave browsers or
+    // test workers running.
+    process.stdin.on('end', () => void shutdown(server, 0, 'stdin ended (client disconnected)'));
+    process.stdin.on('close', () => void shutdown(server, 0, 'stdin closed (client disconnected)'));
+    process.on('uncaughtException', (err) => {
+        logger.error('uncaught exception', { error: err });
+        void shutdown(server, 1, 'uncaughtException');
+    });
+    process.on('unhandledRejection', (reason) => {
+        logger.error('unhandled rejection', { error: reason });
+        void shutdown(server, 1, 'unhandledRejection');
+    });
+    await server.connect(transport);
+    logger.info('connected over stdio', {
+        version: SERVER_VERSION,
+        projectRoot: resolveDefaultProjectRoot(),
+        tools: TOOLS.map((tool) => tool.name),
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/tools/compare-visual-state.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Tool 7 — compare-visual-state: the blueprint's visual regression tool.
+ *
+ * Capture a screenshot of a page (or one element), compare it against a
+ * stored baseline, and report *what* changed: how many pixels, where
+ * (merged regions), and the average color shift — e.g. "the changed
+ * area went from blue rgb(37,99,235) to red rgb(220,38,38)".
+ */
+import { z } from 'zod';
+import type { ToolContext, ToolResponse } from '../types/index.js';
+declare const compareInput: z.ZodObject<{
+    url: z.ZodString;
+    name: z.ZodString;
+    projectRoot: z.ZodOptional<z.ZodString>;
+    selector: z.ZodOptional<z.ZodString>;
+    fullPage: z.ZodOptional<z.ZodBoolean>;
+    waitUntil: z.ZodOptional<z.ZodEnum<{
+        load: "load";
+        domcontentloaded: "domcontentloaded";
+        networkidle: "networkidle";
+    }>>;
+    waitFor: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    action: z.ZodOptional<z.ZodEnum<{
+        compare: "compare";
+        baseline: "baseline";
+    }>>;
+    tolerance: z.ZodOptional<z.ZodNumber>;
+    pixelThreshold: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type CompareVisualStateInput = z.infer<typeof compareInput>;
+export declare const compareVisualStateSchema: z.ZodObject<{
+    url: z.ZodString;
+    name: z.ZodString;
+    projectRoot: z.ZodOptional<z.ZodString>;
+    selector: z.ZodOptional<z.ZodString>;
+    fullPage: z.ZodOptional<z.ZodBoolean>;
+    waitUntil: z.ZodOptional<z.ZodEnum<{
+        load: "load";
+        domcontentloaded: "domcontentloaded";
+        networkidle: "networkidle";
+    }>>;
+    waitFor: z.ZodOptional<z.ZodString>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    action: z.ZodOptional<z.ZodEnum<{
+        compare: "compare";
+        baseline: "baseline";
+    }>>;
+    tolerance: z.ZodOptional<z.ZodNumber>;
+    pixelThreshold: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const compareVisualStateTool: {
+    name: string;
+    description: string;
+    inputSchema: z.ZodObject<{
+        url: z.ZodString;
+        name: z.ZodString;
+        projectRoot: z.ZodOptional<z.ZodString>;
+        selector: z.ZodOptional<z.ZodString>;
+        fullPage: z.ZodOptional<z.ZodBoolean>;
+        waitUntil: z.ZodOptional<z.ZodEnum<{
+            load: "load";
+            domcontentloaded: "domcontentloaded";
+            networkidle: "networkidle";
+        }>>;
+        waitFor: z.ZodOptional<z.ZodString>;
+        timeoutMs: z.ZodOptional<z.ZodNumber>;
+        action: z.ZodOptional<z.ZodEnum<{
+            compare: "compare";
+            baseline: "baseline";
+        }>>;
+        tolerance: z.ZodOptional<z.ZodNumber>;
+        pixelThreshold: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+    handler: (args: CompareVisualStateInput, ctx: ToolContext) => Promise<ToolResponse>;
+};
+export {};