Expo iOS Development MCP Server

Instructions

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."),
  });