@teapotz/electron-mcp 0.1.1

package/README.md

@@ -0,0 +1,288 @@
+# Electron MCP
+
+MCP (Model Context Protocol) server for testing Electron applications using Playwright. Enables AI models like Claude to interact with and test your Electron apps.
+
+## 🚀 Quick Start
+
+```bash
+# Run directly with npx
+npx @teapotz/electron-mcp
+
+# Or install globally
+npm install -g @teapotz/electron-mcp
+electron-mcp
+```
+
+## Features
+
+- **Two Connection Modes**
+  - **CDP Mode**: Connect to a running Electron app via Chrome DevTools Protocol
+  - **Launch Mode**: Launch a fresh Electron app instance for testing
+- **Full Playwright API**: screenshot, click, fill, type, hover, press, wait, evaluate, and more
+- **Accessibility Snapshots**: Get the accessibility tree for element discovery
+- **Main Process Access**: Execute code in Electron's main process (launch mode only)
+
+## How It Works
+
+```
+User <--> AI Model (Claude) <--> MCP Protocol <--> electron-mcp <--> Electron App
+```
+
+1. **User**: "Click the login button and fill in the email field"
+2. **AI Model**: Determines which MCP tools to use
+3. **MCP Protocol**: Standardized communication
+4. **electron-mcp**: Executes Playwright commands on the Electron app
+5. **Electron App**: Actions are performed in the actual application
+
+## Configuration
+
+### Claude Desktop / MCP Clients
+
+Add to your MCP configuration file:
+
+```json
+{
+  "mcpServers": {
+    "electron-test": {
+      "command": "npx",
+      "args": ["@teapotz/electron-mcp"]
+    }
+  }
+}
+```
+
+### OpenCode
+
+```json
+{
+  "mcp": {
+    "electron-test": {
+      "type": "local",
+      "command": ["npx", "@teapotz/electron-mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+## Connection Modes
+
+### CDP Mode (Recommended for Development)
+
+Connect to an already running Electron app with remote debugging enabled:
+
+```bash
+# Start your Electron app with debugging port
+electron your-app --remote-debugging-port=9222
+
+# Or with electron-vite
+electron-vite dev -- --remote-debugging-port=9222
+```
+
+Then use the `connect` tool:
+
+```
+connect({ port: 9222 })
+```
+
+**Advantages:**
+
+- Works with your existing dev workflow
+- App state preserved between tests
+- Hot reload still works
+
+### Launch Mode
+
+Launch a fresh Electron app instance:
+
+```
+launch({ appPath: "./out/main/index.js" })
+
+# With headless mode for CI
+launch({ appPath: "./out/main/index.js", headless: true })
+```
+
+**Advantages:**
+
+- Clean state for each test
+- Access to main process via `evaluateMain`
+- Can pass custom environment variables
+- Supports headless mode for CI/automation
+
+## Headless Mode (CI/Automation)
+
+### Launch Mode
+
+Pass `headless: true` to run without a visible window:
+
+```
+launch({ appPath: "./out/main/index.js", headless: true })
+```
+
+### CDP Mode
+
+Start your Electron app with headless flags before connecting:
+
+```bash
+# Option 1: Electron headless flag (Electron 28+)
+electron your-app --headless=new --remote-debugging-port=9222
+
+# Option 2: xvfb (Linux) - virtual framebuffer
+xvfb-run electron your-app --remote-debugging-port=9222
+
+# Option 3: xvfb with specific display (CI environments)
+Xvfb :99 -screen 0 1920x1080x24 &
+DISPLAY=:99 electron your-app --remote-debugging-port=9222
+```
+
+Then connect normally:
+
+```
+connect({ port: 9222 })
+```
+
+## Available Tools
+
+### Connection
+
+| Tool         | Description                             |
+| ------------ | --------------------------------------- |
+| `connect`    | Connect to running app via CDP          |
+| `disconnect` | Disconnect from CDP (app keeps running) |
+| `launch`     | Launch new Electron app instance        |
+| `close`      | Close launched app                      |
+
+### Interaction
+
+| Tool           | Description                         |
+| -------------- | ----------------------------------- |
+| `click`        | Click an element                    |
+| `dblclick`     | Double-click an element             |
+| `fill`         | Fill text into input (clears first) |
+| `type`         | Type text character by character    |
+| `hover`        | Hover over an element               |
+| `press`        | Press keyboard key                  |
+| `drag`         | Drag and drop                       |
+| `selectOption` | Select from dropdown                |
+
+### Scroll
+
+| Tool              | Description                          |
+| ----------------- | ------------------------------------ |
+| `scroll`          | Scroll using mouse wheel (deltaX/Y)  |
+| `scrollTo`        | Scroll to absolute position          |
+| `scrollIntoView`  | Scroll element into view             |
+
+### Mouse
+
+| Tool           | Description                              |
+| -------------- | ---------------------------------------- |
+| `mouseMove`    | Move mouse cursor to coordinates         |
+| `mouseDown`    | Press mouse button down                  |
+| `mouseUp`      | Release mouse button                     |
+| `mouseClick`   | Click at specific coordinates            |
+
+### Inspection
+
+| Tool           | Description                            |
+| -------------- | -------------------------------------- |
+| `screenshot`   | Take screenshot (returns base64 image) |
+| `snapshot`     | Get accessibility tree                 |
+| `getText`      | Get element text content               |
+| `getAttribute` | Get element attribute                  |
+| `isVisible`    | Check if element is visible            |
+| `count`        | Count matching elements                |
+
+### Advanced
+
+| Tool           | Description                                 |
+| -------------- | ------------------------------------------- |
+| `wait`         | Wait for element state                      |
+| `evaluate`     | Run JS in renderer process                  |
+| `evaluateMain` | Run code in main process (launch mode only) |
+
+## Selectors
+
+Supports all Playwright selectors:
+
+```
+# CSS selectors
+[data-testid="submit-btn"]
+.my-class
+#my-id
+
+# Text selectors
+text=Submit
+text="Exact Match"
+
+# Role selectors
+role=button[name="Submit"]
+
+# Combining
+.form >> text=Submit
+```
+
+## Usage Examples
+
+### Basic Test Flow
+
+```
+1. connect({ port: 9222 })
+2. snapshot()  // See the page structure
+3. click('[data-testid="login-btn"]')
+4. fill('[data-testid="email"]', 'test@example.com')
+5. fill('[data-testid="password"]', 'password123')
+6. click('text=Sign In')
+7. wait({ selector: '[data-testid="dashboard"]' })
+8. screenshot()
+```
+
+### Main Process Access (Launch Mode)
+
+```javascript
+// Get app version
+evaluateMain({
+  script: "({ app }) => app.getVersion()",
+});
+
+// Show dialog
+evaluateMain({
+  script: "({ dialog }) => dialog.showMessageBox({ message: 'Hello!' })",
+});
+```
+
+### With AI Assistant
+
+You can ask Claude or other AI assistants to test your Electron app:
+
+```
+Connect to my Electron app running on port 9222 and:
+1. Take a screenshot of the current state
+2. Click the "Settings" button in the sidebar
+3. Change the theme to dark mode
+4. Verify the theme changed by checking the background color
+```
+
+## Tips for Testable Electron Apps
+
+1. **Add `data-testid` attributes** to important elements
+2. **Enable remote debugging** in development: `--remote-debugging-port=9222`
+3. **Use semantic HTML** for better accessibility snapshots
+4. **Keep selectors stable** - prefer `data-testid` over classes
+
+## Development
+
+```bash
+# Clone repository
+git clone https://github.com/teapotz/electron-mcp.git
+cd electron-mcp
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run locally
+node dist/index.js
+```

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+export declare class NotConnectedError extends Error {
+    constructor(message?: string);
+}
+export declare class NotLaunchedError extends Error {
+    constructor(message?: string);
+}
+export declare function classifyPlaywrightError(error: unknown): {
+    message: string;
+    category: string;
+    remediation: string;
+};

package/dist/errors.js

@@ -0,0 +1,48 @@
+export class NotConnectedError extends Error {
+    constructor(message = "Not connected. Call connect or launch first.") {
+        super(message);
+        this.name = "NotConnectedError";
+    }
+}
+export class NotLaunchedError extends Error {
+    constructor(message = "Not connected. Call launch first.") {
+        super(message);
+        this.name = "NotLaunchedError";
+    }
+}
+export function classifyPlaywrightError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/timeout/i.test(message)) {
+        return {
+            message,
+            category: "Timeout",
+            remediation: "Increase timeout or check selector",
+        };
+    }
+    if (/no node found|no element/i.test(message)) {
+        return {
+            message,
+            category: "ElementNotFound",
+            remediation: "Verify selector with snapshot()",
+        };
+    }
+    if (/target closed|target page/i.test(message)) {
+        return {
+            message,
+            category: "TargetClosed",
+            remediation: "Reconnect to the application",
+        };
+    }
+    if (/protocol error/i.test(message)) {
+        return {
+            message,
+            category: "ProtocolError",
+            remediation: "Check that the application is still running",
+        };
+    }
+    return {
+        message,
+        category: "Unknown",
+        remediation: "Check the error message for details",
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { SessionController } from "./session/SessionController.js";
+export declare function createServer(): {
+    server: Server;
+    session: SessionController;
+};

package/dist/index.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { SessionController } from "./session/SessionController.js";
+import { buildRegistry, dispatch } from "./tools/registry.js";
+const require = createRequire(import.meta.url);
+const { name: PKG_NAME, version: PKG_VERSION } = require("../package.json");
+// ---------------------------------------------------------------------------
+// Server factory (exported for testing)
+// ---------------------------------------------------------------------------
+export function createServer() {
+    const session = new SessionController();
+    const registry = buildRegistry();
+    const server = new Server({ name: PKG_NAME, version: PKG_VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [...registry.values()].map((spec) => spec.definition),
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        return dispatch(registry, session, name, args);
+    });
+    return { server, session };
+}
+// ---------------------------------------------------------------------------
+// Main entry point (only runs when executed directly, not when imported)
+// ---------------------------------------------------------------------------
+const modulePath = fileURLToPath(import.meta.url);
+const isMainModule = (() => {
+    if (typeof process === "undefined" || !process.argv[1])
+        return false;
+    try {
+        // npm/npx binaries are often symlinks; compare real paths first.
+        return realpathSync(process.argv[1]) === realpathSync(modulePath);
+    }
+    catch {
+        return path.resolve(process.argv[1]) === path.resolve(modulePath);
+    }
+})();
+if (isMainModule) {
+    const flag = process.argv[2];
+    if (flag === "--version" || flag === "-v") {
+        console.error(`${PKG_NAME} ${PKG_VERSION}`);
+        process.exit(0);
+    }
+    if (flag === "--help" || flag === "-h") {
+        console.error(`${PKG_NAME} ${PKG_VERSION}
+Electron UI automation via Playwright, exposed as an MCP server.
+
+Usage:
+  electron-mcp              Start the MCP server (communicates over stdio)
+  electron-mcp --help       Show this help message
+  electron-mcp --version    Show version
+
+Environment variables:
+  ELECTRON_MCP_TIMEOUT_MS   Default timeout for Playwright operations (default: 30000)
+
+Connection modes:
+  connect   Attach to a running Electron app via CDP (--remote-debugging-port)
+  launch    Launch a fresh Electron instance with full main-process access
+
+Documentation: https://github.com/teapotznet/electron-mcp`);
+        process.exit(0);
+    }
+    const { server, session } = createServer();
+    let shuttingDown = false;
+    async function cleanup() {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        await session.cleanup();
+    }
+    process.on("SIGTERM", () => void cleanup().finally(() => process.exit(143)));
+    process.on("SIGINT", () => void cleanup().finally(() => process.exit(130)));
+    const transport = new StdioServerTransport();
+    server.connect(transport).catch(console.error);
+}

package/dist/protocol/responses.d.ts

@@ -0,0 +1,4 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare function toolOk(text: string): CallToolResult;
+export declare function toolError(text: string): CallToolResult;
+export declare function toolImage(base64: string): CallToolResult;

package/dist/protocol/responses.js

@@ -0,0 +1,22 @@
+export function toolOk(text) {
+    return {
+        content: [{ type: "text", text }],
+    };
+}
+export function toolError(text) {
+    return {
+        content: [{ type: "text", text }],
+        isError: true,
+    };
+}
+export function toolImage(base64) {
+    return {
+        content: [
+            {
+                type: "image",
+                data: base64,
+                mimeType: "image/png",
+            },
+        ],
+    };
+}

package/dist/session/SessionController.d.ts

@@ -0,0 +1,19 @@
+import { type ElectronApplication, type Page } from "playwright";
+import type { ConnectionMode, LaunchOptions } from "./types.js";
+export declare class SessionController {
+    private electronApp;
+    private cdpBrowser;
+    private page;
+    private mode;
+    private mutex;
+    requirePage(): Page;
+    requireElectronApp(): ElectronApplication;
+    get connectionMode(): ConnectionMode;
+    get isConnected(): boolean;
+    private withMutex;
+    connectCdp(port: number): Promise<string>;
+    launch(opts: LaunchOptions): Promise<string>;
+    disconnect(): Promise<void>;
+    close(): Promise<void>;
+    cleanup(): Promise<void>;
+}

package/dist/session/SessionController.js

@@ -0,0 +1,145 @@
+import { _electron, chromium, } from "playwright";
+import { NotConnectedError, NotLaunchedError } from "../errors.js";
+const DEFAULT_TIMEOUT_MS = Number(process.env.ELECTRON_MCP_TIMEOUT_MS ?? 30_000);
+export class SessionController {
+    electronApp = null;
+    cdpBrowser = null;
+    page = null;
+    mode = null;
+    mutex = Promise.resolve();
+    // ----- Guards -----
+    requirePage() {
+        if (!this.page)
+            throw new NotConnectedError();
+        return this.page;
+    }
+    requireElectronApp() {
+        if (!this.electronApp)
+            throw new NotLaunchedError();
+        return this.electronApp;
+    }
+    get connectionMode() {
+        return this.mode;
+    }
+    get isConnected() {
+        return this.page !== null;
+    }
+    // ----- Mutex for state-mutating operations -----
+    withMutex(fn) {
+        const result = this.mutex.then(fn);
+        this.mutex = result.then(() => { }, () => { });
+        return result;
+    }
+    // ----- Connection lifecycle -----
+    async connectCdp(port) {
+        return this.withMutex(async () => {
+            if (this.page) {
+                throw new Error("Already connected. Disconnect first.");
+            }
+            const browser = await chromium.connectOverCDP(`http://localhost:${port}`);
+            try {
+                browser.on("disconnected", () => {
+                    this.cdpBrowser = null;
+                    this.page = null;
+                    this.mode = null;
+                });
+                const contexts = browser.contexts();
+                if (contexts.length === 0) {
+                    throw new Error("No browser contexts found.");
+                }
+                const pages = contexts[0].pages();
+                if (pages.length === 0) {
+                    throw new Error("No pages found.");
+                }
+                this.cdpBrowser = browser;
+                this.page = pages[0];
+                this.page.setDefaultTimeout(DEFAULT_TIMEOUT_MS);
+                this.page.setDefaultNavigationTimeout(DEFAULT_TIMEOUT_MS);
+                this.mode = "cdp";
+                return await this.page.title();
+            }
+            catch (error) {
+                await browser.close().catch(() => { });
+                throw error;
+            }
+        });
+    }
+    async launch(opts) {
+        return this.withMutex(async () => {
+            if (this.page) {
+                throw new Error("Already connected. Disconnect/close first.");
+            }
+            const launchArgs = [];
+            if (process.platform === "linux") {
+                const ozone = process.env.ELECTRON_OZONE_PLATFORM ??
+                    (process.env.WAYLAND_DISPLAY ? "wayland" : "x11");
+                launchArgs.push(`--ozone-platform=${ozone}`);
+            }
+            if (opts.headless) {
+                launchArgs.push("--headless=new", "--disable-gpu");
+            }
+            launchArgs.push(opts.appPath);
+            const app = await _electron.launch({
+                args: launchArgs,
+                env: { ...process.env, ...opts.env, TEST_MODE: "true" },
+            });
+            try {
+                const page = await app.firstWindow();
+                page.setDefaultTimeout(DEFAULT_TIMEOUT_MS);
+                page.setDefaultNavigationTimeout(DEFAULT_TIMEOUT_MS);
+                await page.waitForLoadState("domcontentloaded");
+                this.electronApp = app;
+                this.page = page;
+                this.mode = "electron";
+                return await page.title();
+            }
+            catch (error) {
+                await app.close().catch(() => { });
+                throw error;
+            }
+        });
+    }
+    async disconnect() {
+        return this.withMutex(async () => {
+            if (this.cdpBrowser) {
+                await this.cdpBrowser.close();
+                this.cdpBrowser = null;
+                this.page = null;
+                this.mode = null;
+            }
+        });
+    }
+    async close() {
+        return this.withMutex(async () => {
+            if (this.mode === "cdp") {
+                throw new Error("Cannot close CDP connection. Use disconnect instead (app keeps running).");
+            }
+            if (this.electronApp) {
+                await this.electronApp.close();
+                this.electronApp = null;
+                this.page = null;
+                this.mode = null;
+            }
+        });
+    }
+    async cleanup() {
+        try {
+            if (this.electronApp)
+                await this.electronApp.close();
+        }
+        catch {
+            /* best-effort */
+        }
+        try {
+            if (this.cdpBrowser)
+                await this.cdpBrowser.close();
+        }
+        catch {
+            /* best-effort */
+        }
+        this.electronApp = null;
+        this.cdpBrowser = null;
+        this.page = null;
+        this.mode = null;
+    }
+}

package/dist/session/types.d.ts

@@ -0,0 +1,6 @@
+export type ConnectionMode = "electron" | "cdp" | null;
+export interface LaunchOptions {
+    appPath: string;
+    env: Record<string, string>;
+    headless: boolean;
+}

package/dist/session/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/connection.tools.d.ts

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