@sensaiorg/adapter-ios 0.1.0

package/src/tools/ios-tools.ts

@@ -0,0 +1,1055 @@
+/**
+ * iOS MCP Tools — registered when an iOS Simulator is connected.
+ *
+ * Uses xcrun simctl for all operations.
+ */
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { SimctlClient } from "../transport/simctl-client.js";
+
+/** Sleep helper */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Parsed accessibility element from idb describe-all output */
+interface IdbAccessibilityElement {
+  type: string | null;
+  label: string | null;
+  value: string | null;
+  frame: { x: number; y: number; w: number; h: number } | null;
+  enabled: boolean;
+  rawLine?: string;
+}
+
+/**
+ * Parse the idb `ui describe-all` output into structured elements.
+ *
+ * idb output varies but typically contains lines like:
+ *   Type: Button, Label: "Save", Frame: {{10, 20}, {100, 44}}, Enabled: true
+ * or a flat accessibility dump. We parse what we can and include raw on failure.
+ */
+function parseIdbAccessibilityOutput(raw: string): IdbAccessibilityElement[] {
+  const elements: IdbAccessibilityElement[] = [];
+  const lines = raw.split("\n").filter(l => l.trim().length > 0);
+
+  for (const line of lines) {
+    try {
+      // Try to extract structured fields from each line
+      const typeMatch = line.match(/(?:Type|AXType|class)\s*[:=]\s*["']?([^"',}\n]+)/i);
+      const labelMatch = line.match(/(?:Label|AXLabel|title|text)\s*[:=]\s*["']?([^"'\n}]+?)["']?\s*(?:,|$|\})/i);
+      const valueMatch = line.match(/(?:Value|AXValue)\s*[:=]\s*["']?([^"'\n}]+?)["']?\s*(?:,|$|\})/i);
+      const frameMatch = line.match(/(?:Frame|frame|AXFrame)\s*[:=]\s*\{\{?\s*([\d.]+)\s*,\s*([\d.]+)\s*\}\s*,\s*\{?\s*([\d.]+)\s*,\s*([\d.]+)/i);
+      const enabledMatch = line.match(/(?:Enabled|enabled|AXEnabled)\s*[:=]\s*(true|false|1|0|yes|no)/i);
+
+      // Only include if we extracted at least something useful
+      const hasData = typeMatch || labelMatch || valueMatch || frameMatch;
+      if (!hasData) {
+        // Try JSON parsing as fallback (some idb versions output JSON)
+        if (line.trim().startsWith("{")) {
+          try {
+            const obj = JSON.parse(line.trim());
+            elements.push({
+              type: obj.type || obj.AXType || obj.class || null,
+              label: obj.label || obj.AXLabel || obj.title || obj.text || null,
+              value: obj.value || obj.AXValue || null,
+              frame: obj.frame ? { x: obj.frame.x ?? 0, y: obj.frame.y ?? 0, w: obj.frame.width ?? obj.frame.w ?? 0, h: obj.frame.height ?? obj.frame.h ?? 0 } : null,
+              enabled: obj.enabled !== false,
+            });
+            continue;
+          } catch {
+            // not JSON either
+          }
+        }
+        // Include raw line if it looks like it has content
+        if (line.trim().length > 2) {
+          elements.push({
+            type: null,
+            label: line.trim(),
+            value: null,
+            frame: null,
+            enabled: true,
+            rawLine: line.trim(),
+          });
+        }
+        continue;
+      }
+
+      elements.push({
+        type: typeMatch?.[1]?.trim() ?? null,
+        label: labelMatch?.[1]?.trim() ?? null,
+        value: valueMatch?.[1]?.trim() ?? null,
+        frame: frameMatch ? {
+          x: parseFloat(frameMatch[1]),
+          y: parseFloat(frameMatch[2]),
+          w: parseFloat(frameMatch[3]),
+          h: parseFloat(frameMatch[4]),
+        } : null,
+        enabled: enabledMatch ? ["true", "1", "yes"].includes(enabledMatch[1].toLowerCase()) : true,
+      });
+    } catch {
+      // If line parsing fails entirely, include raw
+      elements.push({
+        type: null,
+        label: line.trim(),
+        value: null,
+        frame: null,
+        enabled: true,
+        rawLine: line.trim(),
+      });
+    }
+  }
+
+  return elements;
+}
+
+export function registerIosTools(
+  server: McpServer,
+  simctl: SimctlClient,
+  bundleId: string,
+  prefix: string,
+): void {
+
+  // ── diagnose_screen ──────────────────────────────────────────────
+  server.tool(
+    `${prefix}diagnose_screen`,
+    "Get a comprehensive diagnosis of the current iOS screen: screenshot (base64), recent logs, and device info. START HERE for any iOS debugging session.",
+    {},
+    async () => {
+      try {
+        const [deviceInfo, screenshotBuf, logs] = await Promise.allSettled([
+          simctl.getDeviceInfo(),
+          simctl.screenshot(),
+          simctl.getLogs(`processImagePath contains "${bundleId}"`, "30s")
+            .catch(() => "(log retrieval failed)"),
+        ]);
+
+        const device = deviceInfo.status === "fulfilled" ? deviceInfo.value : null;
+        const screenshot = screenshotBuf.status === "fulfilled"
+          ? screenshotBuf.value.toString("base64")
+          : null;
+        const recentLogs = logs.status === "fulfilled"
+          ? (logs.value as string).split("\n").slice(-50).join("\n")
+          : "(unavailable)";
+
+        const result = {
+          platform: "ios",
+          device: device ? { name: device.name, runtime: device.runtime, udid: device.udid } : "unknown",
+          bundleId,
+          hasScreenshot: !!screenshot,
+          recentLogs,
+        };
+
+        const content: Array<{ type: "text"; text: string } | { type: "image"; data: string; mimeType: string }> = [
+          { type: "text" as const, text: JSON.stringify(result) },
+        ];
+        if (screenshot) {
+          content.push({ type: "image" as const, data: screenshot, mimeType: "image/png" });
+        }
+
+        return { content };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Error diagnosing iOS screen: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── take_screenshot ──────────────────────────────────────────────
+  server.tool(
+    `${prefix}take_screenshot`,
+    "Capture the current iOS Simulator screen as a PNG image.",
+    {},
+    async () => {
+      try {
+        const buf = await simctl.screenshot();
+        return {
+          content: [{
+            type: "image" as const,
+            data: buf.toString("base64"),
+            mimeType: "image/png",
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Screenshot failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── tap ──────────────────────────────────────────────────────────
+  server.tool(
+    `${prefix}tap`,
+    "Tap at specific coordinates on the iOS Simulator screen.",
+    {
+      x: z.number().describe("X coordinate"),
+      y: z.number().describe("Y coordinate"),
+    },
+    async ({ x, y }) => {
+      try {
+        await simctl.tap(x, y);
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ ok: true }) }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Tap failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── type_text ────────────────────────────────────────────────────
+  server.tool(
+    `${prefix}type_text`,
+    "Type text into the currently focused field on the iOS Simulator.",
+    {
+      text: z.string().describe("Text to type"),
+    },
+    async ({ text }) => {
+      try {
+        await simctl.typeText(text);
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ ok: true }) }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Type failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── get_logs ─────────────────────────────────────────────────────
+  server.tool(
+    `${prefix}get_logs`,
+    "Get recent iOS Simulator logs filtered by predicate. Defaults to app logs.",
+    {
+      predicate: z.string().optional().describe("Log predicate filter (default: app logs)"),
+      duration: z.string().optional().describe("Time window, e.g. '30s', '5m' (default: '30s')"),
+      grep: z.string().optional().describe("Additional grep filter on output"),
+      maxLines: z.number().optional().describe("Maximum lines to return (default: 100)"),
+    },
+    async ({ predicate, duration, grep, maxLines }) => {
+      try {
+        const pred = predicate ?? `processImagePath contains "${bundleId}"`;
+        const dur = duration ?? "30s";
+        let output = await simctl.getLogs(pred, dur);
+
+        if (grep) {
+          const regex = new RegExp(grep, "i");
+          output = output.split("\n").filter(line => regex.test(line)).join("\n");
+        }
+
+        const lines = output.split("\n");
+        const limit = maxLines ?? 100;
+        const trimmed = lines.slice(-limit).join("\n");
+
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({
+              totalLines: lines.length,
+              returnedLines: Math.min(lines.length, limit),
+              predicate: pred,
+              duration: dur,
+              logs: trimmed,
+            }),
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Log retrieval failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── launch_app ───────────────────────────────────────────────────
+  server.tool(
+    `${prefix}launch_app`,
+    "Launch an app on the iOS Simulator by bundle ID.",
+    {
+      bundle: z.string().optional().describe(`Bundle ID (default: ${bundleId})`),
+    },
+    async ({ bundle }) => {
+      try {
+        const bid = bundle ?? bundleId;
+        await simctl.launchApp(bid);
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ launched: bid, success: true }) }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Launch failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── terminate_app ────────────────────────────────────────────────
+  server.tool(
+    `${prefix}terminate_app`,
+    "Terminate a running app on the iOS Simulator.",
+    {
+      bundle: z.string().optional().describe(`Bundle ID (default: ${bundleId})`),
+    },
+    async ({ bundle }) => {
+      try {
+        const bid = bundle ?? bundleId;
+        await simctl.terminateApp(bid);
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ terminated: bid, success: true }) }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Terminate failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── swipe ───────────────────────────────────────────────────────
+  server.tool(
+    `${prefix}swipe`,
+    "Swipe from one point to another on the iOS Simulator screen.",
+    {
+      startX: z.number().describe("Start X coordinate"),
+      startY: z.number().describe("Start Y coordinate"),
+      endX: z.number().describe("End X coordinate"),
+      endY: z.number().describe("End Y coordinate"),
+      duration: z.number().optional().describe("Swipe duration in seconds (default: 0.3)"),
+    },
+    async ({ startX, startY, endX, endY, duration }) => {
+      try {
+        await simctl.swipe(startX, startY, endX, endY, duration ?? 0.3);
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ ok: true }) }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Swipe failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── describe_all ───────────────────────────────────────────────
+  server.tool(
+    `${prefix}describe_all`,
+    "Get the full accessibility tree of the current iOS screen. Returns structured element info including labels, roles, frames, and states.",
+    {},
+    async () => {
+      try {
+        const output = await simctl.describeAll();
+        return {
+          content: [{ type: "text" as const, text: output }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Describe all failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── describe_point ─────────────────────────────────────────────
+  server.tool(
+    `${prefix}describe_point`,
+    "Get accessibility info for the element at specific coordinates on the iOS screen.",
+    {
+      x: z.number().describe("X coordinate"),
+      y: z.number().describe("Y coordinate"),
+    },
+    async ({ x, y }) => {
+      try {
+        const output = await simctl.describePoint(x, y);
+        return {
+          content: [{ type: "text" as const, text: output }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Describe point failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── open_deep_link ──────────────────────────────────────────────
+  server.tool(
+    `${prefix}open_deep_link`,
+    "Open the app via a deep link URL scheme on iOS Simulator. Navigates directly to a specific screen without tapping through the UI.",
+    {
+      url: z.string().describe("Deep link URL (e.g., myapp://screen/detail?id=123 or https://example.com/path)"),
+    },
+    async ({ url }) => {
+      try {
+        await simctl.exec("openurl", [url]);
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ success: true, url }) }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `open_deep_link failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── get_device_info ──────────────────────────────────────────────
+  server.tool(
+    `${prefix}get_device_info`,
+    "Get detailed info about the connected iOS Simulator (name, runtime, UDID, state).",
+    {},
+    async () => {
+      try {
+        const info = await simctl.getDeviceInfo();
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(info) }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Device info failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── get_ui_tree ────────────────────────────────────────────────
+  server.tool(
+    `${prefix}get_ui_tree`,
+    "Parse the iOS accessibility tree into structured JSON. Returns elements with type, label, value, frame (x,y,w,h), and enabled state.",
+    {},
+    async () => {
+      try {
+        const raw = await simctl.describeAll();
+        const elements = parseIdbAccessibilityOutput(raw);
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({
+              totalElements: elements.length,
+              clickableElements: elements.filter(e => e.type === "Button" || e.type === "Link").length,
+              textElements: elements.filter(e => e.label || e.value).length,
+              elements,
+            }),
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `get_ui_tree failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── get_screen_text ────────────────────────────────────────────
+  server.tool(
+    `${prefix}get_screen_text`,
+    "Extract all visible text from the iOS screen's accessibility tree. Returns a flat array of text strings in reading order.",
+    {},
+    async () => {
+      try {
+        const raw = await simctl.describeAll();
+        const elements = parseIdbAccessibilityOutput(raw);
+        const texts = elements
+          .map(e => e.label || e.value || "")
+          .filter(t => t.length > 0);
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ screenText: texts }) }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `get_screen_text failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── get_element_details ────────────────────────────────────────
+  server.tool(
+    `${prefix}get_element_details`,
+    "Find and inspect iOS UI elements matching a text query or at specific coordinates. Returns full details including frame, type, and state.",
+    {
+      query: z.string().optional().describe("Text to search for (case-insensitive substring match)"),
+      x: z.number().optional().describe("X coordinate to find element at"),
+      y: z.number().optional().describe("Y coordinate to find element at"),
+    },
+    async ({ query, x, y }) => {
+      try {
+        // If coordinates given, use describe_point for precise result
+        if (x !== undefined && y !== undefined) {
+          const pointInfo = await simctl.describePoint(x, y);
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify({ found: 1, raw: pointInfo }) }],
+          };
+        }
+
+        if (!query) {
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify({ error: "Provide either 'query' or x/y coordinates" }) }],
+            isError: true,
+          };
+        }
+
+        const raw = await simctl.describeAll();
+        const elements = parseIdbAccessibilityOutput(raw);
+        const lowerQuery = query.toLowerCase();
+        const matches = elements.filter(e =>
+          (e.label && e.label.toLowerCase().includes(lowerQuery)) ||
+          (e.value && e.value.toLowerCase().includes(lowerQuery)) ||
+          (e.type && e.type.toLowerCase().includes(lowerQuery))
+        );
+
+        if (matches.length === 0) {
+          return {
+            content: [{
+              type: "text" as const,
+              text: JSON.stringify({ found: 0, message: `No elements found matching "${query}"`, hint: "Try ios_get_screen_text to see all visible text." }),
+            }],
+          };
+        }
+
+        const details = matches.map(e => ({
+          ...e,
+          centerX: e.frame ? Math.round(e.frame.x + e.frame.w / 2) : null,
+          centerY: e.frame ? Math.round(e.frame.y + e.frame.h / 2) : null,
+        }));
+
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ found: matches.length, elements: details }) }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `get_element_details failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── wait_for_text ──────────────────────────────────────────────
+  server.tool(
+    `${prefix}wait_for_text`,
+    "Poll the iOS screen until specific text appears. Essential after navigation, screen transitions, or async operations.",
+    {
+      text: z.string().describe("Text to wait for (case-insensitive substring match)"),
+      timeoutMs: z.number().optional().describe("Maximum wait time in ms (default: 10000)"),
+      pollIntervalMs: z.number().optional().describe("Polling interval in ms (default: 1000)"),
+    },
+    async ({ text, timeoutMs, pollIntervalMs }) => {
+      const timeout = timeoutMs ?? 10_000;
+      const interval = pollIntervalMs ?? 1_000;
+      const startTime = Date.now();
+      const searchLower = text.toLowerCase();
+      let attempts = 0;
+
+      while (Date.now() - startTime < timeout) {
+        attempts++;
+        try {
+          const raw = await simctl.describeAll();
+          const elements = parseIdbAccessibilityOutput(raw);
+          const allText = elements
+            .map(e => `${e.label ?? ""} ${e.value ?? ""}`.toLowerCase())
+            .join(" ");
+          if (allText.includes(searchLower)) {
+            return {
+              content: [{ type: "text" as const, text: JSON.stringify({ success: true, found: true, text, elapsedMs: Date.now() - startTime, attempts }) }],
+            };
+          }
+        } catch {
+          // retry
+        }
+        if (Date.now() - startTime + interval < timeout) {
+          await sleep(interval);
+        }
+      }
+
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify({ success: false, found: false, text, elapsedMs: Date.now() - startTime, attempts, hint: "Text did not appear within timeout." }),
+        }],
+      };
+    },
+  );
+
+  // ── scroll_to_text ─────────────────────────────────────────────
+  server.tool(
+    `${prefix}scroll_to_text`,
+    "Swipe/scroll repeatedly until specific text appears on the iOS screen. Useful for finding elements in long scrollable lists.",
+    {
+      text: z.string().describe("Text to scroll to (case-insensitive substring match)"),
+      direction: z.enum(["up", "down", "left", "right"]).optional().describe("Scroll direction (default: down)"),
+      maxScrolls: z.number().optional().describe("Maximum scroll attempts (default: 5)"),
+    },
+    async ({ text, direction, maxScrolls }) => {
+      const dir = direction ?? "down";
+      const max = maxScrolls ?? 5;
+      const searchLower = text.toLowerCase();
+
+      // Default screen dimensions for iPhone (logical points)
+      const screenW = 390;
+      const screenH = 844;
+      const centerX = Math.round(screenW / 2);
+
+      for (let i = 0; i < max; i++) {
+        try {
+          const raw = await simctl.describeAll();
+          const elements = parseIdbAccessibilityOutput(raw);
+          const match = elements.find(e =>
+            (e.label && e.label.toLowerCase().includes(searchLower)) ||
+            (e.value && e.value.toLowerCase().includes(searchLower))
+          );
+
+          if (match) {
+            const center = match.frame
+              ? { x: Math.round(match.frame.x + match.frame.w / 2), y: Math.round(match.frame.y + match.frame.h / 2) }
+              : null;
+            return {
+              content: [{
+                type: "text" as const,
+                text: JSON.stringify({ success: true, found: true, text: match.label || match.value, center, scrollsNeeded: i }),
+              }],
+            };
+          }
+        } catch {
+          // continue scrolling
+        }
+
+        // Perform swipe
+        let startX = centerX, startY = Math.round(screenH * 0.7);
+        let endX = centerX, endY = Math.round(screenH * 0.3);
+        if (dir === "up") { startY = Math.round(screenH * 0.3); endY = Math.round(screenH * 0.7); }
+        if (dir === "left") { startX = Math.round(screenW * 0.7); endX = Math.round(screenW * 0.3); startY = Math.round(screenH / 2); endY = startY; }
+        if (dir === "right") { startX = Math.round(screenW * 0.3); endX = Math.round(screenW * 0.7); startY = Math.round(screenH / 2); endY = startY; }
+
+        await simctl.swipe(startX, startY, endX, endY, 0.3);
+        await sleep(500);
+      }
+
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify({ success: false, found: false, text, scrollAttempts: max, hint: `Text "${text}" not found after ${max} scroll attempts.` }),
+        }],
+      };
+    },
+  );
+
+  // ── fill_form ──────────────────────────────────────────────────
+  server.tool(
+    `${prefix}fill_form`,
+    "Batch fill form fields on iOS. For each field: finds element by label in the accessibility tree, taps its coordinates, clears existing text, types new value.",
+    {
+      fields: z.array(z.object({
+        label: z.string().describe("Label/text to find the field by (case-insensitive)"),
+        value: z.string().describe("Text to enter in the field"),
+        clearFirst: z.boolean().optional().describe("Clear existing text before typing (default: true)"),
+      })).describe("Array of field labels and values to fill"),
+    },
+    async ({ fields }) => {
+      const results: Array<{ field: string; success: boolean; error?: string }> = [];
+
+      for (const field of fields) {
+        const clearFirst = field.clearFirst ?? true;
+        try {
+          const raw = await simctl.describeAll();
+          const elements = parseIdbAccessibilityOutput(raw);
+          const lowerLabel = field.label.toLowerCase();
+
+          // Find the element by label
+          const match = elements.find(e =>
+            (e.label && e.label.toLowerCase().includes(lowerLabel)) ||
+            (e.value && e.value.toLowerCase().includes(lowerLabel))
+          );
+
+          if (!match || !match.frame) {
+            results.push({ field: field.label, success: false, error: "Element not found or no frame" });
+            continue;
+          }
+
+          const tapX = Math.round(match.frame.x + match.frame.w / 2);
+          const tapY = Math.round(match.frame.y + match.frame.h / 2);
+
+          // Tap the field
+          await simctl.tap(tapX, tapY);
+          await sleep(300);
+
+          // Clear existing text if needed (select all + delete)
+          if (clearFirst) {
+            // Triple-tap to select all, then delete
+            await simctl.tap(tapX, tapY);
+            await sleep(50);
+            await simctl.tap(tapX, tapY);
+            await sleep(50);
+            await simctl.tap(tapX, tapY);
+            await sleep(200);
+            await simctl.typeText("");  // This may not clear; use idb key sequence instead
+            try {
+              await simctl.keyPress(42); // DELETE key via idb
+            } catch {
+              // If keyPress fails, try typing empty — field may already be selected
+            }
+          }
+
+          // Type the value
+          await simctl.typeText(field.value);
+          await sleep(200);
+
+          results.push({ field: field.label, success: true });
+        } catch (err) {
+          results.push({ field: field.label, success: false, error: err instanceof Error ? err.message : String(err) });
+        }
+      }
+
+      const allSuccess = results.every(r => r.success);
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify({ success: allSuccess, filledCount: results.filter(r => r.success).length, totalFields: fields.length, results }),
+        }],
+      };
+    },
+  );
+
+  // ── tap_and_wait ───────────────────────────────────────────────
+  server.tool(
+    `${prefix}tap_and_wait`,
+    "Tap an element (by label or coordinates) on iOS, then poll until expected text appears. Combines tap + wait_for_text in one call.",
+    {
+      label: z.string().optional().describe("Label/text of element to tap (case-insensitive)"),
+      x: z.number().optional().describe("X coordinate to tap (used if label not found or not provided)"),
+      y: z.number().optional().describe("Y coordinate to tap (used if label not found or not provided)"),
+      waitForText: z.string().describe("Text to wait for after tap"),
+      timeoutMs: z.number().optional().describe("Max wait time in ms (default: 10000)"),
+    },
+    async ({ label, x, y, waitForText, timeoutMs }) => {
+      try {
+        let tapX = x;
+        let tapY = y;
+        let matchedBy = tapX !== undefined ? `coordinates (${tapX}, ${tapY})` : "";
+
+        // Find element by label if provided
+        if (label) {
+          const raw = await simctl.describeAll();
+          const elements = parseIdbAccessibilityOutput(raw);
+          const lowerLabel = label.toLowerCase();
+          const match = elements.find(e =>
+            (e.label && e.label.toLowerCase().includes(lowerLabel)) ||
+            (e.value && e.value.toLowerCase().includes(lowerLabel))
+          );
+          if (match?.frame) {
+            tapX = Math.round(match.frame.x + match.frame.w / 2);
+            tapY = Math.round(match.frame.y + match.frame.h / 2);
+            matchedBy = `label="${match.label || match.value}"`;
+          }
+        }
+
+        if (tapX === undefined || tapY === undefined) {
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify({ success: false, error: "Element not found and no coordinates provided" }) }],
+          };
+        }
+
+        // Tap
+        await simctl.tap(tapX, tapY);
+
+        // Wait for text
+        const timeout = timeoutMs ?? 10_000;
+        const interval = 500;
+        const startTime = Date.now();
+        const searchLower = waitForText.toLowerCase();
+
+        while (Date.now() - startTime < timeout) {
+          await sleep(interval);
+          try {
+            const raw = await simctl.describeAll();
+            const elements = parseIdbAccessibilityOutput(raw);
+            const allText = elements.map(e => `${e.label ?? ""} ${e.value ?? ""}`.toLowerCase()).join(" ");
+            if (allText.includes(searchLower)) {
+              return {
+                content: [{
+                  type: "text" as const,
+                  text: JSON.stringify({ success: true, tappedBy: matchedBy, tapped: { x: tapX, y: tapY }, waitedFor: waitForText, elapsedMs: Date.now() - startTime }),
+                }],
+              };
+            }
+          } catch {
+            // retry
+          }
+        }
+
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({ success: false, tappedBy: matchedBy, tapped: { x: tapX, y: tapY }, waitedFor: waitForText, timedOut: true, elapsedMs: Date.now() - startTime }),
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `tap_and_wait failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── assert_screen ──────────────────────────────────────────────
+  server.tool(
+    `${prefix}assert_screen`,
+    "Quickly verify the iOS screen contains (or doesn't contain) expected text. Returns pass/fail without the full UI tree, saving tokens.",
+    {
+      contains: z.array(z.string()).optional().describe("Text strings that MUST be on screen"),
+      notContains: z.array(z.string()).optional().describe("Text strings that must NOT be on screen"),
+    },
+    async ({ contains, notContains }) => {
+      try {
+        const raw = await simctl.describeAll();
+        const elements = parseIdbAccessibilityOutput(raw);
+        const allText = elements
+          .map(e => `${e.label ?? ""} ${e.value ?? ""}`.toLowerCase());
+
+        const missing: string[] = [];
+        const unexpected: string[] = [];
+
+        for (const expected of contains ?? []) {
+          if (!allText.some(t => t.includes(expected.toLowerCase()))) {
+            missing.push(expected);
+          }
+        }
+        for (const banned of notContains ?? []) {
+          if (allText.some(t => t.includes(banned.toLowerCase()))) {
+            unexpected.push(banned);
+          }
+        }
+
+        const pass = missing.length === 0 && unexpected.length === 0;
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({
+              pass,
+              ...(missing.length > 0 ? { missing } : {}),
+              ...(unexpected.length > 0 ? { unexpected } : {}),
+            }),
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `assert_screen failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── get_crash_info ─────────────────────────────────────────────
+  server.tool(
+    `${prefix}get_crash_info`,
+    "Get recent crash and exception logs from the iOS Simulator. Searches the last N minutes for crash/exception/fatal/SIGABRT messages.",
+    {
+      minutes: z.number().optional().describe("How many minutes back to search (default: 5)"),
+      maxLines: z.number().optional().describe("Maximum lines to return (default: 50)"),
+    },
+    async ({ minutes, maxLines }) => {
+      try {
+        const output = await simctl.getCrashLogs(minutes ?? 5);
+        const lines = output.split("\n").filter(l => l.trim().length > 0);
+        const limit = maxLines ?? 50;
+        const trimmed = lines.slice(-limit);
+
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({ totalLines: lines.length, returnedLines: trimmed.length, logs: trimmed.join("\n") }),
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `get_crash_info failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── hot_reload ─────────────────────────────────────────────────
+  server.tool(
+    `${prefix}hot_reload`,
+    "Trigger a React Native reload via the Metro bundler on iOS. 'hot' performs a fast refresh, 'full' performs a complete bundle reload.",
+    {
+      type: z.enum(["hot", "full"]).optional().describe("Reload type: 'hot' for fast refresh (default), 'full' for complete reload"),
+    },
+    async ({ type }) => {
+      const reloadType = type ?? "hot";
+      try {
+        const endpoint = reloadType === "full"
+          ? "http://localhost:8081/reload"
+          : "http://localhost:8081/message";
+
+        if (reloadType === "full") {
+          await fetch(endpoint);
+        } else {
+          await fetch(endpoint, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ method: "reload" }),
+          });
+        }
+
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({ success: true, type: reloadType, message: `${reloadType === "full" ? "Full" : "Hot"} reload triggered.` }),
+          }],
+        };
+      } catch (err) {
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({
+              success: false,
+              error: err instanceof Error ? err.message : String(err),
+              hints: ["Ensure Metro bundler is running (npx react-native start)", "Ensure the app is in dev mode"],
+            }),
+          }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── start_recording ───────────────────────────────────────────
+  // eslint-disable-next-line @typescript-eslint/consistent-type-imports
+  let iosRecordingProcess: ReturnType<typeof import("node:child_process").spawn> | null = null;
+  let iosRecordingPath: string | null = null;
+
+  server.tool(
+    `${prefix}start_recording`,
+    "Start recording the iOS Simulator screen. Recording runs in the background. Use stop_recording to finish and retrieve the video.",
+    {
+      maxDurationSec: z.number().optional().describe("Maximum recording duration in seconds (default: 60)"),
+    },
+    async ({ maxDurationSec }) => {
+      if (iosRecordingProcess) {
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ error: "Recording already in progress. Call ios_stop_recording first." }) }],
+          isError: true,
+        };
+      }
+
+      try {
+        const { spawn } = await import("node:child_process");
+        const duration = maxDurationSec ?? 60;
+        iosRecordingPath = `/tmp/sensai-ios-recording-${Date.now()}.mp4`;
+
+        // simctl recordVideo runs until SIGINT
+        const proc = spawn("xcrun", [
+          "simctl", "io", "booted", "recordVideo",
+          "--force", iosRecordingPath,
+        ], { stdio: "ignore" });
+
+        iosRecordingProcess = proc;
+
+        // Auto-stop after max duration
+        setTimeout(() => {
+          if (iosRecordingProcess === proc) {
+            proc.kill("SIGINT");
+            iosRecordingProcess = null;
+          }
+        }, duration * 1000);
+
+        proc.on("exit", () => {
+          if (iosRecordingProcess === proc) {
+            iosRecordingProcess = null;
+          }
+        });
+
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({ ok: true, maxDurationSec: duration, path: iosRecordingPath }),
+          }],
+        };
+      } catch (err) {
+        iosRecordingProcess = null;
+        return {
+          content: [{ type: "text" as const, text: `start_recording failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+
+  // ── stop_recording ────────────────────────────────────────────
+  server.tool(
+    `${prefix}stop_recording`,
+    "Stop the active iOS screen recording and retrieve the MP4 video file.",
+    {
+      savePath: z.string().optional().describe("Local path to save the MP4 (optional). If not provided, returns base64."),
+    },
+    async ({ savePath }) => {
+      if (!iosRecordingProcess) {
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({ error: "No active recording. Call ios_start_recording first." }) }],
+          isError: true,
+        };
+      }
+
+      try {
+        // Send SIGINT to finalize the recording
+        iosRecordingProcess.kill("SIGINT");
+        iosRecordingProcess = null;
+
+        // Wait for file to be finalized
+        await sleep(2000);
+
+        const recordPath = iosRecordingPath!;
+        const { readFile: rf, unlink: ul, copyFile: cp } = await import("node:fs/promises");
+
+        if (savePath) {
+          await cp(recordPath, savePath);
+          await ul(recordPath).catch(() => {});
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify({ ok: true, savedTo: savePath }) }],
+          };
+        }
+
+        const data = await rf(recordPath);
+        await ul(recordPath).catch(() => {});
+        iosRecordingPath = null;
+
+        return {
+          content: [{
+            type: "text" as const,
+            text: JSON.stringify({ ok: true, format: "mp4", sizeBytes: data.length, base64: data.toString("base64") }),
+          }],
+        };
+      } catch (err) {
+        iosRecordingProcess = null;
+        return {
+          content: [{ type: "text" as const, text: `stop_recording failed: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        };
+      }
+    },
+  );
+}