take_screenshot

Instructions

Implementation Reference

• src/screenshot.ts:150-274 (handler)

  Core handler function that connects to running Electron apps via Chrome DevTools Protocol (CDP), takes a screenshot of the target page, encrypts the image data, optionally saves to file, and returns base64-encoded image for AI analysis.

  export async function takeScreenshot(
    outputPath?: string,
    windowTitle?: string,
  ): Promise<{
    filePath?: string;
    base64: string;
    data: string;
    error?: string;
  }> {
    // Validate output path for security
    if (outputPath && !validateScreenshotPath(outputPath)) {
      throw new Error(
        `Invalid output path: ${outputPath}. Path appears to target a restricted system location.`,
      );
    }
  
    // Inform user about screenshot
    logger.info('📸 Taking screenshot of Electron application', {
      outputPath,
      windowTitle,
      timestamp: new Date().toISOString(),
    });
    try {
      // Find running Electron applications
      const apps = await scanForElectronApps();
      if (apps.length === 0) {
        throw new Error('No running Electron applications found with remote debugging enabled');
      }
  
      // Use the first app found (or find by title if specified)
      let targetApp = apps[0];
      if (windowTitle) {
        const namedApp = apps.find((app) =>
          app.targets.some((target) =>
            target.title?.toLowerCase().includes(windowTitle.toLowerCase()),
          ),
        );
        if (namedApp) {
          targetApp = namedApp;
        }
      }
  
      // Connect to the Electron app's debugging port
      const browser = await chromium.connectOverCDP(`http://localhost:${targetApp.port}`);
      const contexts = browser.contexts();
  
      if (contexts.length === 0) {
        throw new Error(
          'No browser contexts found - make sure Electron app is running with remote debugging enabled',
        );
      }
  
      const context = contexts[0];
      const pages = context.pages();
  
      if (pages.length === 0) {
        throw new Error('No pages found in the browser context');
      }
  
      // Find the main application page (skip DevTools pages)
      let targetPage = pages[0];
      for (const page of pages) {
        const url = page.url();
        const title = await page.title().catch(() => '');
  
        // Skip DevTools and about:blank pages
        if (
          !url.includes('devtools://') &&
          !url.includes('about:blank') &&
          title &&
          !title.includes('DevTools')
        ) {
          // If windowTitle is specified, try to match it
          if (windowTitle && title.toLowerCase().includes(windowTitle.toLowerCase())) {
            targetPage = page;
            break;
          } else if (!windowTitle) {
            targetPage = page;
            break;
          }
        }
      }
  
      logger.info(`Taking screenshot of page: ${targetPage.url()} (${await targetPage.title()})`);
  
      // Take screenshot as buffer (in memory)
      const screenshotBuffer = await targetPage.screenshot({
        type: 'png',
        fullPage: false,
      });
  
      await browser.close();
  
      // Encrypt screenshot data for security
      const encryptedScreenshot = encryptScreenshotData(screenshotBuffer);
  
      // Convert buffer to base64 for transmission
      const base64Data = screenshotBuffer.toString('base64');
      logger.info(
        `Screenshot captured and encrypted successfully (${screenshotBuffer.length} bytes)`,
      );
  
      // If outputPath is provided, save encrypted data to file
      if (outputPath) {
        await fs.writeFile(outputPath + '.encrypted', JSON.stringify(encryptedScreenshot));
        // Also save unencrypted for compatibility (in production, consider removing this)
        await fs.writeFile(outputPath, screenshotBuffer);
        return {
          filePath: outputPath,
          base64: base64Data,
          data: `Screenshot saved to: ${outputPath} (encrypted backup: ${outputPath}.encrypted) and returned as base64 data`,
        };
      } else {
        return {
          base64: base64Data,
          data: `Screenshot captured as base64 data (${screenshotBuffer.length} bytes) - no file saved`,
        };
      }
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      throw new Error(
        `Screenshot failed: ${errorMessage}. Make sure the Electron app is running with remote debugging enabled (--remote-debugging-port=9222)`,
      );
    }
  }

• src/schemas.ts:41-47 (schema)

  Zod schema defining the input parameters for the take_screenshot tool: optional outputPath and windowTitle.

  export const TakeScreenshotSchema = z.object({
    outputPath: z
      .string()
      .optional()
      .describe('Path to save the screenshot (optional, defaults to temp directory)'),
    windowTitle: z.string().optional().describe('Specific window title to screenshot (optional)'),
  });

• src/tools.ts:26-31 (registration)

  Tool registration in the tools array, defining name 'take_screenshot', description, and input schema.

  {
    name: ToolName.TAKE_SCREENSHOT,
    description:
      'Take a screenshot of any running Electron application window. Returns base64 image data for AI analysis. No files created unless outputPath is specified.',
    inputSchema: zodToJsonSchema(TakeScreenshotSchema) as ToolInput,
  },

• src/handlers.ts:62-109 (registration)

  Handler dispatch in handleToolCall switch statement: validates args, calls takeScreenshot, and formats MCP response with base64 image.

  case ToolName.TAKE_SCREENSHOT: {
    // Security check for screenshot operation
    const securityResult = await securityManager.executeSecurely({
      command: 'take_screenshot',
      args,
      sourceIP,
      userAgent,
      operationType: 'screenshot',
    });
  
    if (securityResult.blocked) {
      return {
        content: [
          {
            type: 'text',
            text: `Screenshot blocked: ${securityResult.error}`,
          },
        ],
        isError: true,
      };
    }
    const { outputPath, windowTitle } = TakeScreenshotSchema.parse(args);
    const result = await takeScreenshot(outputPath, windowTitle);
  
    // Return the screenshot as base64 data for AI to evaluate
    const content: any[] = [];
  
    if (result.filePath) {
      content.push({
        type: 'text',
        text: `Screenshot saved to: ${result.filePath}`,
      });
    } else {
      content.push({
        type: 'text',
        text: 'Screenshot captured in memory (no file saved)',
      });
    }
  
    // Add the image data for AI evaluation
    content.push({
      type: 'image',
      data: result.base64!,
      mimeType: 'image/png',
    });
  
    return { content, isError: false };
  }