# Android DevTools MCP

An MCP server that lets an agent inspect and operate an already-running
Android emulator or physical device through ADB.

It provides a Chrome-DevTools-style workflow:

1. Capture a semantic UI snapshot or screenshot.
2. Identify a UI node.
3. Tap the revalidated node, type text, swipe, or press a key.
4. Inspect the resulting UI, foreground activity, and application logs.

The server talks to Android through ADB, not directly to QEMU. This keeps the
same interface usable with Android Studio emulators, headless emulators,
third-party QEMU frontends, and physical devices.

## Requirements

- Node.js 20 or later
- Android SDK Platform Tools with `adb` available on `PATH`, or `ADB_PATH`
  set to the executable
- A booted device visible in `adb devices -l`
- USB debugging authorization accepted for physical devices

The server attaches to existing devices. It does not start AVDs, install APKs,
or launch applications.

## Build and run

```powershell
npm install
npm run build
node dist/cli.js
```

The process uses MCP stdio, so its standard output is reserved for protocol
messages. Operational messages are written to standard error.

Example MCP client configuration for this checkout:

```json
{
  "mcpServers": {
    "android-devtools": {
      "command": "node",
      "args": [
        "<path-to-repo>/dist/cli.js"
      ],
      "env": {
        "ANDROID_SERIAL": "emulator-5554"
      }
    }
  }
}
```

`ANDROID_SERIAL` is optional when exactly one ready device is connected. Use
`ADB_PATH` when `adb` is not on `PATH`.

## Tools

| Tool | Purpose |
| --- | --- |
| `android_list_devices` | List ready, offline, and unauthorized ADB devices |
| `android_take_snapshot` | Return a compact semantic UI hierarchy |
| `android_take_screenshot` | Return the current display as PNG |
| `android_get_app_state` | Inspect foreground activity, process, and display state |
| `android_tap` | Tap coordinates or a revalidated snapshot node |
| `android_type_text` | Clear and type into the focused field |
| `android_swipe` | Perform a coordinate-based swipe |
| `android_press_key` | Send Android key events |
| `android_wait_for` | Wait for a selector and semantic state |
| `android_get_logs` | Return bounded logcat lines for an app's current PIDs |

Snapshot selectors use exact AND matching over resource ID, text, content
description, class, and state flags. Node IDs are scoped to one snapshot.
Before a node tap, the server captures a fresh hierarchy and verifies that the
same semantic node still occupies the same bounds. It returns a stale or
ambiguous-target error instead of tapping when that check fails.

## Verification

```powershell
npm run check
npm test
npm run build
```

There is also an opt-in smoke test for a disposable emulator. It sends the
Home key and reads the current launcher's logs:

```powershell
$env:ANDROID_MCP_TEST_SERIAL = "emulator-5554"
npm run test:device
```

## Limitations

- UI Automator exposes the accessibility/semantic tree, not Android Studio's
  private Layout Inspector data.
- Canvas-rendered interfaces, games, protected windows, and some WebViews may
  only be inspectable through screenshots and coordinates.
- Compose elements need usable semantics to appear as distinct nodes.
- Text entry intentionally accepts only ADB-safe ASCII: letters, numbers,
  spaces, and `.,_@+-/:=`. Unicode input requires an optional device-side
  input method or instrumentation component and is not part of this release.
- Network tracing, CPU/memory profiling, frame timing, AVD lifecycle, and APK
  management are outside the current black-box scope.