electron-verify-mcp 0.0.1

package/dist/mcp.js

@@ -0,0 +1,578 @@
+#!/usr/bin/env node
+/**
+ * Thin stdio MCP server over core.
+ * Holds ONE AppSession; all real logic lives in src/core/*.
+ * Logging → stderr only (stdout is the JSON-RPC channel).
+ */
+import { createRequire } from "node:module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { PNG } from "pngjs";
+import { AppSession } from "./core/session.js";
+import { verify, scaleHolesToPhysical } from "./core/verify.js";
+import { waitUntilReady } from "./core/readiness.js";
+import { annotateHoles, captureRawScreenshot, downscaleIfNeeded, } from "./core/screenshot.js";
+import { captureOsWindow, captureWindow } from "./core/windowCapture.js";
+import { detectHoles } from "./core/windows.js";
+import { clickEl, typeEl, waitForSel, evalJs } from "./core/interact.js";
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+const SERVER_VERSION = pkg.version ?? "0.0.0";
+// ─── Session state ───────────────────────────────────────────────────────────
+let session = null;
+/** Serialize tool handlers so concurrent calls never race one Electron app. */
+let lock = Promise.resolve();
+function withLock(fn) {
+    const run = lock.then(fn, fn);
+    lock = run.then(() => undefined, () => undefined);
+    return run;
+}
+const URL_MAX = 120;
+/** Default readiness budget for app_screenshot (verify keeps the longer gate). */
+const SCREENSHOT_READINESS_MS = 1_500;
+function truncateUrl(url, max = URL_MAX) {
+    if (url.length <= max)
+        return url;
+    return url.slice(0, max - 1) + "…";
+}
+function isDeadSessionError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return /target closed|has been closed|browser has been closed|session closed|crashed|Target page, context or browser has been closed/i.test(msg);
+}
+function noSessionResult() {
+    const message = "no active session — call app_launch";
+    return {
+        content: [{ type: "text", text: message }],
+        structuredContent: { error: "no_session", message },
+        isError: true,
+    };
+}
+function deadSessionResult() {
+    session = null;
+    const message = "session died — relaunch with app_launch";
+    return {
+        content: [{ type: "text", text: message }],
+        structuredContent: { error: "session_dead", message },
+        isError: true,
+    };
+}
+function toolError(err) {
+    if (isDeadSessionError(err))
+        return deadSessionResult();
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`[electron-verify-mcp] tool error: ${message}`);
+    return {
+        content: [{ type: "text", text: message }],
+        structuredContent: { error: "tool_error", message },
+        isError: true,
+    };
+}
+async function requireSession() {
+    return session;
+}
+async function listWindows(s) {
+    const pages = s.app.windows();
+    return Promise.all(pages.map(async (p) => {
+        let title = "";
+        try {
+            title = await p.title();
+        }
+        catch {
+            /* closed */
+        }
+        return { title, url: truncateUrl(p.url()) };
+    }));
+}
+function pidOf(s) {
+    try {
+        return s.app.process()?.pid ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+async function closeSession() {
+    if (!session)
+        return;
+    const s = session;
+    session = null;
+    try {
+        await s.close();
+    }
+    catch (err) {
+        console.error(`[electron-verify-mcp] close error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+async function captureForScreenshot(s, opts) {
+    const page = s.page();
+    const pageUrl = page.url();
+    const maxWidth = opts.maxWidth ?? 1280;
+    const want = opts.captureMode ?? "window";
+    const readinessMs = opts.readinessTimeoutMs ?? SCREENSHOT_READINESS_MS;
+    await waitUntilReady(page, { timeoutMs: readinessMs });
+    // Content capture (always for annotation / both mode).
+    const dipHoles = await detectHoles(s.app, pageUrl);
+    let dpr = 1;
+    try {
+        dpr = (await page.evaluate(() => window.devicePixelRatio || 1));
+        if (typeof dpr !== "number" || dpr <= 0)
+            dpr = 1;
+    }
+    catch {
+        dpr = 1;
+    }
+    const holes = scaleHolesToPhysical(dipHoles, dpr);
+    const rawPng = await captureRawScreenshot(page);
+    const rawDecoded = PNG.sync.read(rawPng);
+    // Hole annotation only for content / fallback (not composited window mode).
+    const annotated = holes.length > 0 ? annotateHoles(rawDecoded, holes) : rawDecoded;
+    let contentPng = PNG.sync.write(annotated);
+    contentPng = downscaleIfNeeded(contentPng, maxWidth);
+    if (want === "content") {
+        return { primary: contentPng, content: contentPng, captureMode: "content" };
+    }
+    if (want === "os-window") {
+        const os = await captureOsWindow(s.app, pageUrl);
+        let osPng = os.png;
+        if (osPng)
+            osPng = downscaleIfNeeded(osPng, maxWidth);
+        if (osPng) {
+            return { primary: osPng, window: osPng, captureMode: "os-window" };
+        }
+        const win = await captureWindow(s.app, pageUrl);
+        let windowPng = win.png;
+        if (windowPng)
+            windowPng = downscaleIfNeeded(windowPng, maxWidth);
+        if (windowPng) {
+            return {
+                primary: windowPng,
+                window: windowPng,
+                captureMode: "os-window-fallback:window",
+                captureNote: os.note ?? "os-window capture unavailable; used window",
+            };
+        }
+        return {
+            primary: contentPng,
+            content: contentPng,
+            captureMode: "content-fallback",
+            captureNote: [os.note, win.note].filter(Boolean).join("; ") ||
+                "os-window and window capture unavailable",
+        };
+    }
+    const win = await captureWindow(s.app, pageUrl);
+    let windowPng = win.png;
+    if (windowPng)
+        windowPng = downscaleIfNeeded(windowPng, maxWidth);
+    if (want === "both") {
+        if (windowPng) {
+            return {
+                primary: windowPng,
+                content: contentPng,
+                window: windowPng,
+                captureMode: "window",
+            };
+        }
+        return {
+            primary: contentPng,
+            content: contentPng,
+            captureMode: "content-fallback",
+            captureNote: win.note,
+        };
+    }
+    // window (default)
+    if (windowPng) {
+        return { primary: windowPng, window: windowPng, captureMode: "window" };
+    }
+    return {
+        primary: contentPng,
+        content: contentPng,
+        captureMode: "content-fallback",
+        captureNote: win.note,
+    };
+}
+function verdictStructured(result) {
+    return {
+        verdict: result.verdict,
+        hardFails: result.hardFails,
+        warns: result.warns,
+        signals: result.signals,
+        ...(result.expect !== undefined ? { expect: result.expect } : {}),
+        windowStrategy: result.windowStrategy,
+        windowWarning: result.windowWarning,
+        holes: result.holes,
+        captureMode: result.captureMode,
+        ...(result.captureNote ? { captureNote: result.captureNote } : {}),
+    };
+}
+// ─── MCP server ──────────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: "electron-verify-mcp",
+    version: SERVER_VERSION,
+});
+const captureModeSchema = z
+    .enum(["content", "window", "os-window", "both"])
+    .optional()
+    .describe('Screenshot mode: "window" (default, composited Electron window — menu bar + content, no OS caption), "os-window" (full OS frame including min/max/close caption bar), "content" (viewport only), "both" (window + content images)');
+server.registerTool("app_launch", {
+    title: "Launch Electron app",
+    description: "Launch an Electron app under a single managed session. Closes any prior session first. " +
+        "Returns window list (URLs truncated) and process pid. Call app_close when done.",
+    inputSchema: {
+        appPath: z.string().describe("Path to the app main entry (e.g. dist/main/index.js)"),
+        cwd: z.string().optional().describe("App working directory (defaults to dirname of appPath)"),
+        args: z.array(z.string()).optional().describe("Extra args after the main entry"),
+        env: z.record(z.string()).optional().describe("Extra environment variables"),
+        buildCommand: z
+            .string()
+            .optional()
+            .describe("Shell command run in cwd before launch (avoid stale dist/)"),
+        windowUrlMatch: z
+            .string()
+            .optional()
+            .describe("Force target window URL substring"),
+        ignoreConsolePatterns: z
+            .array(z.string())
+            .optional()
+            .describe("Extra console ignore regexes"),
+        criticalSelectors: z
+            .array(z.string())
+            .optional()
+            .describe("Selectors that must be present and non-zero size"),
+        srcGlobs: z
+            .array(z.string())
+            .optional()
+            .describe("Source globs for stale-build detection"),
+        strictConsole: z
+            .boolean()
+            .optional()
+            .describe("When true, bare console.error is hard-FAIL (default: WARN)"),
+    },
+}, async (args) => withLock(async () => {
+    try {
+        await closeSession();
+        session = await AppSession.launch({
+            appPath: args.appPath,
+            cwd: args.cwd,
+            args: args.args,
+            env: args.env,
+            buildCommand: args.buildCommand,
+            windowUrlMatch: args.windowUrlMatch,
+            ignoreConsolePatterns: args.ignoreConsolePatterns,
+            criticalSelectors: args.criticalSelectors,
+            srcGlobs: args.srcGlobs,
+            strictConsole: args.strictConsole,
+        });
+        try {
+            const { stubAllDialogs } = await import("electron-playwright-helpers");
+            await stubAllDialogs(session.app);
+        }
+        catch (err) {
+            console.error(`[electron-verify-mcp] dialog stub skipped: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const windows = await listWindows(session);
+        const pid = pidOf(session);
+        const structuredContent = { windows, pid };
+        const text = `launched pid=${pid ?? "?"} windows=${windows.length} ${windows
+            .map((w) => `"${w.title}" ${w.url}`)
+            .join(" | ")}`;
+        return {
+            content: [{ type: "text", text }],
+            structuredContent,
+        };
+    }
+    catch (err) {
+        session = null;
+        return toolError(err);
+    }
+}));
+server.registerTool("app_screenshot", {
+    title: "Screenshot app window",
+    description: "Screenshot of the active session window. Default captureMode=window (composited Electron chrome — " +
+        "menu bar + content, no OS caption). Use os-window for the real min/max/close caption bar. " +
+        "Falls back window→content (or os-window→window→content). BrowserView hole annotations only in " +
+        "content/fallback mode. Uses a short readiness budget (~1.5s). PNG returned as image content block(s).",
+    inputSchema: {
+        maxWidth: z
+            .number()
+            .optional()
+            .describe("Max PNG width (default 1280); larger captures are downscaled"),
+        captureMode: captureModeSchema,
+        readinessTimeoutMs: z
+            .number()
+            .optional()
+            .describe("Readiness budget in ms (default 1500 for screenshots)"),
+    },
+}, async (args) => withLock(async () => {
+    const s = await requireSession();
+    if (!s)
+        return noSessionResult();
+    try {
+        const cap = await captureForScreenshot(s, {
+            maxWidth: args.maxWidth,
+            captureMode: args.captureMode,
+            readinessTimeoutMs: args.readinessTimeoutMs,
+        });
+        const content = [
+            {
+                type: "text",
+                text: `screenshot ${cap.primary.length} bytes captureMode=${cap.captureMode}${cap.captureNote ? ` (${cap.captureNote})` : ""}`,
+            },
+            {
+                type: "image",
+                data: cap.primary.toString("base64"),
+                mimeType: "image/png",
+            },
+        ];
+        if (args.captureMode === "both" && cap.content && cap.window) {
+            content.push({
+                type: "image",
+                data: cap.content.toString("base64"),
+                mimeType: "image/png",
+            });
+        }
+        return {
+            content,
+            structuredContent: {
+                bytes: cap.primary.length,
+                captureMode: cap.captureMode,
+                ...(cap.captureNote ? { captureNote: cap.captureNote } : {}),
+            },
+        };
+    }
+    catch (err) {
+        return toolError(err);
+    }
+}));
+server.registerTool("app_click", {
+    title: "Click element",
+    description: "Click a CSS selector in the active session's page.",
+    inputSchema: {
+        selector: z.string().describe("CSS selector to click"),
+    },
+}, async (args) => withLock(async () => {
+    const s = await requireSession();
+    if (!s)
+        return noSessionResult();
+    try {
+        await clickEl(s.page(), args.selector);
+        s.noteInteraction();
+        return {
+            content: [{ type: "text", text: `clicked ${args.selector}` }],
+            structuredContent: { ok: true, selector: args.selector },
+        };
+    }
+    catch (err) {
+        return toolError(err);
+    }
+}));
+server.registerTool("app_type", {
+    title: "Type into element",
+    description: "Fill text into an input matching the CSS selector.",
+    inputSchema: {
+        selector: z.string().describe("CSS selector of the input"),
+        text: z.string().describe("Text to type"),
+    },
+}, async (args) => withLock(async () => {
+    const s = await requireSession();
+    if (!s)
+        return noSessionResult();
+    try {
+        await typeEl(s.page(), args.selector, args.text);
+        s.noteInteraction();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `typed into ${args.selector} (${args.text.length} chars)`,
+                },
+            ],
+            structuredContent: { ok: true, selector: args.selector },
+        };
+    }
+    catch (err) {
+        return toolError(err);
+    }
+}));
+server.registerTool("app_wait_for", {
+    title: "Wait for selector or text",
+    description: "Wait until a CSS selector or visible text appears. " +
+        "Heuristic: target is a CSS selector only if it starts with . # [ or contains " +
+        "selector chars (>, :, [, etc.); otherwise plain text is matched via getByText. " +
+        'Pass by="selector" or by="text" to force the mode. Single-word labels like "Submit" are text.',
+    inputSchema: {
+        target: z.string().describe("CSS selector or visible text to wait for"),
+        timeoutMs: z.number().optional().describe("Timeout in ms (default 10000)"),
+        by: z
+            .enum(["selector", "text"])
+            .optional()
+            .describe('Force interpretation: "selector" (CSS) or "text" (getByText)'),
+    },
+}, async (args) => withLock(async () => {
+    const s = await requireSession();
+    if (!s)
+        return noSessionResult();
+    try {
+        await waitForSel(s.page(), args.target, {
+            timeoutMs: args.timeoutMs,
+            by: args.by,
+        });
+        return {
+            content: [{ type: "text", text: `waited for ${args.target}` }],
+            structuredContent: { ok: true, target: args.target },
+        };
+    }
+    catch (err) {
+        return toolError(err);
+    }
+}));
+server.registerTool("app_evaluate", {
+    title: "Evaluate JS in page",
+    description: "Evaluate a JavaScript expression in the renderer via CDP Runtime.evaluate (CSP-safe). " +
+        "Pass an expression (e.g. document.title). Set asStatement=true for a statement body with return.",
+    inputSchema: {
+        expression: z
+            .string()
+            .describe("JS expression, e.g. document.title or document.querySelector('#ok')?.textContent"),
+        asStatement: z
+            .boolean()
+            .optional()
+            .describe("If true, treat expression as a statement body (may include return)"),
+    },
+}, async (args) => withLock(async () => {
+    const s = await requireSession();
+    if (!s)
+        return noSessionResult();
+    try {
+        const result = await evalJs(s.page(), args.expression, {
+            asStatement: args.asStatement,
+        });
+        // Read-only evaluate does not count as interaction; mutating ones should use click/type.
+        // Still note interaction when asStatement (likely mutates) — conservative.
+        if (args.asStatement)
+            s.noteInteraction();
+        const text = typeof result === "string" ? result : JSON.stringify(result, null, 2);
+        return {
+            content: [{ type: "text", text: text ?? "undefined" }],
+            structuredContent: { result },
+        };
+    }
+    catch (err) {
+        return toolError(err);
+    }
+}));
+server.registerTool("app_verify", {
+    title: "Verify app UI",
+    description: "Run a high-precision signal pass + capture a screenshot. " +
+        "Returns image (PNG) + structuredContent verdict (PASS|WARN|FAIL). " +
+        "freshLoad: when omitted, defaults TRUE if no click/type since last verify " +
+        "(so an unchanged broken app is re-checked); FALSE after interactions. " +
+        "Signal analysis always uses content capture; human image defaults to window (composited). " +
+        "Use captureMode=os-window for the full OS caption bar (min/max/close). " +
+        "console.error → WARN by default; pageerror/crash → FAIL. Set strictConsole to promote console.error.",
+    inputSchema: {
+        expect: z.string().optional().describe("Intent string echoed into the verdict"),
+        freshLoad: z
+            .boolean()
+            .optional()
+            .describe("Reload before verify. Omitted: true if no interaction since last verify, else false"),
+        criticalSelectors: z
+            .array(z.string())
+            .optional()
+            .describe("Override session criticalSelectors for this pass"),
+        captureMode: captureModeSchema,
+        strictConsole: z
+            .boolean()
+            .optional()
+            .describe("When true, bare console.error is hard-FAIL for this pass"),
+    },
+}, async (args) => withLock(async () => {
+    const s = await requireSession();
+    if (!s)
+        return noSessionResult();
+    try {
+        const result = await verify(s, {
+            expect: args.expect,
+            // Undefined → core defaults based on interactionSinceVerify.
+            freshLoad: args.freshLoad,
+            criticalSelectors: args.criticalSelectors,
+            captureMode: args.captureMode ?? "window",
+            strictConsole: args.strictConsole,
+        });
+        const structuredContent = verdictStructured(result);
+        const summary = [
+            result.verdict,
+            result.hardFails.length ? `hardFails=${result.hardFails.join(",")}` : "",
+            result.warns.length ? `warns=${result.warns.join(",")}` : "",
+            `capture=${result.captureMode}`,
+        ]
+            .filter(Boolean)
+            .join(" ");
+        const content = [
+            { type: "text", text: summary },
+            {
+                type: "image",
+                data: result.screenshot.toString("base64"),
+                mimeType: "image/png",
+            },
+        ];
+        if (args.captureMode === "both" &&
+            result.contentScreenshot &&
+            result.windowScreenshot) {
+            content.push({
+                type: "image",
+                data: result.contentScreenshot.toString("base64"),
+                mimeType: "image/png",
+            });
+        }
+        return { content, structuredContent };
+    }
+    catch (err) {
+        return toolError(err);
+    }
+}));
+server.registerTool("app_close", {
+    title: "Close app session",
+    description: "Dispose the active Electron session (graceful close with 5s timeout + force-kill fallback). No arguments.",
+}, async () => withLock(async () => {
+    if (!session) {
+        return {
+            content: [{ type: "text", text: "no session to close" }],
+            structuredContent: { closed: false, reason: "no_session" },
+        };
+    }
+    await closeSession();
+    return {
+        content: [{ type: "text", text: "session closed" }],
+        structuredContent: { closed: true },
+    };
+}));
+// ─── Lifecycle hygiene ───────────────────────────────────────────────────────
+async function shutdown(reason) {
+    console.error(`[electron-verify-mcp] shutting down (${reason})`);
+    await closeSession();
+}
+process.on("SIGINT", () => {
+    void shutdown("SIGINT").finally(() => process.exit(0));
+});
+process.on("SIGTERM", () => {
+    void shutdown("SIGTERM").finally(() => process.exit(0));
+});
+process.stdin.on("end", () => {
+    void shutdown("stdin end").finally(() => process.exit(0));
+});
+process.stdin.on("close", () => {
+    void shutdown("stdin close").finally(() => process.exit(0));
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    transport.onclose = () => {
+        void shutdown("transport close");
+    };
+    await server.connect(transport);
+    console.error(`[electron-verify-mcp] stdio server ready v${SERVER_VERSION}`);
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? (err.stack ?? err.message) : String(err));
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "electron-verify-mcp",
+  "version": "0.0.1",
+  "description": "Give your AI coding agent eyes for Electron apps: launch, drive, screenshot, and get a high-precision pass/fail verdict so it can verify its own UI in a loop.",
+  "type": "module",
+  "license": "MIT",
+  "author": "dpraj007",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dpraj007/electron-verify-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dpraj007/electron-verify-mcp/issues"
+  },
+  "homepage": "https://github.com/dpraj007/electron-verify-mcp#readme",
+  "keywords": [
+    "electron",
+    "mcp",
+    "model-context-protocol",
+    "screenshot",
+    "visual-testing",
+    "verification",
+    "playwright",
+    "ai-agent",
+    "claude"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/core/index.js",
+  "types": "./dist/core/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "electron-verify": "./dist/cli.js",
+    "electron-verify-mcp": "./dist/mcp.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "verify": "tsx src/cli.ts",
+    "mcp": "tsx src/mcp.ts",
+    "test": "node --import tsx --test test/**/*.test.ts",
+    "test:mcp": "node test/mcp-smoke.mjs",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "electron-playwright-helpers": "^1.7.1",
+    "playwright-core": "^1.51.0",
+    "pngjs": "^7.0.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/pngjs": "^6.0.5",
+    "electron": "^35.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}