mobile-debug-mcp 0.33.0 → 0.35.0

package/AGENTS.md

@@ -21,12 +21,18 @@ instructions take precedence.
 Primary areas:
 
 - `src/server.ts` — runtime entrypoint
-- `src/server-core.ts` — tool registration and dispatch logic
+- `src/server-core.ts` and `src/server/` — MCP registration, capability handlers, schemas and definitions
 - `src/interact/` — tap, swipe, typing, waits, and interaction helpers
 - `src/observe/` — logs, screenshots, UI tree, fingerprints, snapshots
 - `src/manage/` — build, install, start, terminate, restart, reset-app-data
 - `src/system/` — environment and toolchain health checks
+- `src/debugger/` — debugger sessions, protocol and Java worker
 - `src/utils/` — shared helpers and platform-specific utility code
+- `src/contracts/` — shared input shapes and validation
+- `src/runtime/` — action results, traces and injectable clocks
+
+See [code structure and quality checks](docs/code-structure.md) for interaction
+subfolders, module ownership, dependency rules and enforced limits.
 
 ## First things an agent should know
 
@@ -61,7 +67,9 @@ If the task is about **reviewing an RFC or spec draft**, load `.agents/skills/sp
 
 ### Repository docs
 
-- `README.md` — high-level repo overview and commands
+- [README.md](README.md) — project overview and setup
+- [CONTRIBUTING.md](CONTRIBUTING.md) — development, validation, and documentation conventions
+- [Documentation index](docs/README.md) — user guides, designs, and benchmarks
 - `docs/specs/process.md` — required development workflow for all agents
 - `docs/tools/TOOLS.md` — tool documentation and contracts
 - `docs/CHANGELOG.md` — recent behavioral changes
@@ -91,7 +99,8 @@ This file is intentionally short. Keep task-specific guidance in `.agents/skills
 
 - `npm run test:unit` runs every automated unit test under `test/unit/...`
 - `npm run test:device` runs the automated device smoke checks under `test/device/automated/...`
-- `npm run verify` runs the default maintainer verification sequence: lint, build, unit tests, and agent-plugin consistency checks
+- `npm run lint` runs ESLint, structural/type limits and ArchUnitTS dependency checks
+- `npm run verify` runs lint, build, unit tests, and agent-plugin consistency checks
 - Manual and debug-oriented device scripts live under `test/device/manual/...` and are not part of the default test commands
 
 ## Utility Scripts

package/CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing
+
+Read the [development process](docs/specs/process.md) before planning, editing,
+or reviewing a change. Documentation and maintenance use its lightweight path;
+new capabilities and material contract changes require intent and specification
+approval. Automated contributors also start with [AGENTS.md](AGENTS.md).
+
+## Local development
+
+Use Node.js 22 or newer and npm. Platform tooling is needed only for the mobile
+operations you exercise; see [requirements and setup](README.md#requirements).
+
+```sh
+npm ci
+npm run build
+npm start
+```
+
+The TypeScript entrypoint is [src/server.ts](src/server.ts); registration and
+dispatch live in [src/server-core.ts](src/server-core.ts) and [src/server/](src/server/).
+The optional Java debugger bridge lives in
+[src/debugger/java/](src/debugger/java/). It is shipped as source and compiled
+on demand by the debugger; the TypeScript build does not compile Java.
+
+Platform operations are grouped under `src/manage/`, `src/interact/`,
+`src/observe/`, `src/debugger/`, and `src/system/`, with shared helpers in `src/utils/`.
+
+## Validation
+
+```sh
+npm run verify
+npm run test:device
+```
+
+`verify` runs lint, the TypeScript build, automated unit tests, and plugin
+consistency checks. Run applicable device checks for native or runtime changes;
+record which devices and behaviours actually ran. See the [process verification
+requirements](docs/specs/process.md#5-verify-and-report) for reporting failures,
+blocked checks, and unrun coverage. Documentation-only work needs diff, relative
+link/path, command, and consistency checks; builds and device tests are unnecessary.
+
+Load the [test-authoring skill](.agents/skills/test-authoring/SKILL.md) before
+changing tests, and the [MCP builder skill](.agents/skills/mcp-builder/SKILL.md)
+for installation or native toolchain work. Automated unit tests belong in
+`test/unit/`, automated device tests in `test/device/automated/`, and manual
+helpers in `test/device/manual/`.
+
+## Code structure
+
+Follow the [code structure and quality checks](docs/code-structure.md) for module
+ownership, enforced limits, and review of legacy exceptions. `npm run lint`
+includes ESLint, structural/type limits and ArchUnitTS dependency checks; CI runs
+the same checks. To diagnose a failure, run `npm run check:quality` or
+`npm run check:architecture` separately. Change a rule or reviewed exception only
+with the corresponding design rationale, rather than suppressing the failure.
+
+## Documentation conventions
+
+Use the [documentation index](docs/README.md) to place new material. Keep one
+page responsible for each contract and link to it from related guides. Keep
+setup in the root README, current tool contracts in `docs/tools/`, design records
+in `docs/specs/`, and measurements in `docs/benchmarks/`.
+
+Write guides around a reader's task: explain when to use the page, show a complete
+example where useful, and link to the likely next step. Keep agent usage
+workflows in the existing plugin skill and detailed contracts in the tool
+reference. Avoid duplicating the full navigation on every page; long references
+should offer task-based links to their own sections.
+
+Use one descriptive level-one heading per document and a logical heading
+hierarchy. Use relative links for repository files. Explain prerequisites before
+commands and distinguish examples, proposals, and verified behaviour. Keep
+historical approval and verification evidence dated; avoid chat-relative wording,
+agent handoff instructions, transient checkout status, and temporary log paths.
+Do not turn an earlier design decision into a current support or release claim.
+
+When usage changes, update the relevant tool reference, README, and changelog.
+When plugin metadata or its server pin changes, run `npm run sync:agent-plugin`
+and `npm run check:agent-plugin`; see the [plugin guide](agent-plugin/README.md).

package/README.md

@@ -1,49 +1,138 @@
 # Mobile Debug Tools
 [![npm version](https://img.shields.io/npm/v/mobile-debug-mcp.svg)](https://www.npmjs.com/package/mobile-debug-mcp)
 
-A minimal, secure MCP server for AI-assisted mobile development. Build, install, interact and inspect Android/iOS apps from an MCP-compatible client.
-
-> **Support:**
-> * KMP
-> * Android
-> * iOS
-> * Flutter - not tested
-> * React native - not tested
-
-Actions, screenshots, trees, and logs expose [correlated evidence](docs/tools/evidence.md)
-with explicit action references, phase timestamps, and conservative freshness.
+Build, install, control, and inspect Android and iOS apps from an MCP-compatible
+client. Mobile Debug Tools connects your client to local device toolchains and
+provides UI actions, screenshots, logs, state assertions, and optional Android
+performance capture and runtime debugging.
+
+Android, iOS, and Kotlin Multiplatform projects are supported. Flutter and React
+Native have not been tested. Platform and device limitations are described in the
+[tool reference](docs/tools/TOOLS.md).
+
+## What you can use it for
+
+Mobile Debug Tools gives a coding agent access to a running app, so development
+can include feedback from the device as well as the source code. For example:
+
+- **Build and test a feature.** After adding a settings screen, build and install
+  the app, navigate to it, and check that its controls display and behave as
+  expected. See [app management](docs/tools/manage.md) and
+  [UI interactions and assertions](docs/tools/interact.md).
+- **Check a bug fix or regression.** Reproduce a sequence such as opening a form,
+  entering text and submitting it, then verify the resulting screen or control
+  state. Repeat the journey after a code change to check the outcome.
+- **Review the UI on a device.** Capture screenshots to inspect layout and visual
+  changes, or inspect the UI hierarchy for exposed labels and control state.
+  See [observations](docs/tools/observe.md).
+- **Investigate an app failure.** Collect logs, screenshots and a debug snapshot
+  around a failing action to understand what happened. [Evidence
+  correlation](docs/tools/correlated-evidence.md) links observations to the action.
+- **Investigate Android performance or runtime behaviour.** Capture a
+  [Perfetto trace](docs/tools/system-traces.md) during a slow flow, or attach the
+  [runtime debugger](docs/tools/debugger.md) to a debuggable app to inspect
+  breakpoints, call stacks and locals.
+
+## How it works
+
+Your agent client launches a local MCP server and communicates with it over
+stdio. The server translates tool calls into operations through Android's ADB
+or Apple's Xcode tools and idb, then returns device observations and action
+results to the client. It connects to emulators, simulators and supported
+physical devices through those toolchains.
+
+The agent plugin bundles the server configuration and usage skill. The same
+server can also be configured directly in an MCP client or run from a source
+checkout. See [code structure](docs/code-structure.md#module-ownership) for the
+implementation's module boundaries.
+
+## Start here
+
+Choose how to connect:
+
+1. **[Agent plugin](#agent-plugin) — Recommended.** Installs the server configuration
+   and usage skill together for supported agent clients.
+2. **[Direct MCP configuration](#mcp-configuration).** Connect the published server
+   to another MCP-compatible client.
+3. **[Manual setup](#manual-setup).** Build and run a local source checkout.
+
+Check the [requirements](#requirements) for your platform before installing.
 
 ## Requirements
 
-- Node.js >= 18
+- Node.js >= 22
 - [Android SDK](https://developer.android.com/studio) (adb) for Android support
-- Xcode command-line tools for iOS support
-- [idb](https://github.com/facebook/idb) for iOS device support
+- Xcode and its command-line tools on macOS for iOS support
+- [idb](https://github.com/facebook/idb) for iOS UI inspection and interaction
+- JDK 17+ for optional [Android runtime debugging](docs/tools/debugger.md)
+
+## Agent plugin
+
+The preferred setup for supported agent clients is the
+[agent plugin](agent-plugin/README.md). It installs the MCP server configuration
+and usage skill together. Choose your client below.
+
+<details>
+
+<summary>Codex plugin</summary>
+
+Install the plugin from this repository's marketplace:
+
+```bash
+codex plugin marketplace add clivejefferies/mobile-debug-tools
+codex plugin add mobile-debug-tools@mobile-debug-tools
+```
+
+</details>
+
+<details>
+
+<summary>Claude Code plugin</summary>
+
+Install the plugin from this repository's marketplace:
+
+```bash
+claude plugin marketplace add clivejefferies/mobile-debug-tools
+claude plugin install mobile-debug-tools@mobile-debug-tools
+```
 
-## Environment Setup
+</details>
 
-The server discovers Android and iOS tools automatically from standard locations by default. Manual environment setup is still supported, but it should be treated as the fallback for non-standard installs, overrides, or reproducible pinned toolchains.
+<details>
 
-Use explicit paths when:
-- you have multiple SDKs installed
-- the tools live outside standard locations
-- you want deterministic setup across machines
-- automatic discovery does not find the expected binary
+<summary>Cursor plugin</summary>
+
+The repository includes a [Cursor marketplace](.cursor-plugin/marketplace.json).
+Teams and Enterprise admins can import the repository in Dashboard → Plugins & MCPs → Team
+Marketplaces. To test it locally, copy [agent-plugin](agent-plugin/) into
+`~/.cursor/plugins/local/mobile-debug-tools`, then reload Cursor.
 
-Leave the variables unset when:
-- the tools are already on `PATH`
-- the standard Android and Xcode locations are enough
+</details>
 
-Common environment variables:
-- `ADB_PATH`: explicit path to `adb`
-- `ANDROID_SDK_ROOT` or `ANDROID_HOME`: Android SDK root
-- `XCRUN_PATH`: explicit path to `xcrun`
-- `MCP_IDB_PATH` or `IDB_PATH`: explicit path to `idb`
-- `GRADLE_JAVA_HOME` or `JAVA_HOME`: Java home for Gradle-backed operations
+Start a new chat or session after installation so the client loads the skill
+and MCP tools. Each plugin launches the published npm package locally and needs
+Node.js 22 or newer and the platform toolchains for your device. If you also
+registered the MCP server directly, disable that registration to avoid
+duplicate tools.
 
-For normal use, call `get_system_status` first. It reports the detected host, Android, and iOS toolchain state so the client can decide whether automatic discovery is sufficient or whether explicit overrides are needed.
+## MCP configuration
 
-## MCP Configuration
+For a standard installation, add this stdio server to your client's MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "mobile-debug": {
+      "command": "npx",
+      "args": ["--yes", "mobile-debug-mcp"]
+    }
+  }
+}
+```
+
+If your client uses separate fields, choose stdio, set the command to `npx`, and
+supply `--yes` and `mobile-debug-mcp` as arguments. The examples below add optional
+path overrides; replace the placeholder paths before using them.
 
 <details>
 
@@ -56,7 +145,7 @@ Recommended when you want Android only, or when you want to make the Android too
   "mcpServers": {
     "mobile-debug": {
       "command": "npx",
-      "args": ["--yes","mobile-debug-mcp","server"],
+      "args": ["--yes", "mobile-debug-mcp"],
       "env": {
         "ADB_PATH": "/path/to/adb",
         "ANDROID_SDK_ROOT": "/path/to/android/sdk",
@@ -82,7 +171,7 @@ Recommended when you want iOS simulator or device support, or when `idb` lives i
   "mcpServers": {
     "mobile-debug": {
       "command": "npx",
-      "args": ["--yes","mobile-debug-mcp","server"],
+      "args": ["--yes", "mobile-debug-mcp"],
       "env": {
         "XCRUN_PATH": "/usr/bin/xcrun",
         "MCP_IDB_PATH": "/path/to/idb",
@@ -97,107 +186,52 @@ For iOS-only setups, `ADB_PATH` and `ANDROID_SDK_ROOT` are not required unless y
 
 </details>
 
-<details>
-
-<summary>Codex</summary>
-
-Use STDIO
-
-command: npx
-
-args: 
-* --yes
-* mobile-debug-mcp
-
-environment variables:
-* ADB_PATH: /path/to/adb
-* XCRUN_PATH: /usr/bin/xcrun
-* IDB_PATH: /path/to/idb
-* MCP_IDB_PATH: /path/to/idb
-* ANDROID_SDK_ROOT: /path/to/android/sdk
-* GRADLE_JAVA_HOME: /path/to/jdk
-* JAVA_HOME: /path/to/jdk
-
-If you are unsure whether the environment is configured correctly, run `get_system_status` first. It reports the detected host, Android, and iOS toolchain state in a structured form.
-
-</details>
-
-## Agent Plugin
-
-For clients that support Agent Plugins, the [agent-plugin](agent-plugin/README.md)
-package installs the MCP server configuration together with the existing usage
-skill. Direct npm/MCP configuration above remains supported.
-
-<details>
+## Manual setup
 
-<summary>Codex plugin</summary>
-
-Install the plugin from this repository's marketplace:
-
-```bash
-codex plugin marketplace add clivejefferies/mobile-debug-tools
-codex plugin add mobile-debug-tools@mobile-debug-tools
-```
-
-</details>
-
-<details>
-
-<summary>Claude Code plugin</summary>
-
-Install the plugin from this repository's marketplace:
+For a local source checkout, follow the [development setup](CONTRIBUTING.md#local-development)
+to install dependencies and build the server. Then configure your MCP client to
+launch that build over stdio:
 
-```bash
-claude plugin marketplace add clivejefferies/mobile-debug-tools
-claude plugin install mobile-debug-tools@mobile-debug-tools
+```json
+{
+  "mcpServers": {
+    "mobile-debug": {
+      "command": "node",
+      "args": ["/absolute/path/to/mobile-debug-mcp/dist/server.js"]
+    }
+  }
+}
 ```
 
-</details>
-
-<details>
-
-<summary>Cursor plugin</summary>
-
-The repository includes a [Cursor marketplace](.cursor-plugin/marketplace.json).
-Teams and Enterprise admins can import the repository in Dashboard → Plugins & MCPs → Team
-Marketplaces. To test it locally, copy [agent-plugin](agent-plugin/) into
-`~/.cursor/plugins/local/mobile-debug-tools`, then reload Cursor.
-
-</details>
-
-Start a new chat or session after installation so the client loads the skill
-and MCP tools. Each plugin launches the published npm package locally and needs
-Node.js 18 or newer and the platform toolchains for your device. If you also
-registered the MCP server directly, disable that registration to avoid
-duplicate tools.
+Replace the path with your checkout location. Rebuild after source changes.
 
-## Usage 
+## Environment setup
 
-Crash fixing:
-> I have a crash on the app, can you diagnose it, fix and validate using the mcp tools available
+The server discovers platform tools from standard locations and `PATH`. Leave
+path overrides unset for a standard installation. Use them for non-standard
+locations, multiple toolchains, or a pinned development environment.
 
-Feature building:
-> Add a button, hook into the repository and confirm API request successful
+| Variable | Purpose |
+| --- | --- |
+| `ADB_PATH` | Path to `adb`. |
+| `ANDROID_SDK_ROOT` or `ANDROID_HOME` | Android SDK root. |
+| `XCRUN_PATH` | Path to `xcrun`. |
+| `MCP_IDB_PATH` or `IDB_PATH` | Path to `idb`. |
+| `GRADLE_JAVA_HOME` or `JAVA_HOME` | Java home for Gradle-backed operations. |
 
-For actions that depend on a previously observed UI, use an optional
-`expectedState` from `get_ui_tree` on the same explicit device. The server checks
-a fresh snapshot immediately before input and returns `PRECONDITION_FAILED`
-with current UI evidence if the state changed. See
-[conditional actions](docs/tools/interact.md#conditional-actions) for supported
-tools, examples, and the limits of the check.
+After connecting the client, call `get_system_status` to check discovery and
+prerequisites. See [environment diagnostics](docs/tools/system.md) if a toolchain
+or device is unavailable.
 
-## Docs
+Android debugger errors include bounded, sanitized failure classifications and recovery guidance; see the [debugger guide](docs/tools/debugger.md#failure-diagnostics).
 
-Use `get_app_readiness` to observe loading, transitioning, settled, or unknown UI
-state, and `wait_for_app_ready` for a bounded wait. Existing UI waits can opt into
-`requireReady: true`. Results include evidence and uncertainty; see
-[app readiness](docs/tools/observe.md#app-readiness) for limits and examples.
+## Documentation
 
-- Tools: [Tools](docs/tools/TOOLS.md) — full input/response examples
-- Changelog: [Changelog](docs/CHANGELOG.md)
-- Agents: [AGENTS.md](AGENTS.md) — cold-start guidance for autonomous agents entering the public repo
-- Skills: [.agents/skills/README.md](.agents/skills/README.md) — portable Markdown skill packages for agents such as Copilot, Codex, Claude, or custom systems
+- [Documentation guide](docs/README.md) — find the guide for your task.
+- [Tool reference](docs/tools/TOOLS.md) — inputs, responses, examples, and shared principles.
+- [Contributing](CONTRIBUTING.md) — develop the server and run its checks.
+- [Changelog](docs/CHANGELOG.md) — release history.
 
 ## License
 
-Apache-2.0
+[Apache-2.0](LICENSE)

package/agent-plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-tools",
-  "version": "0.0.1",
+  "version": "0.0.4",
   "description": "Mobile app debugging tools and usage guidance for Android and iOS agents.",
   "author": {
     "name": "mobile-debug-tools contributors"
@@ -12,7 +12,7 @@
       "command": "npx",
       "args": [
         "--yes",
-        "mobile-debug-mcp@0.33.0",
+        "mobile-debug-mcp@0.35.0",
         "server"
       ]
     }

package/agent-plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-tools",
-  "version": "0.0.1",
+  "version": "0.0.4",
   "description": "Mobile app debugging tools and usage guidance for Android and iOS agents.",
   "repository": "https://github.com/clivejefferies/mobile-debug-tools",
   "license": "Apache-2.0",

package/agent-plugin/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-tools",
-  "version": "0.0.1",
+  "version": "0.0.4",
   "description": "Mobile app debugging tools and usage guidance for Android and iOS agents.",
   "author": {
     "name": "mobile-debug-tools contributors"
@@ -14,7 +14,7 @@
       "command": "npx",
       "args": [
         "--yes",
-        "mobile-debug-mcp@0.33.0",
+        "mobile-debug-mcp@0.35.0",
         "server"
       ],
       "cwd": "${CURSOR_PLUGIN_ROOT}"

package/agent-plugin/.mcp.json

@@ -5,7 +5,7 @@
       "command": "npx",
       "args": [
         "--yes",
-        "mobile-debug-mcp@0.33.0",
+        "mobile-debug-mcp@0.35.0",
         "server"
       ],
       "cwd": "${PLUGIN_DATA}"

package/agent-plugin/README.md

@@ -1,17 +1,22 @@
 # Mobile Debug MCP agent plugin
 
-Install this directory as an Agent Plugins package in a client that supports
-both skills and stdio MCP servers. It provides the existing mobile-debug MCP
+[Documentation](../docs/README.md) · [Client installation](../README.md#agent-plugin)
+
+Use the [client installation instructions](../README.md#agent-plugin) to install
+the plugin. It supports clients with
+both skills and stdio MCP servers. It provides the mobile-debug MCP
 usage skill and launches the published `mobile-debug-mcp` npm package. The
-plugin requires Node.js 18 or newer, `npx`, and the platform toolchains needed
+plugin requires Node.js 22 or newer, `npx`, and the platform toolchains needed
 for the devices you want to use. The first launch may need npm registry access.
 The MCP process starts in the client-managed plugin data directory so npm does
 not resolve the source checkout as a local package when installed from this repo.
 
+## Versions and maintenance
+
 The server is pinned to the published npm version in `mcp.json`. The plugin's
 `plugin.json` version advances independently for guidance-only releases; do not
-change the server pin to an unpublished npm version. The skill in
-`skills/mobile-debug-mcp/SKILL.md` is shared by all three clients. Run
+change the server pin to an unpublished npm version. The
+[usage skill](skills/mobile-debug-mcp/SKILL.md) is shared by all three clients. Run
 `npm run sync:agent-plugin` after updating the plugin metadata or server pin to
 refresh the thin Codex, Claude Code, and Cursor manifests in this directory.
 The three marketplaces all point here and share one skill.
@@ -19,11 +24,20 @@ The packaged directory uses the skill's declared name, `mobile-debug-mcp`, as
 required by Agent Skills. `npm run check:agent-plugin` checks the packaged
 copies and configuration.
 
+## Using the plugin
+
+After installation, the [usage skill](skills/mobile-debug-mcp/SKILL.md) guides the
+agent through device selection, observation, interaction and verification.
+
 The usage skill prefers screenshots for routine visual checks and reserves
 hierarchy reads for semantic selection and structured assertions. Assertion
 timeouts must cover a fresh tree read as well as the expected app transition.
+It also covers optional Android runtime debugging: capability checks, explicit
+process attach, source stops, bounded inspection, stepping and owned cleanup.
+Debugger guidance applies only when the connected server exposes those tools;
+updating the skill does not update the pinned server or installed plugin.
 
 If you already configured the MCP server directly in your agent client, disable
 that separate registration when enabling this plugin to avoid duplicate tools.
 The direct npm installation remains available without this plugin. See the
-repository README for platform toolchain setup and `get_system_status` guidance.
+[repository README](../README.md#environment-setup) for platform toolchain setup and `get_system_status` guidance.

package/agent-plugin/mcp.json

@@ -4,7 +4,7 @@
     "mobile-debug-mcp": {
       "type": "stdio",
       "command": "npx",
-      "args": ["--yes", "mobile-debug-mcp@0.33.0", "server"],
+      "args": ["--yes", "mobile-debug-mcp@0.35.0", "server"],
       "cwd": "${PLUGIN_DATA}"
     }
   }

package/agent-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "mobile-debug-tools",
-  "version": "0.0.1",
+  "version": "0.0.4",
   "description": "Mobile app debugging tools and usage guidance for Android and iOS agents.",
   "repository": "https://github.com/clivejefferies/mobile-debug-tools",
   "license": "Apache-2.0",