device-devtools-mcp 0.1.0

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "device-devtools-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for a phone: read a native app's screen as measurable elements, act on them, and refuse rather than guess",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ios",
+    "android",
+    "xcuitest",
+    "webdriveragent",
+    "uiautomator2",
+    "accessibility",
+    "devtools"
+  ],
+  "repository": "hung977/device-devtools-mcp",
+  "homepage": "https://github.com/hung977/device-devtools-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/hung977/device-devtools-mcp/issues"
+  },
+  "license": "MIT",
+  "mcpName": "io.github.hung977/device-devtools-mcp",
+  "type": "commonjs",
+  "bin": {
+    "device-devtools-mcp": "bin/device-devtools-mcp.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "files": [
+    "bin/",
+    "scripts/",
+    "integrations/",
+    "tests/",
+    "config.example.json",
+    "AGENTS.md",
+    "VERSION",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "scripts/selftest.sh && integrations/mcp/selftest.sh",
+    "prepack": "scripts/relink.sh --write",
+    "verify-npm-package": "node scripts/verify-npm-package.js"
+  }
+}

package/scripts/android/app.sh

@@ -0,0 +1,241 @@
+#!/usr/bin/env bash
+# app.sh — the app under test's lifecycle.
+#
+#   app.sh installed <id>   is some other app present?
+#   app.sh state
+#   app.sh launch | kill | relaunch
+#   app.sh reset
+#   app.sh install [apk]
+#   app.sh build
+#
+# `reset` means something stronger here than it does on iOS. Android has
+# `pm clear`, which discards the app's data and cache in place, so a reset is
+# one command and does not need a copy of the package to reinstall from. It is
+# still destructive: accounts are logged out and stored state is gone.
+#
+# `relaunch` restarts the process and keeps stored data. A test that navigates
+# somewhere and stops there passes once and fails on the second run, which reads
+# like flakiness and is not. Either end where you started, or use `reset`.
+#
+# --snapshot prints the screen this left behind and renumbers the uids, so the
+# read that would have been the next call is folded into this one. In a measured
+# session — log in, open Settings — twelve calls did the work and six of them
+# were snapshots taken only to find out what the previous action produced.
+#
+# exit 0  done
+# exit 1  usage error
+# exit 2  environment or configuration problem
+# exit 3  device unreachable — run doctor.sh
+# exit 4  the command ran but the app did not end up in the expected state
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+CMD="${1-}"
+case "$CMD" in
+  -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+esac
+[ -n "$CMD" ] || die "missing verb (usage: app.sh state|launch|kill|relaunch|reset|install|build)" 1
+shift
+
+# --snapshot IS ANSWERED ONCE, HERE, AND NOT BY EVERY VERB SEPARATELY.
+#
+# Each verb below counts its own arguments and refuses a stray one, which is
+# right and is also why a flag that applies to all of them cannot be added to
+# all of them: it would have to be subtracted from eight separate `[ $# -eq 0 ]`
+# guards. Taken out of the list up front, every verb sees exactly what it saw
+# before, and the screen is printed at the end of whichever one ran.
+DT_ARGV=()
+for a in ${@+"$@"}; do
+  case "$a" in
+    --snapshot) act_snapshot_on ;;
+    *) DT_ARGV+=("$a") ;;
+  esac
+done
+set -- ${DT_ARGV[@]+"${DT_ARGV[@]}"}
+
+load_config
+
+PKG="$(cfg '.app.package' '')"
+[ -n "$PKG" ] || die "app.package is not set in $DT_CONFIG — every verb here needs it" 2
+
+installed() {
+  pkg_installed "$PKG"
+}
+
+running() {
+  [ -n "$(adb_dev shell pidof "$PKG" 2>/dev/null | tr -d '\r ')" ]
+}
+
+# The focused window, as one line, tested afterwards rather than piped into a
+# second grep.
+#
+# `dumpsys | grep -m1 X | grep -q Y` looks equivalent and is not: `grep -q`
+# exits the moment it matches, `grep -m1` likewise, and the SIGPIPE that gives
+# the upstream command becomes a pipeline failure under `set -o pipefail`. The
+# function then reports "not in the foreground" for an app that is — measured
+# here as a launch that worked being reported as a launch that timed out.
+#
+# TWO QUESTIONS, NOT ONE. The focused window is the fast answer and it is wrong
+# for popups: open the overflow menu and the focus moves to a PopupWindow whose
+# name does not carry the package, so an app plainly on screen with its own menu
+# open reports as backgrounded. Found while walking the app, which recorded two taps as
+# "left the app" when they had opened a menu.
+#
+# So the resumed activity is asked as well. That is the activity Android has
+# actually resumed, which a popup belonging to the app does not change.
+foreground() {
+  local line
+  line="$(adb_dev shell dumpsys window 2>/dev/null | tr -d '\r' | awk '/mCurrentFocus/ { print; exit }')"
+  case "$line" in
+    *"$PKG"*) return 0 ;;
+  esac
+  line="$(adb_dev shell dumpsys activity activities 2>/dev/null | tr -d '\r' \
+          | awk '/topResumedActivity|mResumedActivity/ { print; exit }')"
+  case "$line" in
+    *"$PKG"*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# state_name — one of the four words every message here uses, so that "what is
+# the app doing" always reads the same way whichever verb reports it.
+state_name() {
+  if ! installed; then printf 'not installed'
+  elif foreground;    then printf 'foreground'
+  elif running;       then printf 'running in background'
+  else                     printf 'not running'
+  fi
+}
+
+# The launcher activity is resolved rather than configured. Hardcoding it in the
+# config means every launch breaks the day the app renames its entry point, and
+# the package manager already knows the answer.
+launcher_activity() {
+  local a
+  a="$(cfg '.app.activity' '')"
+  if [ -n "$a" ]; then printf '%s' "$a"; return 0; fi
+  a="$(adb_dev shell cmd package resolve-activity --brief "$PKG" 2>/dev/null \
+       | tr -d '\r' | grep -m1 "^$PKG/" || true)"
+  [ -n "$a" ] || die "cannot find a launcher activity for $PKG — set app.activity in $DT_CONFIG" 2
+  printf '%s' "$a"
+}
+
+# Waiting for a state rather than sleeping through it. Launch was measured
+# taking anywhere from under a second to several, and a fixed sleep is either
+# wasted time or a race.
+wait_for() {
+  local want="$1" limit="${2:-15}" i=0
+  while [ "$i" -lt "$((limit * 4))" ]; do
+    case "$want" in
+      up)   foreground && return 0 ;;
+      down) running    || return 0 ;;
+    esac
+    sleep 0.25
+    i=$((i + 1))
+  done
+  return 1
+}
+
+do_launch() {
+  local act
+  act="$(launcher_activity)"
+  adb_dev shell am start -W -n "$act" >/dev/null 2>&1 \
+    || die "am start $act failed — run $(as_cmd doctor)" 3
+  wait_for up || die "launched $PKG but it did not reach the foreground within 15s" 4
+  # The driver's session refers to the process that has just been replaced, so
+  # it is dropped rather than left to fail on the next verb with a message about
+  # sessions that says nothing about what actually happened.
+  ua2_drop_session
+}
+
+case "$CMD" in
+  # installed <package> — is some OTHER app on this device?
+  #
+  # Every other verb here acts on the app under test. This one answers about a
+  # package the test merely depends on: a browser for a deep link, a maps app
+  # for a hand-off. It exists because a CI image is not a phone, and a test that
+  # needs Chrome on an emulator that ships none should say so and be skipped
+  # rather than fail as though the product were broken.
+  #
+  # exit 4 for absent rather than exit 1, because "not there" is an answer.
+  installed)
+    [ $# -eq 1 ] || die "app.sh installed needs exactly one package name" 1
+    if pkg_installed "$1"; then
+      printf 'OK %s — installed\n' "$1"
+    else
+      die "$1 is not installed on $(device_serial)" 4
+    fi ;;
+
+  state)
+    [ $# -eq 0 ] || die "app.sh state takes no arguments" 1
+    printf 'OK %s — %s\n' "$PKG" "$(state_name)" ;;
+
+  launch)
+    [ $# -eq 0 ] || die "app.sh launch takes no arguments" 1
+    installed || die "$PKG is not installed — run $(as_cmd app install)" 4
+    do_launch
+    printf 'OK launched %s — %s\n' "$PKG" "$(state_name)" ;;
+
+  kill)
+    [ $# -eq 0 ] || die "app.sh kill takes no arguments" 1
+    adb_dev shell am force-stop "$PKG" >/dev/null 2>&1 \
+      || die "force-stop failed — run $(as_cmd doctor)" 3
+    ua2_drop_session
+    wait_for down 10 || die "force-stop returned but $PKG is still running" 4
+    printf 'OK killed %s — %s\n' "$PKG" "$(state_name)" ;;
+
+  relaunch)
+    [ $# -eq 0 ] || die "app.sh relaunch takes no arguments" 1
+    installed || die "$PKG is not installed — run $(as_cmd app install)" 4
+    adb_dev shell am force-stop "$PKG" >/dev/null 2>&1 || true
+    ua2_drop_session
+    wait_for down 10 || true
+    do_launch
+    printf 'OK relaunched %s — %s (stored data kept; use reset to discard it)\n' "$PKG" "$(state_name)" ;;
+
+  reset)
+    [ $# -eq 0 ] || die "app.sh reset takes no arguments" 1
+    installed || die "$PKG is not installed — run $(as_cmd app install)" 4
+    out="$(adb_dev shell pm clear "$PKG" 2>&1 | tr -d '\r')"
+    case "$out" in
+      *Success*) ;;
+      *) die "pm clear $PKG did not report success — $(first_line "$out")" 4 ;;
+    esac
+    ua2_drop_session
+    printf 'OK reset %s — data and cache cleared, app is %s\n' "$PKG" "$(state_name)" ;;
+
+  install)
+    [ $# -le 1 ] || die "app.sh install takes at most a path to an apk" 1
+    APK="${1-}"
+    [ -n "$APK" ] || APK="$(cfg '.app.apk' '')"
+    [ -n "$APK" ] || die "install needs an apk — pass a path or set app.apk in $DT_CONFIG" 2
+    APK="$(expand_path "$APK")"
+    [ -f "$APK" ] || die "no such apk: $APK" 2
+    # -r reinstalls over an existing copy and keeps data; -g grants the runtime
+    # permissions declared in the manifest, so a first run does not stop on a
+    # permission dialog that has nothing to do with the test.
+    out="$(adb_dev install -r -g "$APK" 2>&1 | tr -d '\r' | tail -3)"
+    case "$out" in
+      *Success*) ;;
+      *) die "install failed — $(printf '%s' "$out" | grep -m1 -i 'failure\|error' || printf '%s' "$out" | tail -1)" 2 ;;
+    esac
+    installed || die "install reported success but $PKG is not present" 4
+    ua2_drop_session
+    printf 'OK installed %s from %s\n' "$PKG" "$APK" ;;
+
+  build)
+    [ $# -eq 0 ] || die "app.sh build takes no arguments" 1
+    BUILD_CMD="$(cfg '.app.build_command' '')"
+    [ -n "$BUILD_CMD" ] || die "app.build_command is not set in $DT_CONFIG" 2
+    # The build's own output is the one place a wall of text is the right answer:
+    # a failing Gradle build is diagnosed from its log and nothing else. It goes
+    # to stderr so that stdout stays the one-line contract.
+    ( eval "$BUILD_CMD" ) >&2 || die "build failed — see the output above" 2
+    printf 'OK built %s\n' "$PKG" ;;
+
+  *)
+    die "unknown verb '$CMD' (usage: app.sh state|launch|kill|relaunch|reset|install|build)" 1 ;;
+esac
+
+# The screen the verb left behind, when it was asked for.
+act_snapshot_now

package/scripts/android/back.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# back.sh — go back one screen.
+#
+#   back.sh [--method nav|swipe]
+#
+# Android has a real system back action, so unlike iOS this is not a heuristic.
+# `nav` sends the system back event and is the default. `swipe` performs a
+# left-edge swipe, which is what gesture navigation sends and is worth having
+# for the apps that handle the gesture but swallow the key event.
+#
+# The flag exists on both platforms so a test case does not have to know which
+# one it is running on. What it selects differs, because the platforms differ,
+# and pretending otherwise is how a cross-platform abstraction starts lying.
+#
+# It then verifies that the screen actually changed. A back that does nothing is
+# worse than a back that fails: the test carries on believing it moved.
+#
+# --snapshot prints the screen this left behind and renumbers the uids, so the
+# read that would have been the next call is folded into this one. In a measured
+# session — log in, open Settings — twelve calls did the work and six of them
+# were snapshots taken only to find out what the previous action produced.
+#
+# exit 0  went back, and the screen changed
+# exit 1  usage error
+# exit 3  UiAutomator2 unreachable — run doctor.sh
+# exit 4  nothing to go back to, or the screen did not change
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+METHOD=nav
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --method)
+      [ $# -ge 2 ] || die "--method needs nav or swipe" 1
+      case "$2" in nav|swipe) METHOD="$2" ;; *) die "--method must be nav or swipe, got: $2" 1 ;; esac
+      shift 2 ;;
+    --snapshot) act_snapshot_on; shift ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) die "unknown argument: $1 (usage: back.sh [--method nav|swipe])" 1 ;;
+  esac
+done
+
+load_config
+
+src="$(fetch_source)"
+before="$(drv_fingerprint "$src")"
+act_before
+read -r WIN_W WIN_H <<< "$(window_size "$src")"
+
+if [ "$METHOD" = nav ]; then
+  resp="$(session_post '/back' '{}')"
+  err="$(session_error "$resp")"
+  [ -z "$err" ] || die "system back failed — $err" 3
+  used="system back"
+else
+  # Kept off x=0 exactly: some devices treat the very edge as a bezel touch and
+  # discard it. The travel ends past the middle so the gesture is unambiguous.
+  FY=$(( WIN_H / 2 ))
+  TX=$(( WIN_W * 60 / 100 ))
+  err="$(drv_drag 2 "$FY" "$TX" "$FY" 50 200 || true)"
+  [ -z "$err" ] || die "edge swipe failed — $err" 3
+  used="edge swipe from 2,$FY"
+fi
+
+after="$(drv_fingerprint "$(fetch_source)")"
+[ "$before" != "$after" ] \
+  || die "went back using the $used but the screen did not change — there may be nothing to go back to" 4
+
+# back already refuses when the screen did not move, so the SCREEN line here
+# is not the verdict — it is which screen you have arrived at, and what the app
+# said on the way.
+act_report BACK "$used"
+journal_append back "" "" "" "" "" 0 0 0 0 "$DT_ACT_HASH"

package/scripts/android/controls.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# controls.sh — the things on this screen you can actually act on.
+#
+#   controls.sh [--all]
+#
+# One line per interactive element, in find.sh's columns:
+#
+#   type | id | label | text | x,y,w,h
+#
+# This is usually a better first question than `tree`. A screen with 150
+# elements has perhaps a dozen you can tap, and those dozen are what a test is
+# written against; the rest is layout.
+#
+# Android answers this exactly: `clickable` is published on the element. iOS has
+# to infer it from the element's type, so the two adapters disagree slightly in
+# what they can promise, and each says which.
+#
+# --all also includes elements that are focusable or long-clickable but not
+# clickable — scroll containers, and controls that only respond to a hold.
+#
+# exit 0  at least one control
+# exit 1  usage error
+# exit 3  UiAutomator2 unreachable — run doctor.sh
+# exit 4  nothing interactive on screen
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+ALL=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --all) ALL=1; shift ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) die "unknown argument: $1 (usage: controls.sh [--all])" 1 ;;
+  esac
+done
+
+load_config
+src="$(fetch_source)"
+
+# Columns of the table: depth|class|id|label|text|x|y|w|h|vis|en|pw|click|hint
+rows="$(printf '%s' "$src" | awk -F'|' -v all="$ALL" '
+  $1 == "WINDOW" || $1 == "" { next }
+  $10 != 1 || $8 <= 0 || $9 <= 0 { next }
+  {
+    interactive = ($13 == 1)
+    # Text inputs are acted on by typing rather than by tapping, and a field
+    # that is not marked clickable is still very much a control.
+    if (!interactive && $2 ~ /Edit/) interactive = 1
+    if (!interactive && all == 1 && $11 == 1) interactive = 1
+    if (!interactive) next
+    printf "%s|%s|%s|%s|%s,%s,%s,%s\n", $2, $3, $4, $5, $6, $7, $8, $9
+  }')"
+
+[ -n "$rows" ] || die "nothing interactive on screen — is the app in the foreground?" 4
+
+printf '%s\n' "$rows" | awk -F'|' '{ printf "%s | %s | %s | %s | %s\n", $1, $2, $3, $4, $5 }'

package/scripts/android/devices.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# devices.sh — what is attached, one per line.
+#
+#   devices.sh [--ready]
+#
+# Output, pipe-separated so it parses without a JSON reader:
+#
+#   <serial> | <kind> | <name> | <state>
+#
+# kind is emulator or device. state is ready, unauthorized, offline or
+# no-permissions — anything other than ready means the device is attached but
+# cannot be driven, and saying which is the difference between a five-second fix
+# and an afternoon.
+#
+# --ready lists only the ones that can be driven.
+#
+# It reads `adb devices -l` and nothing else: no `adb shell` per device, because
+# this runs before anything is known to be healthy and a shell into a wedged
+# device is exactly where this would hang.
+#
+# exit 0  at least one device listed
+# exit 1  usage error
+# exit 2  adb is not installed
+# exit 4  nothing attached (or nothing ready, with --ready)
+
+source "$(dirname "${BASH_SOURCE[0]}")/lib.sh"
+
+READY_ONLY=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --ready) READY_ONLY=1; shift ;;
+    -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) die "unknown argument: $1 (usage: devices.sh [--ready])" 1 ;;
+  esac
+done
+
+load_config
+command -v adb >/dev/null 2>&1 || die "adb is not on PATH — see README.md" 2
+
+n=0
+while IFS= read -r line; do
+  [ -n "$line" ] || continue
+  case "$line" in "List of devices"*|"* daemon"*) continue ;; esac
+
+  serial="${line%% *}"
+  rest="${line#"$serial"}"
+  raw_state="$(printf '%s' "$rest" | awk '{print $1}')"
+
+  case "$raw_state" in
+    device)         state=ready ;;
+    unauthorized)   state=unauthorized ;;
+    offline)        state=offline ;;
+    no)             state=no-permissions ;;   # "no permissions; see [http://…]"
+    *)              state="$raw_state" ;;
+  esac
+
+  # The serial prefix is enough to tell an emulator apart here. Elsewhere the
+  # adapter also checks ro.kernel.qemu, because a renamed serial could mislead
+  # something that matters; a listing is not that.
+  case "$serial" in emulator-*) kind=emulator ;; *) kind=device ;; esac
+
+  name="$(printf '%s' "$rest" | tr ' ' '\n' | awk -F: '$1=="model" { print $2; exit }')"
+  [ -n "$name" ] || name="$serial"
+  name="$(printf '%s' "$name" | tr '_' ' ')"
+
+  [ "$READY_ONLY" -eq 0 ] || [ "$state" = ready ] || continue
+
+  printf '%s | %s | %s | %s\n' "$serial" "$kind" "$name" "$state"
+  n=$(( n + 1 ))
+done <<< "$(adb devices -l 2>/dev/null | tr -d '\r')"
+
+if [ "$n" -eq 0 ]; then
+  if [ "$READY_ONLY" -eq 1 ]; then
+    die "no device is ready — run $(as_cmd devices) without --ready to see what is attached" 4
+  fi
+  die "nothing attached — connect a device or start an emulator" 4
+fi