mobridge-mcp 0.10.5 → 0.12.0

package/AI-USAGE.md

@@ -103,8 +103,11 @@ After an install/update, connect waits for the companion to become ready (a few
 - Semantic UI (find/click/type/scroll/BACK/HOME/wait) runs through Accessibility; package/process/permission/settings/log/perf run through ADB; opening an app, permission flows, notifications and ads are hybrid; canvas/games/unlabeled icons use vision.
 - With a clear goal call one act directly; find is only for checking or when ambiguous. Several steps: mobile.run/mobridge run or mobridge session --jsonl; one-shot CLI is for single operations only.
 - permission respond answers the dialog that is showing (resource-id, not pm grant); permission set changes state with pm grant/revoke and reads it back to verify. The two do not replace each other.
+- A capture result lists targets [{name, role, at}]: the named controls on the image with the point that clicks each; use that at, never a point estimated from pixels. An observe element with contains [texts] is an unnamed clickable row: click it by query text.
 - NEEDS_VISION: read the current capture (it has a captureId), pick a point on the image, then act CLICK {at:{captureId,x,y}} (dynamic UI such as ads/video/countdown timers: stalePolicy VISUAL_DYNAMIC, act within 8 s); an old image gives STALE_CAPTURE. Never guess coordinates. Find by colour: capture {color:{hex}} → colorMatch. A control without a node: capture {scan:{}} → regionScan.regions[] (regionId, bounds, position, semanticNode, at): neutral facts that do not name the icon. Look at the image, choose a region, act CLICK {at}; if unsure it stays NEEDS_VISION, do not guess.
 - Do not change executor after a dispatch that may have run (timeout/dropped connection): the result is RESULT_UNKNOWN, look up the operation status, do not resend over ADB.
+- adb replacements (typed, verified): file ls|stat|pull|push|rm (--recursive, --run-as), intent start|broadcast|service|stop-service, settings get|put|restore, prop, logcat, keycode, device wake|sleep|rotate|stay-awake|..., forward|reverse; shell <command> (raw adb shell) and adb -- <args> for everything else; chain/parallel/session for several steps. Only uiautomator is refused. Over MCP use mobile.run steps (logcat, file, intent, settings, prop, shell, adb).
+- `key`/`gesture` with --verify DISPATCH_ONLY (MCP: verify.policy DISPATCH_ONLY) skip the screen wait: ~200 ms instead of ~400-740 ms, no verification.
 - Do not use raw adb when a typed command exists. mobridge capabilities [--family F] lists each op's executor, replay class and verification.
 
 ## Choose the tool by goal
@@ -164,15 +167,19 @@ A `wait` condition is always wrapped in nodeExists/nodeAbsent/anyOf/allOf, never
 ## Typed commands (generated from the registry)
 
 - app: app clear · app force · app list · open
-- device: devices · health --preflight · health · doctor · doctor --restart-adb · connect · state
+- device: devices · health --preflight · health · doctor · doctor --restart-adb · connect · device · state · forward
 - diag: diag
+- diagnostics: adb · logcat · logcat --clear · shell · shell run
 - fallback: fallback cancel · fallback commit · fallback prepare · fallback status
-- input: gesture · type · key
+- file: file ls · file pull · file push · file rm · file stat
+- input: gesture · type · key send · key
+- intent: intent broadcast · intent service · intent start · intent stop-service
 - operation: operation status · trace
 - package: app install · app uninstall
 - permission: permission set · permission set --revoke · permission respond
 - run: batch · run · scenario
 - screen: screen act click | type | scroll · screen act at · analyze · screen burst · screen capture · diff · find · inspect · screen observe · record · screen act scroll · wait · watch
+- settings: prop get · settings get · settings put · settings restore
 
 ## Examples
 

package/README.md

@@ -136,6 +136,25 @@ Two or more steps: send a JSONL plan instead of many calls. The daemon keeps the
 5. Do not call `adb`, `uiautomator` or coordinate taps from the agent; use the typed tools.
 6. Coordinates from a capture are valid only for that capture (`STALE_CAPTURE` otherwise).
 
+## Use MoBridge instead of adb
+
+Logs, files, intents, settings, keys, power, ports and raw shell all have MoBridge commands, so an agent never needs bare `adb`:
+
+| adb habit | MoBridge |
+|---|---|
+| `adb logcat -d` | `mobridge logcat --tag Tag:D --max-lines 200 [--since cursor] [--follow ms]` |
+| `adb push` / `pull` | `mobridge file push\|pull <path> [--recursive] [--run-as pkg]` (SHA-256 verified) |
+| `am start` / `broadcast` / `startservice` | `mobridge intent start\|broadcast\|service\|stop-service` |
+| `settings get` / `put` | `mobridge settings get\|put\|restore [--restore-on-exit]` |
+| `input keyevent`, `svc`, rotation, reboot | `mobridge keycode`, `mobridge device wake\|sleep\|rotate\|stay-awake\|reboot\|tcpip\|usb` |
+| `adb forward` / `reverse` | `mobridge forward\|reverse list\|add\|remove` |
+| `adb shell <anything>` / `adb <anything>` | `mobridge shell <command>` / `mobridge adb -- <args>` |
+| several commands | `mobridge chain`, `parallel`, `session --jsonl`, or `mobile.run` steps over MCP |
+
+`shell` and `adb` have no allowlist and ask for no approval, the same trust level as `adb`; only `uiautomator` is refused because it
+breaks the accessibility session. Typed commands read back or hash-check their result; `shell`, `adb` and `key` only dispatch.
+The skill `mobridge-adb` (installed with the skill pack) teaches an agent this map; the full reference is in its `references/commands.md`.
+
 ## Troubleshooting
 
 `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]`: