react-native-ai-debugger 1.0.45 → 1.0.47

package/build/index.js

@@ -2,6 +2,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { getGuideOverview, getGuideByTopic, getAvailableTopics } from "./core/guides.js";
 import { logBuffer, networkBuffer, bundleErrorBuffer, connectedApps, getActiveSimulatorUdid, scanMetroPorts, fetchDevices, selectMainDevice, connectToDevice, getConnectedApps, executeInApp, listDebugGlobals, inspectGlobal, reloadApp, 
 // React Component Inspection
 getComponentTree, getScreenLayout, inspectComponent, findComponents, pressElement, inspectAtPoint, toggleElementInspector, isInspectorActive, getInspectorSelection, getFirstConnectedApp, getLogs, searchLogs, getLogSummary, getNetworkRequests, searchNetworkRequests, getNetworkStats, formatRequestDetails, 
@@ -41,6 +42,8 @@ formatLogsAsTonl, formatNetworkAsTonl } from "./core/index.js";
 const server = new McpServer({
     name: "react-native-ai-debugger",
     version: "1.0.0"
+}, {
+    instructions: "React Native debugging MCP server. Call get_usage_guide to learn recommended workflows for all tools. Quick start: scan_metro → get_logs / search_logs (console debugging) → ios_screenshot → get_inspector_selection(x, y) (identify components)."
 });
 // ============================================================================
 // Telemetry Wrapper
@@ -50,15 +53,15 @@ const server = new McpServer({
  * Only needs the first ~2KB of the image to find dimensions.
  */
 function getJpegDimensions(buffer) {
-    if (buffer.length < 4 || buffer[0] !== 0xFF || buffer[1] !== 0xD8)
+    if (buffer.length < 4 || buffer[0] !== 0xff || buffer[1] !== 0xd8)
         return null;
     let offset = 2;
     while (offset < buffer.length - 9) {
-        if (buffer[offset] !== 0xFF)
+        if (buffer[offset] !== 0xff)
             return null;
         const marker = buffer[offset + 1];
         // SOF markers: C0-CF except C4 (DHT) and CC (DAC)
-        if (marker >= 0xC0 && marker <= 0xCF && marker !== 0xC4 && marker !== 0xCC) {
+        if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xcc) {
             const height = buffer.readUInt16BE(offset + 5);
             const width = buffer.readUInt16BE(offset + 7);
             return { width, height };
@@ -118,13 +121,15 @@ function registerToolWithTelemetry(toolName, config, handler) {
         try {
             inputTokens = Math.ceil(JSON.stringify(args).length / 4);
         }
-        catch { /* circular refs — leave undefined */ }
+        catch {
+            /* circular refs — leave undefined */
+        }
         try {
             const result = await handler(args);
             // Check if result indicates an error
             if (result?.isError) {
                 success = false;
-                errorMessage = result.content?.[0]?.text || 'Unknown error';
+                errorMessage = result.content?.[0]?.text || "Unknown error";
                 // Extract error context if provided (e.g., the expression that caused a syntax error)
                 errorContext = result._errorContext;
             }
@@ -155,6 +160,38 @@ function registerToolWithTelemetry(toolName, config, handler) {
     });
 }
 /* eslint-enable @typescript-eslint/no-explicit-any */
+// Tool: Usage guide for agents
+registerToolWithTelemetry("get_usage_guide", {
+    description: "Get recommended workflows and best practices for using the debugging tools. Call without parameters to see all available topics with short descriptions. Call with a topic parameter to get the full guide for that topic.",
+    inputSchema: {
+        topic: z
+            .string()
+            .optional()
+            .describe("Topic to get the full guide for. Available topics: setup, inspect, layout, interact, logs, network, state, bundle. Omit to see the overview of all topics.")
+    }
+}, async ({ topic }) => {
+    if (!topic) {
+        return {
+            content: [{ type: "text", text: getGuideOverview() }]
+        };
+    }
+    const guide = getGuideByTopic(topic);
+    if (!guide) {
+        const available = getAvailableTopics().join(", ");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Unknown topic: "${topic}". Available topics: ${available}`
+                }
+            ],
+            isError: true
+        };
+    }
+    return {
+        content: [{ type: "text", text: guide }]
+    };
+});
 // Tool: Scan for Metro servers
 registerToolWithTelemetry("scan_metro", {
     description: "Scan for running Metro bundler servers and automatically connect to any found React Native apps. This is typically the FIRST tool to call when starting a debugging session - it establishes the connection needed for other tools like get_logs, list_debug_globals, execute_in_app, and reload_app.",
@@ -380,15 +417,19 @@ registerToolWithTelemetry("ensure_connection", {
 registerToolWithTelemetry("get_logs", {
     description: "Retrieve console logs from connected React Native app. Tip: Use summary=true first for a quick overview (counts by level + last 5 messages), then fetch specific logs as needed.",
     inputSchema: {
-        maxLogs: z.coerce.number().optional().default(50).describe("Maximum number of logs to return (default: 50)"),
+        maxLogs: z.coerce
+            .number()
+            .optional()
+            .default(50)
+            .describe("Maximum number of logs to return (default: 50)"),
         level: z
             .enum(["all", "log", "warn", "error", "info", "debug"])
             .optional()
             .default("all")
             .describe("Filter by log level (default: all)"),
         startFromText: z.string().optional().describe("Start from the first log line containing this text"),
-        maxMessageLength: z
-            .coerce.number()
+        maxMessageLength: z.coerce
+            .number()
             .optional()
             .default(500)
             .describe("Max characters per message (default: 500, set to 0 for unlimited). Tip: Use lower values for overview, higher when debugging specific data structures."),
@@ -426,7 +467,13 @@ registerToolWithTelemetry("get_logs", {
             ]
         };
     }
-    const { logs, count, formatted } = getLogs(logBuffer, { maxLogs, level, startFromText, maxMessageLength, verbose });
+    const { logs, count, formatted } = getLogs(logBuffer, {
+        maxLogs,
+        level,
+        startFromText,
+        maxMessageLength,
+        verbose
+    });
     // Check connection health
     let connectionWarning = "";
     if (count === 0) {
@@ -445,7 +492,7 @@ registerToolWithTelemetry("get_logs", {
     let gapWarning = "";
     if (recentGaps.length > 0) {
         const latestGap = recentGaps[recentGaps.length - 1];
-        const gapDuration = latestGap.durationMs || (Date.now() - latestGap.disconnectedAt.getTime());
+        const gapDuration = latestGap.durationMs || Date.now() - latestGap.disconnectedAt.getTime();
         if (latestGap.reconnectedAt) {
             const secAgo = Math.round((Date.now() - latestGap.reconnectedAt.getTime()) / 1000);
             gapWarning = `\n\n[WARNING] Connection was restored ${secAgo}s ago. Some logs may have been missed during the ${formatDuration(gapDuration)} gap.`;
@@ -481,17 +528,17 @@ registerToolWithTelemetry("search_logs", {
     description: "Search console logs for text (case-insensitive)",
     inputSchema: {
         text: z.string().describe("Text to search for in log messages"),
-        maxResults: z.coerce.number().optional().default(50).describe("Maximum number of results to return (default: 50)"),
-        maxMessageLength: z
-            .coerce.number()
+        maxResults: z.coerce
+            .number()
+            .optional()
+            .default(50)
+            .describe("Maximum number of results to return (default: 50)"),
+        maxMessageLength: z.coerce
+            .number()
             .optional()
             .default(500)
             .describe("Max characters per message (default: 500, set to 0 for unlimited)"),
-        verbose: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("Disable all truncation and return full messages"),
+        verbose: z.boolean().optional().default(false).describe("Disable all truncation and return full messages"),
         format: z
             .enum(["text", "tonl"])
             .optional()
@@ -617,10 +664,16 @@ registerToolWithTelemetry("execute_in_app", {
         "GOOD examples: `__DEV__`, `__APOLLO_CLIENT__.cache.extract()`, `__EXPO_ROUTER__.navigate('/settings')`\n" +
         "BAD examples: `async () => { await fetch(...) }`, `require('react-native')`, `console.log('\\u{1F600}')`",
     inputSchema: {
-        expression: z.string().describe("JavaScript expression to execute. Must be valid Hermes syntax — no require(), no async/await, no emoji/non-ASCII in strings. Use globals discovered via list_debug_globals."),
-        awaitPromise: z.coerce.boolean().optional().default(true).describe("Whether to await promises (default: true)"),
-        maxResultLength: z
-            .coerce.number()
+        expression: z
+            .string()
+            .describe("JavaScript expression to execute. Must be valid Hermes syntax — no require(), no async/await, no emoji/non-ASCII in strings. Use globals discovered via list_debug_globals."),
+        awaitPromise: z.coerce
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Whether to await promises (default: true)"),
+        maxResultLength: z.coerce
+            .number()
             .optional()
             .default(2000)
             .describe("Max characters in result (default: 2000, set to 0 for unlimited). Tip: For large objects like Redux stores, use inspect_global instead or set higher limit."),
@@ -637,7 +690,8 @@ registerToolWithTelemetry("execute_in_app", {
         // If the error is a ReferenceError (accessing a global that doesn't exist),
         // guide the agent to expose the variable as a global first
         if (result.error?.includes("ReferenceError")) {
-            errorText += "\n\nNOTE: This variable is not exposed as a global. To access it, first assign it to a global variable in your app code (e.g., `globalThis.__MY_VAR__ = myVar;`), then use execute_in_app to read `__MY_VAR__`. You can also use list_debug_globals to see what globals ARE currently available.";
+            errorText +=
+                "\n\nNOTE: This variable is not exposed as a global. To access it, first assign it to a global variable in your app code (e.g., `globalThis.__MY_VAR__ = myVar;`), then use execute_in_app to read `__MY_VAR__`. You can also use list_debug_globals to see what globals ARE currently available.";
         }
         return {
             content: [
@@ -654,7 +708,8 @@ registerToolWithTelemetry("execute_in_app", {
     let resultText = result.result ?? "undefined";
     // Apply truncation unless verbose or unlimited
     if (!verbose && maxResultLength > 0 && resultText.length > maxResultLength) {
-        resultText = resultText.slice(0, maxResultLength) + `... [truncated: ${result.result?.length ?? 0} chars total]`;
+        resultText =
+            resultText.slice(0, maxResultLength) + `... [truncated: ${result.result?.length ?? 0} chars total]`;
     }
     return {
         content: [
@@ -706,7 +761,7 @@ registerToolWithTelemetry("inspect_global", {
         // If the error is a ReferenceError (accessing a global that doesn't exist),
         // guide the agent to expose the variable as a global first
         if (result.error?.includes("ReferenceError")) {
-            errorText += `\n\nNOTE: '${objectName}' is not exposed as a global variable. To inspect it, first assign it to a global in your app code (e.g., \`globalThis.${objectName} = ${objectName.replace(/^__/, '').replace(/__$/, '')};\`), then call inspect_global again. Use list_debug_globals to see what globals ARE currently available.`;
+            errorText += `\n\nNOTE: '${objectName}' is not exposed as a global variable. To inspect it, first assign it to a global in your app code (e.g., \`globalThis.${objectName} = ${objectName.replace(/^__/, "").replace(/__$/, "")};\`), then call inspect_global again. Use list_debug_globals to see what globals ARE currently available.`;
         }
         return {
             content: [
@@ -770,7 +825,15 @@ registerToolWithTelemetry("get_component_tree", {
             .describe("Output format: 'json' or 'tonl' (default, compact indented tree). Ignored if structureOnly=true.")
     }
 }, async ({ focusedOnly, structureOnly, maxDepth, includeProps, includeStyles, hideInternals, format }) => {
-    const result = await getComponentTree({ focusedOnly, structureOnly, maxDepth, includeProps, includeStyles, hideInternals, format });
+    const result = await getComponentTree({
+        focusedOnly,
+        structureOnly,
+        maxDepth,
+        includeProps,
+        includeStyles,
+        hideInternals,
+        format
+    });
     if (!result.success) {
         return {
             content: [
@@ -860,21 +923,13 @@ registerToolWithTelemetry("inspect_component", {
             .optional()
             .default(true)
             .describe("Include component state/hooks (default: true)"),
-        includeChildren: z
-            .boolean()
-            .optional()
-            .default(false)
-            .describe("Include children component tree"),
+        includeChildren: z.boolean().optional().default(false).describe("Include children component tree"),
         childrenDepth: z
             .number()
             .optional()
             .default(1)
             .describe("How many levels deep to show children (default: 1 = direct children only, 2+ = nested tree)"),
-        shortPath: z
-            .boolean()
-            .optional()
-            .default(true)
-            .describe("Show only last 3 path segments (default: true)"),
+        shortPath: z.boolean().optional().default(true).describe("Show only last 3 path segments (default: true)"),
         simplifyHooks: z
             .boolean()
             .optional()
@@ -882,7 +937,14 @@ registerToolWithTelemetry("inspect_component", {
             .describe("Simplify hooks output by hiding effects and reducing depth (default: true)")
     }
 }, async ({ componentName, index, includeState, includeChildren, childrenDepth, shortPath, simplifyHooks }) => {
-    const result = await inspectComponent(componentName, { index, includeState, includeChildren, childrenDepth, shortPath, simplifyHooks });
+    const result = await inspectComponent(componentName, {
+        index,
+        includeState,
+        includeChildren,
+        childrenDepth,
+        shortPath,
+        simplifyHooks
+    });
     if (!result.success) {
         return {
             content: [
@@ -910,21 +972,13 @@ registerToolWithTelemetry("find_components", {
         pattern: z
             .string()
             .describe("Regex pattern to match component names (case-insensitive). Examples: 'Button', 'Screen$', 'List.*Item'"),
-        maxResults: z
-            .number()
-            .optional()
-            .default(20)
-            .describe("Maximum number of results to return (default: 20)"),
+        maxResults: z.number().optional().default(20).describe("Maximum number of results to return (default: 20)"),
         includeLayout: z
             .boolean()
             .optional()
             .default(false)
             .describe("Include layout styles (padding, margin, flex) for each matched component"),
-        shortPath: z
-            .boolean()
-            .optional()
-            .default(true)
-            .describe("Show only last 3 path segments (default: true)"),
+        shortPath: z.boolean().optional().default(true).describe("Show only last 3 path segments (default: true)"),
         summary: z
             .boolean()
             .optional()
@@ -970,16 +1024,13 @@ registerToolWithTelemetry("press_element", {
             .string()
             .optional()
             .describe("Case-insensitive partial match on the element's text content (e.g., 'Submit', 'Log in'). ASCII only — non-Latin characters (Cyrillic, CJK, etc.) cause Hermes parse errors. Use testID or component for localized UIs."),
-        testID: z
-            .string()
-            .optional()
-            .describe("Exact match on the element's testID prop"),
+        testID: z.string().optional().describe("Exact match on the element's testID prop"),
         component: z
             .string()
             .optional()
             .describe("Case-insensitive partial match on the component's displayName or name (e.g., 'Button', 'MenuItem')"),
-        index: z
-            .coerce.number()
+        index: z.coerce
+            .number()
             .optional()
             .default(0)
             .describe("Zero-based index when multiple elements match (default: 0). If unsure, omit to press the first match.")
@@ -1078,7 +1129,7 @@ registerToolWithTelemetry("get_inspector_selection", {
         if (!inspectorActive) {
             await toggleElementInspector();
             // Wait for inspector to initialize
-            await new Promise(resolve => setTimeout(resolve, 300));
+            await new Promise((resolve) => setTimeout(resolve, 300));
         }
         // Detect platform from connected app
         const app = getFirstConnectedApp();
@@ -1088,10 +1139,10 @@ registerToolWithTelemetry("get_inspector_selection", {
                 isError: true
             };
         }
-        const isIOS = app.deviceInfo.title?.toLowerCase().includes('iphone') ||
-            app.deviceInfo.title?.toLowerCase().includes('ipad') ||
-            app.deviceInfo.deviceName?.toLowerCase().includes('simulator') ||
-            app.deviceInfo.description?.toLowerCase().includes('ios');
+        const isIOS = app.deviceInfo.title?.toLowerCase().includes("iphone") ||
+            app.deviceInfo.title?.toLowerCase().includes("ipad") ||
+            app.deviceInfo.deviceName?.toLowerCase().includes("simulator") ||
+            app.deviceInfo.description?.toLowerCase().includes("ios");
         // Tap at coordinates
         try {
             if (isIOS) {
@@ -1103,15 +1154,17 @@ registerToolWithTelemetry("get_inspector_selection", {
         }
         catch (tapError) {
             return {
-                content: [{
+                content: [
+                    {
                         type: "text",
                         text: `Failed to tap at (${x}, ${y}): ${tapError instanceof Error ? tapError.message : String(tapError)}`
-                    }],
+                    }
+                ],
                 isError: true
             };
         }
         // Wait for selection to update
-        await new Promise(resolve => setTimeout(resolve, 200));
+        await new Promise((resolve) => setTimeout(resolve, 200));
     }
     // Read the current selection
     const result = await getInspectorSelection();
@@ -1188,7 +1241,9 @@ registerToolWithTelemetry("inspect_at_point", {
         const parsed = JSON.parse(result.result || "{}");
         if (parsed.error) {
             const hint = parsed.hint ? `\n\n${parsed.hint}` : "";
-            const alternatives = parsed.alternatives ? `\n\nAlternatives:\n${parsed.alternatives.map((a) => `  - ${a}`).join('\n')}` : "";
+            const alternatives = parsed.alternatives
+                ? `\n\nAlternatives:\n${parsed.alternatives.map((a) => `  - ${a}`).join("\n")}`
+                : "";
             return {
                 content: [
                     {
@@ -1221,18 +1276,9 @@ registerToolWithTelemetry("get_network_requests", {
             .optional()
             .default(50)
             .describe("Maximum number of requests to return (default: 50)"),
-        method: z
-            .string()
-            .optional()
-            .describe("Filter by HTTP method (GET, POST, PUT, DELETE, etc.)"),
-        urlPattern: z
-            .string()
-            .optional()
-            .describe("Filter by URL pattern (case-insensitive substring match)"),
-        status: z
-            .number()
-            .optional()
-            .describe("Filter by HTTP status code (e.g., 200, 401, 500)"),
+        method: z.string().optional().describe("Filter by HTTP method (GET, POST, PUT, DELETE, etc.)"),
+        urlPattern: z.string().optional().describe("Filter by URL pattern (case-insensitive substring match)"),
+        status: z.number().optional().describe("Filter by HTTP status code (e.g., 200, 401, 500)"),
         format: z
             .enum(["text", "tonl"])
             .optional()
@@ -1286,7 +1332,7 @@ registerToolWithTelemetry("get_network_requests", {
     let gapWarning = "";
     if (recentGaps.length > 0) {
         const latestGap = recentGaps[recentGaps.length - 1];
-        const gapDuration = latestGap.durationMs || (Date.now() - latestGap.disconnectedAt.getTime());
+        const gapDuration = latestGap.durationMs || Date.now() - latestGap.disconnectedAt.getTime();
         if (latestGap.reconnectedAt) {
             const secAgo = Math.round((Date.now() - latestGap.reconnectedAt.getTime()) / 1000);
             gapWarning = `\n\n[WARNING] Connection was restored ${secAgo}s ago. Some requests may have been missed during the ${formatDuration(gapDuration)} gap.`;
@@ -1321,11 +1367,7 @@ registerToolWithTelemetry("search_network", {
     description: "Search network requests by URL pattern (case-insensitive)",
     inputSchema: {
         urlPattern: z.string().describe("URL pattern to search for"),
-        maxResults: z
-            .number()
-            .optional()
-            .default(50)
-            .describe("Maximum number of results to return (default: 50)"),
+        maxResults: z.number().optional().default(50).describe("Maximum number of results to return (default: 50)"),
         format: z
             .enum(["text", "tonl"])
             .optional()
@@ -1372,8 +1414,8 @@ registerToolWithTelemetry("get_request_details", {
     description: "Get full details of a specific network request including headers, body, and timing. Use get_network_requests first to find the request ID.",
     inputSchema: {
         requestId: z.string().describe("The request ID to get details for"),
-        maxBodyLength: z
-            .coerce.number()
+        maxBodyLength: z.coerce
+            .number()
             .optional()
             .default(500)
             .describe("Max characters for request body (default: 500, set to 0 for unlimited). Tip: Large POST bodies (file uploads, base64) can be 10KB+."),
@@ -1500,11 +1542,7 @@ registerToolWithTelemetry("get_bundle_status", {
 registerToolWithTelemetry("get_bundle_errors", {
     description: "Retrieve captured Metro bundling/compilation errors. These are errors that occur during the bundle build process (import resolution, syntax errors, transform errors) that prevent the app from loading. If no errors are captured but Metro is running without connected apps, automatically falls back to screenshot+OCR to capture the error from the device screen.",
     inputSchema: {
-        maxErrors: z
-            .number()
-            .optional()
-            .default(10)
-            .describe("Maximum number of errors to return (default: 10)"),
+        maxErrors: z.number().optional().default(10).describe("Maximum number of errors to return (default: 10)"),
         platform: z
             .enum(["ios", "android"])
             .optional()
@@ -1811,10 +1849,7 @@ registerToolWithTelemetry("android_list_packages", {
             .string()
             .optional()
             .describe("Optional device ID. Uses first available device if not specified."),
-        filter: z
-            .string()
-            .optional()
-            .describe("Optional filter to search packages by name (case-insensitive)")
+        filter: z.string().optional().describe("Optional filter to search packages by name (case-insensitive)")
     }
 }, async ({ deviceId, filter }) => {
     const result = await androidListPackages(deviceId, filter);
@@ -1860,11 +1895,7 @@ registerToolWithTelemetry("android_long_press", {
     inputSchema: {
         x: z.coerce.number().describe("X coordinate in pixels"),
         y: z.coerce.number().describe("Y coordinate in pixels"),
-        durationMs: z
-            .number()
-            .optional()
-            .default(1000)
-            .describe("Press duration in milliseconds (default: 1000)"),
+        durationMs: z.number().optional().default(1000).describe("Press duration in milliseconds (default: 1000)"),
         deviceId: z
             .string()
             .optional()
@@ -1890,11 +1921,7 @@ registerToolWithTelemetry("android_swipe", {
         startY: z.coerce.number().describe("Starting Y coordinate in pixels"),
         endX: z.coerce.number().describe("Ending X coordinate in pixels"),
         endY: z.coerce.number().describe("Ending Y coordinate in pixels"),
-        durationMs: z
-            .number()
-            .optional()
-            .default(300)
-            .describe("Swipe duration in milliseconds (default: 300)"),
+        durationMs: z.number().optional().default(300).describe("Swipe duration in milliseconds (default: 300)"),
         deviceId: z
             .string()
             .optional()
@@ -1938,9 +1965,7 @@ registerToolWithTelemetry("android_input_text", {
 registerToolWithTelemetry("android_key_event", {
     description: `Send a key event to an Android device/emulator. Common keys: ${Object.keys(ANDROID_KEY_EVENTS).join(", ")}`,
     inputSchema: {
-        key: z
-            .string()
-            .describe(`Key name (${Object.keys(ANDROID_KEY_EVENTS).join(", ")}) or numeric keycode`),
+        key: z.string().describe(`Key name (${Object.keys(ANDROID_KEY_EVENTS).join(", ")}) or numeric keycode`),
         deviceId: z
             .string()
             .optional()
@@ -1948,9 +1973,7 @@ registerToolWithTelemetry("android_key_event", {
     }
 }, async ({ key, deviceId }) => {
     // Try to parse as number first, otherwise treat as key name
-    const keyCode = /^\d+$/.test(key)
-        ? parseInt(key, 10)
-        : key.toUpperCase();
+    const keyCode = /^\d+$/.test(key) ? parseInt(key, 10) : key.toUpperCase();
     const result = await androidKeyEvent(keyCode, deviceId);
     return {
         content: [
@@ -2044,22 +2067,10 @@ server.registerTool("android_describe_point", {
 server.registerTool("android_tap_element", {
     description: "Tap an element by its text, content-description, or resource-id using uiautomator. TIP: Consider using ocr_screenshot first - it returns ready-to-use tap coordinates for all visible text and works more reliably across different apps.",
     inputSchema: {
-        text: z
-            .string()
-            .optional()
-            .describe("Exact text match for the element"),
-        textContains: z
-            .string()
-            .optional()
-            .describe("Partial text match (case-insensitive)"),
-        contentDesc: z
-            .string()
-            .optional()
-            .describe("Exact content-description match"),
-        contentDescContains: z
-            .string()
-            .optional()
-            .describe("Partial content-description match (case-insensitive)"),
+        text: z.string().optional().describe("Exact text match for the element"),
+        textContains: z.string().optional().describe("Partial text match (case-insensitive)"),
+        contentDesc: z.string().optional().describe("Exact content-description match"),
+        contentDescContains: z.string().optional().describe("Partial content-description match (case-insensitive)"),
         resourceId: z
             .string()
             .optional()
@@ -2098,15 +2109,9 @@ server.registerTool("android_find_element", {
     description: "Find a UI element on Android screen by text, content description, or resource ID. Returns element details including tap coordinates. Use this to check if an element exists without tapping it. Workflow: 1) wait_for_element, 2) find_element, 3) tap with returned coordinates. Prefer this over screenshots for button taps.",
     inputSchema: {
         text: z.string().optional().describe("Exact text match for the element"),
-        textContains: z
-            .string()
-            .optional()
-            .describe("Partial text match (case-insensitive)"),
+        textContains: z.string().optional().describe("Partial text match (case-insensitive)"),
         contentDesc: z.string().optional().describe("Exact content-description match"),
-        contentDescContains: z
-            .string()
-            .optional()
-            .describe("Partial content-description match (case-insensitive)"),
+        contentDescContains: z.string().optional().describe("Partial content-description match (case-insensitive)"),
         resourceId: z
             .string()
             .optional()
@@ -2158,15 +2163,9 @@ server.registerTool("android_wait_for_element", {
     description: "Wait for a UI element to appear on Android screen. Polls the accessibility tree until the element is found or timeout is reached. Use this FIRST after navigation to ensure screen is ready, then use find_element + tap.",
     inputSchema: {
         text: z.string().optional().describe("Exact text match for the element"),
-        textContains: z
-            .string()
-            .optional()
-            .describe("Partial text match (case-insensitive)"),
+        textContains: z.string().optional().describe("Partial text match (case-insensitive)"),
         contentDesc: z.string().optional().describe("Exact content-description match"),
-        contentDescContains: z
-            .string()
-            .optional()
-            .describe("Partial content-description match (case-insensitive)"),
+        contentDescContains: z.string().optional().describe("Partial content-description match (case-insensitive)"),
         resourceId: z
             .string()
             .optional()
@@ -2456,10 +2455,7 @@ registerToolWithTelemetry("ios_install_app", {
     description: "Install an app bundle (.app) on an iOS simulator",
     inputSchema: {
         appPath: z.string().describe("Path to the .app bundle to install"),
-        udid: z
-            .string()
-            .optional()
-            .describe("Optional simulator UDID. Uses booted simulator if not specified.")
+        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
     }
 }, async ({ appPath, udid }) => {
     const result = await iosInstallApp(appPath, udid);
@@ -2478,10 +2474,7 @@ registerToolWithTelemetry("ios_launch_app", {
     description: "Launch an app on an iOS simulator by bundle ID",
     inputSchema: {
         bundleId: z.string().describe("Bundle ID of the app (e.g., com.example.myapp)"),
-        udid: z
-            .string()
-            .optional()
-            .describe("Optional simulator UDID. Uses booted simulator if not specified.")
+        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
     }
 }, async ({ bundleId, udid }) => {
     const result = await iosLaunchApp(bundleId, udid);
@@ -2500,10 +2493,7 @@ registerToolWithTelemetry("ios_open_url", {
     description: "Open a URL in the iOS simulator (opens in default handler or Safari)",
     inputSchema: {
         url: z.string().describe("URL to open (e.g., https://example.com or myapp://path)"),
-        udid: z
-            .string()
-            .optional()
-            .describe("Optional simulator UDID. Uses booted simulator if not specified.")
+        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
     }
 }, async ({ url, udid }) => {
     const result = await iosOpenUrl(url, udid);
@@ -2522,10 +2512,7 @@ registerToolWithTelemetry("ios_terminate_app", {
     description: "Terminate a running app on an iOS simulator",
     inputSchema: {
         bundleId: z.string().describe("Bundle ID of the app to terminate"),
-        udid: z
-            .string()
-            .optional()
-            .describe("Optional simulator UDID. Uses booted simulator if not specified.")
+        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
     }
 }, async ({ bundleId, udid }) => {
     const result = await iosTerminateApp(bundleId, udid);
@@ -2567,14 +2554,8 @@ server.registerTool("ios_tap", {
     inputSchema: {
         x: z.coerce.number().describe("X coordinate in pixels"),
         y: z.coerce.number().describe("Y coordinate in pixels"),
-        duration: z
-            .number()
-            .optional()
-            .describe("Optional tap duration in seconds (for long press)"),
-        udid: z
-            .string()
-            .optional()
-            .describe("Optional simulator UDID. Uses booted simulator if not specified.")
+        duration: z.number().optional().describe("Optional tap duration in seconds (for long press)"),
+        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
     }
 }, async ({ x, y, duration, udid }) => {
     const result = await iosTap(x, y, { duration, udid });
@@ -2592,10 +2573,7 @@ server.registerTool("ios_tap", {
 server.registerTool("ios_tap_element", {
     description: "Tap an element by its accessibility label. Requires IDB (brew install idb-companion). TIP: Consider using ocr_screenshot first - it returns ready-to-use tap coordinates for all visible text and works without requiring accessibility labels.",
     inputSchema: {
-        label: z
-            .string()
-            .optional()
-            .describe("Exact accessibility label to match (e.g., 'Home', 'Settings')"),
+        label: z.string().optional().describe("Exact accessibility label to match (e.g., 'Home', 'Settings')"),
         labelContains: z
             .string()
             .optional()
@@ -2604,14 +2582,8 @@ server.registerTool("ios_tap_element", {
             .number()
             .optional()
             .describe("If multiple elements match, tap the nth one (0-indexed, default: 0)"),
-        duration: z
-            .number()
-            .optional()
-            .describe("Optional tap duration in seconds (for long press)"),
-        udid: z
-            .string()
-            .optional()
-            .describe("Optional simulator UDID. Uses booted simulator if not specified.")
+        duration: z.number().optional().describe("Optional tap duration in seconds (for long press)"),
+        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
     }
 }, async ({ label, labelContains, index, duration, udid }) => {
     const result = await iosTapElement({ label, labelContains, index, duration, udid });
@@ -2635,10 +2607,7 @@ server.registerTool("ios_swipe", {
         endY: z.coerce.number().describe("Ending Y coordinate in pixels"),
         duration: z.coerce.number().optional().describe("Optional swipe duration in seconds"),
         delta: z.coerce.number().optional().describe("Optional delta between touch events (step size)"),
-        udid: z
-            .string()
-            .optional()
-            .describe("Optional simulator UDID. Uses booted simulator if not specified.")
+        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
     }
 }, async ({ startX, startY, endX, endY, duration, delta, udid }) => {
     const result = await iosSwipe(startX, startY, endX, endY, { duration, delta, udid });
@@ -2657,10 +2626,7 @@ server.registerTool("ios_input_text", {
     description: "Type text into the active input field on an iOS simulator. Requires IDB to be installed (brew install idb-companion).",
     inputSchema: {
         text: z.string().describe("Text to type into the active input field"),
-        udid: z
-            .string()
-            .optional()
-            .describe("Optional simulator UDID. Uses booted simulator if not specified.")
+        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
     }
 }, async ({ text, udid }) => {
     const result = await iosInputText(text, udid);
@@ -2682,10 +2648,7 @@ server.registerTool("ios_button", {
             .enum(IOS_BUTTON_TYPES)
             .describe("Hardware button to press: HOME, LOCK, SIDE_BUTTON, SIRI, or APPLE_PAY"),
         duration: z.coerce.number().optional().describe("Optional button press duration in seconds"),
-        udid: z
-            .string()
-            .optional()
-            .describe("Optional simulator UDID. Uses booted simulator if not specified.")
+        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
     }
 }, async ({ button, duration, udid }) => {
     const result = await iosButton(button, { duration, udid });
@@ -2705,10 +2668,7 @@ server.registerTool("ios_key_event", {
     inputSchema: {
         keycode: z.coerce.number().describe("iOS keycode to send"),
         duration: z.coerce.number().optional().describe("Optional key press duration in seconds"),
-        udid: z
-            .string()
-            .optional()
-            .describe("Optional simulator UDID. Uses booted simulator if not specified.")
+        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
     }
 }, async ({ keycode, duration, udid }) => {
     const result = await iosKeyEvent(keycode, { duration, udid });
@@ -2727,10 +2687,7 @@ server.registerTool("ios_key_sequence", {
     description: "Send a sequence of key events to an iOS simulator. Requires IDB to be installed (brew install idb-companion).",
     inputSchema: {
         keycodes: z.array(z.coerce.number()).describe("Array of iOS keycodes to send in sequence"),
-        udid: z
-            .string()
-            .optional()
-            .describe("Optional simulator UDID. Uses booted simulator if not specified.")
+        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
     }
 }, async ({ keycodes, udid }) => {
     const result = await iosKeySequence(keycodes, udid);
@@ -2748,10 +2705,7 @@ server.registerTool("ios_key_sequence", {
 server.registerTool("ios_describe_all", {
     description: "Get accessibility information for the entire iOS simulator screen. Returns a nested tree of UI elements with labels, values, and frames. Requires IDB to be installed (brew install idb-companion).",
     inputSchema: {
-        udid: z
-            .string()
-            .optional()
-            .describe("Optional simulator UDID. Uses booted simulator if not specified.")
+        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
     }
 }, async ({ udid }) => {
     const result = await iosDescribeAll(udid);
@@ -2771,10 +2725,7 @@ server.registerTool("ios_describe_point", {
     inputSchema: {
         x: z.coerce.number().describe("X coordinate in pixels"),
         y: z.coerce.number().describe("Y coordinate in pixels"),
-        udid: z
-            .string()
-            .optional()
-            .describe("Optional simulator UDID. Uses booted simulator if not specified.")
+        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
     }
 }, async ({ x, y, udid }) => {
     const result = await iosDescribePoint(x, y, udid);
@@ -2793,27 +2744,15 @@ server.registerTool("ios_find_element", {
     description: "Find a UI element on iOS simulator by accessibility label or value. Returns element details including tap coordinates. Requires IDB (brew install idb-companion). Workflow: 1) wait_for_element, 2) find_element, 3) tap with returned coordinates. Prefer this over screenshots for button taps.",
     inputSchema: {
         label: z.string().optional().describe("Exact accessibility label match"),
-        labelContains: z
-            .string()
-            .optional()
-            .describe("Partial label match (case-insensitive)"),
+        labelContains: z.string().optional().describe("Partial label match (case-insensitive)"),
         value: z.string().optional().describe("Exact accessibility value match"),
-        valueContains: z
-            .string()
-            .optional()
-            .describe("Partial value match (case-insensitive)"),
-        type: z
-            .string()
-            .optional()
-            .describe("Element type to match (e.g., 'Button', 'TextField')"),
+        valueContains: z.string().optional().describe("Partial value match (case-insensitive)"),
+        type: z.string().optional().describe("Element type to match (e.g., 'Button', 'TextField')"),
         index: z
             .number()
             .optional()
             .describe("If multiple elements match, select the nth one (0-indexed, default: 0)"),
-        udid: z
-            .string()
-            .optional()
-            .describe("Optional simulator UDID. Uses booted simulator if not specified.")
+        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
     }
 }, async ({ label, labelContains, value, valueContains, type, index, udid }) => {
     const result = await iosFindElement({ label, labelContains, value, valueContains, type, index }, udid);
@@ -2852,19 +2791,10 @@ server.registerTool("ios_wait_for_element", {
     description: "Wait for a UI element to appear on iOS simulator. Polls until found or timeout. Requires IDB (brew install idb-companion). Use this FIRST after navigation to ensure screen is ready, then use find_element + tap.",
     inputSchema: {
         label: z.string().optional().describe("Exact accessibility label match"),
-        labelContains: z
-            .string()
-            .optional()
-            .describe("Partial label match (case-insensitive)"),
+        labelContains: z.string().optional().describe("Partial label match (case-insensitive)"),
         value: z.string().optional().describe("Exact accessibility value match"),
-        valueContains: z
-            .string()
-            .optional()
-            .describe("Partial value match (case-insensitive)"),
-        type: z
-            .string()
-            .optional()
-            .describe("Element type to match (e.g., 'Button', 'TextField')"),
+        valueContains: z.string().optional().describe("Partial value match (case-insensitive)"),
+        type: z.string().optional().describe("Element type to match (e.g., 'Button', 'TextField')"),
         index: z
             .number()
             .optional()
@@ -2879,10 +2809,7 @@ server.registerTool("ios_wait_for_element", {
             .optional()
             .default(500)
             .describe("Time between polls in milliseconds (default: 500)"),
-        udid: z
-            .string()
-            .optional()
-            .describe("Optional simulator UDID. Uses booted simulator if not specified.")
+        udid: z.string().optional().describe("Optional simulator UDID. Uses booted simulator if not specified.")
     }
 }, async ({ label, labelContains, value, valueContains, type, index, timeoutMs, pollIntervalMs, udid }) => {
     const result = await iosWaitForElement({