electron-dev-bridge 0.1.0

package/dist/cli/init.js

@@ -0,0 +1,146 @@
+import { resolve, relative, dirname, basename } from 'node:path';
+import { existsSync, readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs';
+import { scanForHandlers } from '../scanner/ipc-scanner.js';
+import { scanForSchemas } from '../scanner/schema-scanner.js';
+const SKIP_DIRS = new Set(['node_modules', 'dist', '.git', 'out']);
+function findSourceFiles(dir) {
+    const results = [];
+    for (const entry of readdirSync(dir)) {
+        if (SKIP_DIRS.has(entry))
+            continue;
+        const full = resolve(dir, entry);
+        const stat = statSync(full);
+        if (stat.isDirectory()) {
+            results.push(...findSourceFiles(full));
+        }
+        else if (/\.(ts|js|mts|mjs)$/.test(entry) && !entry.endsWith('.d.ts')) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+function singularize(word) {
+    if (word.endsWith('s') && !word.endsWith('ss')) {
+        return word.slice(0, -1);
+    }
+    return word;
+}
+function deriveDescription(channel) {
+    const parts = channel.split(':');
+    if (parts.length === 2) {
+        const domain = parts[0].toLowerCase();
+        const action = parts[1];
+        const capitalAction = action.charAt(0).toUpperCase() + action.slice(1);
+        return `${capitalAction} ${domain}`;
+    }
+    return channel;
+}
+function matchSchemaToChannel(channel, schemas, configDir) {
+    const parts = channel.split(':');
+    if (parts.length !== 2)
+        return undefined;
+    const domain = singularize(parts[0].toLowerCase());
+    const action = parts[1].toLowerCase();
+    for (const schema of schemas) {
+        const schemaLower = schema.name.toLowerCase();
+        if (schemaLower.includes(domain) && schemaLower.includes(action)) {
+            const rel = relative(configDir, schema.file)
+                .replace(/\.(ts|js|mts|mjs)$/, '');
+            const importPath = rel.startsWith('.') ? rel : `./${rel}`;
+            return { schema, importPath };
+        }
+    }
+    return undefined;
+}
+function buildToolEntries(handlers, schemas, configDir) {
+    const imports = new Map();
+    const toolEntries = [];
+    let linkedCount = 0;
+    for (const handler of handlers) {
+        const match = matchSchemaToChannel(handler.channel, schemas, configDir);
+        const description = deriveDescription(handler.channel);
+        if (match) {
+            linkedCount++;
+            if (!imports.has(match.importPath)) {
+                imports.set(match.importPath, new Set());
+            }
+            imports.get(match.importPath).add(match.schema.name);
+            toolEntries.push(`    '${handler.channel}': {\n` +
+                `      description: '${description}',\n` +
+                `      schema: ${match.schema.name},\n` +
+                `    }`);
+        }
+        else {
+            toolEntries.push(`    '${handler.channel}': {\n` +
+                `      description: '${description}',\n` +
+                `    }`);
+        }
+    }
+    return { toolEntries, imports, linkedCount };
+}
+function generateConfigSource(appName, toolEntries, imports) {
+    const importLines = [
+        `import { defineConfig } from 'electron-dev-bridge'`,
+    ];
+    for (const [path, names] of imports) {
+        const sorted = [...names].sort();
+        importLines.push(`import { ${sorted.join(', ')} } from '${path}'`);
+    }
+    const toolsBlock = toolEntries.length > 0
+        ? toolEntries.join(',\n')
+        : `    // No IPC handlers detected. Add tools manually:\n    // 'channel:action': { description: 'Description' }`;
+    return `${importLines.join('\n')}
+
+export default defineConfig({
+  app: {
+    name: '${appName}',
+  },
+  tools: {
+${toolsBlock}
+  },
+})
+`;
+}
+export async function init() {
+    const configPath = resolve('electron-mcp.config.ts');
+    if (existsSync(configPath)) {
+        console.error('electron-mcp.config.ts already exists. Delete it to re-initialize.');
+        process.exit(1);
+    }
+    const cwd = process.cwd();
+    console.log('Scanning source files...');
+    const sourceFiles = findSourceFiles(cwd);
+    console.log(`   Found ${sourceFiles.length} source files`);
+    const allHandlers = [];
+    for (const file of sourceFiles) {
+        allHandlers.push(...scanForHandlers(file));
+    }
+    console.log(`   Found ${allHandlers.length} ipcMain.handle() calls`);
+    const allSchemas = [];
+    for (const file of sourceFiles) {
+        allSchemas.push(...scanForSchemas(file));
+    }
+    console.log(`   Found ${allSchemas.length} Zod schema exports`);
+    let appName = basename(cwd);
+    const pkgPath = resolve(cwd, 'package.json');
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+            if (pkg.name)
+                appName = pkg.name;
+        }
+        catch {
+            // ignore parse errors
+        }
+    }
+    const { toolEntries, imports, linkedCount } = buildToolEntries(allHandlers, allSchemas, dirname(configPath));
+    console.log(`   Linked ${linkedCount} schemas to handlers`);
+    const config = generateConfigSource(appName, toolEntries, imports);
+    writeFileSync(configPath, config, 'utf-8');
+    console.log(`\nGenerated electron-mcp.config.ts`);
+    console.log(`   ${allHandlers.length} tools, ${linkedCount} with schemas`);
+    console.log(`\nNext steps:`);
+    console.log(`   1. Review and edit electron-mcp.config.ts`);
+    console.log(`   2. Run: npx electron-mcp validate`);
+    console.log(`   3. Run: npx electron-mcp register`);
+}

package/dist/cli/register.d.ts

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

package/dist/cli/register.js

@@ -0,0 +1,40 @@
+import { resolve } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+const CONFIG_NAMES = [
+    'electron-mcp.config.ts',
+    'electron-mcp.config.js',
+    'electron-mcp.config.mjs',
+];
+export async function register() {
+    let configPath;
+    for (const name of CONFIG_NAMES) {
+        const candidate = resolve(name);
+        if (existsSync(candidate)) {
+            configPath = candidate;
+            break;
+        }
+    }
+    if (!configPath) {
+        console.error('Error: No electron-mcp config found. Run: npx electron-mcp init');
+        process.exit(1);
+    }
+    const configContent = readFileSync(configPath, 'utf-8');
+    const nameMatch = configContent.match(/name:\s*['"]([^'"]+)['"]/);
+    const appName = nameMatch?.[1] || 'electron-app';
+    console.log('Registering with Claude Code...');
+    console.log(`   Server name: ${appName}`);
+    console.log(`   Working directory: ${process.cwd()}`);
+    try {
+        execFileSync('claude', [
+            'mcp', 'add', '--scope', 'user',
+            appName, '--', 'npx', 'electron-mcp', 'serve'
+        ], { stdio: 'inherit' });
+        console.log('\nRegistered! Run: claude mcp list to verify.');
+    }
+    catch {
+        console.error('\nRegistration failed. Is Claude Code CLI installed?');
+        console.error(`   Manual: claude mcp add --scope user "${appName}" -- npx electron-mcp serve`);
+        process.exit(1);
+    }
+}

package/dist/cli/serve.d.ts

@@ -0,0 +1 @@
+export declare function serve(configPath?: string): Promise<void>;

package/dist/cli/serve.js

@@ -0,0 +1,34 @@
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { startServer } from '../server/mcp-server.js';
+import { loadConfig } from '../utils/load-config.js';
+const CONFIG_NAMES = [
+    'electron-mcp.config.ts',
+    'electron-mcp.config.js',
+    'electron-mcp.config.mjs',
+];
+export async function serve(configPath) {
+    let resolvedPath;
+    if (configPath) {
+        resolvedPath = resolve(configPath);
+    }
+    else {
+        for (const name of CONFIG_NAMES) {
+            const candidate = resolve(name);
+            if (existsSync(candidate)) {
+                resolvedPath = candidate;
+                break;
+            }
+        }
+    }
+    if (!resolvedPath || !existsSync(resolvedPath)) {
+        console.error('Error: No config file found. Create electron-mcp.config.ts or run: npx electron-mcp init');
+        process.exit(1);
+    }
+    const config = await loadConfig(resolvedPath);
+    if (!config || !config.app || !config.tools) {
+        console.error('Error: Invalid config. Must export default defineConfig({ app, tools })');
+        process.exit(1);
+    }
+    await startServer(config);
+}

package/dist/cli/validate.d.ts

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

package/dist/cli/validate.js

@@ -0,0 +1,65 @@
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { loadConfig } from '../utils/load-config.js';
+const CONFIG_NAMES = [
+    'electron-mcp.config.ts',
+    'electron-mcp.config.js',
+    'electron-mcp.config.mjs',
+];
+export async function validate() {
+    let configPath;
+    for (const name of CONFIG_NAMES) {
+        const candidate = resolve(name);
+        if (existsSync(candidate)) {
+            configPath = candidate;
+            break;
+        }
+    }
+    if (!configPath) {
+        console.error('Config file: not found');
+        console.error('   Run: npx electron-mcp init');
+        process.exit(1);
+    }
+    console.log(`Config file: ${configPath.split('/').pop()}`);
+    let config;
+    try {
+        config = await loadConfig(configPath);
+    }
+    catch (err) {
+        console.error(`Config load failed: ${err.message}`);
+        process.exit(1);
+    }
+    if (!config.app?.name) {
+        console.error('app.name is required');
+        process.exit(1);
+    }
+    const toolCount = Object.keys(config.tools || {}).length;
+    const schemasCount = Object.values(config.tools || {}).filter(t => t.schema).length;
+    console.log(`${toolCount} IPC tools defined, ${schemasCount} with Zod schemas`);
+    const resourceCount = Object.keys(config.resources || {}).length;
+    if (resourceCount > 0) {
+        console.log(`${resourceCount} resources defined`);
+    }
+    let cdpCount = 0;
+    if (config.cdpTools) {
+        const { getCdpTools } = await import('../cdp-tools/index.js');
+        const { CdpBridge } = await import('../server/cdp-bridge.js');
+        const dummyBridge = new CdpBridge();
+        let allCdpTools = getCdpTools(dummyBridge, config.app, config.screenshots);
+        if (Array.isArray(config.cdpTools)) {
+            const allowed = new Set(config.cdpTools);
+            allCdpTools = allCdpTools.filter(t => allowed.has(t.definition.name));
+        }
+        cdpCount = allCdpTools.length;
+        console.log(`CDP tools: enabled (${cdpCount} tools)`);
+    }
+    else {
+        console.log('CDP tools: disabled');
+    }
+    for (const [channel, tool] of Object.entries(config.tools || {})) {
+        if (tool.preloadPath) {
+            console.log(`Note: Tool '${channel}' has preloadPath override: ${tool.preloadPath}`);
+        }
+    }
+    console.log(`\nTotal: ${toolCount + cdpCount} MCP tools ready`);
+}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import type { ZodType } from 'zod';
+export interface ToolConfig {
+    description: string;
+    schema?: ZodType<any>;
+    preloadPath?: string;
+    returns?: string;
+}
+export interface ResourceConfig {
+    description: string;
+    uri: string;
+    pollExpression: string;
+}
+export interface AppConfig {
+    name: string;
+    path?: string;
+    debugPort?: number;
+    electronBin?: string;
+}
+export interface ScreenshotConfig {
+    dir?: string;
+    format?: 'png' | 'jpeg';
+}
+export interface ElectronMcpConfig {
+    app: AppConfig;
+    tools: Record<string, ToolConfig>;
+    resources?: Record<string, ResourceConfig>;
+    cdpTools?: boolean | string[];
+    screenshots?: ScreenshotConfig;
+}
+export declare function defineConfig(config: ElectronMcpConfig): ElectronMcpConfig;

package/dist/index.js

@@ -0,0 +1,3 @@
+export function defineConfig(config) {
+    return config;
+}

package/dist/scanner/ipc-scanner.d.ts

@@ -0,0 +1,6 @@
+export interface DetectedHandler {
+    channel: string;
+    line: number;
+    file: string;
+}
+export declare function scanForHandlers(filePath: string): DetectedHandler[];

package/dist/scanner/ipc-scanner.js

@@ -0,0 +1,14 @@
+import { readFileSync } from 'node:fs';
+export function scanForHandlers(filePath) {
+    const content = readFileSync(filePath, 'utf-8');
+    const handlers = [];
+    const regex = /ipcMain\.handle\(\s*['"]([^'"]+)['"]/g;
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+        const channel = match[1];
+        const upToMatch = content.slice(0, match.index);
+        const line = upToMatch.split('\n').length;
+        handlers.push({ channel, line, file: filePath });
+    }
+    return handlers;
+}

package/dist/scanner/schema-scanner.d.ts

@@ -0,0 +1,6 @@
+export interface DetectedSchema {
+    name: string;
+    line: number;
+    file: string;
+}
+export declare function scanForSchemas(filePath: string): DetectedSchema[];

package/dist/scanner/schema-scanner.js

@@ -0,0 +1,14 @@
+import { readFileSync } from 'node:fs';
+export function scanForSchemas(filePath) {
+    const content = readFileSync(filePath, 'utf-8');
+    const schemas = [];
+    const regex = /export\s+const\s+(\w+Schema)\s*=\s*z\./g;
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+        const name = match[1];
+        const upToMatch = content.slice(0, match.index);
+        const line = upToMatch.split('\n').length;
+        schemas.push({ name, line, file: filePath });
+    }
+    return schemas;
+}

package/dist/server/cdp-bridge.d.ts

@@ -0,0 +1,12 @@
+export declare class CdpBridge {
+    private client;
+    private port;
+    constructor(port?: number);
+    get connected(): boolean;
+    setPort(port: number): void;
+    connect(maxRetries?: number): Promise<void>;
+    ensureConnected(): void;
+    evaluate(expression: string, awaitPromise?: boolean): Promise<any>;
+    getRawClient(): any;
+    close(): Promise<void>;
+}

package/dist/server/cdp-bridge.js

@@ -0,0 +1,72 @@
+import CDP from 'chrome-remote-interface';
+export class CdpBridge {
+    client = null;
+    port;
+    constructor(port = 9229) {
+        this.port = port;
+    }
+    get connected() {
+        return this.client !== null;
+    }
+    setPort(port) {
+        this.port = port;
+    }
+    async connect(maxRetries = 10) {
+        let lastError;
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            try {
+                const targets = await CDP.List({ port: this.port });
+                const page = targets.find((t) => t.type === 'page');
+                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();
+                this.client.on('disconnect', () => { this.client = null; });
+                return;
+            }
+            catch (err) {
+                lastError = err;
+                if (attempt < maxRetries) {
+                    await new Promise(r => setTimeout(r, 1000));
+                }
+            }
+        }
+        throw new Error(`Cannot connect to Electron app on port ${this.port} after ${maxRetries} attempts. ` +
+            `Is the app running with --remote-debugging-port=${this.port}? ` +
+            `(${lastError?.message})`);
+    }
+    ensureConnected() {
+        if (!this.client) {
+            throw new Error('Not connected to an Electron app. ' +
+                'Start the app with --remote-debugging-port and use the connect tool first.');
+        }
+    }
+    async evaluate(expression, awaitPromise = true) {
+        this.ensureConnected();
+        const { result, exceptionDetails } = await this.client.Runtime.evaluate({
+            expression,
+            returnByValue: true,
+            awaitPromise,
+        });
+        if (exceptionDetails) {
+            const errText = exceptionDetails.exception?.description ||
+                exceptionDetails.text ||
+                'Unknown evaluation error';
+            throw new Error(`JS evaluation error: ${errText}`);
+        }
+        return result.value;
+    }
+    getRawClient() {
+        this.ensureConnected();
+        return this.client;
+    }
+    async close() {
+        if (this.client) {
+            await this.client.close();
+            this.client = null;
+        }
+    }
+}

package/dist/server/mcp-server.d.ts

@@ -0,0 +1,2 @@
+import type { ElectronMcpConfig } from '../index.js';
+export declare function startServer(config: ElectronMcpConfig): Promise<void>;

package/dist/server/mcp-server.js

@@ -0,0 +1,126 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+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) {
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            ...ipcTools.map(t => ({
+                name: t.name,
+                description: t.description,
+                inputSchema: t.inputSchema,
+            })),
+            ...cdpToolDefs.map(t => t.definition),
+        ],
+    }));
+    const ipcHandlerMap = new Map();
+    for (const tool of ipcTools) {
+        ipcHandlerMap.set(tool.name, tool);
+    }
+    const cdpHandlerMap = new Map();
+    for (const tool of cdpToolDefs) {
+        cdpHandlerMap.set(tool.definition.name, tool.handler);
+    }
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const ipcTool = ipcHandlerMap.get(name);
+        if (ipcTool) {
+            try {
+                const argsJson = args && Object.keys(args).length > 0
+                    ? JSON.stringify(args)
+                    : '';
+                const expression = argsJson
+                    ? `${ipcTool.preloadPath}(${argsJson})`
+                    : `${ipcTool.preloadPath}()`;
+                const result = await bridge.evaluate(expression, true);
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            catch (err) {
+                return {
+                    content: [{ type: 'text', text: `Error: ${err.message}` }],
+                    isError: true,
+                };
+            }
+        }
+        const cdpHandler = cdpHandlerMap.get(name);
+        if (cdpHandler) {
+            try {
+                return await cdpHandler(args || {});
+            }
+            catch (err) {
+                return {
+                    content: [{ type: 'text', text: `Error: ${err.message}` }],
+                    isError: true,
+                };
+            }
+        }
+        return {
+            content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+            isError: true,
+        };
+    });
+}
+function registerResourceHandlers(server, bridge, resources) {
+    if (resources.length === 0)
+        return;
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: resources.map(r => ({
+            uri: r.uri,
+            name: r.name,
+            description: r.description,
+            mimeType: r.mimeType,
+        })),
+    }));
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const resource = resources.find(r => r.uri === request.params.uri);
+        if (!resource) {
+            throw new Error(`Unknown resource: ${request.params.uri}`);
+        }
+        try {
+            const data = await bridge.evaluate(resource.pollExpression, true);
+            return {
+                contents: [{
+                        uri: resource.uri,
+                        mimeType: resource.mimeType,
+                        text: JSON.stringify(data, null, 2),
+                    }],
+            };
+        }
+        catch (err) {
+            throw new Error(`Failed to read resource ${resource.uri}: ${err.message}`);
+        }
+    });
+}
+export async function startServer(config) {
+    const bridge = new CdpBridge(config.app.debugPort || 9229);
+    const ipcTools = await buildTools(config);
+    let cdpToolDefs = [];
+    if (config.cdpTools) {
+        cdpToolDefs = getCdpTools(bridge, config.app, config.screenshots);
+        if (Array.isArray(config.cdpTools)) {
+            const allowed = new Set(config.cdpTools);
+            cdpToolDefs = cdpToolDefs.filter(t => allowed.has(t.definition.name));
+        }
+    }
+    const resources = buildResources(config);
+    const server = new Server({ name: config.app.name, version: '0.1.0' }, { capabilities: {
+            tools: {},
+            ...(resources.length > 0 ? { resources: {} } : {}),
+        } });
+    registerToolHandlers(server, bridge, ipcTools, cdpToolDefs);
+    registerResourceHandlers(server, bridge, resources);
+    const cleanup = async () => {
+        await bridge.close();
+        await server.close();
+        process.exit(0);
+    };
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/server/resource-builder.d.ts

@@ -0,0 +1,9 @@
+import type { ElectronMcpConfig } from '../index.js';
+export interface ResolvedResource {
+    uri: string;
+    name: string;
+    description: string;
+    pollExpression: string;
+    mimeType: string;
+}
+export declare function buildResources(config: ElectronMcpConfig): ResolvedResource[];

package/dist/server/resource-builder.js

@@ -0,0 +1,15 @@
+export function buildResources(config) {
+    if (!config.resources)
+        return [];
+    const resources = [];
+    for (const [channel, resourceConfig] of Object.entries(config.resources)) {
+        resources.push({
+            uri: resourceConfig.uri,
+            name: channel,
+            description: resourceConfig.description,
+            pollExpression: resourceConfig.pollExpression,
+            mimeType: 'application/json',
+        });
+    }
+    return resources;
+}

package/dist/server/tool-builder.d.ts

@@ -0,0 +1,9 @@
+import type { ElectronMcpConfig } from '../index.js';
+export interface ResolvedTool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, any>;
+    channel: string;
+    preloadPath: string;
+}
+export declare function buildTools(config: ElectronMcpConfig): Promise<ResolvedTool[]>;

package/dist/server/tool-builder.js

@@ -0,0 +1,39 @@
+function channelToToolName(channel) {
+    return channel.replace(/:/g, '_');
+}
+function channelToPreloadPath(channel) {
+    const [domain, action] = channel.split(':');
+    return `window.electronAPI.${domain}.${action}`;
+}
+async function zodToJsonSchema(schema) {
+    try {
+        const { zodToJsonSchema: convert } = await import('zod-to-json-schema');
+        const jsonSchema = convert(schema, { target: 'openApi3' });
+        const { $schema, ...rest } = jsonSchema;
+        return rest;
+    }
+    catch {
+        return { type: 'object' };
+    }
+}
+export async function buildTools(config) {
+    const tools = [];
+    for (const [channel, toolConfig] of Object.entries(config.tools)) {
+        let inputSchema = { type: 'object' };
+        if (toolConfig.schema) {
+            inputSchema = await zodToJsonSchema(toolConfig.schema);
+        }
+        let description = toolConfig.description;
+        if (toolConfig.returns) {
+            description += ` Returns: ${toolConfig.returns}`;
+        }
+        tools.push({
+            name: channelToToolName(channel),
+            description,
+            inputSchema,
+            channel,
+            preloadPath: toolConfig.preloadPath || channelToPreloadPath(channel),
+        });
+    }
+    return tools;
+}

package/dist/utils/load-config.d.ts

@@ -0,0 +1,5 @@
+import type { ElectronMcpConfig } from '../index.js';
+/**
+ * Load an electron-mcp config file, with TypeScript support via tsx.
+ */
+export declare function loadConfig(configPath: string): Promise<ElectronMcpConfig>;