electron-dev-bridge 0.1.0

package/dist/cdp-tools/lifecycle.js

@@ -0,0 +1,78 @@
+import { spawn } from 'node:child_process';
+import { join, resolve } from 'node:path';
+import { toolResult } from './helpers.js';
+export function createLifecycleTools(ctx) {
+    const { bridge, appConfig, state } = ctx;
+    return [
+        {
+            definition: {
+                name: 'electron_launch',
+                description: 'Launch an Electron application with remote debugging enabled and connect to it via CDP.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        appPath: {
+                            type: 'string',
+                            description: 'Path to the Electron app directory. Defaults to the path set in the SDK config.',
+                        },
+                        args: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'Additional command-line arguments to pass to Electron.',
+                        },
+                    },
+                },
+            },
+            handler: async ({ appPath, args = [] } = {}) => {
+                const rawPath = appPath || appConfig.path;
+                if (!rawPath) {
+                    throw new Error('No app path provided. Pass appPath or set app.path in your config.');
+                }
+                const resolvedAppPath = resolve(rawPath);
+                const debugPort = appConfig.debugPort || 9229;
+                const electronBin = appConfig.electronBin || join(resolvedAppPath, 'node_modules', '.bin', 'electron');
+                const child = spawn(electronBin, [`--remote-debugging-port=${debugPort}`, resolvedAppPath, ...args], { stdio: ['ignore', 'ignore', 'pipe'] });
+                state.electronProcess = child;
+                const stderrChunks = [];
+                child.stderr.on('data', (chunk) => stderrChunks.push(chunk.toString()));
+                child.on('exit', () => {
+                    state.electronProcess = null;
+                });
+                await new Promise(r => setTimeout(r, 2000));
+                if (child.exitCode !== null) {
+                    throw new Error(`Electron process exited immediately with code ${child.exitCode}. ` +
+                        `stderr: ${stderrChunks.join('')}. ` +
+                        'Check that the app path is correct and Electron is installed.');
+                }
+                await bridge.connect();
+                return toolResult({
+                    pid: child.pid,
+                    debugPort,
+                    connected: true,
+                    stderr: stderrChunks.join(''),
+                });
+            },
+        },
+        {
+            definition: {
+                name: 'electron_connect',
+                description: 'Connect to an already-running Electron app via Chrome DevTools Protocol.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        port: {
+                            type: 'number',
+                            description: 'CDP debugging port. Defaults to app.debugPort in config or 9229.',
+                        },
+                    },
+                },
+            },
+            handler: async ({ port } = {}) => {
+                const targetPort = port || appConfig.debugPort || 9229;
+                bridge.setPort(targetPort);
+                await bridge.connect();
+                return toolResult({ connected: true, port: targetPort });
+            },
+        },
+    ];
+}

package/dist/cdp-tools/navigation.d.ts

@@ -0,0 +1,2 @@
+import type { CdpTool, ToolContext } from './types.js';
+export declare function createNavigationTools(ctx: ToolContext): CdpTool[];

package/dist/cdp-tools/navigation.js

@@ -0,0 +1,128 @@
+import { evaluateSelector, toolResult } from './helpers.js';
+export function createNavigationTools(ctx) {
+    const { bridge } = ctx;
+    return [
+        {
+            definition: {
+                name: 'electron_wait_for_selector',
+                description: 'Wait for a DOM element matching a CSS selector to appear, polling until found or timeout.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        selector: {
+                            type: 'string',
+                            description: 'CSS selector to wait for.',
+                        },
+                        timeout: {
+                            type: 'number',
+                            description: 'Maximum time to wait in milliseconds. Defaults to 5000.',
+                        },
+                    },
+                    required: ['selector'],
+                },
+            },
+            handler: async ({ selector, timeout = 5000 }) => {
+                bridge.ensureConnected();
+                const interval = 250;
+                let elapsed = 0;
+                while (elapsed < timeout) {
+                    const found = await bridge.evaluate(`!!document.querySelector(${JSON.stringify(selector)})`);
+                    if (found) {
+                        return toolResult({ found: true, selector, elapsed });
+                    }
+                    await new Promise(r => setTimeout(r, interval));
+                    elapsed += interval;
+                }
+                throw new Error(`Timeout after ${timeout}ms waiting for selector "${selector}". ` +
+                    'The element may not exist yet, or the selector may be incorrect. ' +
+                    'Try increasing the timeout or verifying the selector.');
+            },
+        },
+        {
+            definition: {
+                name: 'electron_set_viewport',
+                description: 'Set the viewport dimensions of the Electron window for responsive testing.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        width: {
+                            type: 'number',
+                            description: 'Viewport width in pixels.',
+                        },
+                        height: {
+                            type: 'number',
+                            description: 'Viewport height in pixels.',
+                        },
+                    },
+                    required: ['width', 'height'],
+                },
+            },
+            handler: async ({ width, height }) => {
+                bridge.ensureConnected();
+                const client = bridge.getRawClient();
+                await client.Emulation.setDeviceMetricsOverride({
+                    width,
+                    height,
+                    deviceScaleFactor: 1,
+                    mobile: false,
+                });
+                return toolResult({ width, height });
+            },
+        },
+        {
+            definition: {
+                name: 'electron_scroll',
+                description: 'Scroll the page or a specific element in a given direction.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        direction: {
+                            type: 'string',
+                            description: 'Scroll direction: "up", "down", "left", or "right". Defaults to "down".',
+                        },
+                        amount: {
+                            type: 'number',
+                            description: 'Number of pixels to scroll. Defaults to 500.',
+                        },
+                        selector: {
+                            type: 'string',
+                            description: 'CSS selector of a scrollable element. If omitted, scrolls the page window.',
+                        },
+                    },
+                },
+            },
+            handler: async ({ direction = 'down', amount = 500, selector } = {}) => {
+                bridge.ensureConnected();
+                let dx = 0;
+                let dy = 0;
+                switch (direction) {
+                    case 'up':
+                        dy = -amount;
+                        break;
+                    case 'down':
+                        dy = amount;
+                        break;
+                    case 'left':
+                        dx = -amount;
+                        break;
+                    case 'right':
+                        dx = amount;
+                        break;
+                    default:
+                        throw new Error(`Invalid direction: "${direction}". Use "up", "down", "left", or "right".`);
+                }
+                if (selector) {
+                    const result = await evaluateSelector(bridge, selector, `(el.scrollBy(${dx}, ${dy}), { success: true, scrollTop: el.scrollTop, scrollLeft: el.scrollLeft })`);
+                    return toolResult(result);
+                }
+                const result = await bridge.evaluate(`
+          (() => {
+            window.scrollBy(${dx}, ${dy});
+            return { success: true, scrollX: window.scrollX, scrollY: window.scrollY };
+          })()
+        `);
+                return toolResult(result);
+            },
+        },
+    ];
+}

package/dist/cdp-tools/state.d.ts

@@ -0,0 +1,2 @@
+import type { CdpTool, ToolContext } from './types.js';
+export declare function createStateTools(ctx: ToolContext): CdpTool[];

package/dist/cdp-tools/state.js

@@ -0,0 +1,109 @@
+import { evaluateSelector, getBoundingBox, toolResult } from './helpers.js';
+export function createStateTools(ctx) {
+    const { bridge } = ctx;
+    return [
+        {
+            definition: {
+                name: 'electron_get_text',
+                description: 'Get the innerText of a DOM element by CSS selector.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        selector: {
+                            type: 'string',
+                            description: 'CSS selector of the element.',
+                        },
+                    },
+                    required: ['selector'],
+                },
+            },
+            handler: async ({ selector }) => {
+                bridge.ensureConnected();
+                const text = await evaluateSelector(bridge, selector, 'el.innerText');
+                return toolResult({ text });
+            },
+        },
+        {
+            definition: {
+                name: 'electron_get_value',
+                description: 'Get the value property of an input, textarea, or select element.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        selector: {
+                            type: 'string',
+                            description: 'CSS selector of the form element.',
+                        },
+                    },
+                    required: ['selector'],
+                },
+            },
+            handler: async ({ selector }) => {
+                bridge.ensureConnected();
+                const value = await evaluateSelector(bridge, selector, 'el.value');
+                return toolResult({ value });
+            },
+        },
+        {
+            definition: {
+                name: 'electron_get_attribute',
+                description: 'Get a specific attribute value from a DOM element.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        selector: {
+                            type: 'string',
+                            description: 'CSS selector of the element.',
+                        },
+                        attribute: {
+                            type: 'string',
+                            description: "Attribute name to read (e.g. 'href', 'src', 'data-id').",
+                        },
+                    },
+                    required: ['selector', 'attribute'],
+                },
+            },
+            handler: async ({ selector, attribute }) => {
+                bridge.ensureConnected();
+                const value = await evaluateSelector(bridge, selector, `el.getAttribute(${JSON.stringify(attribute)})`);
+                return toolResult({ attribute, value });
+            },
+        },
+        {
+            definition: {
+                name: 'electron_get_bounding_box',
+                description: 'Get the position and dimensions of a DOM element (x, y, width, height).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        selector: {
+                            type: 'string',
+                            description: 'CSS selector of the element.',
+                        },
+                    },
+                    required: ['selector'],
+                },
+            },
+            handler: async ({ selector }) => {
+                bridge.ensureConnected();
+                const box = await getBoundingBox(bridge, selector);
+                return toolResult({ x: box.x, y: box.y, width: box.width, height: box.height });
+            },
+        },
+        {
+            definition: {
+                name: 'electron_get_url',
+                description: 'Get the current page URL of the Electron app.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            },
+            handler: async () => {
+                bridge.ensureConnected();
+                const url = await bridge.evaluate('window.location.href');
+                return toolResult({ url });
+            },
+        },
+    ];
+}

package/dist/cdp-tools/types.d.ts

@@ -0,0 +1,22 @@
+import type { ChildProcess } from 'node:child_process';
+import type { AppConfig } from '../index.js';
+import type { CdpBridge } from '../server/cdp-bridge.js';
+export interface CdpToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, any>;
+}
+export interface CdpTool {
+    definition: CdpToolDefinition;
+    handler: (args: any) => Promise<any>;
+}
+export interface ToolContext {
+    bridge: CdpBridge;
+    appConfig: AppConfig;
+    screenshotDir: string;
+    screenshotFormat: 'png' | 'jpeg';
+    state: {
+        screenshotCounter: number;
+        electronProcess: ChildProcess | null;
+    };
+}

package/dist/cdp-tools/types.js

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

package/dist/cdp-tools/visual.d.ts

@@ -0,0 +1,2 @@
+import type { CdpTool, ToolContext } from './types.js';
+export declare function createVisualTools(ctx: ToolContext): CdpTool[];

package/dist/cdp-tools/visual.js

@@ -0,0 +1,130 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getBoundingBox, toolResult } from './helpers.js';
+export function createVisualTools(ctx) {
+    const { bridge, screenshotDir, screenshotFormat, state } = ctx;
+    return [
+        {
+            definition: {
+                name: 'electron_screenshot',
+                description: 'Take a screenshot of the entire page or a specific element. Saves to disk and returns the file path.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        selector: {
+                            type: 'string',
+                            description: 'CSS selector of an element to screenshot. If omitted, captures the full page.',
+                        },
+                        fullPage: {
+                            type: 'boolean',
+                            description: 'Capture the full scrollable page (not just the viewport). Defaults to true.',
+                        },
+                    },
+                },
+            },
+            handler: async ({ selector, fullPage = true } = {}) => {
+                bridge.ensureConnected();
+                const captureParams = { format: screenshotFormat };
+                if (selector) {
+                    const box = await getBoundingBox(bridge, selector);
+                    captureParams.clip = {
+                        x: box.x,
+                        y: box.y,
+                        width: box.width,
+                        height: box.height,
+                        scale: 1,
+                    };
+                }
+                else if (fullPage) {
+                    captureParams.captureBeyondViewport = true;
+                }
+                const client = bridge.getRawClient();
+                const { data } = await client.Page.captureScreenshot(captureParams);
+                mkdirSync(screenshotDir, { recursive: true });
+                state.screenshotCounter++;
+                const filename = `screenshot-${Date.now()}-${state.screenshotCounter}.${screenshotFormat}`;
+                const filepath = join(screenshotDir, filename);
+                const buffer = Buffer.from(data, 'base64');
+                writeFileSync(filepath, buffer);
+                return toolResult({
+                    path: filepath,
+                    filename,
+                    base64Length: data.length,
+                    selector: selector || null,
+                });
+            },
+        },
+        {
+            definition: {
+                name: 'electron_compare_screenshots',
+                description: 'Compare two screenshot files byte-by-byte and report whether they are identical or how much they differ.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        pathA: {
+                            type: 'string',
+                            description: 'Absolute path to the first screenshot file.',
+                        },
+                        pathB: {
+                            type: 'string',
+                            description: 'Absolute path to the second screenshot file.',
+                        },
+                    },
+                    required: ['pathA', 'pathB'],
+                },
+            },
+            handler: async ({ pathA, pathB }) => {
+                const [bufA, bufB] = await Promise.all([
+                    readFile(pathA),
+                    readFile(pathB),
+                ]);
+                const identical = bufA.equals(bufB);
+                let diffBytes = 0;
+                if (!identical) {
+                    const len = Math.max(bufA.length, bufB.length);
+                    for (let i = 0; i < len; i++) {
+                        if ((bufA[i] || 0) !== (bufB[i] || 0)) {
+                            diffBytes++;
+                        }
+                    }
+                }
+                const totalBytes = Math.max(bufA.length, bufB.length);
+                const diffPercent = totalBytes > 0
+                    ? parseFloat(((diffBytes / totalBytes) * 100).toFixed(2))
+                    : 0;
+                return toolResult({ identical, diffPercent, totalBytes, diffBytes });
+            },
+        },
+        {
+            definition: {
+                name: 'electron_highlight_element',
+                description: 'Temporarily highlight a DOM element with a red outline for visual identification (lasts 3 seconds).',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        selector: {
+                            type: 'string',
+                            description: 'CSS selector of the element to highlight.',
+                        },
+                    },
+                    required: ['selector'],
+                },
+            },
+            handler: async ({ selector }) => {
+                bridge.ensureConnected();
+                await bridge.evaluate(`
+          (() => {
+            const el = document.querySelector(${JSON.stringify(selector)});
+            if (!el) throw new Error('Element not found: ' + ${JSON.stringify(selector)} + '. Check the selector.');
+            const prev = el.style.outline;
+            el.style.outline = '3px solid red';
+            setTimeout(() => { el.style.outline = prev; }, 3000);
+            return true;
+          })()
+        `);
+                return toolResult({ success: true, selector });
+            },
+        },
+    ];
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+const VERSION = '0.1.0';
+const command = process.argv[2];
+switch (command) {
+    case 'serve':
+    case undefined: {
+        const configPath = process.argv[3];
+        const { serve } = await import('./serve.js');
+        await serve(configPath);
+        break;
+    }
+    case 'init': {
+        const { init } = await import('./init.js');
+        await init();
+        break;
+    }
+    case 'register': {
+        const { register } = await import('./register.js');
+        await register();
+        break;
+    }
+    case 'validate': {
+        const { validate } = await import('./validate.js');
+        await validate();
+        break;
+    }
+    case '--version':
+    case '-v':
+        console.log(VERSION);
+        break;
+    case '--help':
+    case '-h':
+    case 'help':
+    default:
+        console.log(`electron-dev-bridge v${VERSION}
+
+Commands:
+  serve [config]    Start the MCP server (default)
+  init              Scaffold a config file from source code
+  register          Register with Claude Code
+  validate          Validate config and check readiness
+
+Usage:
+  npx electron-mcp serve
+  npx electron-mcp init
+  npx electron-mcp register
+  npx electron-mcp validate`);
+        break;
+}
+export {};

package/dist/cli/init.d.ts

@@ -0,0 +1 @@
+export declare function init(): Promise<void>;