ui.screenshot
Capture iOS Simulator screenshots to document UI states during React Native/Expo development, using simctl for reliable image capture.
Instructions
Take a screenshot of the current UI state (via simctl)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Name prefix for the screenshot file. | screenshot |
Implementation Reference
- src/simulator/screenshots.ts:19-65 (handler)Core handler function that captures screenshot using simctl on the booted simulator, handles errors, manages state and artifacts, returns path and timestamp.
export async function takeScreenshot(name: string = "screenshot"): Promise<ScreenshotResult> { logger.info("simulator", `Taking screenshot: ${name}`); // Check if simulator is booted if (!stateManager.isSimulatorReady()) { const bootedDevice = await getBootedDevice(); if (!bootedDevice) { throw createError("SIM_NOT_BOOTED", "No simulator is currently booted", { details: "Boot a simulator first using simulator.boot", }); } stateManager.updateSimulator({ state: "booted", udid: bootedDevice.udid, deviceName: bootedDevice.name, }); } const screenshotPath = await artifactManager.getScreenshotPath(name); // Use 'booted' to target the currently booted simulator const result = await simctl(["io", "booted", "screenshot", screenshotPath], { timeoutMs: 30000, }); if (result.exitCode !== 0) { throw createError("SIMCTL_FAILED", "Failed to take screenshot", { details: result.stderr, evidence: [logger.formatForEvidence("simulator", 50)], }); } const timestamp = new Date().toISOString(); artifactManager.registerArtifact({ type: "screenshot", path: screenshotPath, metadata: { name, captureMethod: "simctl" }, }); logger.info("simulator", `Screenshot saved to ${screenshotPath}`); return { path: screenshotPath, timestamp, }; } - src/mcp/server.ts:685-704 (registration)MCP server registration of the 'ui.screenshot' tool, including thin wrapper handler that calls takeScreenshot.
server.tool( "ui.screenshot", "Take a screenshot of the current UI state (via simctl)", SimulatorScreenshotInputSchema.shape, async (args) => { try { const result = await takeScreenshot(args.name ?? "ui-screenshot"); return { content: [ { type: "text", text: JSON.stringify({ success: true, ...result }, null, 2), }, ], }; } catch (error) { return handleToolError(error); } } ); - src/mcp/schemas.ts:28-30 (schema)Zod input schema for screenshot tools: optional 'name' parameter with default 'screenshot'.
export const SimulatorScreenshotInputSchema = z.object({ name: z.string().optional().default("screenshot").describe("Name prefix for the screenshot file."), });