@debugelectron/debug-electron-mcp 1.6.7

package/dist/schemas.d.ts

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+export declare const CommandArgsSchema: z.ZodObject<{
+    selector: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodString>;
+    placeholder: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    code: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    value?: string | undefined;
+    code?: string | undefined;
+    message?: string | undefined;
+    text?: string | undefined;
+    selector?: string | undefined;
+    placeholder?: string | undefined;
+}, {
+    value?: string | undefined;
+    code?: string | undefined;
+    message?: string | undefined;
+    text?: string | undefined;
+    selector?: string | undefined;
+    placeholder?: string | undefined;
+}>;
+export declare const SendCommandToElectronSchema: z.ZodObject<{
+    command: z.ZodString;
+    args: z.ZodOptional<z.ZodObject<{
+        selector: z.ZodOptional<z.ZodString>;
+        text: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        placeholder: z.ZodOptional<z.ZodString>;
+        message: z.ZodOptional<z.ZodString>;
+        code: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        value?: string | undefined;
+        code?: string | undefined;
+        message?: string | undefined;
+        text?: string | undefined;
+        selector?: string | undefined;
+        placeholder?: string | undefined;
+    }, {
+        value?: string | undefined;
+        code?: string | undefined;
+        message?: string | undefined;
+        text?: string | undefined;
+        selector?: string | undefined;
+        placeholder?: string | undefined;
+    }>>;
+    targetId: z.ZodOptional<z.ZodString>;
+    windowTitle: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    command: string;
+    windowTitle?: string | undefined;
+    args?: {
+        value?: string | undefined;
+        code?: string | undefined;
+        message?: string | undefined;
+        text?: string | undefined;
+        selector?: string | undefined;
+        placeholder?: string | undefined;
+    } | undefined;
+    targetId?: string | undefined;
+}, {
+    command: string;
+    windowTitle?: string | undefined;
+    args?: {
+        value?: string | undefined;
+        code?: string | undefined;
+        message?: string | undefined;
+        text?: string | undefined;
+        selector?: string | undefined;
+        placeholder?: string | undefined;
+    } | undefined;
+    targetId?: string | undefined;
+}>;
+export declare const TakeScreenshotSchema: z.ZodObject<{
+    outputPath: z.ZodOptional<z.ZodString>;
+    windowTitle: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    outputPath?: string | undefined;
+    windowTitle?: string | undefined;
+}, {
+    outputPath?: string | undefined;
+    windowTitle?: string | undefined;
+}>;
+export declare const ReadElectronLogsSchema: z.ZodObject<{
+    logType: z.ZodOptional<z.ZodEnum<["console", "main", "renderer", "all"]>>;
+    lines: z.ZodOptional<z.ZodNumber>;
+    follow: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    logType?: "console" | "main" | "renderer" | "all" | undefined;
+    lines?: number | undefined;
+    follow?: boolean | undefined;
+}, {
+    logType?: "console" | "main" | "renderer" | "all" | undefined;
+    lines?: number | undefined;
+    follow?: boolean | undefined;
+}>;
+export declare const GetElectronWindowInfoSchema: z.ZodObject<{
+    includeChildren: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    includeChildren?: boolean | undefined;
+}, {
+    includeChildren?: boolean | undefined;
+}>;
+export declare const ListElectronWindowsSchema: z.ZodObject<{
+    includeDevTools: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    includeDevTools?: boolean | undefined;
+}, {
+    includeDevTools?: boolean | undefined;
+}>;
+export type ToolInput = {
+    type: 'object';
+    properties: Record<string, any>;
+    required?: string[];
+};

package/dist/screenshot.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Take a screenshot of the running Electron application using Chrome DevTools Protocol
+ */
+export declare function takeScreenshot(outputPath?: string, windowTitle?: string): Promise<{
+    filePath?: string;
+    base64: string;
+    data: string;
+    error?: string;
+}>;

package/dist/tools.d.ts

@@ -0,0 +1,13 @@
+import { ToolInput } from './schemas';
+export declare enum ToolName {
+    SEND_COMMAND_TO_ELECTRON = "send_command_to_electron",
+    TAKE_SCREENSHOT = "take_screenshot",
+    READ_ELECTRON_LOGS = "read_electron_logs",
+    GET_ELECTRON_WINDOW_INFO = "get_electron_window_info",
+    LIST_ELECTRON_WINDOWS = "list_electron_windows"
+}
+export declare const tools: {
+    name: ToolName;
+    description: string;
+    inputSchema: ToolInput;
+}[];

package/dist/utils/electron-commands.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Enhanced Electron interaction commands for React-based applications
+ * Addresses common issues with form interactions, event handling, and state management
+ */
+export interface ElementAnalysis {
+    element?: Element;
+    tag: string;
+    text: string;
+    id: string;
+    className: string;
+    name: string;
+    placeholder: string;
+    type: string;
+    value: string;
+    ariaLabel: string;
+    ariaRole: string;
+    title: string;
+    href: string;
+    src: string;
+    alt: string;
+    position: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    isVisible: boolean;
+    isInteractive: boolean;
+    zIndex: number;
+    backgroundColor: string;
+    color: string;
+    fontSize: string;
+    fontWeight: string;
+    cursor: string;
+    context: string;
+    selector: string;
+    xpath: string;
+}
+export interface PageAnalysis {
+    clickable: ElementAnalysis[];
+    inputs: ElementAnalysis[];
+    links: ElementAnalysis[];
+    images: ElementAnalysis[];
+    text: ElementAnalysis[];
+    containers: ElementAnalysis[];
+    metadata: {
+        totalElements: number;
+        visibleElements: number;
+        interactiveElements: number;
+        pageTitle: string;
+        pageUrl: string;
+        viewport: {
+            width: number;
+            height: number;
+        };
+    };
+}
+/**
+ * Generate the enhanced find_elements command with deep DOM analysis
+ */
+export declare function generateFindElementsCommand(): string;
+/**
+ * Generate the enhanced click_by_text command with improved element scoring
+ */
+export declare function generateClickByTextCommand(text: string): string;

package/dist/utils/electron-connection.d.ts

@@ -0,0 +1,39 @@
+import WebSocket from 'ws';
+export interface DevToolsTarget {
+    id: string;
+    title: string;
+    url: string;
+    webSocketDebuggerUrl: string;
+    type: string;
+}
+export interface CommandResult {
+    success: boolean;
+    result?: any;
+    error?: string;
+    message: string;
+}
+/** Options for targeting a specific Electron window */
+export interface WindowTargetOptions {
+    /** CDP target ID (exact match) */
+    targetId?: string;
+    /** Window title (case-insensitive partial match) */
+    windowTitle?: string;
+}
+/**
+ * Find and connect to a running Electron application.
+ * @param options - Optional targeting options to select a specific window
+ * @returns The DevTools target matching the given options
+ * @example
+ * findElectronTarget() // first available main window
+ * findElectronTarget({ targetId: 'ABC123' }) // exact ID match
+ * findElectronTarget({ windowTitle: 'Settings' }) // partial title match
+ */
+export declare function findElectronTarget(options?: WindowTargetOptions): Promise<DevToolsTarget>;
+/**
+ * Execute JavaScript code in an Electron application via Chrome DevTools Protocol
+ */
+export declare function executeInElectron(javascriptCode: string, target?: DevToolsTarget): Promise<string>;
+/**
+ * Connect to Electron app for real-time log monitoring
+ */
+export declare function connectForLogs(target?: DevToolsTarget, onLog?: (log: string) => void): Promise<WebSocket>;

package/dist/utils/electron-discovery.d.ts

@@ -0,0 +1,52 @@
+export interface ElectronAppInfo {
+    port: number;
+    targets: any[];
+}
+export interface WindowInfo {
+    id: string;
+    title: string;
+    url: string;
+    type: string;
+    description: string;
+    webSocketDebuggerUrl: string;
+}
+/** Simplified window target info for the list_electron_windows tool */
+export interface ElectronWindowTarget {
+    id: string;
+    title: string;
+    url: string;
+    port: number;
+    type: string;
+}
+export interface ElectronWindowResult {
+    platform: string;
+    devToolsPort?: number;
+    windows: WindowInfo[];
+    totalTargets: number;
+    electronTargets: number;
+    processInfo?: any;
+    message: string;
+    automationReady: boolean;
+}
+/**
+ * Scan for running Electron applications with DevTools enabled
+ */
+export declare function scanForElectronApps(): Promise<ElectronAppInfo[]>;
+/**
+ * Get detailed process information for running Electron applications
+ */
+export declare function getElectronProcessInfo(): Promise<any>;
+/**
+ * Find the main target from a list of targets
+ */
+export declare function findMainTarget(targets: any[]): any | null;
+/**
+ * List all available Electron window targets across all detected apps.
+ * @param includeDevTools - Whether to include DevTools windows (default: false)
+ * @returns Array of window targets with id, title, url, port, and type
+ */
+export declare function listElectronWindows(includeDevTools?: boolean): Promise<ElectronWindowTarget[]>;
+/**
+ * Get window information from any running Electron app
+ */
+export declare function getElectronWindowInfo(includeChildren?: boolean): Promise<ElectronWindowResult>;

package/dist/utils/electron-enhanced-commands.d.ts

@@ -0,0 +1,51 @@
+import { WindowTargetOptions } from './electron-connection';
+export interface CommandArgs {
+    selector?: string;
+    text?: string;
+    value?: string;
+    placeholder?: string;
+    message?: string;
+    code?: string;
+}
+/**
+ * Enhanced command executor with improved React support.
+ * @param command - The command to execute
+ * @param args - Command-specific arguments
+ * @param windowOptions - Optional window targeting (targetId or windowTitle)
+ */
+export declare function sendCommandToElectron(command: string, args?: CommandArgs, windowOptions?: WindowTargetOptions): Promise<string>;
+/**
+ * Enhanced click function with better React support
+ */
+export declare function clickByText(text: string): Promise<string>;
+/**
+ * Enhanced input filling with React state management
+ */
+export declare function fillInput(searchText: string, value: string, selector?: string): Promise<string>;
+/**
+ * Enhanced select option with proper event handling
+ */
+export declare function selectOption(value: string, selector?: string, text?: string): Promise<string>;
+/**
+ * Get comprehensive page structure analysis
+ */
+export declare function getPageStructure(): Promise<string>;
+/**
+ * Get enhanced element analysis
+ */
+export declare function findElements(): Promise<string>;
+/**
+ * Execute custom JavaScript with error handling
+ */
+export declare function executeCustomScript(code: string): Promise<string>;
+/**
+ * Get debugging information about page elements
+ */
+export declare function debugElements(): Promise<string>;
+/**
+ * Verify current form state and validation
+ */
+export declare function verifyFormState(): Promise<string>;
+export declare function getTitle(): Promise<string>;
+export declare function getUrl(): Promise<string>;
+export declare function getBodyText(): Promise<string>;

package/dist/utils/electron-input-commands.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Enhanced input interaction commands for React-based Electron applications
+ * Focuses on proper event handling and React state management
+ */
+/**
+ * Generate the enhanced fill_input command with React-aware event handling
+ */
+export declare function generateFillInputCommand(selector: string, value: string, searchText: string): string;
+/**
+ * Generate the enhanced select_option command
+ */
+export declare function generateSelectOptionCommand(selector: string, value: string, text: string): string;
+/**
+ * Generate page structure analysis command
+ */
+export declare function generatePageStructureCommand(): string;

package/dist/utils/electron-logs.d.ts

@@ -0,0 +1,11 @@
+export type LogType = 'console' | 'main' | 'renderer' | 'all';
+export interface LogEntry {
+    timestamp: string;
+    level: string;
+    message: string;
+    source: 'console' | 'system';
+}
+/**
+ * Read logs from running Electron applications
+ */
+export declare function readElectronLogs(logType?: LogType, lines?: number, follow?: boolean): Promise<string>;

package/dist/utils/electron-process.d.ts

@@ -0,0 +1,27 @@
+import { ChildProcess } from 'child_process';
+export declare let electronProcess: ChildProcess | null;
+export declare let electronLogs: string[];
+/**
+ * Set the current Electron process reference
+ */
+export declare function setElectronProcess(process: ChildProcess | null): void;
+/**
+ * Get the current Electron process reference
+ */
+export declare function getElectronProcess(): ChildProcess | null;
+/**
+ * Add a log entry to the Electron logs
+ */
+export declare function addElectronLog(log: string): void;
+/**
+ * Get all Electron logs
+ */
+export declare function getElectronLogs(): string[];
+/**
+ * Clear all Electron logs
+ */
+export declare function clearElectronLogs(): void;
+/**
+ * Reset the Electron process state
+ */
+export declare function resetElectronProcess(): void;

package/dist/utils/logger.d.ts

@@ -0,0 +1,19 @@
+export declare enum LogLevel {
+    ERROR = 0,
+    WARN = 1,
+    INFO = 2,
+    DEBUG = 3
+}
+export declare class Logger {
+    private static instance;
+    private level;
+    constructor(level?: LogLevel);
+    static getInstance(): Logger;
+    setLevel(level: LogLevel): void;
+    error(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    info(message: string, ...args: any[]): void;
+    debug(message: string, ...args: any[]): void;
+    isEnabled(level: LogLevel): boolean;
+}
+export declare const logger: Logger;

package/dist/utils/logs.d.ts

@@ -0,0 +1 @@
+export declare function readElectronLogs(logType?: string, lines?: number): Promise<string[]>;

package/dist/utils/project.d.ts

@@ -0,0 +1 @@
+export declare function isElectronInstalled(appPath?: string): Promise<boolean>;

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "@debugelectron/debug-electron-mcp",
+  "version": "1.6.7",
+  "description": "MCP server for Electron application automation and management. See MCP_USAGE_GUIDE.md for proper argument structure examples.",
+  "main": "dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "debug-electron-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js",
+    "dev:inspect": "npm run build && npm run inspect",
+    "dev:hmr": "mcpmon -- npm run dev",
+    "build": "webpack --config webpack.config.ts --mode production",
+    "build:dev": "webpack --config webpack.config.ts --mode development",
+    "dev": "tsx src/index.ts",
+    "dev:watch": "tsx --watch src/index.ts",
+    "start": "node dist/index.js",
+    "watch": "webpack --config webpack.config.ts --mode development --watch",
+    "watch-and-serve": "webpack --config webpack.config.ts --mode development --watch & node --watch dist/index.js",
+    "prepare": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:react": "cd tests/integration/react-compatibility && electron test-react-electron.cjs",
+    "test:coverage": "vitest run --coverage",
+    "test:security": "npm run build && node test/security-test.js",
+    "test:clean": "tsx -e \"import('./test/utils/cleanup.js').then(m => m.TestCleanup.cleanup())\"",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
+    "format": "prettier --write \"src/**/*.{ts,js,json,md}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,js,json,md}\"",
+    "code:check": "npm run lint && npm run format:check",
+    "code:fix": "npm run lint:fix && npm run format"
+  },
+  "keywords": [
+    "mcp",
+    "electron",
+    "automation",
+    "desktop",
+    "model-context-protocol",
+    "devtools",
+    "testing",
+    "ai",
+    "chrome-devtools-protocol",
+    "screenshot",
+    "electron-automation"
+  ],
+  "author": "DebugElectron",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@types/ws": "^8.18.1",
+    "electron": "^28.0.0",
+    "playwright": "^1.54.1",
+    "ws": "^8.18.3",
+    "zod": "^3.22.4",
+    "zod-to-json-schema": "^3.22.4"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.32.0",
+    "@types/node": "^20.19.10",
+    "@types/webpack": "^5.28.5",
+    "@types/webpack-node-externals": "^3.0.4",
+    "@typescript-eslint/eslint-plugin": "^8.38.0",
+    "@typescript-eslint/parser": "^8.38.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "eslint": "^9.32.0",
+    "globals": "^16.3.0",
+    "jest": "^29.0.0",
+    "jiti": "^2.5.1",
+    "prettier": "^3.6.2",
+    "ts-jest": "^29.0.0",
+    "ts-loader": "^9.5.2",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.6.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.38.0",
+    "vitest": "^3.2.4",
+    "webpack": "^5.101.0",
+    "webpack-cli": "^6.0.1",
+    "webpack-node-externals": "^3.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TheDarkSkyXD/debug-electron-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/TheDarkSkyXD/debug-electron-mcp/issues"
+  },
+  "homepage": "https://github.com/TheDarkSkyXD/debug-electron-mcp#readme"
+}