electron-dev-bridge 0.1.1 → 0.2.1

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

@@ -0,0 +1,29 @@
+import type { CdpTool, ToolContext } from './types.js';
+export interface ConsoleEntry {
+    level: string;
+    message: string;
+    timestamp: number;
+}
+export interface NetworkEntry {
+    requestId: string;
+    method: string;
+    url: string;
+    status?: number;
+    statusText?: string;
+    error?: string;
+    startTime: number;
+    endTime?: number;
+    duration?: number;
+}
+export declare class DevtoolsStore {
+    console: ConsoleEntry[];
+    network: Map<string, NetworkEntry>;
+    private attached;
+    attach(client: any): void;
+    detach(): void;
+    clearConsole(): void;
+    clearNetwork(): void;
+    clearAll(): void;
+    getNetworkEntries(): NetworkEntry[];
+}
+export declare function createDevtoolsTools(ctx: ToolContext): CdpTool[];

package/dist/cdp-tools/devtools.js

@@ -0,0 +1,249 @@
+import { toolResult } from './helpers.js';
+const MAX_CONSOLE_ENTRIES = 1000;
+const MAX_NETWORK_ENTRIES = 500;
+const MAX_BODY_LENGTH = 1024;
+export class DevtoolsStore {
+    console = [];
+    network = new Map();
+    attached = false;
+    attach(client) {
+        if (this.attached)
+            return;
+        this.attached = true;
+        client.Runtime.consoleAPICalled(({ type, args, timestamp }) => {
+            const message = (args || [])
+                .map((a) => a.value ?? a.description ?? String(a.type))
+                .join(' ');
+            this.console.push({ level: type, message, timestamp });
+            if (this.console.length > MAX_CONSOLE_ENTRIES) {
+                this.console.splice(0, this.console.length - MAX_CONSOLE_ENTRIES);
+            }
+        });
+        client.Network.requestWillBeSent(({ requestId, request, timestamp }) => {
+            if (this.network.size >= MAX_NETWORK_ENTRIES) {
+                const oldest = this.network.keys().next().value;
+                this.network.delete(oldest);
+            }
+            this.network.set(requestId, {
+                requestId,
+                method: request.method,
+                url: request.url,
+                startTime: timestamp,
+            });
+        });
+        client.Network.responseReceived(({ requestId, response }) => {
+            const entry = this.network.get(requestId);
+            if (entry) {
+                entry.status = response.status;
+                entry.statusText = response.statusText;
+            }
+        });
+        client.Network.loadingFinished(({ requestId, timestamp }) => {
+            const entry = this.network.get(requestId);
+            if (entry) {
+                entry.endTime = timestamp;
+                entry.duration = Math.round((timestamp - entry.startTime) * 1000);
+            }
+        });
+        client.Network.loadingFailed(({ requestId, errorText }) => {
+            const entry = this.network.get(requestId);
+            if (entry) {
+                entry.error = errorText;
+            }
+        });
+    }
+    detach() {
+        this.attached = false;
+    }
+    clearConsole() {
+        this.console = [];
+    }
+    clearNetwork() {
+        this.network.clear();
+    }
+    clearAll() {
+        this.clearConsole();
+        this.clearNetwork();
+    }
+    getNetworkEntries() {
+        return Array.from(this.network.values());
+    }
+}
+export function createDevtoolsTools(ctx) {
+    const { bridge, state } = ctx;
+    return [
+        {
+            definition: {
+                name: 'electron_get_console_logs',
+                description: 'Get captured console messages from the Electron app. Captures console.log/info/warn/error/debug calls.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        level: {
+                            type: 'string',
+                            description: 'Filter by level: log, info, warn, error, debug. Comma-separated for multiple.',
+                        },
+                        search: {
+                            type: 'string',
+                            description: 'Filter by message content (case-insensitive substring match).',
+                        },
+                        limit: {
+                            type: 'number',
+                            description: 'Max results to return. Default: 100.',
+                        },
+                        since: {
+                            type: 'string',
+                            description: 'ISO timestamp — only return logs after this time.',
+                        },
+                    },
+                },
+            },
+            handler: async ({ level, search, limit = 100, since, } = {}) => {
+                bridge.ensureConnected();
+                const store = state.devtoolsStore;
+                if (!store)
+                    return toolResult({ logs: [], total: 0 });
+                let entries = store.console;
+                if (level) {
+                    const levels = new Set(level.split(',').map(l => l.trim().toLowerCase()));
+                    entries = entries.filter(e => levels.has(e.level));
+                }
+                if (search) {
+                    const lower = search.toLowerCase();
+                    entries = entries.filter(e => e.message.toLowerCase().includes(lower));
+                }
+                if (since) {
+                    const sinceTs = new Date(since).getTime() / 1000;
+                    entries = entries.filter(e => e.timestamp >= sinceTs);
+                }
+                const total = entries.length;
+                const logs = entries.slice(-limit).map(e => ({
+                    level: e.level,
+                    message: e.message.length > MAX_BODY_LENGTH
+                        ? e.message.slice(0, MAX_BODY_LENGTH) + '...'
+                        : e.message,
+                    timestamp: new Date(e.timestamp * 1000).toISOString(),
+                }));
+                return toolResult({ logs, total, returned: logs.length });
+            },
+        },
+        {
+            definition: {
+                name: 'electron_get_network_requests',
+                description: 'Get captured network requests from the Electron app. Captures all HTTP/HTTPS requests with status, timing, and errors.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        urlPattern: {
+                            type: 'string',
+                            description: 'Regex pattern to filter by URL.',
+                        },
+                        method: {
+                            type: 'string',
+                            description: 'HTTP method filter (e.g. GET, POST).',
+                        },
+                        errorsOnly: {
+                            type: 'boolean',
+                            description: 'Only return failed requests (4xx/5xx or network errors).',
+                        },
+                        limit: {
+                            type: 'number',
+                            description: 'Max results to return. Default: 50.',
+                        },
+                        since: {
+                            type: 'string',
+                            description: 'ISO timestamp — only return requests after this time.',
+                        },
+                    },
+                },
+            },
+            handler: async ({ urlPattern, method, errorsOnly, limit = 50, since, } = {}) => {
+                bridge.ensureConnected();
+                const store = state.devtoolsStore;
+                if (!store)
+                    return toolResult({ requests: [], total: 0 });
+                let entries = store.getNetworkEntries();
+                if (urlPattern) {
+                    const re = new RegExp(urlPattern, 'i');
+                    entries = entries.filter(e => re.test(e.url));
+                }
+                if (method) {
+                    const upper = method.toUpperCase();
+                    entries = entries.filter(e => e.method === upper);
+                }
+                if (errorsOnly) {
+                    entries = entries.filter(e => e.error || (e.status !== undefined && e.status >= 400));
+                }
+                if (since) {
+                    const sinceTs = new Date(since).getTime() / 1000;
+                    entries = entries.filter(e => e.startTime >= sinceTs);
+                }
+                const total = entries.length;
+                const requests = entries.slice(-limit).map(e => ({
+                    method: e.method,
+                    url: e.url.length > MAX_BODY_LENGTH
+                        ? e.url.slice(0, MAX_BODY_LENGTH) + '...'
+                        : e.url,
+                    status: e.status,
+                    statusText: e.statusText,
+                    error: e.error,
+                    duration: e.duration != null ? `${e.duration}ms` : undefined,
+                    timestamp: new Date(e.startTime * 1000).toISOString(),
+                }));
+                return toolResult({ requests, total, returned: requests.length });
+            },
+        },
+        {
+            definition: {
+                name: 'electron_clear_devtools_data',
+                description: 'Clear captured console logs and/or network request buffers.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        type: {
+                            type: 'string',
+                            enum: ['all', 'console', 'network'],
+                            description: 'What to clear. Default: all.',
+                        },
+                    },
+                },
+            },
+            handler: async ({ type = 'all' } = {}) => {
+                const store = state.devtoolsStore;
+                if (!store)
+                    return toolResult({ cleared: type });
+                if (type === 'console')
+                    store.clearConsole();
+                else if (type === 'network')
+                    store.clearNetwork();
+                else
+                    store.clearAll();
+                return toolResult({ cleared: type });
+            },
+        },
+        {
+            definition: {
+                name: 'electron_get_devtools_stats',
+                description: 'Get counts of captured console logs and network requests.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            },
+            handler: async () => {
+                const store = state.devtoolsStore;
+                if (!store)
+                    return toolResult({ console: 0, network: 0, capturing: false });
+                return toolResult({
+                    console: store.console.length,
+                    network: store.network.size,
+                    capturing: true,
+                    limits: {
+                        maxConsole: MAX_CONSOLE_ENTRIES,
+                        maxNetwork: MAX_NETWORK_ENTRIES,
+                    },
+                });
+            },
+        },
+    ];
+}

package/dist/cdp-tools/index.js

@@ -1,3 +1,4 @@
+import { createDevtoolsTools } from './devtools.js';
 import { createDomQueryTools } from './dom-query.js';
 import { createInteractionTools } from './interaction.js';
 import { createLifecycleTools } from './lifecycle.js';
@@ -13,6 +14,7 @@ export function getCdpTools(bridge, appConfig, screenshotConfig) {
         state: {
             screenshotCounter: 0,
             electronProcess: null,
+            devtoolsStore: null,
         },
     };
     return [
@@ -22,5 +24,6 @@ export function getCdpTools(bridge, appConfig, screenshotConfig) {
         ...createStateTools(ctx),
         ...createNavigationTools(ctx),
         ...createVisualTools(ctx),
+        ...createDevtoolsTools(ctx),
     ];
 }

package/dist/cdp-tools/lifecycle.js

@@ -1,6 +1,15 @@
 import { spawn } from 'node:child_process';
 import { join, resolve } from 'node:path';
+import { DevtoolsStore } from './devtools.js';
 import { toolResult } from './helpers.js';
+function attachDevtoolsStore(bridge, state) {
+    if (state.devtoolsStore) {
+        state.devtoolsStore.detach();
+    }
+    const store = new DevtoolsStore();
+    store.attach(bridge.getRawClient());
+    state.devtoolsStore = store;
+}
 export function createLifecycleTools(ctx) {
     const { bridge, appConfig, state } = ctx;
     return [
@@ -45,6 +54,7 @@ export function createLifecycleTools(ctx) {
                         'Check that the app path is correct and Electron is installed.');
                 }
                 await bridge.connect();
+                attachDevtoolsStore(bridge, state);
                 return toolResult({
                     pid: child.pid,
                     debugPort,
@@ -69,8 +79,12 @@ export function createLifecycleTools(ctx) {
             },
             handler: async ({ port } = {}) => {
                 const targetPort = port || appConfig.debugPort || 9229;
+                if (bridge.connected) {
+                    return toolResult({ connected: true, port: targetPort, message: 'Already connected' });
+                }
                 bridge.setPort(targetPort);
                 await bridge.connect();
+                attachDevtoolsStore(bridge, state);
                 return toolResult({ connected: true, port: targetPort });
             },
         },

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

@@ -1,6 +1,7 @@
 import type { ChildProcess } from 'node:child_process';
 import type { AppConfig } from '../index.js';
 import type { CdpBridge } from '../server/cdp-bridge.js';
+import type { DevtoolsStore } from './devtools.js';
 export interface CdpToolDefinition {
     name: string;
     description: string;
@@ -18,5 +19,6 @@ export interface ToolContext {
     state: {
         screenshotCounter: number;
         electronProcess: ChildProcess | null;
+        devtoolsStore: DevtoolsStore | null;
     };
 }

package/dist/cli/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const VERSION = '0.1.1';
+const VERSION = '0.2.0';
 const command = process.argv[2];
 switch (command) {
     case 'serve':

package/dist/index.d.ts

@@ -20,14 +20,28 @@ export interface ScreenshotConfig {
     dir?: string;
     format?: 'png' | 'jpeg';
 }
+export interface CustomTool {
+    name: string;
+    description: string;
+    inputSchema: object;
+    handler: (args: Record<string, unknown>) => Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        isError?: boolean;
+    }>;
+}
 export interface ElectronMcpConfig {
     app: AppConfig;
     tools: Record<string, ToolConfig>;
     resources?: Record<string, ResourceConfig>;
     cdpTools?: boolean | string[];
     screenshots?: ScreenshotConfig;
+    customTools?: CustomTool[];
 }
 export declare function defineConfig(config: ElectronMcpConfig): ElectronMcpConfig;
 export { CdpBridge } from './server/cdp-bridge.js';
 export { getCdpTools } from './cdp-tools/index.js';
+export { startServer } from './server/mcp-server.js';
 export type { CdpTool, CdpToolDefinition } from './cdp-tools/types.js';

package/dist/index.js

@@ -3,3 +3,4 @@ export function defineConfig(config) {
 }
 export { CdpBridge } from './server/cdp-bridge.js';
 export { getCdpTools } from './cdp-tools/index.js';
+export { startServer } from './server/mcp-server.js';

package/dist/server/cdp-bridge.js

@@ -12,6 +12,8 @@ export class CdpBridge {
         this.port = port;
     }
     async connect(maxRetries = 10) {
+        if (this.client)
+            return;
         let lastError;
         for (let attempt = 1; attempt <= maxRetries; attempt++) {
             try {
@@ -20,17 +22,19 @@ export class CdpBridge {
                 if (!page)
                     throw new Error('No page target found among CDP targets');
                 this.client = await CDP({ target: page, port: this.port });
-                await this.client.Runtime.enable();
-                await this.client.DOM.enable();
-                await this.client.Page.enable();
-                await this.client.Network.enable();
+                await Promise.all([
+                    this.client.Runtime.enable(),
+                    this.client.DOM.enable(),
+                    this.client.Page.enable(),
+                    this.client.Network.enable(),
+                ]);
                 this.client.on('disconnect', () => { this.client = null; });
                 return;
             }
             catch (err) {
                 lastError = err;
                 if (attempt < maxRetries) {
-                    await new Promise(r => setTimeout(r, 1000));
+                    await new Promise(r => setTimeout(r, 300));
                 }
             }
         }

package/dist/server/mcp-server.js

@@ -5,7 +5,7 @@ import { CdpBridge } from './cdp-bridge.js';
 import { buildTools } from './tool-builder.js';
 import { buildResources } from './resource-builder.js';
 import { getCdpTools } from '../cdp-tools/index.js';
-function registerToolHandlers(server, bridge, ipcTools, cdpToolDefs) {
+function registerToolHandlers(server, bridge, ipcTools, cdpToolDefs, customTools) {
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: [
             ...ipcTools.map(t => ({
@@ -14,6 +14,11 @@ function registerToolHandlers(server, bridge, ipcTools, cdpToolDefs) {
                 inputSchema: t.inputSchema,
             })),
             ...cdpToolDefs.map(t => t.definition),
+            ...customTools.map(t => ({
+                name: t.name,
+                description: t.description,
+                inputSchema: t.inputSchema,
+            })),
         ],
     }));
     const ipcHandlerMap = new Map();
@@ -24,6 +29,10 @@ function registerToolHandlers(server, bridge, ipcTools, cdpToolDefs) {
     for (const tool of cdpToolDefs) {
         cdpHandlerMap.set(tool.definition.name, tool.handler);
     }
+    const customHandlerMap = new Map();
+    for (const tool of customTools) {
+        customHandlerMap.set(tool.name, tool);
+    }
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { name, arguments: args } = request.params;
         const ipcTool = ipcHandlerMap.get(name);
@@ -59,6 +68,18 @@ function registerToolHandlers(server, bridge, ipcTools, cdpToolDefs) {
                 };
             }
         }
+        const customTool = customHandlerMap.get(name);
+        if (customTool) {
+            try {
+                return await customTool.handler((args || {}));
+            }
+            catch (err) {
+                return {
+                    content: [{ type: 'text', text: `Error: ${err.message}` }],
+                    isError: true,
+                };
+            }
+        }
         return {
             content: [{ type: 'text', text: `Unknown tool: ${name}` }],
             isError: true,
@@ -107,12 +128,21 @@ export async function startServer(config) {
             cdpToolDefs = cdpToolDefs.filter(t => allowed.has(t.definition.name));
         }
     }
+    if (config.cdpTools) {
+        try {
+            await bridge.connect();
+        }
+        catch {
+            // App may not be running yet — tools will prompt to connect
+        }
+    }
     const resources = buildResources(config);
-    const server = new Server({ name: config.app.name, version: '0.1.0' }, { capabilities: {
+    const server = new Server({ name: config.app.name, version: '0.2.0' }, { capabilities: {
             tools: {},
             ...(resources.length > 0 ? { resources: {} } : {}),
         } });
-    registerToolHandlers(server, bridge, ipcTools, cdpToolDefs);
+    const customTools = config.customTools || [];
+    registerToolHandlers(server, bridge, ipcTools, cdpToolDefs, customTools);
     registerResourceHandlers(server, bridge, resources);
     const cleanup = async () => {
         await bridge.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "electron-dev-bridge",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Expose Electron IPC handlers as MCP tools for Claude Code, with 22 built-in CDP tools for DOM automation",
   "type": "module",
   "main": "dist/index.js",