adb-ready 0.1.2 → 0.2.0

package/docs/agent-integration.md

@@ -0,0 +1,204 @@
+# AI agent integration
+
+ADB Ready exposes Android workflows to local AI agents through a typed Model
+Context Protocol (MCP) server. The agent works with the same deterministic
+target, application identity, verification rules, and structured problems as
+the CLI—without receiving a generic shell or raw ADB command.
+
+## Install and verify
+
+Pin ADB Ready in the Android project the agent will work on:
+
+```bash
+npm install --save-dev --save-exact adb-ready
+node ./node_modules/adb-ready/dist/cli.js doctor
+```
+
+The MCP server uses standard input/output and must be started from the project
+root:
+
+```bash
+node ./node_modules/adb-ready/dist/cli.js mcp
+```
+
+Do not run that command by hand for normal use; the MCP client starts and stops
+it. ADB Ready does not open an MCP network listener.
+
+## Connect an agent
+
+Preview the exact project change first, then apply it:
+
+```bash
+adb-ready agent setup codex --dry-run
+adb-ready agent setup codex
+```
+
+Replace `codex` with `claude-code`, `cursor`, or `vscode`. Existing unrelated
+configuration is preserved. An existing `adb-ready` entry with different
+settings is reported as a conflict and is never replaced automatically.
+
+### Codex
+
+Create a project-scoped `.codex/config.toml`:
+
+```toml
+[mcp_servers.adb_ready]
+command = "node"
+args = ["./node_modules/adb-ready/dist/cli.js", "mcp"]
+default_tools_approval_mode = "writes"
+```
+
+Codex CLI, the Codex IDE extension, and the ChatGPT desktop app share Codex MCP
+configuration. See the [official Codex MCP guide](https://learn.chatgpt.com/docs/extend/mcp).
+
+### Claude Code
+
+Run this from the project root:
+
+```bash
+claude mcp add --scope project adb-ready -- node ./node_modules/adb-ready/dist/cli.js mcp
+claude mcp get adb-ready
+```
+
+Claude Code stores project-scoped servers in `.mcp.json` and asks users to
+approve them. See the [official Claude Code MCP guide](https://docs.anthropic.com/en/docs/claude-code/mcp).
+
+### Cursor
+
+Create `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "adb-ready": {
+      "command": "node",
+      "args": ["./node_modules/adb-ready/dist/cli.js", "mcp"]
+    }
+  }
+}
+```
+
+See the [official Cursor MCP guide](https://docs.cursor.com/context/model-context-protocol).
+
+### VS Code and GitHub Copilot
+
+Create `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "adb-ready": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${workspaceFolder}/node_modules/adb-ready/dist/cli.js", "mcp"]
+    }
+  }
+}
+```
+
+See the [official VS Code MCP guide](https://code.visualstudio.com/docs/agent-customization/mcp-servers).
+
+### Windsurf
+
+Windsurf currently keeps MCP configuration in a user-scoped file. Generate a
+project-bound snippet and merge it through Windsurf MCP settings:
+
+```bash
+adb-ready agent setup windsurf
+```
+
+ADB Ready deliberately does not edit this global file. The generated entry
+uses an absolute local package path and `ADB_READY_MCP_PROJECT_ROOT` so Cascade
+still resolves the intended project. See the [official Windsurf MCP guide](https://docs.windsurf.com/windsurf/cascade/mcp).
+
+### Other MCP clients
+
+Generate a standard `mcpServers` entry:
+
+```bash
+adb-ready agent setup generic
+```
+
+Merge the result at the location required by the client and ensure the server
+starts in the Android project root.
+
+## Recommended agent workflow
+
+Ask the agent to follow this sequence:
+
+1. Call `doctor` when host or ADB health is unknown.
+2. Call `ensure_ready`; provide an exact device serial, configured alias, or
+   transport ID when more than one ready target exists.
+3. Resolve the project app with `resolve_app`.
+4. Use `inspect_app` or `inspect_ui` for bounded current evidence.
+5. Perform one typed action, then inspect again instead of assuming success.
+6. Use `get_session_problems` or `compile_debug_context` for an existing
+   development session.
+
+The first successful `ensure_ready` binds one target to that MCP connection.
+Later tools cannot silently switch to another target.
+
+Tool calls within one MCP connection are executed in submission order. This
+prevents parallel agent requests from interleaving target binding, UI snapshots,
+or device mutations. Separate MCP connections remain independent.
+
+## Tool surface
+
+| Capability | MCP tools |
+| --- | --- |
+| Host and target readiness | `doctor`, `list_targets`, `ensure_ready` |
+| App identity and lifecycle | `resolve_app`, `install_app`, `launch_app`, `restart_app`, `open_url` |
+| Current evidence | `inspect_app`, `inspect_ui`, `capture_screenshot` |
+| Safe UI actions | `tap_ui`, `long_press_ui`, `swipe_ui`, `type_text_ui`, `press_key_ui`, `wait_for_ui` |
+| Saved diagnostics | `get_session_problems`, `compile_debug_context` |
+
+MCP resources keep larger read-only context outside tool calls:
+
+| Resource | Content |
+| --- | --- |
+| `adb-ready://targets` | current target inventory and this connection's bound target |
+| `adb-ready://sessions` | bounded saved-session manifests |
+| `adb-ready://sessions/{sessionId}` | one session manifest |
+| `adb-ready://sessions/{sessionId}/events/{offset}/{limit}` | a page of up to 200 redacted events |
+| `adb-ready://sessions/{sessionId}/context` | a bounded redacted Markdown context document |
+
+Tool results contain the same structured success, problem, evidence, and
+verification data used by CLI JSON output.
+
+The npm package also ships `schema/agent-tools-v1.json`, generated from the
+server's real `tools/list` response during every build. Integrations can inspect
+version-matched input schemas and safety annotations without starting ADB.
+
+## Safety boundary
+
+- There is no arbitrary command, shell, or raw ADB tool.
+- MCP tool arguments are schema-validated before execution.
+- Local APK installation accepts only a real path inside the project.
+- Screenshots require an explicit tool call and are stored as project files.
+- UI hierarchy and app inspection are marked sensitive and remain bounded.
+- UI references are checked against a fresh hierarchy digest before mutation;
+  stale references are rejected.
+- Data clearing and uninstall are intentionally absent from the agent surface.
+- Tool annotations help clients request approval, but ADB Ready enforces its
+  own target, path, and destructive-action rules.
+- Nothing is uploaded by ADB Ready. The selected AI client controls what tool
+  results it sends to its model provider.
+
+Review the client configuration before approving it and keep write-capable
+tools behind the client's approval policy. See [Security](../SECURITY.md) for
+the complete trust model.
+
+## Runtime alternatives
+
+The published bundle is smoke-tested as an MCP stdio server under Node.js, Bun,
+and Deno. Replace the command and arguments when Node.js is not your chosen
+runtime:
+
+```text
+Bun:  bun  ./node_modules/adb-ready/dist/cli.js mcp
+Deno: deno run -A ./node_modules/adb-ready/dist/cli.js mcp
+```
+
+Deno's `-A` grants the local server the filesystem, process, environment, and
+network access required to find project metadata and invoke ADB. Use the
+client's sandbox controls when a narrower host boundary is required.

package/docs/apps-and-evidence.md

@@ -0,0 +1,157 @@
+# Apps and evidence
+
+ADB Ready resolves project identity locally when possible, then binds
+target-based app operations and evidence to one deterministic Android target.
+It reports success only after the requested postcondition is observed.
+
+## App identity
+
+Inspect the project app without hard-coding its package name:
+
+```bash
+adb-ready app resolve
+adb-ready app info
+```
+
+Resolution prefers an explicit `APP_ID`, then project configuration and
+detected Android project metadata. Every resolved result includes provenance.
+If equally valid candidates remain, ADB Ready asks for an explicit choice
+instead of selecting the first package.
+
+Explicit, configured, Gradle, Expo, and manifest identity can be resolved with
+no running emulator, connected phone, or ADB binary. Only the final
+installed-package fallback requires a target.
+
+Set a stable project value when detection is not sufficient:
+
+```json
+{
+  "app": {
+    "android": {
+      "package": "com.example.app"
+    }
+  }
+}
+```
+
+List installed packages when investigating a target:
+
+```bash
+adb-ready apps list
+adb-ready apps list --system --filter google
+adb-ready apps list --all --json --non-interactive
+```
+
+User packages are the default. Enumeration and machine output are bounded.
+
+## App lifecycle
+
+```bash
+adb-ready app install ./android/app/build/outputs/apk/debug/app-debug.apk --replace
+adb-ready app launch
+adb-ready app restart
+adb-ready app stop
+adb-ready open 'myapp://orders/42' --package com.example.app
+```
+
+- Installation currently accepts one ordinary APK. Split APK sets, `.apks`,
+  `.aab`, and implicit downloads are not accepted.
+- Install, launch, stop, restart, and explicit deep-link handlers are checked
+  after ADB accepts the request.
+- `restart` is a verified stop followed by a verified launch.
+- Add `--activity .MainActivity` only when Android cannot resolve a launchable
+  activity.
+- Add `--grant-runtime-permissions` to an install only when that behavior is
+  intended.
+
+Preview exact target-scoped ADB operations without changing the device:
+
+```bash
+adb-ready app restart --dry-run --json
+adb-ready app clear-data --dry-run
+```
+
+`clear-data` and `uninstall` are destructive. Interactive use requires a
+confirmation; automation must pass `--allow-destructive`. A dry run never asks
+for destructive approval because it performs no mutation.
+
+## Structured inspection
+
+Build a compact snapshot of the project app, foreground state, and a small
+classified log window:
+
+```bash
+adb-ready inspect app
+adb-ready inspect app com.example.app --json --non-interactive
+```
+
+Screenshots are deliberately not captured by this read-only command. The
+result reports `adb-ready capture screenshot` as the explicit next action so
+sensitive pixels never enter evidence or AI context implicitly.
+
+Read the current Android accessibility hierarchy:
+
+```bash
+adb-ready inspect ui --interactive-only
+adb-ready inspect ui --max-depth 20 --json --non-interactive
+```
+
+The snapshot is capped at 2,000 nodes and includes a SHA-256 digest. Each node
+reference contains a prefix of that digest, so callers can distinguish stale
+references after the UI changes. `--interactive-only` keeps enabled actionable
+nodes; `--max-depth` accepts 1–100. Secure windows and missing accessibility
+data are reported as unavailable rather than as an empty successful snapshot.
+
+UI text and hierarchy data are marked `sensitive: true`. They are returned only
+by the explicit inspect command and are never included in diagnostic AI context
+automatically.
+
+## Evidence capture
+
+Capture a PNG directly from the selected target:
+
+```bash
+adb-ready capture screenshot
+adb-ready capture screenshot --out artifacts/login.png
+```
+
+Capture a bounded MP4 recording:
+
+```bash
+adb-ready capture screen-record --duration 15s
+adb-ready capture screen-record --duration 30s --out artifacts/repro.mp4
+```
+
+Evidence paths are relative to the current project. A capture never follows a
+symlink outside that root and never replaces an existing file unless `--force`
+is explicit. Files are written through a private temporary path and published
+only after validation.
+
+Some multi-display Android builds, including foldables, emit a short textual
+warning before the screenshot bytes. ADB Ready removes only a bounded text
+preamble and still requires a valid PNG signature before publishing the file.
+
+The result contains:
+
+- a project-relative path;
+- media type and byte size;
+- SHA-256 digest;
+- selected target and capture-command provenance.
+
+Binary data is stored as a file rather than embedded into JSON or AI context.
+Screenshots and recordings can contain private information; ADB Ready does not
+upload or implicitly attach them to diagnostic context.
+
+## Target selection and automation
+
+All commands accept the standard target selectors:
+
+```bash
+adb-ready app info --device SERIAL
+adb-ready capture screenshot --transport-id ID
+adb-ready app restart --last
+```
+
+Use `--json --non-interactive` for one versioned result on `stdout`, or
+`--format ndjson` for structured progress plus the final result. Human progress
+and errors remain on `stderr`.

package/docs/automation.md

@@ -43,6 +43,12 @@ JSON commands return this top-level shape:
 Consumers must ignore unknown additive fields and event types within the same
 schema version.
 
+The npm package includes two versioned public artifacts:
+
+- `schema/config-v1.schema.json` validates project configuration; and
+- `schema/agent-tools-v1.json` catalogs every MCP tool's generated input schema
+  and safety annotations for the matching package version.
+
 ## Event envelope
 
 NDJSON events include:

package/docs/threat-model.md

@@ -0,0 +1,85 @@
+# Threat model
+
+ADB Ready runs locally with the same Android access as the selected ADB server.
+Its security goal is to make that authority explicit, narrow, target-bound, and
+observable; it cannot sandbox ADB, the Android device, a project command, or an
+AI client that already has broader host access.
+
+## Trust boundaries
+
+| Boundary | ADB Ready assumes | ADB Ready enforces |
+| --- | --- | --- |
+| CLI caller | arguments may be malformed or automated | strict parsing, no implicit shell, bounded values, explicit destructive approval |
+| ADB server and device | may be remote, stale, unavailable, or return hostile text | exact target selection, postcondition checks, output bounds, terminal sanitization |
+| Project filesystem | may contain symlinks, existing files, or untrusted config | root containment, schema validation, atomic writes, no overwrite by default |
+| Session storage | contains sensitive diagnostics | per-user location, bounded retention, redaction, restrictive file modes |
+| MCP client | chooses what reaches a model provider | local stdio only, typed tools, one bound target, no generic shell/raw ADB |
+| npm and CI | dependencies and release credentials can be attacked | pinned lockfile, package allowlist, short-lived OIDC publishing, provenance |
+
+## Protected assets
+
+- pairing codes, environment secrets, logs, screenshots, and UI text;
+- the identity and state of the intended Android target and app;
+- project files and existing ADB port mappings;
+- the integrity of the published npm package and its command/tool contracts.
+
+## Main threats and controls
+
+### Command and input injection
+
+Child commands use an executable plus argument array without an implicit shell.
+MCP exposes allowlisted workflows rather than command execution. Android text
+input accepts only a conservative character set; key actions map to numeric
+allowlisted keycodes.
+
+### Wrong-target mutation
+
+Every target-aware operation uses an exact ADB serial or transport ID. Ambiguous
+selection fails. An MCP connection binds one target and refuses a silent
+switch. UI references include the current hierarchy digest and are revalidated
+immediately before mutation.
+
+### Unsafe file mutation
+
+Capture and setup paths are constrained to the project, checked for unsafe
+symlinks, written atomically, and not replaced without an explicit policy. MCP
+APK installation accepts only an existing project-local file.
+
+### Secret or terminal escape disclosure
+
+Human output is terminal-sanitized. Stored diagnostic events are bounded and
+redacted. Pairing codes use protected input or stdin and never enter process
+arguments. Screenshots and UI hierarchies require explicit calls and never join
+AI context automatically.
+
+### Unbounded or misleading automation
+
+Process output, recordings, UI trees, session storage, context, retries, and
+waits are bounded. Results distinguish process acceptance (`ok`) from observed
+postconditions (`verified`). An unchanged UI is reported as a verification gap,
+not silently upgraded to verified success.
+
+### Network exposure
+
+The 0.2 MCP server uses stdio and opens no listener. ADB itself may connect to a
+local or remote server selected by the user; that existing authority is outside
+ADB Ready's isolation boundary.
+
+## Intentionally absent
+
+- arbitrary shell or raw ADB MCP tools;
+- automatic downloads, mutable `latest` execution, or implicit tool installs;
+- MCP data clearing and uninstall operations;
+- autonomous destructive recovery;
+- automatic screenshot or UI-text upload.
+
+## Residual risk
+
+A trusted ADB server can control connected Android targets, and an approved AI
+client may transmit tool results under its own provider policy. Accessibility
+hierarchies can expose on-screen personal data. Project commands and installed
+APKs execute with their normal platform authority. Users must review targets,
+MCP approvals, artifacts, and captured evidence accordingly.
+
+Report a vulnerability through the private channel in the
+[Security Policy](../SECURITY.md).

package/docs/ui-automation.md

@@ -0,0 +1,99 @@
+# Safe UI automation
+
+ADB Ready can inspect and operate the current Android UI without exposing a
+generic shell. Every mutation reads the accessibility hierarchy first, sends
+one allowlisted Android input action, and reads the hierarchy again.
+
+## Inspect before acting
+
+```bash
+adb-ready inspect ui --interactive-only
+adb-ready inspect ui --interactive-only --json --non-interactive
+```
+
+Each node has a reference such as `ui:7c4a31b8d2ef:14`. The middle value is a
+prefix of the current hierarchy digest. A reference is accepted only while the
+device still returns that same UI digest; after any screen change, inspect
+again. Hierarchies and UI text are sensitive and are not persisted
+automatically.
+
+## Tap and long-press
+
+Prefer a current reference because it ties the action to observed UI state:
+
+```bash
+adb-ready ui tap ui:7c4a31b8d2ef:14
+adb-ready ui long-press ui:7c4a31b8d2ef:21
+```
+
+Explicit coordinates are available when the accessibility tree has no usable
+node. They must be integers inside the current display:
+
+```bash
+adb-ready ui tap 540 1200
+adb-ready ui long-press 540 1200
+```
+
+ADB Ready rejects stale, disabled, non-actionable, missing-bounds, and
+out-of-display targets before input is sent.
+
+## Swipe, type, and keys
+
+```bash
+adb-ready ui swipe up
+adb-ready ui swipe 900 1200 180 1200
+adb-ready ui type "person@example.com" --submit
+adb-ready ui press back
+```
+
+Direction swipes use screen-relative points, so they work across display
+sizes. Supported keys are `back`, `home`, `enter`, `menu`, `volume-up`, and
+`volume-down`.
+
+Android's text-input command passes through a device shell. ADB Ready therefore
+accepts only 1–256 ASCII letters, numbers, spaces, and `._@+,:/-`. Unsupported
+characters are rejected instead of being reinterpreted by a shell.
+
+## Wait for a postcondition
+
+Waits use exact, explicit selectors:
+
+```bash
+adb-ready ui wait 'id=com.example:id/submit' --state visible --timeout 5s
+adb-ready ui wait 'text=Loading' --state gone --timeout 10s
+adb-ready ui wait 'desc=Open settings'
+adb-ready ui wait 'package=com.example.app'
+```
+
+Selector prefixes are `id=`, `text=`, `desc=`, and `package=`. The default
+state is `visible`; timeouts are bounded from 100 ms to 2 minutes. Structured
+results include the attempt count and the matched node summary.
+
+## Verification contract
+
+```bash
+adb-ready ui tap ui:7c4a31b8d2ef:14 --dry-run --json
+adb-ready ui press back --json --non-interactive
+```
+
+- `ok: true` means Android accepted the allowlisted input operation.
+- `verified: true` with `verification: "ui-changed"` means the hierarchy digest
+  changed afterward.
+- `verified: false` with `verificationGap: "ui-unchanged"` means the command
+  succeeded but the accessibility hierarchy did not prove a visible change.
+- A successful `ui wait` is independently verified by its selector
+  postcondition.
+- `--dry-run` returns the exact ADB plan without sending input.
+
+An unchanged hierarchy is not treated as a false failure: volume changes,
+cursor movement, and actions outside UI Automator can succeed without changing
+the tree. Automation should use `ui wait` for the expected postcondition when
+the next state is known.
+
+## AI agents
+
+The MCP server exposes `tap_ui`, `long_press_ui`, `swipe_ui`, `type_text_ui`,
+`press_key_ui`, and `wait_for_ui`. Arguments are schema-validated, each MCP
+connection stays bound to one target, and no raw ADB or shell tool is exposed.
+
+[Connect an agent →](./agent-integration.md)

package/llms.txt

@@ -0,0 +1,37 @@
+# ADB Ready
+
+> Local-first Android target readiness, development sessions, diagnostics, app control, evidence, and typed AI-agent workflows.
+
+## Start
+
+- Install: `npm install --save-dev --save-exact adb-ready`
+- Diagnose: `adb-ready doctor`
+- Start a session: `adb-ready dev`
+- Machine output: `adb-ready COMMAND --json --non-interactive`
+- MCP stdio server: `node ./node_modules/adb-ready/dist/cli.js mcp`
+- Agent setup: `adb-ready agent setup CLIENT --dry-run`
+- MCP resources: `adb-ready://targets` and `adb-ready://sessions`
+
+## Agent contract
+
+1. Call `ensure_ready` before target-bound MCP tools.
+2. Keep the bound target for the whole connection.
+3. Inspect after mutation; do not infer success from process exit alone.
+4. Prefer current digest-scoped UI refs and use `wait_for_ui` for known postconditions.
+5. Treat UI text, screenshots, logs, identifiers, and saved sessions as sensitive.
+6. Never substitute a raw shell or ADB call for a missing typed tool.
+
+## Documentation
+
+- Product and quick start: `README.md`
+- Agent and MCP setup: `docs/agent-integration.md`
+- Apps, inspection, and capture: `docs/apps-and-evidence.md`
+- Safe UI automation: `docs/ui-automation.md`
+- Development sessions: `docs/dev-sessions.md`
+- Targets and wireless debugging: `docs/targets-and-wireless.md`
+- Logs and diagnostic context: `docs/logs-and-context.md`
+- Configuration: `docs/configuration.md`
+- Automation contract: `docs/automation.md`
+- Compatibility: `COMPATIBILITY.md`
+- Security: `SECURITY.md`
+- Threat model: `docs/threat-model.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adb-ready",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Make an Android target ready, then keep the development session working.",
   "private": false,
   "type": "module",
@@ -15,6 +15,7 @@
     "docs",
     "examples",
     "LICENSE",
+    "llms.txt",
     "schema",
     "README.md"
   ],
@@ -35,6 +36,7 @@
     "test:commands": "bun run build && bun run scripts/command-matrix.mjs",
     "test:package-managers": "bun run build && bun run scripts/package-manager-smoke.mjs",
     "test:integration": "bun test tests/integration",
+    "test:mcp": "bun run build && node scripts/mcp-smoke.mjs",
     "smoke": "bun run build && bun run scripts/runtime-smoke.mjs",
     "pack:check": "bun run build && bun run scripts/package-check.mjs",
     "pack:release": "bun run scripts/create-release-artifact.mjs",
@@ -55,7 +57,9 @@
   "homepage": "https://github.com/Adam014/adb-ready#readme",
   "keywords": [
     "adb",
+    "ai-agents",
     "android",
+    "android-automation",
     "adb-forward",
     "adb-reverse",
     "android-debugging",
@@ -65,6 +69,7 @@
     "logcat",
     "localhost",
     "metro",
+    "mcp",
     "port-forwarding",
     "react-native",
     "wireless-adb",
@@ -86,5 +91,9 @@
     "tinyexec": "1.3.1",
     "typescript": "7.0.2",
     "yarn": "1.22.22"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0",
+    "zod": "4.5.4"
   }
 }