get_electron_window_info

Instructions

Implementation Reference

• src/utils/electron-discovery.ts:134-190 (handler)

  Core handler function that implements the tool logic: scans common DevTools ports for Electron apps, fetches window targets, filters DevTools windows optionally, gathers process info, and returns comprehensive window information.

  export async function getElectronWindowInfo(
    includeChildren: boolean = false,
  ): Promise<ElectronWindowResult> {
    try {
      const foundApps = await scanForElectronApps();
  
      if (foundApps.length === 0) {
        return {
          platform: process.platform,
          windows: [],
          totalTargets: 0,
          electronTargets: 0,
          message: 'No Electron applications found with remote debugging enabled',
          automationReady: false,
        };
      }
  
      // Use the first found app
      const app = foundApps[0];
      const windows: WindowInfo[] = app.targets.map((target: any) => ({
        id: target.id,
        title: target.title,
        url: target.url,
        type: target.type,
        description: target.description || '',
        webSocketDebuggerUrl: target.webSocketDebuggerUrl,
      }));
  
      // Get additional process information
      const processInfo = await getElectronProcessInfo();
  
      return {
        platform: process.platform,
        devToolsPort: app.port,
        windows: includeChildren
          ? windows
          : windows.filter((w: WindowInfo) => !w.title.includes('DevTools')),
        totalTargets: windows.length,
        electronTargets: windows.length,
        processInfo,
        message: `Found running Electron application with ${windows.length} windows on port ${app.port}`,
        automationReady: true,
      };
    } catch (error) {
      logger.error('Failed to scan for applications:', error);
      return {
        platform: process.platform,
        windows: [],
        totalTargets: 0,
        electronTargets: 0,
        message: `Failed to scan for Electron applications: ${
          error instanceof Error ? error.message : String(error)
        }`,
        automationReady: false,
      };
    }
  }

• src/schemas.ts:58-60 (schema)

  Zod schema defining the input parameters for the tool, specifically the optional 'includeChildren' boolean flag.

  export const GetElectronWindowInfoSchema = z.object({
    includeChildren: z.boolean().optional().describe('Include child windows information'),
  });

• src/tools.ts:20-25 (registration)

  Tool registration in the exported tools array, specifying the tool name, description, and JSON schema for MCP protocol compliance.

  {
    name: ToolName.GET_ELECTRON_WINDOW_INFO,
    description:
      'Get information about running Electron applications and their windows. Automatically detects any Electron app with remote debugging enabled (port 9222).',
    inputSchema: zodToJsonSchema(GetElectronWindowInfoSchema) as ToolInput,
  },

• src/handlers.ts:26-60 (registration)

  Dispatch handler in the main tool call switch statement that validates input, performs security checks, invokes the core handler, and formats the response for MCP.

  case ToolName.GET_ELECTRON_WINDOW_INFO: {
    // This is a low-risk read operation - basic validation only
    const { includeChildren } = GetElectronWindowInfoSchema.parse(args);
  
    const securityResult = await securityManager.executeSecurely({
      command: 'get_window_info',
      args,
      sourceIP,
      userAgent,
      operationType: 'window_info',
    });
  
    if (securityResult.blocked) {
      return {
        content: [
          {
            type: 'text',
            text: `Operation blocked: ${securityResult.error}`,
          },
        ],
        isError: true,
      };
    }
  
    const result = await getElectronWindowInfo(includeChildren);
    return {
      content: [
        {
          type: 'text',
          text: `Window Information:\n\n${JSON.stringify(result, null, 2)}`,
        },
      ],
      isError: false,
    };
  }

• src/utils/electron-discovery.ts:33-87 (helper)

  Supporting helper function that scans common DevTools ports (9222+) for running Electron apps by fetching /json endpoints.

  export async function scanForElectronApps(): Promise<ElectronAppInfo[]> {
    logger.debug('Scanning for running Electron applications...');
  
    // Extended port range to include test apps and common custom ports
    const commonPorts = [
      9222,
      9223,
      9224,
      9225, // Default ports
      9200,
      9201,
      9202,
      9203,
      9204,
      9205, // Security test range
      9300,
      9301,
      9302,
      9303,
      9304,
      9305, // Integration test range
      9400,
      9401,
      9402,
      9403,
      9404,
      9405, // Additional range
    ];
    const foundApps: ElectronAppInfo[] = [];
  
    for (const port of commonPorts) {
      try {
        const response = await fetch(`http://localhost:${port}/json`, {
          signal: AbortSignal.timeout(1000),
        });
  
        if (response.ok) {
          const targets = await response.json();
          const pageTargets = targets.filter((target: any) => target.type === 'page');
  
          if (pageTargets.length > 0) {
            foundApps.push({
              port,
              targets: pageTargets,
            });
            logger.debug(`Found Electron app on port ${port} with ${pageTargets.length} windows`);
          }
        }
      } catch {
        // Continue to next port
      }
    }
  
    return foundApps;
  }