MCP Mobile Server

Instructions

Implementation Reference

• src/tools/android/media.ts:102-193 (handler)

  The handler function that implements the core logic for the android_screenshot tool. It validates input with Zod schema, ensures output directory exists, captures screenshot using ADB screencap to a temp location on device, pulls the file to local path, cleans up the temp file, verifies the file, and returns success/error response.
  handler: async (args: any) => { const parsed = AndroidScreenshotSchema.parse(args); try { // Ensure output directory exists const outputDir = path.dirname(parsed.outputPath); await fs.mkdir(outputDir, { recursive: true }); const adbArgs = ['-s', parsed.serial, 'exec-out', 'screencap']; if (parsed.options?.format === 'png') { adbArgs.push('-p'); // PNG format } if (parsed.options?.display !== undefined) { adbArgs.push('-d', parsed.options.display.toString()); } // Capture screenshot to temporary location first const tempPath = `/sdcard/screenshot_${Date.now()}.png`; const captureResult = await processExecutor.execute('adb', [ '-s', parsed.serial, 'shell', 'screencap', '-p', tempPath ], { timeout: 30000, }); if (captureResult.exitCode !== 0) { return { success: false, error: { code: 'SCREENSHOT_CAPTURE_FAILED', message: 'Failed to capture screenshot on device', details: captureResult.stderr } }; } // Pull screenshot to local machine const pullResult = await processExecutor.execute('adb', [ '-s', parsed.serial, 'pull', tempPath, parsed.outputPath ], { timeout: 30000, }); // Clean up temporary file await processExecutor.execute('adb', [ '-s', parsed.serial, 'shell', 'rm', tempPath ], { timeout: 10000, }); if (pullResult.exitCode === 0) { // Verify file was created let fileStats; try { fileStats = await fs.stat(parsed.outputPath); } catch { throw new Error(`Screenshot file was not created at ${parsed.outputPath}`); } return { success: true, data: { screenshotPath: parsed.outputPath, fileSize: fileStats.size, format: parsed.options?.format || 'png', device: parsed.serial, timestamp: new Date().toISOString() } }; } else { return { success: false, error: { code: 'SCREENSHOT_PULL_FAILED', message: 'Failed to pull screenshot from device', details: pullResult.stderr } }; } } catch (error: any) { return { success: false, error: { code: 'SCREENSHOT_ERROR', message: error.message, details: error } }; } }
• src/tools/android/media.ts:23-34 (schema)

  Zod schema used internally by the handler for input validation of android_screenshot tool parameters: serial, outputPath, and optional format/display options.
  * Zod validation schema for android_screenshot tool. * * @type {z.ZodObject} */ const AndroidScreenshotSchema = z.object({ serial: z.string().min(1), outputPath: z.string().min(1), options: z.object({ format: z.enum(['png', 'raw']).default('png'), display: z.number().optional(), }).optional(), });
• src/tools/android/media.ts:70-194 (registration)

  Registration of the android_screenshot tool in the tools Map within createAndroidMediaTools function. Includes name, description, inputSchema (JSON Schema for MCP), and the handler function.
  tools.set('android_screenshot', { name: 'android_screenshot', description: 'Capture screenshot from Android device or emulator', inputSchema: { type: 'object', properties: { serial: { type: 'string', description: 'Device serial number (use android_devices_list to get available devices)' }, outputPath: { type: 'string', description: 'Local path where screenshot will be saved (e.g., ./screenshot.png)' }, options: { type: 'object', properties: { format: { type: 'string', enum: ['png', 'raw'], description: 'Screenshot format', default: 'png' }, display: { type: 'number', description: 'Display ID for multi-display devices' } } } }, required: ['serial', 'outputPath'] }, handler: async (args: any) => { const parsed = AndroidScreenshotSchema.parse(args); try { // Ensure output directory exists const outputDir = path.dirname(parsed.outputPath); await fs.mkdir(outputDir, { recursive: true }); const adbArgs = ['-s', parsed.serial, 'exec-out', 'screencap']; if (parsed.options?.format === 'png') { adbArgs.push('-p'); // PNG format } if (parsed.options?.display !== undefined) { adbArgs.push('-d', parsed.options.display.toString()); } // Capture screenshot to temporary location first const tempPath = `/sdcard/screenshot_${Date.now()}.png`; const captureResult = await processExecutor.execute('adb', [ '-s', parsed.serial, 'shell', 'screencap', '-p', tempPath ], { timeout: 30000, }); if (captureResult.exitCode !== 0) { return { success: false, error: { code: 'SCREENSHOT_CAPTURE_FAILED', message: 'Failed to capture screenshot on device', details: captureResult.stderr } }; } // Pull screenshot to local machine const pullResult = await processExecutor.execute('adb', [ '-s', parsed.serial, 'pull', tempPath, parsed.outputPath ], { timeout: 30000, }); // Clean up temporary file await processExecutor.execute('adb', [ '-s', parsed.serial, 'shell', 'rm', tempPath ], { timeout: 10000, }); if (pullResult.exitCode === 0) { // Verify file was created let fileStats; try { fileStats = await fs.stat(parsed.outputPath); } catch { throw new Error(`Screenshot file was not created at ${parsed.outputPath}`); } return { success: true, data: { screenshotPath: parsed.outputPath, fileSize: fileStats.size, format: parsed.options?.format || 'png', device: parsed.serial, timestamp: new Date().toISOString() } }; } else { return { success: false, error: { code: 'SCREENSHOT_PULL_FAILED', message: 'Failed to pull screenshot from device', details: pullResult.stderr } }; } } catch (error: any) { return { success: false, error: { code: 'SCREENSHOT_ERROR', message: error.message, details: error } }; } } });
• src/tools/android/media.ts:73-100 (schema)

  JSON Schema definition for the android_screenshot tool input, provided in the tool registration for MCP protocol compliance.
  inputSchema: { type: 'object', properties: { serial: { type: 'string', description: 'Device serial number (use android_devices_list to get available devices)' }, outputPath: { type: 'string', description: 'Local path where screenshot will be saved (e.g., ./screenshot.png)' }, options: { type: 'object', properties: { format: { type: 'string', enum: ['png', 'raw'], description: 'Screenshot format', default: 'png' }, display: { type: 'number', description: 'Display ID for multi-display devices' } } } }, required: ['serial', 'outputPath']
• src/utils/tool-categories.ts:254-262 (helper)

  Tool metadata registration in the central TOOL_REGISTRY, categorizing android_screenshot as essential Android tool requiring ADB.
  'android_screenshot': { name: 'android_screenshot', category: ToolCategory.ESSENTIAL, platform: 'android', requiredTools: [RequiredTool.ADB], description: 'Capture screenshot from Android device', safeForTesting: false, performance: { expectedDuration: 5000, timeout: 30000 } },