mobai-mcp 2.2.0 → 2.3.0

package/README.md

@@ -107,7 +107,7 @@ Tests are `.mob` files on disk inside project directories. You read, write, and
 |---|---|
 | `test_get_active` | Get the active test project directory and its `.mob` cases |
 | `test_list_projects` | List all known test project directories with their `.mob` cases |
-| `test_run` | Run a `.mob` test case on a device (`project_dir` + `case_path` + `device_id`) |
+| `test_run` | Run a `.mob` test case on a device (`project_dir` + `case_path` + `device_id`, optional `params` for `${name}` substitution) |
 
 ## Resources
 

package/dist/index.js

@@ -7,10 +7,11 @@
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
+import { RESOURCES, getResourceContent } from "./resources.js";
 const API_BASE_URL = "http://127.0.0.1:8686/api/v1";
 const DEFAULT_TIMEOUT_MS = 300000; // 5 minutes (matches Go httpClient timeout)
 const SCREENSHOT_DIR = path.join(os.tmpdir(), "mobai", "screenshots");
@@ -22,15 +23,6 @@ function ensureScreenshotDir() {
         fs.mkdirSync(SCREENSHOT_DIR, { recursive: true });
     }
 }
-function saveBase64ToTemp(base64Data, prefix) {
-    if (!base64Data || base64Data.length <= 200)
-        return null;
-    ensureScreenshotDir();
-    const filename = `${prefix}_${Date.now()}.png`;
-    const filePath = path.join(SCREENSHOT_DIR, filename);
-    fs.writeFileSync(filePath, Buffer.from(base64Data, "base64"));
-    return filePath;
-}
 function screenshotToFile(body) {
     if (body?.path) {
         return `Screenshot saved to ${body.path}`;
@@ -47,28 +39,6 @@ function screenshotToFile(body) {
     }
     return JSON.stringify(body, null, 2);
 }
-function extractDSLScreenshots(body) {
-    if (!body?.step_results)
-        return body;
-    for (const step of body.step_results) {
-        const native = step.result?.observations?.native;
-        if (native?.screenshot && typeof native.screenshot === "string" && native.screenshot.length > 200) {
-            const filePath = saveBase64ToTemp(native.screenshot, "observe");
-            if (filePath) {
-                native.screenshot = filePath;
-                native.screenshot_saved = true;
-            }
-        }
-        if (step.debug?.screenshot && typeof step.debug.screenshot === "string" && step.debug.screenshot.length > 200) {
-            const filePath = saveBase64ToTemp(step.debug.screenshot, "debug");
-            if (filePath) {
-                step.debug.screenshot = filePath;
-                step.debug.screenshot_saved = true;
-            }
-        }
-    }
-    return body;
-}
 // ---------------------------------------------------------------------------
 // HTTP helpers
 // ---------------------------------------------------------------------------
@@ -127,6 +97,7 @@ const server = new Server({ name: "mobai", version: "1.0.0" }, {
     instructions: `MobAI controls Android and iOS devices. Before starting any device task, read the relevant MCP resources:
 - mobai://reference/device-automation — how to control devices (read before ANY device interaction)
 - mobai://reference/testing — .mob script syntax (read ONLY when user asks to create or fix test scripts)
+- mobai://reference/debugging — how to attach lldb, set breakpoints, inspect state (read before ANY debug_* tool)
 Check available skills in current work directory and load any relevant to the user's request.`,
 });
 // ---------------------------------------------------------------------------
@@ -272,17 +243,106 @@ Input: JSON string with "version": "0.2" and "steps" array. Example:
     },
     {
         name: "test_run",
-        description: "Run a .mob test case on a device. The case_path is relative to the project directory.",
+        description: "Run a .mob test case on a device. The case_path is relative to the project directory. Pass params to supply values for ${name} substitution in the script.",
         inputSchema: {
             type: "object",
             properties: {
                 project_dir: { type: "string", description: "Absolute path to the project directory" },
                 case_path: { type: "string", description: "Relative path to the .mob file within the project, e.g. auth/login.mob" },
                 device_id: { type: "string", description: "Device ID to run the test on" },
+                params: { type: "object", additionalProperties: { type: "string" }, description: "Optional key-value parameters for ${name} substitution in the script" },
             },
             required: ["project_dir", "case_path", "device_id"],
         },
     },
+    // Live app debugging via lldb-dap. iOS only. Read mobai://reference/debugging
+    // before using any of these.
+    {
+        name: "debug_attach",
+        description: "Start a debug session for an iOS app. Provide either bundle_id (launches and attaches) or pid (attaches to a running process). Optional breakpoints[] are armed before the target resumes. Read mobai://reference/debugging first.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                device_id: { type: "string", description: "Device ID" },
+                bundle_id: { type: "string", description: "App bundle ID to launch and attach. Either this or pid is required." },
+                pid: { type: "number", description: "Attach to an already-running PID. Either this or bundle_id is required." },
+                breakpoints: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: `Initial breakpoint specs. "File.swift:42" (preferred), "Module.Type.method" (no parameter signature), "-[Class method:]", or runtime symbol.`,
+                },
+                stop_on_entry: { type: "boolean", description: "Simulator only — pause at first instruction." },
+            },
+            required: ["device_id"],
+        },
+    },
+    {
+        name: "debug_state",
+        description: "Query the current debug session. Returns {state, breakpoints} by default. Set include_stack=true to also fetch the stack of the stopped thread; include_vars=true to also fetch frame[0] locals; include_threads=true to enumerate all threads.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                device_id: { type: "string", description: "Device ID" },
+                include_stack: { type: "boolean", description: "Include stack of stopped thread." },
+                include_vars: { type: "boolean", description: "Include frame[0] locals." },
+                include_threads: { type: "boolean", description: "Include all threads." },
+            },
+            required: ["device_id"],
+        },
+    },
+    {
+        name: "debug_breakpoint",
+        description: "Add or remove a breakpoint in the active debug session. For action=add provide spec; for action=remove provide id.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                device_id: { type: "string", description: "Device ID" },
+                action: { type: "string", enum: ["add", "remove"], description: `"add" or "remove"` },
+                spec: { type: "string", description: `Breakpoint spec for action=add. "File.swift:42", "Module.Type.method", "-[Class method:]", or runtime symbol.` },
+                id: { type: "number", description: "Breakpoint id for action=remove." },
+            },
+            required: ["device_id", "action"],
+        },
+    },
+    {
+        name: "debug_eval",
+        description: `Evaluate a Swift/ObjC expression at the current pause. Session must be paused. Examples: "p defaultPrivate", "po self.viewModel.user.email", "frame variable".`,
+        inputSchema: {
+            type: "object",
+            properties: {
+                device_id: { type: "string", description: "Device ID" },
+                expression: { type: "string", description: "Expression to evaluate" },
+                frame_id: { type: "number", description: "Optional frame id to evaluate in" },
+            },
+            required: ["device_id", "expression"],
+        },
+    },
+    {
+        name: "debug_step",
+        description: `Advance the target.\n  "in" — step into next call (blocks ~ms, returns {state, breakpoints, stack, frame0_locals})\n  "over" — step over next call (same shape)\n  "out" — run until current frame returns (same shape)\n  "continue" — resume until next breakpoint (fire-and-forget; returns just {state, breakpoints} — poll debug_state for next stop)`,
+        inputSchema: {
+            type: "object",
+            properties: {
+                device_id: { type: "string", description: "Device ID" },
+                direction: { type: "string", enum: ["in", "over", "out", "continue"], description: `"in" | "over" | "out" | "continue"` },
+                include_stack: { type: "boolean", description: `Include the new stack. Default true. Ignored for direction="continue".` },
+                include_vars: { type: "boolean", description: `Include the new frame[0] locals. Default true. Ignored for direction="continue".` },
+            },
+            required: ["device_id", "direction"],
+        },
+    },
+    {
+        name: "debug_detach",
+        description: "End the debug session. Pass kill=true to terminate the debuggee; otherwise it keeps running.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                device_id: { type: "string", description: "Device ID" },
+                kill: { type: "boolean", description: "Terminate debuggee on detach." },
+            },
+            required: ["device_id"],
+        },
+    },
 ];
 // ---------------------------------------------------------------------------
 // List tools
@@ -291,6 +351,22 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     return { tools: TOOLS };
 });
 // ---------------------------------------------------------------------------
+// Resources (reference docs)
+// ---------------------------------------------------------------------------
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    return { resources: RESOURCES };
+});
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const { uri } = request.params;
+    const text = getResourceContent(uri);
+    if (text == null) {
+        throw new Error(`Unknown resource: ${uri}`);
+    }
+    return {
+        contents: [{ uri, mimeType: "text/plain", text }],
+    };
+});
+// ---------------------------------------------------------------------------
 // Tool call handler
 // ---------------------------------------------------------------------------
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -347,19 +423,118 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     throw new Error("invalid DSL JSON: " + commandsStr);
                 }
                 const body = await doPost(`/devices/${args?.device_id}/dsl/execute`, script);
-                return textResult(extractDSLScreenshots(body));
+                return textResult(body);
             }
             // Test management
             case "test_get_active":
                 return textResult(await doGet("/tests/active"));
             case "test_list_projects":
                 return textResult(await doGet("/tests/projects"));
-            case "test_run":
-                return textResult(await doPost("/tests/cases/run", {
+            case "test_run": {
+                const body = {
                     project_dir: args?.project_dir,
                     case_path: args?.case_path,
                     device_id: args?.device_id,
-                }));
+                };
+                const rawParams = args?.params;
+                if (rawParams && typeof rawParams === "object") {
+                    const params = {};
+                    for (const [k, v] of Object.entries(rawParams)) {
+                        params[k] = String(v);
+                    }
+                    body.params = params;
+                }
+                return textResult(await doPost("/tests/cases/run", body));
+            }
+            // Debug session
+            case "debug_attach": {
+                const dev = args?.device_id;
+                const bundleID = args?.bundle_id;
+                const pid = args?.pid;
+                if (!bundleID && !pid)
+                    throw new Error("either bundle_id or pid is required");
+                const body = {};
+                if (Array.isArray(args?.breakpoints))
+                    body.breakpoints = args.breakpoints;
+                if (args?.stop_on_entry)
+                    body.stopOnEntry = true;
+                let path;
+                if (pid && pid > 0) {
+                    body.pid = pid;
+                    path = `/devices/${dev}/debug-session/attach-running`;
+                }
+                else {
+                    body.bundleId = bundleID;
+                    path = `/devices/${dev}/debug-session/attach`;
+                }
+                return textResult(await doPost(path, body));
+            }
+            case "debug_detach": {
+                const dev = args?.device_id;
+                const body = args?.kill ? { kill: true } : {};
+                return textResult(await doRequest("DELETE", `/devices/${dev}/debug-session`, body));
+            }
+            case "debug_state": {
+                const dev = args?.device_id;
+                const includeStack = args?.include_stack === true;
+                const includeVars = args?.include_vars === true;
+                const includeThreads = args?.include_threads === true;
+                const base = `/devices/${dev}/debug-session`;
+                const snap = await doGet(base);
+                if (snap?.state === "paused") {
+                    if (includeThreads) {
+                        const t = await doGet(`${base}/threads`);
+                        snap.threads = t?.threads;
+                    }
+                    if (includeStack || includeVars) {
+                        const stack = await doGet(`${base}/stack`);
+                        if (includeStack)
+                            snap.stack = stack?.frames;
+                        if (includeVars && Array.isArray(stack?.frames) && stack.frames.length > 0) {
+                            const frameID = stack.frames[0].id;
+                            const vars = await doGet(`${base}/frames/${frameID}/variables`);
+                            snap.frame0_locals = vars?.scopes;
+                        }
+                    }
+                }
+                return textResult(snap);
+            }
+            case "debug_breakpoint": {
+                const dev = args?.device_id;
+                const action = args?.action;
+                if (action === "add") {
+                    const spec = args?.spec;
+                    if (!spec)
+                        throw new Error("spec is required for action=add");
+                    return textResult(await doPost(`/devices/${dev}/debug-session/breakpoints`, { spec }));
+                }
+                else if (action === "remove") {
+                    const id = args?.id;
+                    if (!id || id <= 0)
+                        throw new Error("id is required for action=remove");
+                    return textResult(await doDelete(`/devices/${dev}/debug-session/breakpoints/${id}`));
+                }
+                throw new Error(`action must be "add" or "remove"`);
+            }
+            case "debug_eval": {
+                const dev = args?.device_id;
+                const body = { expression: args?.expression };
+                if (args?.frame_id)
+                    body.frameId = args.frame_id;
+                return textResult(await doPost(`/devices/${dev}/debug-session/eval`, body));
+            }
+            case "debug_step": {
+                const dev = args?.device_id;
+                const direction = args?.direction;
+                if (!direction)
+                    throw new Error(`direction is required ("in" | "over" | "out")`);
+                const body = { direction };
+                if (typeof args?.include_stack === "boolean")
+                    body.includeStack = args.include_stack;
+                if (typeof args?.include_vars === "boolean")
+                    body.includeVars = args.include_vars;
+                return textResult(await doPost(`/devices/${dev}/debug-session/step`, body));
+            }
             default:
                 return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
         }

package/dist/resources.js

@@ -17,6 +17,12 @@ export const RESOURCES = [
         description: "How to preview a MobAI device's control UI inside Claude Code's preview panel",
         mimeType: "text/plain",
     },
+    {
+        uri: "mobai://reference/debugging",
+        name: "App Debugging Reference",
+        description: "How to attach lldb, set breakpoints, inspect stack/variables, evaluate Swift/ObjC expressions — read before any debug_* tool",
+        mimeType: "text/plain",
+    },
 ];
 export function getResourceContent(uri) {
     switch (uri) {
@@ -26,6 +32,8 @@ export function getResourceContent(uri) {
             return TESTING_REF;
         case "mobai://claude-code-preview":
             return CLAUDE_CODE_PREVIEW;
+        case "mobai://reference/debugging":
+            return DEBUGGING_REF;
         default:
             return null;
     }
@@ -69,6 +77,7 @@ const DEVICE_AUTOMATION_REF = `<device-automation-reference>
   <script-format>
     {"version": "0.2", "steps": [...actions...], "on_fail": {"strategy": "retry", "max_retries": 2}}
     Every script must include "version": "0.2" and a "steps" array.
+    Optional "params": {"name": "default_value"} declares parameters. Callers supply values via the API; \${name} is substituted in step string fields at runtime.
   </script-format>
 
   <important>
@@ -96,6 +105,14 @@ const DEVICE_AUTOMATION_REF = `<device-automation-reference>
 
   <workflow>Observe screen → plan → act via execute_dsl → verify (end script with wait_for stable + observe) → repeat until done.</workflow>
 
+  <siri-shortcuts>
+    iOS only. Before navigating through multiple screens to reach a feature, check if Siri can take you there directly. Many apps register SiriKit intents and App Shortcuts — a single siri action can replace 5-10 tap/scroll/wait steps.
+    Use observe with include: installed_apps to check what an app exposes. Common shortcuts: play media, send messages, open specific screens, make payments, start workouts, get directions.
+    Examples: "Open my cart in Amazon", "Play my playlist on Spotify", "Show my reservations in Booking", "Search YouTube for cats".
+    If Siri asks a follow-up question, dismiss and re-invoke with a more specific prompt that includes the missing detail.
+    Always prefer siri over manual UI navigation when the app supports it — it is faster, more reliable, and survives UI redesigns.
+  </siri-shortcuts>
+
   <per-app-skills>
     Before working with a known app, check ~/.claude/skills/ for a skill matching its bundle id or name (e.g. com-instagram-android, uber) and load it — it may already encode selectors, flows, and quirks learned on a prior run.
     When you discover app-specific gotchas that would cost future sessions time — unstable selectors that only work with a specific predicate, hidden taps, flows that need an extra wait_for, React Native / Flutter screens that need OCR, dialogs that hijack input — create or update a skill at ~/.claude/skills/&lt;app-slug&gt;/SKILL.md capturing the finding. Keep each skill short: the specific quirk, the selector/flow that works, and one sentence on why the obvious approach fails. Do not write generic mobile-automation advice there — that belongs in this reference.
@@ -219,9 +236,11 @@ const DEVICE_AUTOMATION_REF = `<device-automation-reference>
     <field name="from_coords" type="Coordinates" required="one-of"/>
     <field name="to_element" type="TargetElement" required="one-of"/>
     <field name="to_coords" type="Coordinates" required="one-of"/>
-    <field name="duration_ms" type="int"/>
-    <field name="press_duration_ms" type="int">Press-and-hold before drag (for moving app icons)</field>
+    <field name="duration_ms" type="int">Drag motion duration (default 500)</field>
+    <field name="press_duration_ms" type="int">Hold before moving (for moving app icons, picking up list items)</field>
+    <field name="hold_duration_ms" type="int">Hold at destination before release (useful for iOS drop zones that need a dwell)</field>
     <example>{"action": "drag", "from": {"predicate": {"text": "Item"}}, "to_element": {"predicate": {"text": "Trash"}}}</example>
+    <example>{"action": "drag", "from": {"predicate": {"text": "App"}}, "to_element": {"predicate": {"text": "Folder"}}, "press_duration_ms": 500, "hold_duration_ms": 200}</example>
   </action>
 
   <action name="press_key">
@@ -299,6 +318,16 @@ const DEVICE_AUTOMATION_REF = `<device-automation-reference>
   <action name="reset_location">
     <example>{"action": "reset_location"}</example>
   </action>
+
+  <action name="siri">
+    iOS only. Sends a voice command to Siri via XCUISiriService. Auto-approves consent dialogs, captures Siri's response text, then dismisses the Siri UI.
+    Use for triggering SiriKit intents and App Shortcuts registered by apps (media playback, messaging, banking shortcuts, etc.).
+    The captured response is stored in "siri_response" and returned in the step result. If Siri asks a follow-up question, reformulate the prompt with more detail and call siri again.
+    <field name="prompt" required="yes">Voice command text</field>
+    <example>{"action": "siri", "prompt": "Search YouTube for cat videos"}</example>
+    <example>{"action": "siri", "prompt": "Send an email to john@example.com via Gmail"}</example>
+    <note>Check the app's siri field in the installed apps list (observe with include: installed_apps) to see which intents and activities it supports before calling siri.</note>
+  </action>
 </native-actions>
 
 <web-actions>
@@ -496,7 +525,7 @@ const TESTING_REF = `<testing-reference>
     toggle type:switch near "Wi-Fi" on  — modifier-only
     drag "Item" to "Trash"             — drag element
     drag 100,200 to 300,400 duration:500 — coordinate drag
-    drag "App" to "Folder" press_duration:500 — press-and-drag
+    drag "App" to "Folder" press_duration:500 hold_duration:200 — press-hold-move-hold-release
     wait_for "Element" timeout:5000     — wait for element
     wait_for type:button bounds:bottom_half timeout:3000 — modifier-only
     delay 1000                          — wait N ms
@@ -510,6 +539,7 @@ const TESTING_REF = `<testing-reference>
     paste_text "Field"                  — paste clipboard into element
     set_location 40.7128,-74.0060       — simulate GPS location (lat,lon)
     reset_location                      — stop location simulation
+    siri "Search YouTube for cats"      — invoke Siri with voice command (iOS only)
     observe                             — observe screen
     screenshot "path.png"               — take screenshot
   </actions>
@@ -533,8 +563,30 @@ const TESTING_REF = `<testing-reference>
     # Device: iPhone 15                 — device filter
     # Timeout: 30000                    — global timeout (ms)
     # On-Fail: abort                    — abort or continue
+    # Param: username                   — declare a parameter (no default)
+    # Param: timeout = 5000             — declare with default value
   </metadata>
 
+  <variables>
+    \${name} substitution: use \${param_name} anywhere in a step line to reference a parameter or extracted value.
+    Parameters declared via # Param: are available as \${name}. Extracted values (see extract below) are also available.
+    Example:
+      # Param: email
+      # Param: password = secret123
+      type "Email" → "\${email}"
+      type "Password" → "\${password}"
+  </variables>
+
+  <extract>
+    extract key from "Element"           — extract text from matched element into \${key}
+    extract key from #AccessibilityID    — extract text by accessibility ID
+    extract key from ~"partial" regex:"(\\d+)" — extract with regex capture group
+    extract key screenshot               — save screenshot to disk, store path in \${key}
+    extract key = "literal value"        — store a literal string in \${key}
+    Extracted values are available as \${key} in subsequent steps and returned in the API response as "extracted" map.
+    The optional regex: modifier applies a regex to the matched text; if it has a capture group, group 1 is stored.
+  </extract>
+
   <platform-blocks>
     # ios / # android                   — open platform block
     # end                               — close block
@@ -549,7 +601,131 @@ const TESTING_REF = `<testing-reference>
         tap "Other"
     }
   </conditionals>
+
+  <run-includes>
+    run "./path/to/other.mob"            — inline another .mob file at compile time
+    run "./auth/login.mob" email="x@y" password="hunter2" — pass args; values overlay the target file's # Param: defaults
+    run "/abs/path/to/file.mob"          — absolute path is allowed
+    run "~/shared/login.mob"             — ~ expands to the user home directory
+    Path is relative to the calling file's directory unless absolute. Args use key=value (no colon, no quotes around the key). Values may contain \${name} references that resolve from the caller's scope at execute time. The target file's extracts flow back into the caller's scope (flat namespace).
+  </run-includes>
 </mob-script-syntax>
 
+<apis>
+  Mobile apps can be turned into callable APIs by saving parameterized .mob scripts to the APIs directory.
+
+  <directory>{MOBAI_DATA_DIR}/apis/ — global directory for API scripts. Each .mob file is a named API. Subdirectories are supported and become slash-separated names (e.g. apis/youtube/search.mob is callable as "youtube/search"). Resolves to ~/Library/Application Support/mobai/data/apis on macOS, %AppData%/mobai/data/apis on Windows, ~/.config/mobai/data/apis on Linux.</directory>
+
+  <workflow-create-api>
+    When the user asks to create an API from a mobile app flow:
+    1. Observe the app and understand the flow
+    2. Write a .mob script with # Param: declarations for inputs and extract actions for outputs
+    3. Save it to {MOBAI_DATA_DIR}/apis/{name}.mob — flat (gmail-send.mob) or nested (gmail/send.mob)
+    4. Test it with test_run using project_dir: {MOBAI_DATA_DIR}/apis/ and case_path: {name}.mob
+    5. List available APIs:    GET  /api/v1/apis
+       Call an API:            POST /api/v1/apis/run/{name}  with {"device_id": "...", "params": {...}}
+       The {name} segment is the path inside apis/ minus the .mob extension.
+       API runs do not persist results to .mobai/runs/ — only the extracted values come back in the response.
+  </workflow-create-api>
+
+  <example-api>
+    # Search YouTube
+    # Param: query
+    siri "Search YouTube for \${query}"
+    wait_for ~"\${query}" timeout:5000
+    extract result from ~"\${query}"
+
+    POST /api/v1/apis/run/youtube-search {"device_id":"X","params":{"query":"cats"}}
+    → {"result": "cats"}
+  </example-api>
+</apis>
+
 </testing-reference>
 `;
+const DEBUGGING_REF = `<debugging-reference>
+
+<scope>
+  Live debugging of an iOS app running on a connected device or booted simulator. Attach lldb, set breakpoints, inspect stack and variables, evaluate Swift/ObjC expressions, continue. Six MCP tools cover the full workflow.
+
+  Requires: a debug-signed build of the app (debug provisioning profile with get-task-allow). App Store / TestFlight builds cannot be attached. iOS 17+ for physical devices. macOS host with Xcode installed.
+</scope>
+
+<workflow>
+  Bps fire asynchronously when the user (or your execute_dsl) drives the UI. The agent observes via debug_state, not by waiting on debug_continue.
+
+    1. debug_attach {device_id, bundle_id, breakpoints: ["File.swift:42"]}
+    2. (trigger the action — usually via execute_dsl)
+    3. debug_state {device_id, include_stack: true, include_vars: true}   // poll until state == "paused"
+    4. debug_eval {device_id, expression: "po self.viewModel.user"}
+    5. debug_step {device_id, direction: "continue"}                        // resume; fire-and-forget
+    6. (loop 2-5 as needed)
+    7. debug_detach {device_id}
+
+  direction: "continue" is fire-and-forget. For deterministic line-stepping use "in" / "over" / "out" — those block (~ms) and return fresh stack + locals.
+</workflow>
+
+<tools>
+  debug_attach — start a debug session.
+    device_id (required), bundle_id OR pid (one required), breakpoints (optional [string]),
+    stop_on_entry (optional bool, simulator only).
+
+  debug_state — query the current session state.
+    device_id (required), include_stack (bool, default false), include_vars (bool, default false), include_threads (bool, default false).
+    Default returns just {state, breakpoints}. Stack, frame[0] locals, and the thread list are opt-in (each costs a round-trip; ~few seconds on physical hardware).
+
+  debug_breakpoint — add or remove a breakpoint.
+    device_id, action: "add" | "remove", spec (for add), id (for remove).
+
+  debug_eval — evaluate a Swift/ObjC expression at the current pause.
+    device_id, expression, frame_id (optional). Session must be paused.
+
+  debug_step — advance the target.
+    device_id, direction one of:
+      "in" / "over" / "out" — block ~ms until next stop; return {state, breakpoints, stack, frame0_locals}.
+      "continue"            — fire-and-forget; return {state, breakpoints}; poll debug_state for next stop.
+    include_stack / include_vars (default true; ignored for "continue").
+
+  debug_detach — end the session. kill (default false) terminates the debuggee.
+</tools>
+
+<breakpoint-specs>
+  Three accepted forms. Prefer file:line for application code.
+
+    "File.swift:42"             file:line (basename or absolute path)
+    "Module.Type.method"        Swift demangled prefix (NO parameter signature, NO return type)
+    "-[ClassName method:]"      ObjC method
+    "swift_willThrow"           bare runtime symbol
+
+  Caveats:
+    - Release/optimized builds without DWARF return verified=false.
+    - swift_willThrow / objc_exception_throw fire on EVERY internal Swift/ObjC throw — Apple frameworks throw constantly under the hood. Use only when actually hunting an uncaught error.
+</breakpoint-specs>
+
+<eval-expressions>
+  debug_eval runs lldb expression --. Accepts ObjC++ syntax by default; Swift syntax when frame is in a Swift compile unit.
+
+    p expr            evaluate, default-format
+    po expr           call objects description
+    frame variable    list all locals (no eval — fast)
+    bt                full backtrace
+    image lookup -n NAME   resolve a symbol name to module + addresses
+</eval-expressions>
+
+<state-machine>
+  paused — debug_eval works; debug_continue resumes.
+  running — debug_eval returns 409; debug_breakpoint still works for next hit.
+  dead — exited or crashed. Detach and reattach.
+
+  While the foreground app on a device is paused at a bp, UI input via execute_dsl tap/swipe blocks at WDA until you debug_continue.
+</state-machine>
+
+<common-failures>
+  "lldb-dap not found" — install Xcode 15+.
+  "device debugging requires iOS 17+" — physical-device path needs the on-device tunnel.
+  "bundle is not installed on device" — install_app first with a debug-signed build.
+  verified=false — symbol mangling mismatch or no debug info. Try image lookup -n NAME via debug_eval.
+  "___lldb_unnamed_symbol_*" in stacks — dSYM not loaded. For device builds, run debug_eval "target symbols add /path/to/MyApp.app.dSYM".
+</common-failures>
+
+</debugging-reference>
+`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobai-mcp",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "mcpName": "io.github.MobAI-App/mobai-mcp",
   "description": "MCP server for MobAI - AI-powered mobile device automation",
   "type": "module",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/MobAI-App/mobai-mcp",
     "source": "github"
   },
-  "version": "2.2.0",
+  "version": "2.3.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "mobai-mcp",
-      "version": "2.2.0",
+      "version": "2.3.0",
       "transport": {
         "type": "stdio"
       }