MUA Driver

A mobile-use driver for agents. It controls Android and iOS devices and exposes them over MCP, a JSON CLI, and a small Python SDK. It runs no model of its own: an agent brings the decisions, MUA carries them out and reports what actually happened on the device.

• Android devices and emulators through adb, with an optional Accessibility Helper for the things adb cannot do
• iOS Simulators through xcrun simctl and idb, physical devices through xcrun devicectl and WebDriverAgent
• MCP over stdio or authenticated HTTP, with a capability-filtered tool list

Install

python3 -m pip install -e '.[dev]'

Host tools: Android platform-tools (MUA resolves MUA_ADB_PATH, then ANDROID_SDK_ROOT/ANDROID_HOME, then PATH); Xcode command line tools with xcrun for iOS Simulators; Facebook idb for iOS touch and text input; Xcode 15+ with Developer Mode and a signed, running WDA for physical iOS devices.

Quick start

mua-driver call list_devices
mua-driver call screenshot --device emulator-5554 --output /tmp/screen.png
mua-driver call tap_element --device emulator-5554 --platform android \
  --using text --value "Continue"
mua-driver mcp                      # MCP server over stdio

from mua_driver import MuaDriver

driver = MuaDriver.create()
driver.tap_element(device_id="emulator-5554", platform="android",
                   using="text", value="Continue")

mua-driver call --help lists every tool. docs/ has the details.

Tool coverage

What MUA does differently

Actions are verified by their effect. Every semantic action re-resolves its target on a live hierarchy before dispatch, declares what it expects (screen_change, element_present, text_value, activity, …), waits for that outcome, and reports verified or a structured failure with a bounded retry. A tool that reports success has either dispatched a real action or told you it degraded. See docs/action-safety.md.

Gestures are motion, not two events. adb shell input swipe delivers a press and a release with no movement between them on many devices. MUA ships its own Accessibility Helper and prefers it for drags, flings and pinches, so a ScrollView actually scrolls and a pinch actually produces a scale event. See docs/android-helper.md.

Platform limits are named, not hidden. A capability the platform does not expose is reported unsupported_by_platform with a reason. The verification suite records the same way: every tool ends as verified, requires_setup, or unsupported — never a silent skip.

Compared to other mobile drivers

Read from each project's own README at the time of writing. Not stated means the project does not document the capability; it is not a claim that it is missing.

The comparison is about shape, not depth: all four expose an MCP tool surface, and all four can find an element semantically before falling back to coordinates. What differs is in this repository's column — it ships an on-device helper, and it verifies the effect of an action rather than reporting that a command was accepted.

Where MUA is behind: ARTEMIS runs a vision model as a third fallback for Canvas and Compose interfaces. MUA runs no model of any kind, so a target it cannot find semantically is reached by coordinate or not at all — see docs/targeting.md.

Verification

Both device surfaces are measured, not asserted. A suite drives the real driver against a live device and records an explicit verdict per tool, asserting against what the test app recorded receiving — event counts, pointer contact time, peak velocity, pinch span, selected range — rather than against a returned ok.

MUA_ANDROID_TEST_DEVICE=emulator-5554 python -m pytest tests/verification -q
MUA_IOS_SIMULATOR_UDID=6F7241FF-... python -m pytest tests/verification_ios -q

Android: 123 tests in about 2¾ minutes, 163 verdicts across 129 tools — 161 verified, 1 requires_setup (clipboard read, which Android 10+ grants only to the focused app), 1 unsupported (get_screen_state, iOS-only in this surface).

iOS: the same seven modules against a booted Simulator — 141 tests, about eleven minutes, 159 verdicts across 122 tools, with every tool the schema lets a caller reach on iOS covered. 125 verified; the other 34 are platform limits the Simulator cannot lift, each recorded with the measurement behind it and a typed refusal from the driver rather than an ok.

Neither run has a failing or unrun tool, and a coverage gate fails either one if a tool lacks a verdict or fails one.

DRIVER_VERIFICATION.md has the method, both results and the defects they found — among them an iOS tap path that passed floats to a command that parses integers, which had broken every element-addressed tool on that platform; a selector table in the iOS backend that resolved content-desc nowhere, which made scroll_element_into_view scroll a screen looking for an element the hierarchy already held; an Android set_permission that returned ok for a grant the platform had silently declined to make; and an Android handle_alert("accept") that returned ok after pressing Deny, because the two dialog buttons were held in a set and sets do not keep an order.

Boundaries

• Android defaults to platform tools (adb shell input, adb exec-out, package manager); the accessibility helper is opt-in and never installed or enabled without being asked.
• iOS Simulator discovery, screenshots, launch and termination use simctl; gesture, text and accessibility operations use idb. Physical iOS uses devicectl for discovery and diagnostics, WDA for interaction.
• The MCP server is stdio JSON-RPC with initialize, tools/list, and tools/call.

Documentation