mobai-mcp 2.1.0 → 2.2.1

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

@@ -22,15 +22,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 +38,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 +96,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 +242,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
@@ -347,19 +406,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

@@ -11,6 +11,18 @@ export const RESOURCES = [
         description: "Testing workflow, rules, error fixes, and .mob script syntax for test generation",
         mimeType: "text/plain",
     },
+    {
+        uri: "mobai://claude-code-preview",
+        name: "Claude Code Preview Setup",
+        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) {
@@ -18,10 +30,45 @@ export function getResourceContent(uri) {
             return DEVICE_AUTOMATION_REF;
         case "mobai://reference/testing":
             return TESTING_REF;
+        case "mobai://claude-code-preview":
+            return CLAUDE_CODE_PREVIEW;
+        case "mobai://reference/debugging":
+            return DEBUGGING_REF;
         default:
             return null;
     }
 }
+const CLAUDE_CODE_PREVIEW = `<claude-code-preview>
+Prerequisite: the MobAI desktop app must be running. It owns the
+localhost 8787 web server the preview panel will render.
+
+1. Call list_devices and grab the device's id and controlUrl.
+
+2. Write .claude/launch.json at the project root (or, inside a git
+   worktree, at the worktree root):
+
+   {
+     "version": "0.0.1",
+     "configurations": [{
+       "name": "MobAI — <device name>",
+       "runtimeExecutable": "sleep",
+       "runtimeArgs": ["86400"],
+       "port": 8787,
+       "url": "<controlUrl>"
+     }]
+   }
+
+   - runtimeExecutable + runtimeArgs is a no-op lifetime anchor for
+     Claude Code's panel; the real server is MobAI.
+   - port is the localhost port Claude Code binds the preview to;
+     always 8787 for MobAI.
+   - url is the device-specific URL (controlUrl from step 1) that the
+     panel actually displays.
+
+3. Call the mcp__Claude_Preview__preview_start tool with the "name"
+   from the configuration above.
+</claude-code-preview>
+`;
 const DEVICE_AUTOMATION_REF = `<device-automation-reference>
 
 <guide>
@@ -30,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>
@@ -57,6 +105,21 @@ 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.
+
+    Also save reusable multi-step flows as labeled mobai CLI command sequences inside the same SKILL.md. When you confirm a flow works (login, dismiss onboarding, open-settings-and-toggle-X, checkout), add a section with a heading like "## Flow: login" and a fenced shell code block of "mobai ..." commands in order — one per step. Mark variable inputs with placeholders (&lt;EMAIL&gt;, &lt;OTP_CODE&gt;) so future sessions know what to substitute. On next run, replay the commands (shell them out or translate to execute_dsl) with placeholders substituted — this avoids re-deriving the flow from scratch. Shell commands are saved (not JSON DSL) because the MobAI CLI does not execute DSL JSON blobs, and shell commands stay replayable from either CLI or MCP sessions. If a snippet breaks because the app changed, update it in place.
+  </per-app-skills>
+
   <screenshot-tools>
     get_screenshot — fast low-quality image for LLM visual analysis.
     save_screenshot — full-quality PNG for reporting, debugging, or sharing.
@@ -253,6 +316,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>
@@ -464,6 +537,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>
@@ -487,8 +561,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
@@ -505,5 +601,121 @@ const TESTING_REF = `<testing-reference>
   </conditionals>
 </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.1.0",
+  "version": "2.2.1",
   "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.1.0",
+  "version": "2.2.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "mobai-mcp",
-      "version": "2.1.0",
+      "version": "2.2.1",
       "transport": {
         "type": "stdio"
       }