chore: add device selection tools (#7)

<!--
Thanks for your contribution! Take a moment to answer these questions so
that reviewers have the information they need to properly understand
your changes:

* What is the current state of things and why does it need to change?
* What is the solution your changes offer and how does it work?

Are there any issues or other links reviewers should consult to
understand this pull request better? For instance:

* Fixes #12345
* See: #67890
-->

Author: pnarayanaswamy

README.md

@@ -1,6 +1,6 @@
 # @metamask/device-mcp
 
-MCP server for mobile device interaction — iOS (IDB), Android (ADB), and remote devices (Appium/BrowserStack).
+MCP server for mobile device interaction — iOS (simctl + IDB), Android (ADB), and remote devices (Appium/BrowserStack).
 
 Provides device interaction tools for LLM agents to inspect UI state, interact with elements, capture evidence, and control app lifecycle. Works standalone for debugging or as part of the [self-healing test infrastructure](https://github.com/MetaMask/metamask-mobile) for MetaMask Mobile.
 
@@ -15,8 +15,8 @@ Provides device interaction tools for LLM agents to inspect UI state, interact w
 ## Requirements
 
 - **Node.js** `^20 || ^22 || >=24`
-- **iOS local**: [IDB](https://fbidb.io/) (`brew tap facebook/fb && brew install idb-companion && pip3 install fb-idb`)
-- **Android local**: ADB (Android SDK platform-tools)
+- **iOS local**: Xcode Command Line Tools (for `xcrun simctl`) + [IDB](https://fbidb.io/) for UI interaction (`brew tap facebook/fb && brew install idb-companion && pip3 install fb-idb`)
+- **Android local**: ADB (Android SDK platform-tools) — auto-discovered from `$ANDROID_HOME`, `$ANDROID_SDK_ROOT`, or `~/Library/Android/sdk`
 - **Remote/BrowserStack**: No local tools needed — connects via Appium W3C WebDriver HTTP
 
 ## Installation
@@ -41,15 +41,32 @@ device-mcp
 
 # Target a specific device
 DEVICE_ID=<udid-or-serial> device-mcp
+
+# Target a specific platform (useful in CI with one device per platform)
+DEVICE_PLATFORM=ios device-mcp
+DEVICE_PLATFORM=android device-mcp
 ```
 
 ### Backend Selection
 
 The server selects a backend in this order:
 
 1. **`.device-session` file** — if present in the working directory, connects via Appium (local or BrowserStack)
-2. **`DEVICE_ID` env var** — format determines platform (UUID = iOS, serial = Android)
-3. **Auto-detect** — checks for booted iOS simulator (IDB), then connected Android device (ADB)
+2. **`DEVICE_ID` + `DEVICE_PLATFORM`** — direct connect, no auto-detection
+3. **`DEVICE_ID` only** — platform inferred from format (UUID = iOS, serial/emulator-\* = Android)
+4. **`DEVICE_PLATFORM` only** — auto-detect first device of that platform
+5. **Nothing set, 1 device** — auto-connect
+6. **Nothing set, multiple devices** — returns device list, agent asks user to pick via `device_select_device`
+
+### Multi-Device Selection
+
+When multiple devices are connected and no `DEVICE_ID` is set, the server enters an "awaiting selection" state. Any tool call returns the list of available devices. Use `device_list_devices` to enumerate them and `device_select_device` to choose one.
+
+### Device Discovery
+
+- **iOS simulators** are discovered via `xcrun simctl list devices booted --json` — no IDB needed for discovery
+- **Android devices** are discovered via `adb devices` — the server probes `$ANDROID_HOME/platform-tools/adb`, `$ANDROID_SDK_ROOT/platform-tools/adb`, and `~/Library/Android/sdk/platform-tools/adb` when `adb` is not on `$PATH`
+- **IDB** is resolved from `$PATH`, `/usr/local/bin`, `/opt/homebrew/bin`, and `~/Library/Python/*/bin` (pip user installs)
 
 ### BrowserStack / Appium
 
@@ -102,6 +119,13 @@ The `.device-session` file is typically written by the test runner when it creat
 
 ## Tools
 
+### Device Management
+
+| Tool                   | Description                                                        |
+| ---------------------- | ------------------------------------------------------------------ |
+| `device_list_devices`  | List all connected devices and simulators/emulators.               |
+| `device_select_device` | Select a device for this session. Use after `device_list_devices`. |
+
 ### Inspection
 
 | Tool                | Description                                                      |
@@ -142,24 +166,26 @@ Elements are identified by accessibility attributes — not internal refs. Match
 
 ### Backend Implementation
 
-| Tool                      | iOS (IDB)               | Android (ADB)        | Appium (W3C WebDriver)        |
-| ------------------------- | ----------------------- | -------------------- | ----------------------------- |
-| `device_snapshot`         | `idb ui describe-all`   | `uiautomator dump`   | `mobile: source`              |
-| `device_screenshot`       | `idb screenshot`        | `screencap` + `pull` | `mobile: getScreenshot`       |
-| `device_info`             | `idb describe`          | `getprop`            | session capabilities          |
-| `device_tap_element`      | find + `idb ui tap`     | find + `input tap`   | find + W3C Actions            |
-| `device_tap_coordinates`  | `idb ui tap x y`        | `input tap x y`      | W3C Actions                   |
-| `device_type`             | `idb ui text`           | `input text`         | `findElement` + `sendKeys`    |
-| `device_swipe`            | `idb ui swipe`          | `input swipe`        | W3C Actions                   |
-| `device_long_press`       | `idb ui tap --duration` | `input swipe` (hold) | W3C Actions (pause)           |
-| `device_wait_for`         | poll snapshot           | poll snapshot        | poll snapshot                 |
-| `device_app_state`        | `idb list-apps`         | `dumpsys activity`   | `mobile: queryAppState`       |
-| `device_open_app`         | `idb launch`            | `monkey -p`          | `mobile: activateApp`         |
-| `device_close_app`        | `idb terminate`         | `am force-stop`      | `mobile: terminateApp`        |
-| `device_press_button`     | `idb ui key`            | `input keyevent`     | `mobile: pressButton/Key`     |
-| `device_dismiss_keyboard` | `idb ui key RETURN`     | `input keyevent 111` | `mobile: hideKeyboard`        |
-| `device_dismiss_alert`    | find button + tap       | find button + tap    | `mobile: accept/dismissAlert` |
-| `device_logs`             | `idb log`               | `logcat`             | `mobile: getLog`              |
+| Tool                      | iOS (IDB)                            | Android (ADB)        | Appium (W3C WebDriver)        |
+| ------------------------- | ------------------------------------ | -------------------- | ----------------------------- |
+| `device_snapshot`         | `idb ui describe-all`                | `uiautomator dump`   | `mobile: source`              |
+| `device_screenshot`       | `idb screenshot`                     | `screencap` + `pull` | `mobile: getScreenshot`       |
+| `device_info`             | `idb describe`                       | `getprop`            | session capabilities          |
+| `device_tap_element`      | find + `idb ui tap`                  | find + `input tap`   | find + W3C Actions            |
+| `device_tap_coordinates`  | `idb ui tap x y`                     | `input tap x y`      | W3C Actions                   |
+| `device_type`             | `idb ui text`                        | `input text`         | `findElement` + `sendKeys`    |
+| `device_swipe`            | `idb ui swipe`                       | `input swipe`        | W3C Actions                   |
+| `device_long_press`       | `idb ui tap --duration`              | `input swipe` (hold) | W3C Actions (pause)           |
+| `device_wait_for`         | poll snapshot                        | poll snapshot        | poll snapshot                 |
+| `device_list_devices`     | `xcrun simctl list`                  | `adb devices`        | N/A                           |
+| `device_select_device`    | select by UDID                       | select by serial     | N/A                           |
+| `device_app_state`        | `idb list-apps` / `simctl listapps`  | `dumpsys activity`   | `mobile: queryAppState`       |
+| `device_open_app`         | `idb launch` / `simctl launch`       | `monkey -p`          | `mobile: activateApp`         |
+| `device_close_app`        | `idb terminate` / `simctl terminate` | `am force-stop`      | `mobile: terminateApp`        |
+| `device_press_button`     | `idb ui key`                         | `input keyevent`     | `mobile: pressButton/Key`     |
+| `device_dismiss_keyboard` | `idb ui key RETURN`                  | `input keyevent 111` | `mobile: hideKeyboard`        |
+| `device_dismiss_alert`    | find button + tap                    | find button + tap    | `mobile: accept/dismissAlert` |
+| `device_logs`             | `idb log`                            | `logcat`             | `mobile: getLog`              |
 
 ## MCP Client Configuration
 
@@ -172,15 +198,14 @@ Add to `~/.config/opencode/opencode.json`:
   "mcp": {
     "device": {
       "type": "local",
-      "command": ["node", "/path/to/metamask-device-mcp/dist/index.js"],
-      "environment": {
-        "PATH": "/path/to/idb/bin:/usr/local/bin:/usr/bin:/bin"
-      }
+      "command": ["npx", "-y", "@metamask/device-mcp"]
     }
   }
 }
 ```
 
+IDB and ADB are auto-discovered from standard install locations. No `PATH` override needed unless tools are installed in custom directories.
+
 ### Cursor
 
 Add to `.cursor/mcp.json` in your project root:
@@ -235,27 +260,30 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 @metamask/device-mcp
 ├── src/
 │   ├── index.ts                # Entry point — lazy backend, stdio MCP server
-│   ├── server.ts               # MCP server — registers 16 tools
+│   ├── server.ts               # MCP server — registers 25 tools
 │   ├── backends/
-│   │   ├── types.ts            # DeviceBackend interface (16 operations)
-│   │   ├── idb-backend.ts      # iOS local — IDB commands + JSON parser
+│   │   ├── types.ts            # DeviceBackend interface
+│   │   ├── idb-backend.ts      # iOS local — IDB commands + simctl fallback
 │   │   ├── adb-backend.ts      # Android local — ADB commands + XML parser
 │   │   ├── appium-backend.ts   # Remote — Appium/BrowserStack via W3C WebDriver
 │   │   ├── webdriver-client.ts # Minimal W3C WebDriver HTTP client (fetch)
 │   │   ├── session-file.ts     # .device-session file reader
 │   │   └── index.ts            # createBackend() + createLazyBackend() factory
-│   ├── tools/                  # One file per MCP tool (16 tools)
+│   ├── tools/                  # One file per MCP tool (25 tools)
+│   │   ├── list-devices.ts     # device_list_devices — enumerate connected devices
+│   │   ├── select-device.ts    # device_select_device — choose device for session
+│   │   └── ...                 # snapshot, tap, type, swipe, etc.
 │   └── utils/
 │       ├── exec.ts             # Shell execution wrapper
-│       ├── platform.ts         # Platform auto-detection
+│       ├── platform.ts         # Device discovery (simctl, adb), path resolution
 │       └── element.ts          # Element search, matching, formatting
 ```
 
 ## Development
 
 ```bash
 yarn build        # Compile TypeScript
-yarn test         # Run tests (69 tests)
+yarn test         # Run tests
 yarn lint         # Lint everything (ESLint + Prettier + changelog)
 yarn lint:fix     # Auto-fix lint issues
 yarn dev          # Watch mode compilation

SKILL.md

@@ -1,6 +1,6 @@
 # @metamask/device-mcp — Agent Reference
 
-You interact with a mobile device (iOS simulator, Android emulator, or BrowserStack remote device) through the `device-mcp` MCP server. It exposes 16 tools for inspecting UI state, interacting with elements, capturing evidence, and controlling app lifecycle.
+You interact with a mobile device (iOS simulator, Android emulator, or BrowserStack remote device) through the `device-mcp` MCP server. It exposes 25 tools for device management, inspecting UI state, interacting with elements, capturing evidence, and controlling app lifecycle.
 
 ## When to Use This
 
@@ -10,6 +10,17 @@ You interact with a mobile device (iOS simulator, Android emulator, or BrowserSt
 - **Verifying UI changes** — check that a screen looks right after a code change
 - **Self-healing test recovery** — find alternative paths when an element is missing
 
+## Getting Started — Device Selection
+
+When multiple devices are connected, the server won't auto-pick one. Use the device management tools first:
+
+```
+device_list_devices         # See all connected simulators/emulators/devices
+device_select_device        # Pick the one you want to use
+```
+
+If only one device is connected, it's auto-selected. If `DEVICE_ID` is set, this step is skipped.
+
 ## Core Loop
 
 ```
@@ -29,6 +40,30 @@ device_snapshot             # 3. See the result — NEVER assume screen state
 
 ## Tools
 
+### device_list_devices (read-only)
+
+List all connected devices and simulators/emulators. Returns platform and device ID for each.
+
+**When:** Multiple devices are connected and you need to pick one. Checking what's available before starting.
+
+**Output format:**
+
+```
+Platform	Device ID
+ios	FACF3006-1FF8-482A-B6EF-58995E1DF1CB
+android	emulator-5554
+```
+
+### device_select_device
+
+Select a device to use for this session. Call `device_list_devices` first to see available devices.
+
+```json
+{ "deviceId": "FACF3006-1FF8-482A-B6EF-58995E1DF1CB" }
+```
+
+**When:** After `device_list_devices` shows multiple devices. The agent should present the list to the user and let them choose.
+
 ### device_snapshot (read-only)
 
 Capture the full UI accessibility hierarchy. Returns every visible element with type, label, identifier, value, frame coordinates, and enabled state.
@@ -204,6 +239,15 @@ Capture recent device logs with optional text filter.
 
 ## Common Patterns
 
+### Select a device when multiple are connected
+
+```
+device_list_devices                                     # see all devices
+# present list to user, get their choice
+device_select_device { "deviceId": "FACF3006-..." }     # select device
+device_snapshot                                          # start working
+```
+
 ### Navigate to a screen and verify
 
 ```
@@ -299,6 +343,10 @@ xcrun simctl boot "iPhone 16"
 emulator -avd Pixel_7_API_34
 ```
 
+iOS simulators are discovered via `xcrun simctl` (ships with Xcode). ADB is auto-discovered from `$ANDROID_HOME`, `$ANDROID_SDK_ROOT`, or `~/Library/Android/sdk`. IDB is auto-discovered from `$PATH`, `/usr/local/bin`, `/opt/homebrew/bin`, or `~/Library/Python/*/bin`.
+
+No `PATH` configuration is needed in the MCP client — tools are found automatically.
+
 ### Remote (BrowserStack/Appium)
 
 Create a `.device-session` file — see the README for the full schema. The test runner typically writes this when starting the Appium session.