android_screenshot

Instructions

Implementation Reference

• src/handlers.ts:91-130 (handler)

  The screenshotHandler function that executes the core logic of the android_screenshot tool. It invokes ADBWrapper.screenshot and formats the response as MCP content (text for file path or image with base64 data).

  export async function screenshotHandler(
    adb: ADBWrapper,
    args: any
  ): Promise<{ content: Array<{ type: string; text?: string; data?: string; mimeType?: string }> }> {
    const { outputPath, deviceSerial } = args as ScreenshotArgs;
  
    try {
      const result = await adb.screenshot(outputPath, deviceSerial);
  
      if (typeof result === 'string') {
        // Path returned
        return {
          content: [
            {
              type: 'text',
              text: `Screenshot saved to: ${result}`,
            },
          ],
        };
      } else {
        // Buffer returned - encode as base64
        const base64 = result.toString('base64');
        return {
          content: [
            {
              type: 'text',
              text: 'Screenshot captured successfully',
            },
            {
              type: 'image',
              data: base64,
              mimeType: 'image/png',
            },
          ],
        };
      }
    } catch (error) {
      throw new Error(`Screenshot failed: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/index.ts:41-56 (schema)

  Input schema and description for the android_screenshot tool, provided in the ListToolsRequestHandler response.

  {
    name: 'android_screenshot',
    description: 'Capture a screenshot from the Android device',
    inputSchema: {
      type: 'object',
      properties: {
        outputPath: {
          type: 'string',
          description: 'Local path to save the screenshot (optional). If not provided, returns base64 encoded image.',
        },
        deviceSerial: {
          type: 'string',
          description: 'Specific device serial number to target (optional)',
        },
      },
    },

• src/index.ts:464-465 (registration)

  Registration of the screenshotHandler in the switch statement within CallToolRequestSchema handler.

  case 'android_screenshot':
    return await screenshotHandler(this.adb, args);

• src/adb-wrapper.ts:264-288 (helper)

  Core implementation in ADBWrapper.screenshot method: captures screenshot using 'adb shell screencap', pulls via 'adb pull', cleans up, and returns file path or buffer.

  async screenshot(outputPath?: string, deviceSerial?: string): Promise<string | Buffer> {
    const device = await this.getTargetDevice(deviceSerial);
    const devicePath = '/sdcard/screenshot.png';
  
    // Take screenshot on device
    await this.exec(['shell', 'screencap', '-p', devicePath], device);
  
    if (outputPath) {
      // Pull screenshot to local path
      await this.exec(['pull', devicePath, outputPath], device);
      // Clean up device screenshot
      await this.exec(['shell', 'rm', devicePath], device);
      return outputPath;
    } else {
      // Pull screenshot to temp and read as buffer
      const tempPath = join(tmpdir(), `screenshot_${Date.now()}.png`);
      await this.exec(['pull', devicePath, tempPath], device);
      await this.exec(['shell', 'rm', devicePath], device);
  
      const buffer = await readFile(tempPath);
      // Clean up temp file
      await rm(tempPath, { force: true });
      return buffer;
    }
  }

• src/handlers.ts:3-6 (schema)

  TypeScript interface defining the expected input arguments for the screenshotHandler, matching the tool schema.

  interface ScreenshotArgs {
    outputPath?: string;
    deviceSerial?: string;
  }