@metamask/device-mcp 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0]
+
+### Added
+
+- Add Hermes CDP tools (`hermes_cdp`, `hermes_targets`) for inspecting the React Native Hermes JS runtime via Metro ([#14](https://github.com/MetaMask/device-mcp/pull/14))
+
+### Changed
+
+- Make screenshot base64 encoding optional — `DeviceBackend.screenshot(outputPath, { encode })` accepts `{ encode: false }` to return only the file `path` and skip base64 encoding. `ScreenshotResult.data` is now optional; the default (`encode: true`) preserves existing behavior ([#15](https://github.com/MetaMask/device-mcp/pull/15))
+- The Appium backend now saves the screenshot to `outputPath` when one is provided (previously the argument was ignored) ([#15](https://github.com/MetaMask/device-mcp/pull/15))
+
+### Fixed
+
+- Fix `device_screenshot` failing on macOS — the captured PNG is now read in-process via `fs.readFile(path, 'base64')` instead of shelling out to the `base64` CLI, which is not portable (BSD `base64` on macOS rejects the GNU positional-file syntax that was used previously) ([#15](https://github.com/MetaMask/device-mcp/pull/15))
+
+### Security
+
+- Harden screenshot and screen-recording file writes across the ADB, IDB, and Appium backends — default captures now use a private per-process temporary directory (`0700`) with unpredictable names instead of the predictable `/tmp/device-mcp-*-<timestamp>` paths, files are written owner-only (`0600`), and a symlink at the destination is never followed. Caller-supplied output paths can be confined to a single directory via the new `DEVICE_MCP_OUTPUT_DIR` environment variable
+
+## [0.2.0]
+
+### Added
+
+- Add get element text and mapping to all backends ([#9](https://github.com/MetaMask/device-mcp/pull/9))
+- Add device selection tools ([#7](https://github.com/MetaMask/device-mcp/pull/7))
+
 ## [0.1.0]
 
 ### Added
@@ -16,19 +42,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Three backends: iOS (IDB), Android (ADB), Appium/BrowserStack (W3C WebDriver)
 - `.device-session` file for attaching to existing Appium sessions or creating new ones
 - 16 MCP tools: `device_snapshot`, `device_screenshot`, `device_info`, `device_tap_element`, `device_tap_coordinates`, `device_type`, `device_swipe`, `device_long_press`, `device_wait_for`, `device_app_state`, `device_open_app`, `device_close_app`, `device_press_button`, `device_dismiss_keyboard`, `device_dismiss_alert`, `device_logs`
-- Fuzzy element matching (case-insensitive, partial text)
-- Android tree-structured UI hierarchy parser (nested, not flat)
-- iOS `snapshotMaxDepth` and `mobile: source` fallback for deep hierarchies
-- Auto-detection of platform from `.device-session`, `DEVICE_ID`, or booted simulator/emulator
-- Runtime health check with actionable error messages for missing IDB/ADB
-- SKILL.md agent reference with core loop, common patterns, and platform differences
-- MetaMask module template compliance (ts-bridge, dual CJS/ESM, yarn constraints, CI workflows)
-
-### Fixed
-
-- fix: GH workflow release creation
-- chore: add additional tools
-- chore: add MetaMask Security Code Scanner workflow
 
-[Unreleased]: https://github.com/MetaMask/device-mcp/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/MetaMask/device-mcp/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/MetaMask/device-mcp/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/MetaMask/device-mcp/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/MetaMask/device-mcp/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,6 @@
+This project is licensed under either of
+
+- MIT license ([LICENSE.MIT](LICENSE.MIT))
+- Apache License, Version 2.0 ([LICENSE.APACHE2](LICENSE.APACHE2))
+
+at your option.

package/LICENSE.APACHE2

@@ -0,0 +1,201 @@
+                              Apache License
+                        Version 2.0, January 2004
+                     http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction,
+   and distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by
+   the copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all
+   other entities that control, are controlled by, or are under common
+   control with that entity. For the purposes of this definition,
+   "control" means (i) the power, direct or indirect, to cause the
+   direction or management of such entity, whether by contract or
+   otherwise, or (ii) ownership of fifty percent (50%) or more of the
+   outstanding shares, or (iii) beneficial ownership of such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity
+   exercising permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation
+   source, and configuration files.
+
+   "Object" form shall mean any form resulting from mechanical
+   transformation or translation of a Source form, including but
+   not limited to compiled object code, generated documentation,
+   and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or
+   Object form, made available under the License, as indicated by a
+   copyright notice that is included in or attached to the work
+   (an example is provided in the Appendix below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object
+   form, that is based on (or derived from) the Work and for which the
+   editorial revisions, annotations, elaborations, or other modifications
+   represent, as a whole, an original work of authorship. For the purposes
+   of this License, Derivative Works shall not include works that remain
+   separable from, or merely link (or bind by name) to the interfaces of,
+   the Work and Derivative Works thereof.
+
+   "Contribution" shall mean any work of authorship, including
+   the original version of the Work and any modifications or additions
+   to that Work or Derivative Works thereof, that is intentionally
+   submitted to Licensor for inclusion in the Work by the copyright owner
+   or by an individual or Legal Entity authorized to submit on behalf of
+   the copyright owner. For the purposes of this definition, "submitted"
+   means any form of electronic, verbal, or written communication sent
+   to the Licensor or its representatives, including but not limited to
+   communication on electronic mailing lists, source code control systems,
+   and issue tracking systems that are managed by, or on behalf of, the
+   Licensor for the purpose of discussing and improving the Work, but
+   excluding communication that is conspicuously marked or otherwise
+   designated in writing by the copyright owner as "Not a Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity
+   on behalf of whom a Contribution has been received by Licensor and
+   subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   copyright license to reproduce, prepare Derivative Works of,
+   publicly display, publicly perform, sublicense, and distribute the
+   Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+   this License, each Contributor hereby grants to You a perpetual,
+   worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+   (except as stated in this section) patent license to make, have made,
+   use, offer to sell, sell, import, and otherwise transfer the Work,
+   where such license applies only to those patent claims licensable
+   by such Contributor that are necessarily infringed by their
+   Contribution(s) alone or by combination of their Contribution(s)
+   with the Work to which such Contribution(s) was submitted. If You
+   institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work
+   or a Contribution incorporated within the Work constitutes direct
+   or contributory patent infringement, then any patent licenses
+   granted to You under this License for that Work shall terminate
+   as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+   Work or Derivative Works thereof in any medium, with or without
+   modifications, and in Source or Object form, provided that You
+   meet the following conditions:
+
+   (a) You must give any other recipients of the Work or
+       Derivative Works a copy of this License; and
+
+   (b) You must cause any modified files to carry prominent notices
+       stating that You changed the files; and
+
+   (c) You must retain, in the Source form of any Derivative Works
+       that You distribute, all copyright, patent, trademark, and
+       attribution notices from the Source form of the Work,
+       excluding those notices that do not pertain to any part of
+       the Derivative Works; and
+
+   (d) If the Work includes a "NOTICE" text file as part of its
+       distribution, then any Derivative Works that You distribute must
+       include a readable copy of the attribution notices contained
+       within such NOTICE file, excluding those notices that do not
+       pertain to any part of the Derivative Works, in at least one
+       of the following places: within a NOTICE text file distributed
+       as part of the Derivative Works; within the Source form or
+       documentation, if provided along with the Derivative Works; or,
+       within a display generated by the Derivative Works, if and
+       wherever such third-party notices normally appear. The contents
+       of the NOTICE file are for informational purposes only and
+       do not modify the License. You may add Your own attribution
+       notices within Derivative Works that You distribute, alongside
+       or as an addendum to the NOTICE text from the Work, provided
+       that such additional attribution notices cannot be construed
+       as modifying the License.
+
+   You may add Your own copyright statement to Your modifications and
+   may provide additional or different license terms and conditions
+   for use, reproduction, or distribution of Your modifications, or
+   for any such Derivative Works as a whole, provided Your use,
+   reproduction, and distribution of the Work otherwise complies with
+   the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+   To apply the Apache License to your work, attach the following
+   boilerplate notice, with the fields enclosed by brackets "[]"
+   replaced with your own identifying information. (Don't include
+   the brackets!)  The text should be enclosed in the appropriate
+   comment syntax for the file format. We also recommend that a
+   file or class name and description of purpose be included on the
+   same "printed page" as the copyright notice for easier
+   identification within third-party archives.
+
+Copyright 2025 MetaMask
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/LICENSE.MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MetaMask
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/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,9 +15,10 @@ 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
+- **Hermes CDP** (debugging the React Native JS runtime): uses the global `WebSocket` API. Node 22+ works out of the box; **Node 20 requires launching with `NODE_OPTIONS="--experimental-websocket"`**.
 
 ## Installation
 
@@ -41,6 +42,10 @@ 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
@@ -48,8 +53,21 @@ DEVICE_ID=<udid-or-serial> device-mcp
 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 +120,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                                                      |
@@ -133,6 +158,13 @@ The `.device-session` file is typically written by the test runner when it creat
 | `device_dismiss_keyboard` | Hide the on-screen keyboard after typing.              |
 | `device_dismiss_alert`    | Accept or dismiss a system alert or permission dialog. |
 
+### Hermes CDP
+
+| Tool             | Description                                                               |
+| ---------------- | ------------------------------------------------------------------------- |
+| `hermes_cdp`     | Speak raw Chrome DevTools Protocol to the React Native Hermes JS runtime. |
+| `hermes_targets` | List and diagnose the debuggable Hermes targets exposed by Metro.         |
+
 ### Element Identification
 
 Elements are identified by accessibility attributes — not internal refs. Matching is **fuzzy**: partial text and case-insensitive matches work. For example, querying `{ label: "Confirm" }` matches an element with label `"Confirm Transaction"`.
@@ -142,24 +174,71 @@ 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`              |
+
+## Hermes CDP
+
+Beyond native UI automation (idb/adb), the server can speak [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) (CDP) directly to the **React Native Hermes** JS runtime of a running app via Metro's inspector proxy. This lets an agent evaluate JavaScript, inspect runtime state, and diagnose the app's JS layer — complementing the native tools. Works on **both iOS and Android** (the transport is identical HTTP/WebSocket to Metro; only the default `appId` differs).
+
+This is _React Native Hermes CDP via Metro's inspector proxy_ — not WebView/browser CDP, and not the iOS WebKit Inspector Protocol. The app's Hermes runtime connects out to Metro; Metro exposes debuggable targets over `http://localhost:<metroPort>/json` and a per-target `webSocketDebuggerUrl`, and the server speaks real CDP over that WebSocket.
+
+### Prerequisites
+
+- A **DEBUG build with Metro running** on the inspector port. Release builds expose no inspector (`/json` returns `[]`).
+- The global `WebSocket` API: **Node 22+ works out of the box**; **Node 20 requires launching with `NODE_OPTIONS="--experimental-websocket"`** (see [Requirements](#requirements)).
+
+### Tools
+
+| Tool             | Description                                                               |
+| ---------------- | ------------------------------------------------------------------------- |
+| `hermes_cdp`     | Speak raw Chrome DevTools Protocol to the React Native Hermes JS runtime. |
+| `hermes_targets` | List and diagnose the debuggable Hermes targets exposed by Metro.         |
+
+Example `hermes_cdp` call: method `Runtime.evaluate` with params `{"expression":"1+1","returnByValue":true}` — the raw response nests the value at `result.result.value`.
+
+### Safety model
+
+A single Metro can have multiple apps/simulators registered, so executing CDP against the wrong target could run code in the wrong workspace. The server applies five fail-closed checks before executing:
+
+1. **Strict `appId` match** — only targets whose `appId` equals the expected id (no substring, no `targets[0]` fallback).
+2. **`HermesInternal` identity probe** — evaluates `HermesInternal.getRuntimeProperties()` before the user's method; non-Hermes targets fail closed.
+3. **Device pin** — pins `reactNative.logicalDeviceId` on first success; later calls are filtered to the pin.
+4. **Multi-device fail-closed** — multiple distinct logical devices (or any missing the field) fail closed rather than guess.
+5. **WebSocket URL validation** — protocol must be `ws:`, hostname must be loopback, and port must equal the resolved Metro port.
+
+The synthetic legacy page (`React Native Experimental (Improved Chrome Reloads)`) is filtered out, and destructive methods `Runtime.terminateExecution` and `Inspector.detached` are blocked.
+
+### Configuration
+
+- **appId** defaults to `io.metamask.MetaMask` (iOS) / `io.metamask` (Android). Override globally via the `HERMES_APP_ID` env var or per-call via the tool's `appId` param. Android users not on the default must pass `appId` or set `HERMES_APP_ID`; `hermes_targets` with `all: true` aids discovery of the real appId.
+- **Metro port** defaults to `8081`. Override via the `HERMES_METRO_PORT` env var or per-call via the tool's `metroPort` param.
+
+## File Output & Safety
+
+`device_screenshot` and `device_screen_recording` write image/video files to disk. These artifacts can contain sensitive on-screen content (seed phrases, private keys, balances), so writes are hardened:
+
+- **No `outputPath`** — the file is written into a private, per-process temporary directory (`0700`) with an unpredictable name, rather than a predictable `/tmp/device-mcp-*-<timestamp>` path (which is exposed to symlink and information-disclosure attacks on shared hosts).
+- **With `outputPath`** — the path is resolved to an absolute path and written owner-only (`0600`); a symlink already present at the destination is never followed.
+- **`DEVICE_MCP_OUTPUT_DIR`** — set this to confine every caller-supplied `outputPath` to a single directory. Any path resolving outside it is rejected. Leave it unset to allow writing to any path the server process can access.
 
 ## MCP Client Configuration
 
@@ -172,15 +251,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,19 +313,22 @@ 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 28 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 (28 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
 ```
 
@@ -255,7 +336,7 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
 ```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

package/dist/backends/adb-backend.cjs

@@ -16,9 +16,11 @@ exports.AdbBackend = void 0;
 exports.parseAndroidHierarchy = parseAndroidHierarchy;
 exports.parseNodeAttributes = parseNodeAttributes;
 const node_child_process_1 = require("node:child_process");
+const promises_1 = require("node:fs/promises");
 const alert_labels_js_1 = require("../utils/alert-labels.cjs");
 const element_js_1 = require("../utils/element.cjs");
 const exec_js_1 = require("../utils/exec.cjs");
+const output_path_js_1 = require("../utils/output-path.cjs");
 class AdbBackend {
     constructor(serial) {
         _AdbBackend_instances.add(this);
@@ -79,6 +81,15 @@ class AdbBackend {
             targetDescription: (0, element_js_1.describeElement)(element),
         };
     }
+    async getElementText(query) {
+        const snapshot = await this.snapshot();
+        const element = (0, element_js_1.findElement)(snapshot.hierarchy, query);
+        if (!element) {
+            throw new Error(`Element not found: ${JSON.stringify(query)}\n` +
+                'Use device_snapshot to inspect the current UI hierarchy.');
+        }
+        return element.label ?? element.value ?? '';
+    }
     async tapCoordinates(x, y) {
         await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_adb).call(this, ['shell', 'input', 'tap', String(x), String(y)]);
     }
@@ -149,8 +160,8 @@ class AdbBackend {
         }
         return { bundleId, state: 'Not Installed' };
     }
-    async screenshot(outputPath) {
-        const localPath = outputPath ?? `/tmp/device-mcp-screenshot-${Date.now()}.png`;
+    async screenshot(outputPath, options) {
+        const localPath = (0, output_path_js_1.resolveArtifactPath)(outputPath, 'screenshot');
         await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_adb).call(this, ['shell', 'screencap', '-p', '/sdcard/screenshot.png']);
         await (0, exec_js_1.execStrict)('adb', [
             '-s',
@@ -160,8 +171,12 @@ class AdbBackend {
             localPath,
         ]);
         await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_adb).call(this, ['shell', 'rm', '-f', '/sdcard/screenshot.png']);
-        const data = await (0, exec_js_1.execStrict)('base64', [localPath]);
-        return { data: data.trim(), format: 'png', path: localPath };
+        (0, output_path_js_1.hardenArtifactFile)(localPath);
+        if (options?.encode === false) {
+            return { data: undefined, format: 'png', path: localPath };
+        }
+        const data = await (0, promises_1.readFile)(localPath, 'base64');
+        return { data, format: 'png', path: localPath };
     }
     async openApp(bundleId) {
         await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_adb).call(this, [
@@ -311,7 +326,7 @@ class AdbBackend {
         if (__classPrivateFieldGet(this, _AdbBackend_recordingProcess, "f")) {
             throw new Error('Screen recording is already in progress');
         }
-        __classPrivateFieldSet(this, _AdbBackend_recordingPath, outputPath ?? `/tmp/device-mcp-recording-${Date.now()}.mp4`, "f");
+        __classPrivateFieldSet(this, _AdbBackend_recordingPath, (0, output_path_js_1.resolveArtifactPath)(outputPath, 'recording'), "f");
         __classPrivateFieldSet(this, _AdbBackend_recordingProcess, (0, node_child_process_1.spawn)('adb', [
             '-s',
             __classPrivateFieldGet(this, _AdbBackend_serial, "f"),
@@ -341,6 +356,7 @@ class AdbBackend {
             localPath,
         ]);
         await __classPrivateFieldGet(this, _AdbBackend_instances, "m", _AdbBackend_adb).call(this, ['shell', 'rm', '-f', __classPrivateFieldGet(this, _AdbBackend_recordingRemotePath, "f")]);
+        (0, output_path_js_1.hardenArtifactFile)(localPath);
         return localPath;
     }
 }