mobridge-mcp 0.8.1 → 0.8.3

package/README.md

@@ -121,7 +121,8 @@ Two or more steps: send a JSONL plan instead of many calls. The daemon keeps the
 | Fill a form | One `mobile.run` plan with `type` steps and a final `tap`. |
 | Answer a permission dialog | CLI `mobridge permission respond --decision ALLOW_WHILE_USING` (answers the dialog like a user). `permission set <pkg> CAMERA` changes the state directly via ADB and reads it back. They are not interchangeable. |
 | Close an ad | CLI `mobridge ad dismiss`. It tries BACK, then assisted capture; it never taps a call-to-action. Exit 8 = pick the close point from the returned capture, then `mobridge ad tap-close`. |
-| Install / force-stop / uninstall | CLI `mobridge package install|uninstall`, `mobridge process stop`; each reads the package/process state back. |
+| Install / force-stop / uninstall | CLI `mobridge app install <file.apk>` (copies it into `MSM_APK_DIR` and reads the package id with aapt2/aapt, from PATH or the Android SDK build-tools), `app install <package> --apk <name>`, `app uninstall`, `app force`; `package install|uninstall` and `process stop` are aliases. Each reads the package/process state back. |
+| Wait / exit codes | `mobridge wait` that runs out of time returns status `TIMEOUT` and exit 10 (never VERIFIED/0). Exit codes: 0 VERIFIED, 1 FAILED, 2 DISPATCHED, 3 RESULT_UNKNOWN, 4 needs setup, 5 ambiguous, 6 policy, 7 transport, 8/9 `ad`, 10 TIMEOUT. |
 | Diagnose | CLI `mobridge diag LOGCAT|CRASH|BATTERY|NETWORK|DISPLAY|POWER`. |
 | Anything missing | `mobridge capabilities [--family F]` lists every operation, its executor, replay class and verification. |
 
@@ -136,14 +137,23 @@ Two or more steps: send a JSONL plan instead of many calls. The daemon keeps the
 
 ## Troubleshooting
 
-| Symptom | Fix |
-|---|---|
-| `AMBIGUOUS_DEVICE` | Pass `deviceId` (`mobridge devices`). |
-| `COMPONENT_MISSING` / `COMPANION_UNAVAILABLE` | Run `mobridge connect -d ANDROID:<serial>` again; it reinstalls and re-enables the companion. |
-| `ACCESSIBILITY_PREEMPTED` / `EXTERNAL_INSTRUMENTATION_ACTIVE` | Another tool (UiAutomator, a test runner, another agent) owns accessibility. Stop it and reconnect. |
-| `TRANSPORT_DEGRADED` | Link dropped; prefer USB over wireless adb. `mobridge health` shows the socket state. |
-| `UNSUPPORTED_PLATFORM` | You asked for iOS. Only Android is supported. |
-| Companion disables itself | By design after 5 minutes without a controller; the next connect re-arms it. |
+`mobile.device.connect` does the whole setup: installs the companion APK if missing, updates it when it differs from the host version, enables Accessibility over ADB, creates the port forward and waits for the companion to answer. You never run `adb` yourself. If it fails, read `error.code`, then `details.diagnostics` and `recovery[0]`:
+
+| Symptom / `error.code` | Cause | Fix |
+|---|---|---|
+| `COMPANION_NOT_READY` ("socket hang up") | The companion did not answer the handshake. `details.diagnostics` says why: not installed, version mismatch, Accessibility off, service not bound, process not running. | Run `mobridge connect` again (it installs/updates). On Android 13+ a sideloaded app may need Settings > Apps > MoBridge Runtime > ⋮ > *Allow restricted settings* before Accessibility can be enabled. If the service is not bound, open the MoBridge Runtime app once and exclude it from battery optimisation. |
+| `COMPANION_INSTALL_BLOCKED` | The phone refused the USB install (Xiaomi/Oppo/Vivo/Samsung prompts, Play Protect). | Follow `recovery`: unlock and tap Install/Allow; Xiaomi: enable *Install via USB* and *USB debugging (Security settings)*; then `mobridge connect`. |
+| `ACCESSIBILITY_ENABLE_BLOCKED` | The phone refused to enable Accessibility over ADB. | Xiaomi: *USB debugging (Security settings)*; or enable it by hand in Settings > Accessibility; Android 13+: *Allow restricted settings* first. |
+| `COMPONENT_MISSING` | No APK to install. | Re-run `npx -y mobridge-mcp@latest install`, or set `MSM_COMPANION_APK`. |
+| `EXTERNAL_INSTRUMENTATION_ACTIVE` | Another tool (UiAutomator, a test runner, another agent) holds UiAutomation. | Stop it, then `mobridge connect`. |
+| `ACCESSIBILITY_PREEMPTED` | Service enabled but unbound. | Wait a few seconds, then `mobridge connect`. |
+| `ADB_UNAUTHORIZED` / `DEVICE_OFFLINE` | USB debugging not authorised, or no device. | Unlock the phone, accept the prompt, check `adb devices`. |
+| `AMBIGUOUS_DEVICE` | Several devices attached. | Pass `deviceId` (`mobridge devices`). |
+| `TRANSPORT_DEGRADED` | Link dropped. | Prefer USB over wireless adb; `mobridge health` shows the socket state. |
+| `UNSUPPORTED_PLATFORM` | iOS requested. | Only Android is supported. |
+| Companion disables itself | By design after 5 minutes without a controller. | The next connect re-arms it. |
+
+Still stuck: `mobridge doctor`, `mobridge health`, and report `details.diagnostics` with the error.
 
 ## CLI contract