MobAI MCP

Claim exclusive use of a device for this session. You rarely need this: a host that requires claims auto-claims on your first action, and a host that does not require them needs no claim at all. Do not call it to fix a device that is missing, still connecting, or busy - none of those are lease problems. Use it only to reserve a device up front or to set a custom holder label. A session can hold several devices at once; each lease is attached automatically to subsequent calls targeting its device and auto-renews on every action, expiring only after the app's configured idle timeout. Call release_device when you are done with a device.

Launch an app in debug mode and write logs to a file. Returns the log file path — use Read/Grep to inspect logs. Use kill_app to stop.

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.

Add or remove a breakpoint in the active debug session. For action=add provide spec; for action=remove provide id.

End the debug session. Pass kill=true to terminate the debuggee; otherwise it keeps running.

Evaluate a Swift/ObjC expression at the current pause. Session must be paused. Examples: "p defaultPrivate", "po self.viewModel.user.email", "frame variable".

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.

Advance the target. "in" — step into next call (blocks ~ms, returns {state, breakpoints, stack, frame0_locals}) "over" — step over next call (same shape) "out" — run until current frame returns (same shape) "continue" — resume until next breakpoint (fire-and-forget; returns just {state, breakpoints} — poll debug_state for next stop)

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.

To find visual/UI bugs on the current screen, run a single {"action":"audit"} step: it returns deterministic findings (touch targets, clipping, alignment, spacing, safe area, accessibility) plus an annotated screenshot whose red boxes are labelled with the element ids in the findings. Findings are evidence, not verdicts - cross-check the annotated screenshot to decide which are real bugs.

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".

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":"repeat","times":"3","body":[{"action":"tap","predicate":{"text":"Increment"}}]}, {"action":"repeat","while":{"text":"Loading"},"max_iterations":20,"body":[{"action":"delay","duration_ms":500}]}, {"action":"run_script","script":"var r = http.get('https://api.example.com/seed'); vars.seed_id = JSON.parse(r.body).id;"}, {"action":"eval_script","script":"1 + 1","store_as":"two"}, {"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"}, {"action":"audit"} ]}

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"}.

Get details about a specific device

Capture a fast, low-quality screenshot for LLM visual analysis. Returns the file path to the saved image. The image may be downscaled by an integer factor so its long edge stays ≤ 2000px; when that happens the response includes a scale factor — multiply any coordinates you read off the image by that factor before using them in device actions (tap, swipe, drag, long-press, etc.). UI tree coordinates are already in device pixels, do not scale those. Use this for AI/LLM processing only — for full-quality screenshots use save_screenshot instead.

Install an app on the device from a local file path (.apk for Android, .ipa for iOS). For cloud devices nothing is installed directly: the build is uploaded to the provider's app storage and the response returns an appRef - pass it to start_bridge as "app" (restart the bridge if a session is already running).

List installed apps on the device

List all connected Android and iOS devices. Devices with "remote": true are physically attached to ANOTHER machine (a peer MobAI node, hostname in "node") and devices with "cloud": true live in a cloud device farm - all MobAI tools (tap, observe, DSL, screenshots, recording) work on them transparently, but host-local tooling (ffmpeg, simctl, adb, xcodebuild) cannot reach them; stay within MobAI tools for those devices. Devices with "inUse": true are claimed by the holder named in "inUseBy" - claim a different device or wait for the lease to expire.

Release device lease(s) held by this session. With device_id, releases that device's lease; without, releases every lease this session holds. Succeeds quietly if nothing is held.

Save a full-quality PNG screenshot to disk. Use this when you need a high-quality image for reporting, debugging, or sharing — not for LLM processing (use get_screenshot instead).

Start the automation bridge on a device. Required before interacting with the device. For cloud devices this allocates the provider session; pass "app" to pick the app under test (e.g. the appRef returned by install_app).

Stop the automation bridge on a device

Get the currently active test project directory and its .mob test cases. Use this to discover the project path and available tests. The agent can then read/write/create/delete .mob files directly in the returned directory.

List all known test project directories with their .mob test cases. Each project is a directory containing .mob script files.

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.

Uninstall an app from the device