@teapotz/electron-mcp 0.1.1

package/dist/tools/registry.js

@@ -0,0 +1,40 @@
+import { toolError } from "../protocol/responses.js";
+import { NotConnectedError, NotLaunchedError, classifyPlaywrightError, } from "../errors.js";
+import { connectionTools } from "./connection.tools.js";
+import { interactionTools } from "./interaction.tools.js";
+import { inspectionTools } from "./inspection.tools.js";
+import { scrollTools } from "./scroll.tools.js";
+import { mouseTools } from "./mouse.tools.js";
+import { evaluateTools } from "./evaluate.tools.js";
+export function buildRegistry() {
+    const registry = new Map();
+    const allTools = [
+        ...connectionTools,
+        ...interactionTools,
+        ...inspectionTools,
+        ...scrollTools,
+        ...mouseTools,
+        ...evaluateTools,
+    ];
+    for (const tool of allTools) {
+        registry.set(tool.definition.name, tool);
+    }
+    return registry;
+}
+export async function dispatch(registry, session, name, rawArgs) {
+    const spec = registry.get(name);
+    if (!spec) {
+        return toolError(`Unknown tool: ${name}`);
+    }
+    try {
+        const parsed = spec.parse(rawArgs);
+        return await spec.handler(session, parsed);
+    }
+    catch (error) {
+        if (error instanceof NotConnectedError || error instanceof NotLaunchedError) {
+            return toolError(`Error: ${error.message}`);
+        }
+        const classified = classifyPlaywrightError(error);
+        return toolError(`Error: ${classified.message}`);
+    }
+}

package/dist/tools/scroll.tools.d.ts

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

package/dist/tools/scroll.tools.js

@@ -0,0 +1,84 @@
+import { toolOk } from "../protocol/responses.js";
+import { ScrollArgs, ScrollToArgs, SelectorArgs } from "../validation/schemas.js";
+export const scrollTools = [
+    {
+        definition: {
+            name: "scroll",
+            description: "Scroll the page using mouse wheel",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    deltaX: {
+                        type: "number",
+                        description: "Horizontal scroll amount (positive = right, negative = left)",
+                    },
+                    deltaY: {
+                        type: "number",
+                        description: "Vertical scroll amount (positive = down, negative = up)",
+                    },
+                },
+            },
+        },
+        parse: (raw) => ScrollArgs.parse(raw ?? {}),
+        handler: async (session, args) => {
+            const p = session.requirePage();
+            const { deltaX, deltaY } = args;
+            await p.mouse.wheel(deltaX, deltaY);
+            return toolOk(`Scrolled by (${deltaX}, ${deltaY})`);
+        },
+    },
+    {
+        definition: {
+            name: "scrollTo",
+            description: "Scroll to absolute position on the page",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    x: {
+                        type: "number",
+                        description: "Horizontal position in pixels (default: 0)",
+                    },
+                    y: {
+                        type: "number",
+                        description: "Vertical position in pixels (default: 0)",
+                    },
+                    behavior: {
+                        type: "string",
+                        enum: ["auto", "smooth"],
+                        description: "Scroll behavior (default: auto)",
+                    },
+                },
+            },
+        },
+        parse: (raw) => ScrollToArgs.parse(raw ?? {}),
+        handler: async (session, args) => {
+            const p = session.requirePage();
+            const { x, y, behavior } = args;
+            await p.evaluate(({ x, y, behavior }) => window.scrollTo({ left: x, top: y, behavior }), { x, y, behavior });
+            return toolOk(`Scrolled to position (${x}, ${y})`);
+        },
+    },
+    {
+        definition: {
+            name: "scrollIntoView",
+            description: "Scroll element into view",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    selector: {
+                        type: "string",
+                        description: "CSS selector for the element to scroll into view",
+                    },
+                },
+                required: ["selector"],
+            },
+        },
+        parse: (raw) => SelectorArgs.parse(raw),
+        handler: async (session, args) => {
+            const p = session.requirePage();
+            const { selector } = args;
+            await p.locator(selector).scrollIntoViewIfNeeded();
+            return toolOk(`Scrolled ${selector} into view`);
+        },
+    },
+];

package/dist/validation/schemas.d.ts

@@ -0,0 +1,86 @@
+import { z } from "zod";
+export declare const ConnectArgs: z.ZodObject<{
+    port: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+}, z.core.$strip>;
+export declare const LaunchArgs: z.ZodObject<{
+    appPath: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    env: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>>;
+    headless: z.ZodDefault<z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodBoolean>>>;
+}, z.core.$strip>;
+export declare const EmptyArgs: z.ZodObject<{}, z.core.$strip>;
+export declare const ScreenshotArgs: z.ZodObject<{
+    fullPage: z.ZodDefault<z.ZodOptional<z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodBoolean>>>;
+}, z.core.$strip>;
+export declare const SelectorArgs: z.ZodObject<{
+    selector: z.ZodString;
+}, z.core.$strip>;
+export declare const FillArgs: z.ZodObject<{
+    selector: z.ZodString;
+    text: z.ZodString;
+}, z.core.$strip>;
+export declare const TypeArgs: z.ZodObject<{
+    selector: z.ZodString;
+    text: z.ZodString;
+}, z.core.$strip>;
+export declare const PressArgs: z.ZodObject<{
+    key: z.ZodString;
+}, z.core.$strip>;
+export declare const WaitArgs: z.ZodObject<{
+    selector: z.ZodString;
+    state: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        visible: "visible";
+        hidden: "hidden";
+        attached: "attached";
+        detached: "detached";
+    }>>>;
+    waitTimeoutMs: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+}, z.core.$strip>;
+export declare const EvaluateArgs: z.ZodObject<{
+    script: z.ZodString;
+}, z.core.$strip>;
+export declare const DragArgs: z.ZodObject<{
+    source: z.ZodString;
+    target: z.ZodString;
+}, z.core.$strip>;
+export declare const SelectOptionArgs: z.ZodObject<{
+    selector: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strip>;
+export declare const GetAttributeArgs: z.ZodObject<{
+    selector: z.ZodString;
+    attribute: z.ZodString;
+}, z.core.$strip>;
+export declare const ScrollArgs: z.ZodObject<{
+    deltaX: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+    deltaY: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+}, z.core.$strip>;
+export declare const ScrollToArgs: z.ZodObject<{
+    x: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+    y: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+    behavior: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        smooth: "smooth";
+    }>>>;
+}, z.core.$strip>;
+export declare const MouseMoveArgs: z.ZodObject<{
+    x: z.ZodCoercedNumber<unknown>;
+    y: z.ZodCoercedNumber<unknown>;
+    steps: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+}, z.core.$strip>;
+export declare const MouseButtonArgs: z.ZodObject<{
+    button: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        left: "left";
+        right: "right";
+        middle: "middle";
+    }>>>;
+}, z.core.$strip>;
+export declare const MouseClickArgs: z.ZodObject<{
+    x: z.ZodCoercedNumber<unknown>;
+    y: z.ZodCoercedNumber<unknown>;
+    button: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        left: "left";
+        right: "right";
+        middle: "middle";
+    }>>>;
+    clickCount: z.ZodDefault<z.ZodOptional<z.ZodCoercedNumber<unknown>>>;
+}, z.core.$strip>;

package/dist/validation/schemas.js

@@ -0,0 +1,84 @@
+import { z } from "zod";
+// Use z.coerce for backward compat (clients may send "9222" as string)
+/** Coerce string booleans correctly ("false" → false, not true). */
+const coerceBool = z.preprocess((val) => {
+    if (typeof val === "string") {
+        if (val === "true" || val === "1")
+            return true;
+        if (val === "false" || val === "0" || val === "")
+            return false;
+    }
+    return val;
+}, z.boolean());
+export const ConnectArgs = z.object({
+    port: z.coerce.number().int().positive().optional().default(9222),
+});
+export const LaunchArgs = z.object({
+    appPath: z.string().optional().default("./out/main/index.js"),
+    env: z.record(z.string(), z.string()).optional().default({}),
+    headless: coerceBool.optional().default(false),
+});
+export const EmptyArgs = z.object({});
+export const ScreenshotArgs = z.object({
+    fullPage: coerceBool.optional().default(false),
+});
+export const SelectorArgs = z.object({
+    selector: z.string().min(1),
+});
+export const FillArgs = z.object({
+    selector: z.string().min(1),
+    text: z.string(),
+});
+export const TypeArgs = z.object({
+    selector: z.string().min(1),
+    text: z.string(),
+});
+export const PressArgs = z.object({
+    key: z.string().min(1),
+});
+export const WaitArgs = z.object({
+    selector: z.string().min(1),
+    state: z
+        .enum(["visible", "hidden", "attached", "detached"])
+        .optional()
+        .default("visible"),
+    waitTimeoutMs: z.coerce.number().positive().optional().default(5000),
+});
+export const EvaluateArgs = z.object({
+    script: z.string().min(1),
+});
+export const DragArgs = z.object({
+    source: z.string().min(1),
+    target: z.string().min(1),
+});
+export const SelectOptionArgs = z.object({
+    selector: z.string().min(1),
+    value: z.string(),
+});
+export const GetAttributeArgs = z.object({
+    selector: z.string().min(1),
+    attribute: z.string().min(1),
+});
+export const ScrollArgs = z.object({
+    deltaX: z.coerce.number().optional().default(0),
+    deltaY: z.coerce.number().optional().default(0),
+});
+export const ScrollToArgs = z.object({
+    x: z.coerce.number().optional().default(0),
+    y: z.coerce.number().optional().default(0),
+    behavior: z.enum(["auto", "smooth"]).optional().default("auto"),
+});
+export const MouseMoveArgs = z.object({
+    x: z.coerce.number(),
+    y: z.coerce.number(),
+    steps: z.coerce.number().int().positive().optional().default(1),
+});
+export const MouseButtonArgs = z.object({
+    button: z.enum(["left", "right", "middle"]).optional().default("left"),
+});
+export const MouseClickArgs = z.object({
+    x: z.coerce.number(),
+    y: z.coerce.number(),
+    button: z.enum(["left", "right", "middle"]).optional().default("left"),
+    clickCount: z.coerce.number().int().positive().optional().default(1),
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@teapotz/electron-mcp",
+  "version": "0.1.1",
+  "description": "Electron UI automation via Playwright",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "electron-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "electron",
+    "testing",
+    "mcp",
+    "model-context-protocol",
+    "playwright",
+    "automation",
+    "e2e",
+    "end-to-end"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome lint src/ tests/",
+    "format": "biome format --write src/ tests/",
+    "format:check": "biome format src/ tests/",
+    "test": "bun test tests/unit/ tests/characterization.test.ts",
+    "test:unit": "bun test tests/unit/",
+    "test:characterization": "bun test tests/characterization.test.ts",
+    "test:integration": "bun test tests/integration/",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "playwright": "^1.58.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/bun": "^1.2.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}