# mobile driver

Unified iOS + Android UI-driving verify-proof driver. Wraps the
[`mobile-mcp`](https://github.com/mobile-next/mobile-mcp) MCP server
(mobile-next, Apache-2.0) — one backend for both platforms, driven via the
native accessibility tree with screenshot-coordinate fallback (ADB for
Android, idb for iOS).

- **Targets:** `ios`, `android`, `expo`, `react-native`.
- **Transport:** `{ mcp_server_id: "mobile-mcp" }` (provisioned as
  `npx -y @mobilenext/mobile-mcp@latest`).
- **Platform selection:** chosen INSIDE the tool call
  (`mobile_list_available_devices` → device id), NOT at resolver time — that
  is why one driver covers both platforms (decision D-01).

## Lifecycle boundary

This driver only **drives UI + captures evidence** against a foregrounded,
JS-ready app. The app lifecycle — build, install, launch, Metro start, and
the launch-readiness gate — is owned by `apt-tools mobile prepare`
(decisions D-03/D-04), which runs BEFORE any verb is dispatched.

## System prerequisites (validated, not installed)

`mobile-mcp` is pure npm, but the underlying device toolchain is NOT:

- **iOS:** `idb-companion` (`brew install idb-companion`) + Xcode + a booted
  Simulator.
- **Android:** Android SDK + `adb` (`$ANDROID_HOME/platform-tools`) + an
  emulator/device.

These are validated by the manifest's `preflight[]` via
`apt-tools driver doctor` (which records `missing_deps` with guidance) — the
framework never auto-installs them (decision D-09).

## Out of scope

Real-device runs and Mac Catalyst (separate RFCs). XcodeBuildMCP is an
optional future escalation for native-Xcode-heavy iOS builds, not a
dependency of this driver (decision D-02).
