Expo iOS Development MCP Server

Instructions

Implementation Reference

• src/detox/runner.ts:188-273 (handler)

  The main handler function that starts the Detox session by generating and running a warmup test using the detox CLI, updating the state manager, and handling errors.

  export async function startDetoxSession(configuration?: string): Promise<{
    sessionId: string;
    configuration: string;
  }> {
    logger.info("detox", "Starting Detox session");
  
    if (!hasConfig()) {
      throw createError("CONFIG_NOT_FOUND", "Configuration required for Detox session");
    }
  
    const config = getConfig();
    const detoxConfig = configuration ?? config.detox.configuration;
    const sessionId = uuidv4();
  
    stateManager.updateDetox({
      state: "starting",
      configuration: detoxConfig,
    });
  
    // Run a warmup/healthcheck action
    try {
      // Generate a simple noop test to warm up Detox
      const template = await loadTemplate();
      const warmupCode = ejs.render(template, {
        timestamp: new Date().toISOString(),
        actionName: "warmup",
        actionSnippet: "// Warmup - no action",
        launchApp: true,
        captureData: false,
      });
  
      const testDir = join(config.projectPath, ".mcp-detox-tmp");
      const testFile = join(testDir, "mcp-warmup.test.js");
  
      if (!existsSync(testDir)) {
        await mkdir(testDir, { recursive: true });
      }
  
      await writeFile(testFile, warmupCode, "utf-8");
  
      const detoxBinary = join(config.projectPath, config.detox.detoxBinary);
      const args = [
        "test",
        "--configuration",
        detoxConfig,
        "--testNamePattern",
        "^mcp_action run$",
        testFile,
      ];
  
      const result = await execa(detoxBinary, args, {
        cwd: config.projectPath,
        timeout: config.detox.testTimeoutMs,
        reject: false,
      });
  
      // Cleanup
      try {
        await unlink(testFile);
      } catch {
        // Ignore
      }
  
      if (result.exitCode !== 0) {
        stateManager.updateDetox({ state: "failed" });
        throw createError("DETOX_SESSION_FAILED", "Failed to start Detox session", {
          details: result.stderr || result.stdout,
        });
      }
  
      stateManager.updateDetox({
        state: "ready",
        sessionId,
      });
  
      logger.info("detox", `Detox session started: ${sessionId}`);
  
      return {
        sessionId,
        configuration: detoxConfig,
      };
    } catch (error) {
      stateManager.updateDetox({ state: "failed" });
      throw error;
    }
  }

• src/mcp/schemas.ts:46-49 (schema)

  Zod schema defining the input parameters for the detox.session.start tool, including optional configuration and reuse flags.

  export const DetoxSessionStartInputSchema = z.object({
    configuration: z.string().optional().describe("Detox configuration name. Defaults to config value."),
    reuse: z.boolean().optional().default(true).describe("Reuse existing session if available."),
  });

• src/mcp/server.ts:383-402 (registration)

  Registers the 'detox.session.start' tool in the MCP server, linking the schema and delegating execution to the startDetoxSession handler.

  server.tool(
    "detox.session.start",
    "Start a Detox testing session. Required before running UI actions.",
    DetoxSessionStartInputSchema.shape,
    async (args) => {
      try {
        const result = await startDetoxSession(args.configuration);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify({ success: true, ...result }, null, 2),
            },
          ],
        };
      } catch (error) {
        return handleToolError(error);
      }
    }
  );