@teapotz/electron-mcp 0.1.1

package/dist/tools/connection.tools.js

@@ -0,0 +1,106 @@
+import { toolOk, toolError } from "../protocol/responses.js";
+import { ConnectArgs, LaunchArgs, EmptyArgs } from "../validation/schemas.js";
+export const connectionTools = [
+    {
+        definition: {
+            name: "connect",
+            description: "Connect to already running Electron app via CDP (e.g., bun run dev:local with --remote-debugging-port)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    port: {
+                        type: "number",
+                        description: "CDP port (default: 9222)",
+                    },
+                },
+            },
+        },
+        parse: (raw) => ConnectArgs.parse(raw ?? {}),
+        handler: async (session, args) => {
+            if (session.isConnected) {
+                return toolError("Already connected. Disconnect first.");
+            }
+            const { port } = args;
+            try {
+                const title = await session.connectCdp(port);
+                return toolOk(`Connected via CDP (port ${port}). Window title: ${title}`);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return toolError(message);
+            }
+        },
+    },
+    {
+        definition: {
+            name: "disconnect",
+            description: "Disconnect from CDP (does not close the app)",
+            inputSchema: { type: "object", properties: {} },
+        },
+        parse: (raw) => EmptyArgs.parse(raw ?? {}),
+        handler: async (session) => {
+            if (!session.isConnected) {
+                return toolOk("Not connected.");
+            }
+            if (session.connectionMode !== "cdp") {
+                return toolError("Cannot disconnect in launch mode. Use close instead.");
+            }
+            await session.disconnect();
+            return toolOk("Disconnected from CDP.");
+        },
+    },
+    {
+        definition: {
+            name: "launch",
+            description: "Launch Electron app for testing (builds and runs fresh instance)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    appPath: {
+                        type: "string",
+                        description: "Path to Electron main.js (default: ./out/main/index.js)",
+                    },
+                    env: {
+                        type: "object",
+                        description: "Environment variables to pass to the app",
+                        additionalProperties: { type: "string" },
+                    },
+                    headless: {
+                        type: "boolean",
+                        description: "Run in headless mode (no visible window, for CI/automation)",
+                    },
+                },
+            },
+        },
+        parse: (raw) => LaunchArgs.parse(raw ?? {}),
+        handler: async (session, args) => {
+            if (session.isConnected) {
+                return toolError("Already connected. Disconnect/close first.");
+            }
+            const { appPath, env, headless } = args;
+            try {
+                const title = await session.launch({ appPath, env, headless });
+                return toolOk(`App launched${headless ? " (headless)" : ""}. Window title: ${title}`);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return toolError(message);
+            }
+        },
+    },
+    {
+        definition: {
+            name: "close",
+            description: "Close the Electron app (only works with launch, not connect)",
+            inputSchema: { type: "object", properties: {} },
+        },
+        parse: (raw) => EmptyArgs.parse(raw ?? {}),
+        handler: async (session) => {
+            if (session.connectionMode === "cdp") {
+                return toolError("Cannot close CDP connection. Use disconnect instead (app keeps running).");
+            }
+            await session.close();
+            return toolOk("App closed.");
+        },
+    },
+];

package/dist/tools/evaluate.tools.d.ts

@@ -0,0 +1,3 @@
+import type { ToolSpec } from "./registry.js";
+export declare function withTimeout<T>(promise: Promise<T>, ms?: number): Promise<T>;
+export declare const evaluateTools: ToolSpec[];

package/dist/tools/evaluate.tools.js

@@ -0,0 +1,73 @@
+import { toolOk, toolError } from "../protocol/responses.js";
+import { EvaluateArgs } from "../validation/schemas.js";
+const DEFAULT_TIMEOUT_MS = Number(process.env.ELECTRON_MCP_TIMEOUT_MS ?? 30_000);
+export function withTimeout(promise, ms = DEFAULT_TIMEOUT_MS) {
+    let timer;
+    return Promise.race([
+        promise,
+        new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`Operation timed out after ${ms}ms`)), ms);
+        }),
+    ]).finally(() => clearTimeout(timer));
+}
+export const evaluateTools = [
+    {
+        definition: {
+            name: "evaluate",
+            description: "Execute JavaScript in the renderer process",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    script: {
+                        type: "string",
+                        description: "JavaScript code to execute",
+                    },
+                },
+                required: ["script"],
+            },
+        },
+        parse: (raw) => EvaluateArgs.parse(raw),
+        handler: async (session, args) => {
+            const p = session.requirePage();
+            const { script } = args;
+            const result = await withTimeout(p.evaluate(script));
+            const resultText = result === undefined ? "undefined" : JSON.stringify(result, null, 2);
+            return toolOk(resultText);
+        },
+    },
+    {
+        definition: {
+            name: "evaluateMain",
+            description: "Execute code in the Electron main process",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    script: {
+                        type: "string",
+                        description: "Code to execute (receives { app, ipcMain, dialog, BrowserWindow })",
+                    },
+                },
+                required: ["script"],
+            },
+        },
+        parse: (raw) => EvaluateArgs.parse(raw),
+        handler: async (session, args) => {
+            if (session.connectionMode === "cdp") {
+                return toolError("evaluateMain is not available in CDP mode. Main process access requires launch mode.");
+            }
+            const app = session.requireElectronApp();
+            const { script } = args;
+            const result = await withTimeout(app.evaluate((electron, source) => {
+                // biome-ignore lint/security/noGlobalEval: intentional eval inside Electron main process
+                // biome-ignore lint/style/noCommaOperator: indirect eval pattern
+                const fn = (0, eval)(`(${source})`);
+                if (typeof fn !== "function") {
+                    throw new Error("evaluateMain script must be a function expression");
+                }
+                return fn(electron);
+            }, script));
+            const resultText = result === undefined ? "undefined" : JSON.stringify(result, null, 2);
+            return toolOk(resultText);
+        },
+    },
+];

package/dist/tools/inspection.tools.d.ts

@@ -0,0 +1,2 @@
+import type { ToolSpec } from "./registry.js";
+export declare const inspectionTools: ToolSpec[];

package/dist/tools/inspection.tools.js

@@ -0,0 +1,120 @@
+import { toolOk, toolImage } from "../protocol/responses.js";
+import { ScreenshotArgs, EmptyArgs, SelectorArgs, GetAttributeArgs, } from "../validation/schemas.js";
+export const inspectionTools = [
+    {
+        definition: {
+            name: "screenshot",
+            description: "Take a screenshot of the current window",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    fullPage: {
+                        type: "boolean",
+                        description: "Capture full scrollable page",
+                    },
+                },
+            },
+        },
+        parse: (raw) => ScreenshotArgs.parse(raw ?? {}),
+        handler: async (session, args) => {
+            const p = session.requirePage();
+            const { fullPage } = args;
+            const buffer = await p.screenshot({ fullPage });
+            return toolImage(buffer.toString("base64"));
+        },
+    },
+    {
+        definition: {
+            name: "snapshot",
+            description: "Get accessibility tree snapshot of the page (for finding elements)",
+            inputSchema: { type: "object", properties: {} },
+        },
+        parse: (raw) => EmptyArgs.parse(raw ?? {}),
+        handler: async (session) => {
+            const p = session.requirePage();
+            const snapshot = await p.locator("body").ariaSnapshot();
+            return toolOk(snapshot);
+        },
+    },
+    {
+        definition: {
+            name: "getText",
+            description: "Get text content of an element",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    selector: { type: "string", description: "CSS selector" },
+                },
+                required: ["selector"],
+            },
+        },
+        parse: (raw) => SelectorArgs.parse(raw),
+        handler: async (session, args) => {
+            const p = session.requirePage();
+            const { selector } = args;
+            const text = await p.locator(selector).textContent();
+            return toolOk(text || "(empty)");
+        },
+    },
+    {
+        definition: {
+            name: "getAttribute",
+            description: "Get attribute value of an element",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    selector: { type: "string", description: "CSS selector" },
+                    attribute: { type: "string", description: "Attribute name" },
+                },
+                required: ["selector", "attribute"],
+            },
+        },
+        parse: (raw) => GetAttributeArgs.parse(raw),
+        handler: async (session, args) => {
+            const p = session.requirePage();
+            const { selector, attribute } = args;
+            const value = await p.locator(selector).getAttribute(attribute);
+            return toolOk(value ?? "(null)");
+        },
+    },
+    {
+        definition: {
+            name: "isVisible",
+            description: "Check if element is visible",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    selector: { type: "string", description: "CSS selector" },
+                },
+                required: ["selector"],
+            },
+        },
+        parse: (raw) => SelectorArgs.parse(raw),
+        handler: async (session, args) => {
+            const p = session.requirePage();
+            const { selector } = args;
+            const visible = await p.locator(selector).isVisible();
+            return toolOk(String(visible));
+        },
+    },
+    {
+        definition: {
+            name: "count",
+            description: "Count elements matching selector",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    selector: { type: "string", description: "CSS selector" },
+                },
+                required: ["selector"],
+            },
+        },
+        parse: (raw) => SelectorArgs.parse(raw),
+        handler: async (session, args) => {
+            const p = session.requirePage();
+            const { selector } = args;
+            const count = await p.locator(selector).count();
+            return toolOk(String(count));
+        },
+    },
+];

package/dist/tools/interaction.tools.d.ts

@@ -0,0 +1,2 @@
+import type { ToolSpec } from "./registry.js";
+export declare const interactionTools: ToolSpec[];

package/dist/tools/interaction.tools.js

@@ -0,0 +1,233 @@
+import { toolOk } from "../protocol/responses.js";
+import { SelectorArgs, FillArgs, TypeArgs, PressArgs, WaitArgs, DragArgs, SelectOptionArgs, } from "../validation/schemas.js";
+function normalizeWaitArgs(raw) {
+    if (!raw || typeof raw !== "object")
+        return raw;
+    const args = raw;
+    if (args.waitTimeoutMs === undefined && args.timeout !== undefined) {
+        return { ...args, waitTimeoutMs: args.timeout };
+    }
+    return raw;
+}
+export const interactionTools = [
+    {
+        definition: {
+            name: "click",
+            description: "Click an element",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    selector: {
+                        type: "string",
+                        description: 'CSS selector or text selector (e.g., "text=Submit")',
+                    },
+                },
+                required: ["selector"],
+            },
+        },
+        parse: (raw) => SelectorArgs.parse(raw),
+        handler: async (session, args) => {
+            const p = session.requirePage();
+            const { selector } = args;
+            await p.click(selector);
+            return toolOk(`Clicked: ${selector}`);
+        },
+    },
+    {
+        definition: {
+            name: "fill",
+            description: "Fill text into an input field",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    selector: {
+                        type: "string",
+                        description: "CSS selector for the input",
+                    },
+                    text: { type: "string", description: "Text to fill" },
+                },
+                required: ["selector", "text"],
+            },
+        },
+        parse: (raw) => FillArgs.parse(raw),
+        handler: async (session, args) => {
+            const p = session.requirePage();
+            const { selector, text } = args;
+            await p.fill(selector, text);
+            return toolOk(`Filled "${text}" into ${selector}`);
+        },
+    },
+    {
+        definition: {
+            name: "type",
+            description: "Type text character by character (triggers key events)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    selector: {
+                        type: "string",
+                        description: "CSS selector for the input",
+                    },
+                    text: { type: "string", description: "Text to type" },
+                },
+                required: ["selector", "text"],
+            },
+        },
+        parse: (raw) => TypeArgs.parse(raw),
+        handler: async (session, args) => {
+            const p = session.requirePage();
+            const { selector, text } = args;
+            await p.locator(selector).pressSequentially(text);
+            return toolOk(`Typed "${text}" into ${selector}`);
+        },
+    },
+    {
+        definition: {
+            name: "hover",
+            description: "Hover over an element",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    selector: { type: "string", description: "CSS selector" },
+                },
+                required: ["selector"],
+            },
+        },
+        parse: (raw) => SelectorArgs.parse(raw),
+        handler: async (session, args) => {
+            const p = session.requirePage();
+            const { selector } = args;
+            await p.hover(selector);
+            return toolOk(`Hovered: ${selector}`);
+        },
+    },
+    {
+        definition: {
+            name: "press",
+            description: "Press a keyboard key",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    key: {
+                        type: "string",
+                        description: 'Key to press (e.g., "Enter", "Escape", "Control+S")',
+                    },
+                },
+                required: ["key"],
+            },
+        },
+        parse: (raw) => PressArgs.parse(raw),
+        handler: async (session, args) => {
+            const p = session.requirePage();
+            const { key } = args;
+            await p.keyboard.press(key);
+            return toolOk(`Pressed: ${key}`);
+        },
+    },
+    {
+        definition: {
+            name: "wait",
+            description: "Wait for an element or condition",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    selector: {
+                        type: "string",
+                        description: "CSS selector to wait for",
+                    },
+                    state: {
+                        type: "string",
+                        enum: ["visible", "hidden", "attached", "detached"],
+                        description: "State to wait for (default: visible)",
+                    },
+                    waitTimeoutMs: {
+                        type: "number",
+                        description: "Timeout in ms (default: 5000)",
+                    },
+                },
+                required: ["selector"],
+            },
+        },
+        parse: (raw) => WaitArgs.parse(normalizeWaitArgs(raw)),
+        handler: async (session, args) => {
+            const p = session.requirePage();
+            const { selector, state, waitTimeoutMs } = args;
+            await p.locator(selector).waitFor({ state, timeout: waitTimeoutMs });
+            return toolOk(`Element ${selector} is ${state}`);
+        },
+    },
+    {
+        definition: {
+            name: "drag",
+            description: "Drag and drop from source to target element",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    source: {
+                        type: "string",
+                        description: "CSS selector for source element to drag",
+                    },
+                    target: {
+                        type: "string",
+                        description: "CSS selector for target drop zone",
+                    },
+                },
+                required: ["source", "target"],
+            },
+        },
+        parse: (raw) => DragArgs.parse(raw),
+        handler: async (session, args) => {
+            const p = session.requirePage();
+            const { source, target } = args;
+            await p.dragAndDrop(source, target);
+            return toolOk(`Dragged ${source} to ${target}`);
+        },
+    },
+    {
+        definition: {
+            name: "selectOption",
+            description: "Select option(s) from a dropdown",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    selector: {
+                        type: "string",
+                        description: "CSS selector for select element",
+                    },
+                    value: {
+                        type: "string",
+                        description: "Value or label to select",
+                    },
+                },
+                required: ["selector", "value"],
+            },
+        },
+        parse: (raw) => SelectOptionArgs.parse(raw),
+        handler: async (session, args) => {
+            const p = session.requirePage();
+            const { selector, value } = args;
+            await p.selectOption(selector, value);
+            return toolOk(`Selected "${value}" in ${selector}`);
+        },
+    },
+    {
+        definition: {
+            name: "dblclick",
+            description: "Double-click an element",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    selector: { type: "string", description: "CSS selector" },
+                },
+                required: ["selector"],
+            },
+        },
+        parse: (raw) => SelectorArgs.parse(raw),
+        handler: async (session, args) => {
+            const p = session.requirePage();
+            const { selector } = args;
+            await p.dblclick(selector);
+            return toolOk(`Double-clicked: ${selector}`);
+        },
+    },
+];

package/dist/tools/mouse.tools.d.ts

@@ -0,0 +1,2 @@
+import type { ToolSpec } from "./registry.js";
+export declare const mouseTools: ToolSpec[];

package/dist/tools/mouse.tools.js

@@ -0,0 +1,105 @@
+import { toolOk } from "../protocol/responses.js";
+import { MouseMoveArgs, MouseButtonArgs, MouseClickArgs, } from "../validation/schemas.js";
+export const mouseTools = [
+    {
+        definition: {
+            name: "mouseMove",
+            description: "Move mouse cursor to specific coordinates",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    x: { type: "number", description: "X coordinate" },
+                    y: { type: "number", description: "Y coordinate" },
+                    steps: {
+                        type: "number",
+                        description: "Number of intermediate steps for smooth movement (default: 1)",
+                    },
+                },
+                required: ["x", "y"],
+            },
+        },
+        parse: (raw) => MouseMoveArgs.parse(raw),
+        handler: async (session, args) => {
+            const p = session.requirePage();
+            const { x, y, steps } = args;
+            await p.mouse.move(x, y, { steps });
+            return toolOk(`Mouse moved to (${x}, ${y})`);
+        },
+    },
+    {
+        definition: {
+            name: "mouseDown",
+            description: "Press mouse button down",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    button: {
+                        type: "string",
+                        enum: ["left", "right", "middle"],
+                        description: "Mouse button (default: left)",
+                    },
+                },
+            },
+        },
+        parse: (raw) => MouseButtonArgs.parse(raw ?? {}),
+        handler: async (session, args) => {
+            const p = session.requirePage();
+            const { button } = args;
+            await p.mouse.down({ button });
+            return toolOk(`Mouse ${button} button pressed`);
+        },
+    },
+    {
+        definition: {
+            name: "mouseUp",
+            description: "Release mouse button",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    button: {
+                        type: "string",
+                        enum: ["left", "right", "middle"],
+                        description: "Mouse button (default: left)",
+                    },
+                },
+            },
+        },
+        parse: (raw) => MouseButtonArgs.parse(raw ?? {}),
+        handler: async (session, args) => {
+            const p = session.requirePage();
+            const { button } = args;
+            await p.mouse.up({ button });
+            return toolOk(`Mouse ${button} button released`);
+        },
+    },
+    {
+        definition: {
+            name: "mouseClick",
+            description: "Click at specific coordinates (without selector)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    x: { type: "number", description: "X coordinate" },
+                    y: { type: "number", description: "Y coordinate" },
+                    button: {
+                        type: "string",
+                        enum: ["left", "right", "middle"],
+                        description: "Mouse button (default: left)",
+                    },
+                    clickCount: {
+                        type: "number",
+                        description: "Number of clicks (default: 1, use 2 for double-click)",
+                    },
+                },
+                required: ["x", "y"],
+            },
+        },
+        parse: (raw) => MouseClickArgs.parse(raw),
+        handler: async (session, args) => {
+            const p = session.requirePage();
+            const { x, y, button, clickCount } = args;
+            await p.mouse.click(x, y, { button, clickCount });
+            return toolOk(`Mouse clicked at (${x}, ${y})`);
+        },
+    },
+];

package/dist/tools/registry.d.ts

@@ -0,0 +1,10 @@
+import type { Tool, CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { SessionController } from "../session/SessionController.js";
+export interface ToolSpec<TArgs = unknown> {
+    definition: Tool;
+    parse: (raw: unknown) => TArgs;
+    handler: (session: SessionController, args: TArgs) => Promise<CallToolResult>;
+}
+export type ToolRegistry = Map<string, ToolSpec>;
+export declare function buildRegistry(): ToolRegistry;
+export declare function dispatch(registry: ToolRegistry, session: SessionController, name: string, rawArgs: unknown): Promise<CallToolResult>;