Expo iOS Development MCP Server

Instructions

Implementation Reference

• src/expo/flow.ts:33-151 (handler)

  Core handler function that executes a sequence of FlowSteps using a provided ToolExecutor, with error handling, logging, and optional screenshots on failure.
  export async function runFlow( steps: FlowStep[], executor: ToolExecutor, options: { stopOnError?: boolean; screenshotOnError?: boolean; } = {} ): Promise<FlowResult> { const { stopOnError = true, screenshotOnError = true } = options; const startTime = Date.now(); const results: StepResult[] = []; const evidence: string[] = []; logger.info("expo", `Starting flow with ${steps.length} steps`); for (let i = 0; i < steps.length; i++) { const step = steps[i]; const stepNumber = i + 1; const stepStart = Date.now(); logger.info("expo", `Step ${stepNumber}/${steps.length}: ${step.tool}`, { description: step.description, }); try { const { success, result, error } = await executor( step.tool, step.input as Record<string, unknown> ); const stepResult: StepResult = { step: stepNumber, tool: step.tool, success, elapsedMs: Date.now() - stepStart, result, error, }; results.push(stepResult); if (!success) { logger.error("expo", `Step ${stepNumber} failed: ${error}`); if (screenshotOnError) { try { const screenshot = await takeScreenshot(`flow-error-step-${stepNumber}`); evidence.push(screenshot.path); } catch { logger.warn("expo", "Failed to capture error screenshot"); } } if (stopOnError) { return { success: false, totalSteps: steps.length, completedSteps: stepNumber - 1, failedStep: stepNumber, results, totalElapsedMs: Date.now() - startTime, evidence: evidence.length > 0 ? evidence : undefined, }; } } else { logger.info("expo", `Step ${stepNumber} completed in ${stepResult.elapsedMs}ms`); } } catch (err) { const stepResult: StepResult = { step: stepNumber, tool: step.tool, success: false, elapsedMs: Date.now() - stepStart, error: err instanceof Error ? err.message : "Unknown error", }; results.push(stepResult); if (screenshotOnError) { try { const screenshot = await takeScreenshot(`flow-error-step-${stepNumber}`); evidence.push(screenshot.path); } catch { // Ignore screenshot errors } } if (stopOnError) { return { success: false, totalSteps: steps.length, completedSteps: stepNumber - 1, failedStep: stepNumber, results, totalElapsedMs: Date.now() - startTime, evidence: evidence.length > 0 ? evidence : undefined, }; } } } const allSuccess = results.every((r) => r.success); logger.info("expo", `Flow completed: ${allSuccess ? "SUCCESS" : "FAILED"}`, { totalSteps: steps.length, completedSteps: results.filter((r) => r.success).length, totalElapsedMs: Date.now() - startTime, }); return { success: allSuccess, totalSteps: steps.length, completedSteps: results.filter((r) => r.success).length, failedStep: allSuccess ? undefined : results.findIndex((r) => !r.success) + 1, results, totalElapsedMs: Date.now() - startTime, evidence: evidence.length > 0 ? evidence : undefined, }; }
• src/mcp/server.ts:765-787 (registration)

  MCP server.tool registration for the 'flow.run' tool, delegating to runFlow with a custom toolExecutor.
  server.tool( "flow.run", "Execute a sequence of tool calls (macro flow)", FlowRunInputSchema.shape, async (args) => { try { const result = await runFlow(args.steps, toolExecutor, { stopOnError: args.stopOnError, }); return { content: [ { type: "text", text: JSON.stringify(result, null, 2), }, ], isError: !result.success, }; } catch (error) { return handleToolError(error); } } );
• src/mcp/schemas.ts:115-118 (schema)

  Zod schema defining the input parameters for the flow.run tool, including steps array and stopOnError option.
  export const FlowRunInputSchema = z.object({ steps: z.array(FlowStepSchema).describe("Steps to execute in sequence."), stopOnError: z.boolean().optional().default(true).describe("Stop flow on first error."), });
• src/mcp/server.ts:709-763 (helper)

  Custom ToolExecutor implementation used by flow.run to execute individual UI and simulator tools via Detox actions.
  const toolExecutor: ToolExecutor = async (toolName, input) => { // This is a simplified executor - in production you might want to // route through the actual MCP tool handlers try { switch (toolName) { case "ui.tap": const tapSnippet = generateTapSnippet({ selector: input.selector as { by: "id" | "text" | "label"; value: string }, x: input.x as number | undefined, y: input.y as number | undefined, }); const tapResult = await runDetoxAction({ actionName: `tap:${(input.selector as { value: string }).value}`, actionSnippet: tapSnippet, }); return { success: tapResult.success, result: tapResult, error: tapResult.error?.message }; case "ui.type": const typeSnippet = generateTypeSnippet({ selector: input.selector as { by: "id" | "text" | "label"; value: string }, text: input.text as string, replace: input.replace as boolean | undefined, }); const typeResult = await runDetoxAction({ actionName: `type:${(input.selector as { value: string }).value}`, actionSnippet: typeSnippet, }); return { success: typeResult.success, result: typeResult, error: typeResult.error?.message }; case "ui.wait_for": const waitSnippet = generateWaitForSnippet({ selector: input.selector as { by: "id" | "text" | "label"; value: string }, visible: input.visible as boolean | undefined, timeout: input.timeout as number | undefined, }); const waitResult = await runDetoxAction({ actionName: `waitFor:${(input.selector as { value: string }).value}`, actionSnippet: waitSnippet, }); return { success: waitResult.success, result: waitResult, error: waitResult.error?.message }; case "simulator.screenshot": const screenshot = await takeScreenshot(input.name as string | undefined); return { success: true, result: screenshot }; default: return { success: false, error: `Unknown tool: ${toolName}` }; } } catch (error) { return { success: false, error: error instanceof Error ? error.message : "Unknown error", }; } };