mobai-mcp 2.3.0 → 2.4.0

package/README.md

@@ -140,7 +140,7 @@ Pass this as the `commands` argument (a JSON string) to `execute_dsl` along with
 
 ## Troubleshooting
 
-**"Connection refused"** — Make sure the MobAI desktop app is running and the API is reachable at `http://127.0.0.1:8686`.
+**"Connection refused" / "Could not reach the MobAI desktop app"** — Make sure the MobAI desktop app is installed and running, and the API is reachable at `http://127.0.0.1:8686`. If you don't have it yet, download and install it from [https://mobai.run/download](https://mobai.run/download).
 
 **"Bridge not running"** — Call `start_bridge` first. The iOS bridge can take up to a minute to come up.
 

package/dist/index.js

@@ -15,6 +15,28 @@ 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");
+const DOWNLOAD_URL = "https://mobai.run/download";
+// Message shown when the MobAI desktop app is not reachable at its local API.
+const APP_NOT_RUNNING_MESSAGE = `Could not reach the MobAI desktop app at 127.0.0.1:8686. ` +
+    `Make sure the MobAI desktop app is installed and running, then try again. ` +
+    `If you don't have it yet, download and install it from ${DOWNLOAD_URL}.`;
+/**
+ * Detects the "connection refused" / "could not connect" family of errors that
+ * Node's fetch throws when nothing is listening on the MobAI API port. These
+ * surface as a TypeError ("fetch failed") whose `cause` carries an errno code
+ * such as ECONNREFUSED / ENOTFOUND / ECONNRESET.
+ */
+function isConnectionError(err) {
+    if (!(err instanceof Error))
+        return false;
+    const codes = ["ECONNREFUSED", "ENOTFOUND", "ECONNRESET", "EHOSTUNREACH", "ETIMEDOUT"];
+    const cause = err.cause;
+    const causeCode = cause && typeof cause === "object" ? cause.code : undefined;
+    if (typeof causeCode === "string" && codes.includes(causeCode))
+        return true;
+    // Fallback: undici reports a bare "fetch failed" TypeError for these.
+    return err.name === "TypeError" && /fetch failed/i.test(err.message);
+}
 // ---------------------------------------------------------------------------
 // Screenshot helpers
 // ---------------------------------------------------------------------------
@@ -55,7 +77,16 @@ async function doRequest(method, urlPath, payload, timeoutMs = DEFAULT_TIMEOUT_M
         if (payload !== undefined && ["POST", "PUT", "PATCH"].includes(method)) {
             opts.body = typeof payload === "string" ? payload : JSON.stringify(payload);
         }
-        const response = await fetch(url, opts);
+        let response;
+        try {
+            response = await fetch(url, opts);
+        }
+        catch (err) {
+            if (isConnectionError(err)) {
+                throw new Error(APP_NOT_RUNNING_MESSAGE);
+            }
+            throw err;
+        }
         clearTimeout(timeoutId);
         const text = await response.text();
         let body;
@@ -192,6 +223,12 @@ const TOOLS = [
             properties: {
                 device_id: { type: "string", description: "Device ID" },
                 path: { type: "string", description: "Local file path to the app (.apk or .ipa)" },
+                resign: { type: "boolean", description: "Sign the IPA with iloader before installing (iOS only)" },
+                apple_id: { type: "string", description: "Apple ID for signing (optional; used when resign=true)" },
+                password: { type: "string", description: "Apple ID password for signing (optional; uses cached credentials if empty)" },
+                profile_path: { type: "string", description: "Provisioning profile to reuse for an offline re-sign (with cert_path/key_path); falls back to online signing if invalid" },
+                cert_path: { type: "string", description: "Signing certificate PEM to reuse for an offline re-sign" },
+                key_path: { type: "string", description: "Signing private key PEM to reuse for an offline re-sign" },
             },
             required: ["device_id", "path"],
         },
@@ -211,16 +248,62 @@ const TOOLS = [
     // DSL execution
     {
         name: "execute_dsl",
-        description: `Execute a batch of DSL commands on a device. This is the primary tool for all device interaction — tap, type, swipe, observe, launch apps, assertions, web automation, and more.
+        description: `The example below is the full command surface. For richer semantics - per-action defaults, platform notes, retry/failure strategies, observe and scroll guidance, web/OCR caveats - read the MCP resource mobai://reference/device-automation. Read it the first time you hit anything the example doesn't make obvious.
+
+Execute a batch of DSL commands on a device. This is the primary tool for all device interaction - tap, type, swipe, observe, launch apps, assertions, web automation, and more.
+
+Input: JSON string with "version": "0.2" and a "steps" array. Optional script-wide "params" (declared defaults, substituted as \${name}) and "on_fail" (strategy: abort|skip|retry|replan|require_user; retry also takes max_retries, retry_delay_ms, fallback_strategy). Any step may carry its own "on_fail".
 
-You MUST read the MCP resource mobai://reference/device-automation to learn how to control devices before using this tool.
+Every action below appears at least once - this is the full command surface (semantics, defaults, and platform notes are in mobai://reference/device-automation):
+{"version":"0.2","params":{"query":"shoes"},"on_fail":{"strategy":"retry","max_retries":2,"retry_delay_ms":1000,"fallback_strategy":{"strategy":"skip"}},"steps":[
+  {"action":"open_app","bundle_id":"com.apple.Preferences","fresh":true,"debug":false},
+  {"action":"kill_app","bundle_id":"com.apple.mobilesafari"},
+  {"action":"open_link","url":"myapp://profile/42"},
+  {"action":"tap","predicate":{"text_contains":"Wi-Fi","type":"button"}},
+  {"action":"tap","coords":{"x":200,"y":640}},
+  {"action":"double_tap","predicate":{"text":"Photo"}},
+  {"action":"two_finger_tap","predicate":{"text":"Map"}},
+  {"action":"long_press","predicate":{"text":"Item"},"duration_ms":1000},
+  {"action":"pinch","predicate":{"text_contains":"Map"},"scale":0.5,"velocity":1.0},
+  {"action":"type","text":"\${query}","predicate":{"type":"input"},"clear_first":true,"dismiss_keyboard":true},
+  {"action":"type_secret","secret_id":"test-account-password","predicate":{"type":"input","text_contains":"Password"}},
+  {"action":"clear","predicate":{"type":"input"}},
+  {"action":"toggle","predicate":{"type":"switch","text_contains":"Wi-Fi"},"state":"on"},
+  {"action":"press_key","key":"enter"},
+  {"action":"swipe","direction":"up","distance":"medium"},
+  {"action":"swipe","from_coords":{"x":200,"y":600},"to_coords":{"x":200,"y":200},"duration_ms":300},
+  {"action":"scroll","direction":"down","to_element":{"predicate":{"text":"Privacy"}},"predicate":{"type":"scrollview"},"max_scrolls":10,"amount":"page"},
+  {"action":"drag","from":{"predicate":{"text":"Item"}},"to_element":{"predicate":{"text":"Trash"}},"press_duration_ms":500,"hold_duration_ms":200,"duration_ms":500},
+  {"action":"drag","from_coords":{"x":100,"y":400},"to_coords":{"x":300,"y":400}},
+  {"action":"drag_path","points":[{"x":100,"y":400,"duration_ms":200},{"x":150,"y":300,"duration_ms":150},{"x":300,"y":500,"duration_ms":300}]},
+  {"action":"navigate","target":"home"},
+  {"action":"set_location","lat":40.7128,"lon":-74.0060},
+  {"action":"reset_location"},
+  {"action":"siri","prompt":"Search YouTube for cat videos"},
+  {"action":"if_exists","predicate":{"text":"Allow"},"then":[{"action":"tap","predicate":{"text":"Allow"}}],"else":[{"action":"tap","predicate":{"text":"Don't Allow"}}]},
+  {"action":"delay","duration_ms":1000},
+  {"action":"wait_for","predicate":{"text":"Welcome"},"timeout_ms":5000,"poll_interval_ms":500},
+  {"action":"assert_exists","predicate":{"text":"Success"},"timeout_ms":3000},
+  {"action":"assert_not_exists","predicate":{"text":"Error"}},
+  {"action":"assert_count","predicate":{"type":"cell"},"count":5},
+  {"action":"assert_screen_changed","threshold_percent":15},
+  {"action":"metrics_start","types":["system_cpu","fps"],"interval_ms":1000,"label":"login_flow","capture_logs":true,"thresholds":{"cpu_high":80,"fps_low":45}},
+  {"action":"metrics_stop","format":"summary"},
+  {"action":"record_start","file_path":"/tmp/mobai/rec"},
+  {"action":"record_stop"},
+  {"action":"select_web_context","url_contains":"google.com"},
+  {"action":"navigate","context":"web","url":"https://example.com"},
+  {"action":"tap","context":"web","predicate":{"css_selector":"button.submit"}},
+  {"action":"type","context":"web","predicate":{"css_selector":"input#email"},"text":"user@example.com","clear_first":true},
+  {"action":"execute_js","context":"web","script":"return document.title","async":false},
+  {"action":"screenshot","file_path":"/tmp/mobai","name":"final_state"},
+  {"action":"wait_for","stable":true,"timeout_ms":3000},
+  {"action":"observe","include":["ui_tree"],"only_visible":true,"filter":{"text_regex":"Settings|Wi-Fi"},"store_as":"end_state"}
+]}
 
-Input: JSON string with "version": "0.2" and "steps" array. Example:
-{"version":"0.2","steps":[
-  {"action":"open_app","bundle_id":"com.apple.Preferences"},
-  {"action":"tap","predicate":{"text_contains":"Wi-Fi"}},
-  {"action":"wait_for","predicate":{"type":"switch"},"timeout_ms":3000}
-]}`,
+Predicate - object passed in a step's "predicate"/"from"/"to_element". Combine fields (AND); prefer text_contains over exact text. All native fields:
+{"text":"exact","text_contains":"substr","text_starts_with":"prefix","text_regex":"\\d+ items","value":"typed value","value_contains":"typed substr","type":"button|input|switch|text|image|cell|scrollview","accessibility_id":"login_btn","enabled":true,"visible":true,"selected":false,"index":0,"bounds_hint":"top_half|bottom_half|left_half|right_half|center","near":{"text_contains":"Email","direction":"below|above|left|right|any","max_distance":100},"parent_of":{"text":"child label"}}
+Web predicate (context:"web") uses instead: {"css_selector":"button.submit"}.`,
         inputSchema: {
             type: "object",
             properties: {
@@ -406,8 +489,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             case "list_apps":
                 return textResult(await doGet(`/devices/${args?.device_id}/apps`));
-            case "install_app":
-                return textResult(await doPost(`/devices/${args?.device_id}/install-app`, { path: args?.path }));
+            case "install_app": {
+                const body = { path: args?.path };
+                if (args?.resign) {
+                    body.resign = true;
+                    if (args?.apple_id)
+                        body.appleId = args.apple_id;
+                    if (args?.password)
+                        body.password = args.password;
+                    if (args?.profile_path)
+                        body.profilePath = args.profile_path;
+                    if (args?.cert_path)
+                        body.certPath = args.cert_path;
+                    if (args?.key_path)
+                        body.keyPath = args.key_path;
+                }
+                return textResult(await doPost(`/devices/${args?.device_id}/install-app`, body));
+            }
             case "uninstall_app":
                 return textResult(await doDelete(`/devices/${args?.device_id}/apps/${encodeURIComponent(args?.bundle_id)}`));
             // DSL execution

package/dist/resources.js

@@ -123,7 +123,7 @@ const DEVICE_AUTOMATION_REF = `<device-automation-reference>
   <screenshot-tools>
     get_screenshot — fast low-quality image for LLM visual analysis.
     save_screenshot — full-quality PNG for reporting, debugging, or sharing.
-    To verify animations and UI transitions, use record_start/record_stop.
+    A screenshot is a single settled frame — it cannot capture motion. Anything transient (animations, transitions, loading spinners; a screen transition is often only ~300ms) will be missed or caught mid-frame. To verify transitional behavior, use record_start/record_stop, which samples continuously and flags suspicious frames.
   </screenshot-tools>
 
   <infinite-scrolling>To collect data from infinite-scrolling views (feeds, search results), scroll to load a batch first, then observe with only_visible:false to get all loaded items in one go.</infinite-scrolling>
@@ -132,6 +132,7 @@ const DEVICE_AUTOMATION_REF = `<device-automation-reference>
     Element not visible — use scroll with to_element to find it.
     App launches and page transitions take time — use wait_for or delay.
     Observe before acting on unfamiliar screens.
+    NO_MATCH / failed assert_exists: if the element exists off-screen, the error lists it under "candidates" — scroll to bring it into view (off-screen elements cannot be tapped). Empty candidates means it is genuinely absent or not yet rendered.
   </troubleshooting>
 </guide>
 
@@ -145,6 +146,8 @@ const DEVICE_AUTOMATION_REF = `<device-automation-reference>
     <field name="text_contains" type="string">Substring, case-insensitive — preferred for most matching</field>
     <field name="text_starts_with" type="string">Prefix match</field>
     <field name="text_regex" type="string">Regex pattern — use for dynamic text (numbers, dates, counts)</field>
+    <field name="value" type="string">Exact match on the element's entered/current value (not its label/placeholder). Use to verify what was typed into a field — text matching sees the placeholder, value sees the content. Shown as content="..." in the UI tree. Secure fields are masked, so only length/non-empty is meaningful.</field>
+    <field name="value_contains" type="string">Substring match (case-insensitive) on the entered/current value</field>
     <field name="type" type="string">button, input, switch, text, image, cell, scrollview</field>
     <field name="accessibility_id" type="string">Exact match on the #id shown in UI tree (without the # prefix)</field>
     <field name="enabled" type="bool">Enabled state</field>
@@ -158,7 +161,6 @@ const DEVICE_AUTOMATION_REF = `<device-automation-reference>
 
   <predicate context="web">
     <field name="css_selector" type="string">CSS selector</field>
-    <field name="xpath" type="string">XPath expression</field>
   </predicate>
 
   <failure-strategy>
@@ -173,8 +175,11 @@ const DEVICE_AUTOMATION_REF = `<device-automation-reference>
 
   <action name="open_app">
     <field name="bundle_id" required="yes"/>
+    <field name="fresh" type="bool">Kill the app before launching to ensure a clean start from the home screen. Use when the app may have been left on an arbitrary screen from a previous run.</field>
+    <field name="debug" type="bool">ONLY for debug-built apps (e.g. Flutter dev builds, Xcode debug builds) that need a debugger attached to run. Attaches debugserver, streams stdout/stderr to a log file; result has log_path. Do NOT use for release/App Store apps — they launch fine with debug: false.</field>
     <example>{"action": "open_app", "bundle_id": "com.apple.Preferences"}</example>
-    <note>If open_app fails or the app disappears immediately after launch, the app has likely crashed. Do NOT retry or try alternative launch methods — start crash investigation instead. Use metrics_start with capture_logs: true to capture device logs, then diagnose.</note>
+    <example>{"action": "open_app", "bundle_id": "com.apple.Preferences", "fresh": true}</example>
+    <note>If open_app fails or the app disappears immediately after launch, the app has likely crashed. Do NOT retry or try alternative launch methods — start crash investigation instead. Use debug: true (or metrics_start with capture_logs: true) to capture device logs, then diagnose.</note>
   </action>
 
   <action name="tap">
@@ -211,6 +216,21 @@ const DEVICE_AUTOMATION_REF = `<device-automation-reference>
     <example>{"action": "type", "text": "Hello", "predicate": {"type": "input"}, "clear_first": true}</example>
   </action>
 
+  <action name="type_secret">
+    Type a stored credential without ever exposing its value. secret_id names a credential saved in the app; its value is resolved from the keychain at run time and typed on-device - it never appears in the script, logs, results, or the model context. Use for passwords/tokens in login steps. Same field-targeting as type.
+    <field name="secret_id" required="yes">Id of a stored credential (see list_secrets)</field>
+    <field name="predicate">Optional target field to focus first</field>
+    <field name="clear_first" type="bool"/>
+    <field name="dismiss_keyboard" type="bool" default="false"/>
+    <example>{"action": "type_secret", "secret_id": "test-account-password", "predicate": {"type": "input", "text_contains": "Password"}}</example>
+  </action>
+
+  <action name="clear">
+    Clear a field's text without typing. With a predicate, focuses that field first; without one, clears the currently focused field.
+    <field name="predicate">Optional target element</field>
+    <example>{"action": "clear", "predicate": {"type": "input"}}</example>
+  </action>
+
   <action name="swipe">
     Direction = finger movement. Use direction OR from_coords/to_coords.
     <field name="direction">up, down, left, right</field>
@@ -223,11 +243,13 @@ const DEVICE_AUTOMATION_REF = `<device-automation-reference>
 
   <action name="scroll">
     Direction = semantic (where to look), not finger movement.
-    <field name="direction" required="yes">down (look below), up (look above)</field>
+    <field name="direction" required="yes">down (look below), up (look above), left (look left), right (look right). All four directions are supported - use left/right for horizontal scrollviews (carousels, palettes, paging) instead of falling back to raw-coordinate swipe.</field>
+    <field name="predicate" type="Predicate">Targets a specific scrollable container so the gesture lands inside it (e.g. {"type": "scrollview"} or {"parent_of": {"text": "Work"}}). Without it the gesture is applied at screen center - set this when multiple scrollviews share the screen (e.g. a horizontal palette above a vertical list) to avoid scrolling the wrong one.</field>
     <field name="to_element" type="TargetElement"/>
     <field name="max_scrolls" type="int" default="10"/>
     <field name="amount">small, page, full</field>
     <example>{"action": "scroll", "direction": "down", "to_element": {"predicate": {"text": "Privacy"}}, "max_scrolls": 10}</example>
+    <example>{"action": "scroll", "direction": "right", "predicate": {"type": "scrollview"}}</example>
     <note>scroll with to_element returns "reached end of scrollable content" if the list ends before the element is found. If it returns "element not found after scrolling" instead, the list has more content — increase max_scrolls or call scroll again to continue searching.</note>
   </action>
 
@@ -243,6 +265,12 @@ const DEVICE_AUTOMATION_REF = `<device-automation-reference>
     <example>{"action": "drag", "from": {"predicate": {"text": "App"}}, "to_element": {"predicate": {"text": "Folder"}}, "press_duration_ms": 500, "hold_duration_ms": 200}</example>
   </action>
 
+  <action name="drag_path">
+    <field name="points" type="array of {x, y, duration_ms}" required="true">Single-finger drag along a multi-point path. Each point's duration_ms is the time to move to it from the previous point. The first point is the touch-down location and its duration_ms is an optional initial press-hold (omit or 0 for none). Needs at least 2 points; every point after the first must have duration_ms > 0. Use this (not drag) for swipe-path gestures like unlock patterns, freeform draws, or curved scrolls.</field>
+    <example>{"action": "drag_path", "points": [{"x": 100, "y": 400}, {"x": 150, "y": 300, "duration_ms": 150}, {"x": 300, "y": 500, "duration_ms": 300}]}</example>
+    <example>{"action": "drag_path", "points": [{"x": 100, "y": 400, "duration_ms": 200}, {"x": 300, "y": 400, "duration_ms": 250}]}</example>
+  </action>
+
   <action name="press_key">
     <field name="key" required="yes"/>
     <platform name="android">enter, tab, delete, escape, volume_up, volume_down, home, back, recent_apps, mute, power, play_pause, next, previous</platform>
@@ -319,8 +347,15 @@ const DEVICE_AUTOMATION_REF = `<device-automation-reference>
     <example>{"action": "reset_location"}</example>
   </action>
 
+  <action name="open_link">
+    Opens a URL or deep link on the device. The OS routes custom schemes (myapp://path) to the registered app, so this jumps straight to a screen without navigating the UI. Use for deep-link entry points instead of tapping through the app.
+    <field name="url" required="yes">Full URL or deep link, e.g. https://example.com or myapp://profile/42</field>
+    <example>{"action": "open_link", "url": "myapp://profile/42"}</example>
+    <example>{"action": "open_link", "url": "https://example.com"}</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.
+    iOS only. Sends a voice command to Siri service on iOS devices. 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>
@@ -342,7 +377,7 @@ const DEVICE_AUTOMATION_REF = `<device-automation-reference>
   </action>
 
   <action name="tap/type/press_key/wait_for/if_exists">
-    Same fields as native but use css_selector or xpath in predicate.
+    Same fields as native but use css_selector in predicate.
     <example>{"action": "tap", "context": "web", "predicate": {"css_selector": "button.submit"}}</example>
     <example>{"action": "type", "context": "web", "predicate": {"css_selector": "input#email"}, "text": "user@example.com", "clear_first": true}</example>
     Web press_key keys: enter, tab, delete, escape.
@@ -383,6 +418,15 @@ const DEVICE_AUTOMATION_REF = `<device-automation-reference>
     <example>{"action": "assert_screen_changed", "threshold_percent": 15}</example>
     <note>Pattern: observe(screenshot) then action then delay then assert_screen_changed. Do NOT observe after the action — it resets the baseline.</note>
   </action>
+
+  <action name="ai_assert">
+    <field name="assert_prompt" required="yes"/>
+    <field name="include" type="[]string" note="opt-in extra context: screenshot, ocr (iOS). UI tree + the source script are always included."/>
+    <field name="timeout_ms" type="int" note="bounds the verdict (LLM/CLI reply), excluding context gathering. Default 60000."/>
+    <field name="message" note="prefixes the failure reason"/>
+    <example>{"action": "ai_assert", "assert_prompt": "the reply answers the user's question and is not an error", "include": ["screenshot"]}</example>
+    <note>Judges a natural-language assertion with the user's configured agent — either an LLM API provider (direct call) or Claude Code (spawned, reports back via report_assertion). Use for non-deterministic content (AI/LLM output, dynamic feeds) where exact-match assertions don't work. Treat as a soft assertion — it is non-deterministic.</note>
+  </action>
 </assertions>
 
 <metrics>
@@ -435,7 +479,7 @@ const TESTING_REF = `<testing-reference>
 
 <rules>
   <rule>Never ask the user for information you can get yourself — use observe, list_apps, get_ui_tree.</rule>
-  <rule>Always add wait_for before every element interaction (tap, type, toggle, long_press, double_tap, drag). Exception: the element was asserted on the immediately preceding line.</rule>
+  <rule>Add wait_for before an interaction only when the PREVIOUS action may have changed the screen and the target might not be ready yet - after opening an app, navigating, a screen transition, opening a modal/sheet, scrolling, or submitting something that reloads. If the previous action left the same screen up (typing into a field, toggling a switch, tapping a control that stays put) the element is already there - skip wait_for. Never add it before the element you just asserted.</rule>
   <rule>Always use predicates over coordinates — predicates survive layout changes.</rule>
   <rule>Always prefer UI tree and OCR over screenshots for element discovery.</rule>
   <rule>Your first action must be observe — never ask the user first.</rule>
@@ -495,6 +539,7 @@ const TESTING_REF = `<testing-reference>
 
   <actions>
     app "com.example.app"              — launch app
+    app "com.example.app" fresh        — kill + launch for clean state
     kill_app "com.example.app"         — force-close app
     tap "Text"                          — tap by text
     tap "Field" near "Label"            — tap near another element
@@ -514,6 +559,8 @@ const TESTING_REF = `<testing-reference>
     type ~"Field" → "text"             — partial match field
     type "Field" → "text" clear        — clear first
     type "Field" → "text" keep_keyboard — keep keyboard open
+    type_secret "Field" → "secret-id"  - type a stored credential (value never in script/logs)
+    type_secret "secret-id"             - type credential into focused field
     swipe up|down|left|right            — swipe direction
     swipe up distance:long              — short/medium/long
     swipe up duration:500               — custom duration (ms)
@@ -521,11 +568,13 @@ const TESTING_REF = `<testing-reference>
     scroll down                         — scroll
     scroll down to "Element"            — scroll until visible
     scroll down to "Footer" max_scrolls:10 — limit attempts
+    scroll right in type:scrollview     - target a specific container
     toggle "Wi-Fi" on|off              — toggle switch
     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 hold_duration:200 — press-hold-move-hold-release
+    drag_path 100,400 150,300:150 300,500:300 - multi-point path (X,Y:moveMs, first point's :ms = optional press-hold)
     wait_for "Element" timeout:5000     — wait for element
     wait_for type:button bounds:bottom_half timeout:3000 — modifier-only
     delay 1000                          — wait N ms
@@ -539,6 +588,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
+    open_link "myapp://profile/42"      - open a URL or deep link (routes to the app)
     siri "Search YouTube for cats"      — invoke Siri with voice command (iOS only)
     observe                             — observe screen
     screenshot "path.png"               — take screenshot
@@ -548,6 +598,8 @@ const TESTING_REF = `<testing-reference>
     assert_exists "Element"             — element is on screen
     assert_not_exists "Element"         — element is NOT on screen
     assert_exists "Header" bounds:top_right — with region filter
+    assert_exists value:"hello"         — assert a field's entered value (exact); sees typed content, not placeholder
+    assert_exists value_contains:"@mail" — assert a substring of the entered value
     assert_count "Cell" expected:5      — element count
     checkpoint "name"                   — mark checkpoint
   </assertions>
@@ -620,9 +672,10 @@ const TESTING_REF = `<testing-reference>
     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
+    3. Use app "bundle.id" fresh to ensure a clean start — the app may be left on any screen from a previous call
+    4. Save it to {MOBAI_DATA_DIR}/apis/{name}.mob — flat (gmail-send.mob) or nested (gmail/send.mob)
+    5. Test it with test_run using project_dir: {MOBAI_DATA_DIR}/apis/ and case_path: {name}.mob
+    6. 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobai-mcp",
-  "version": "2.3.0",
+  "version": "2.4.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.3.0",
+  "version": "2.4.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "mobai-mcp",
-      "version": "2.3.0",
+      "version": "2.4.0",
       "transport": {
         "type": "stdio"
       }