device-devtools-mcp 0.1.0

package/bin/devicetools

@@ -0,0 +1,315 @@
+#!/usr/bin/env bash
+# devicetools — the one command.
+#
+#   devicetools <verb> [args...]     run a verb (snapshot, tap, type, logs, …)
+#   devicetools config set <k> <v>   edit config.json without opening it
+#   devicetools init [dir]           make a directory into a DeviceTools project
+#   devicetools version              what is installed, and what it is pointed at
+#   devicetools help                 the verbs
+#
+# WHY THIS FILE EXISTS
+#
+# Until now the only way to use DeviceTools was to cd into the checkout and call
+# ./scripts/<verb>.sh, which quietly made the tool and the work the same
+# directory: your tests lived in our repository. That is fine for developing
+# DeviceTools and wrong for using it. This entry point is the seam — it can be
+# symlinked onto PATH from anywhere, it resolves its own checkout through the
+# symlink, and the project it acts on is wherever you are standing.
+#
+# It adds no behaviour of its own beyond config/init/update/version. `devicetools tap` is
+# exactly `scripts/tap.sh`: same arguments, same output, same exit codes. A
+# wrapper that reinterpreted either would be a second contract to keep true.
+set -euo pipefail
+
+# Resolve this file through any chain of symlinks. macOS has no `readlink -f`
+# and no `realpath` in the base system, so the loop is the portable spelling.
+self="${BASH_SOURCE[0]}"
+while [ -L "$self" ]; do
+  dir="$(cd "$(dirname "$self")" && pwd)"
+  self="$(readlink "$self")"
+  case "$self" in /*) ;; *) self="$dir/$self" ;; esac
+done
+HOME_DIR="$(cd "$(dirname "$self")/.." && pwd)"
+
+# THE PROJECT FORMAT THIS BUILD UNDERSTANDS.
+#
+# A project is marked by a .devicetools file whose first line is
+# "devicetools-project <n>". The number is not decoration: a tool upgraded past a
+# project is the failure mode nobody sees coming — it reads a config or a
+# baseline in a shape it no longer means and does something plausible with it.
+# So the number is checked, and a project from the future is refused rather
+# than half-read.
+PROJECT_FORMAT=1
+
+# A package manager drops every symlink in scripts/, which is the whole verb
+# surface. Restored here for the same reason the npx entry point does it, and by
+# the same script — on a git checkout this finds nothing to do. See relink.sh.
+if [ ! -e "$HOME_DIR/scripts/tap.sh" ] && [ -f "$HOME_DIR/scripts/links.tsv" ]; then
+  "$HOME_DIR/scripts/relink.sh" >&2 || true
+fi
+
+# So a verb can spell its own remedies back the way you called it: `devicetools
+# doctor --recover` when you typed `devicetools`, `scripts/doctor.sh --recover`
+# when you ran the script. A message naming a path that is not how the reader
+# invokes anything is a message they have to translate.
+#
+# Set here rather than beside the exec at the bottom, because `init` execs from
+# a case arm above it and was printing `scripts/doctor.sh` at somebody who had
+# typed `devicetools`.
+export DT_CLI=1
+
+project_dir() {
+  if [ -n "${DEVICETOOLS_PROJECT:-}" ]; then printf '%s' "$DEVICETOOLS_PROJECT"; return 0; fi
+  d="$PWD"
+  while [ -n "$d" ] && [ "$d" != / ]; do
+    [ -f "$d/.devicetools" ] && { printf '%s' "$d"; return 0; }
+    d="$(dirname "$d")"
+  done
+  return 1
+}
+
+# project_format_check <dir> — prints a line, returns non-zero when unusable.
+project_format_check() {
+  local f="$1/.devicetools" n
+  [ -f "$f" ] || { printf 'PROJECT  ?  no .devicetools in %s\n' "$1"; return 1; }
+  n="$(awk '{ print $2; exit }' "$f" 2>/dev/null)"
+  case "$n" in
+    ''|*[!0-9]*) printf 'PROJECT  ?  %s does not name a format version — expected "devicetools-project %s"\n' "$f" "$PROJECT_FORMAT"; return 1 ;;
+  esac
+  if [ "$n" -gt "$PROJECT_FORMAT" ]; then
+    printf 'PROJECT  !  format %s, and this build understands %s — upgrade DeviceTools, or use the version that wrote it\n' "$n" "$PROJECT_FORMAT"
+    return 1
+  fi
+  printf 'PROJECT  ok format %s\n' "$n"
+  return 0
+}
+
+usage() {
+  cat <<'EOF'
+usage: devicetools <command> [args...]
+
+  see                 snapshot, screenshot, measure, tree, controls, find
+  act                 tap, type, swipe, scroll, back, key, open, wait
+  several at once     run, flow
+  the device          devices, doctor, app, logs, settings, permission
+  come back           waypoint
+
+  setup               install the driver this platform needs
+  config              print, or: config get <key> | set <key> <value>
+  init [dir]          make a directory into a DeviceTools project
+  update [--check]    pull a newer DeviceTools, and check the project still fits
+  version             print the version, the checkout and the project
+  help                this
+
+Every verb is `devicetools <verb> --help`. Exit codes are uniform:
+0 ok, 1 usage, 2 environment, 3 connectivity, 4 the screen did not satisfy.
+EOF
+}
+
+cmd="${1-}"
+[ $# -gt 0 ] && shift || true
+
+case "$cmd" in
+  ""|help|-h|--help) usage; [ -n "$cmd" ] && exit 0 || exit 1 ;;
+
+  version|--version)
+    # Sourcing lib.sh for this would require a config, and "what version is
+    # this" must answer on a machine that has not been configured yet.
+    v="$(cat "$HOME_DIR/VERSION" 2>/dev/null || printf 'unknown')"
+    c="$(git -C "$HOME_DIR" rev-parse --short HEAD 2>/dev/null || true)"
+    [ -n "$c" ] && v="$v+$c"
+    printf 'VERSION  %s\n' "$v"
+    printf 'HOME     %s\n' "$HOME_DIR"
+    if [ -n "${DEVICETOOLS_PROJECT:-}" ]; then
+      printf 'PROJECT  %s (DEVICETOOLS_PROJECT)\n' "$DEVICETOOLS_PROJECT"
+    else
+      d="$PWD"; p=""
+      while [ -n "$d" ] && [ "$d" != / ]; do
+        [ -f "$d/.devicetools" ] && { p="$d"; break; }
+        d="$(dirname "$d")"
+      done
+      if [ -n "$p" ]; then printf 'PROJECT  %s\n' "$p"
+      else printf 'PROJECT  %s (no .devicetools found — the checkout is the project)\n' "$HOME_DIR"; fi
+    fi
+    printf 'CONFIG   %s\n' "${DEVICETOOLS_CONFIG:-<project>/config.json}"
+    exit 0
+    ;;
+
+  init)
+    # ONE IMPLEMENTATION, IN scripts/. It used to live here as a `case` arm,
+    # which made it invisible over MCP — `flow save` told an agent to run `init`
+    # in its repository and there was no tool that could. Every verb in scripts/
+    # is reachable from both sides; a branch of this wrapper is reachable from
+    # one.
+    exec "$HOME_DIR/scripts/init.sh" "$@"
+    ;;
+
+  update|--update)
+    # `git pull` on a directory somebody else owns, so it says what it is about
+    # to do and refuses when the answer is not obvious.
+    check_only=0
+    [ "${1-}" = --check ] && check_only=1
+    git -C "$HOME_DIR" rev-parse --git-dir >/dev/null 2>&1 \
+      || { printf 'not a git checkout: %s — update it the way you installed it\n' "$HOME_DIR" >&2; exit 2; }
+
+    before="$(git -C "$HOME_DIR" rev-parse --short HEAD 2>/dev/null || printf '?')"
+    dirty="$(git -C "$HOME_DIR" status --porcelain 2>/dev/null | head -5)"
+    branch="$(git -C "$HOME_DIR" rev-parse --abbrev-ref HEAD 2>/dev/null || printf '?')"
+
+    git -C "$HOME_DIR" fetch --quiet 2>/dev/null || { printf 'could not reach the remote\n' >&2; exit 2; }
+    behind="$(git -C "$HOME_DIR" rev-list --count "HEAD..@{u}" 2>/dev/null || printf 0)"
+    ahead="$(git -C "$HOME_DIR" rev-list --count "@{u}..HEAD" 2>/dev/null || printf 0)"
+
+    printf 'VERSION  %s at %s on %s\n' "$(cat "$HOME_DIR/VERSION" 2>/dev/null || printf '?')" "$before" "$branch"
+    if [ "${behind:-0}" -eq 0 ]; then
+      printf 'UPDATE   none — already at the latest commit on %s\n' "$branch"
+      exit 0
+    fi
+    printf 'UPDATE   %s commit(s) behind\n' "$behind"
+    git -C "$HOME_DIR" log --oneline "HEAD..@{u}" 2>/dev/null | head -10 | sed 's/^/  /'
+    [ "${ahead:-0}" -gt 0 ] && printf 'NOTE     and %s commit(s) ahead — a pull here would merge, not fast-forward\n' "$ahead"
+
+    if [ "$check_only" -eq 1 ]; then
+      printf 'NEXT     devicetools update\n'
+      exit 0
+    fi
+    # LOCAL EDITS ARE SOMEBODY'S WORK. THEY ARE NOT AN OBSTACLE TO ROUTE AROUND.
+    if [ -n "$dirty" ]; then
+      printf '%s\n' "$dirty" | sed 's/^/  /'
+      printf 'refusing to pull over uncommitted changes in %s — commit or stash them first\n' "$HOME_DIR" >&2
+      exit 2
+    fi
+    git -C "$HOME_DIR" pull --ff-only --quiet 2>/dev/null \
+      || { printf 'pull failed — resolve it in %s by hand\n' "$HOME_DIR" >&2; exit 2; }
+    printf 'UPDATE   %s -> %s\n' "$before" "$(git -C "$HOME_DIR" rev-parse --short HEAD)"
+
+    # An upgraded tool against an older project is the case worth checking, and
+    # it is checked here rather than left for the first verb to trip over.
+    if p="$(project_dir)"; then project_format_check "$p" || exit 2; fi
+    exit 0
+    ;;
+
+  config)
+    # Read and edit config.json without opening it.
+    #
+    #   config                    print it
+    #   config get <key>          one value
+    #   config set <key> <value>  write one value
+    #
+    # A key is a dotted path: app.bundle_id, device.udid, wda.team_id. One way to
+    # write a value, not two — a shorthand for the app id would be a second
+    # spelling of `set` that has to stay in step with it forever.
+    #
+    # NOT A VERB, so not an MCP tool. Verbs drive a device; this rewrites the
+    # file that says which device. An agent that can repoint the tool at another
+    # app mid-session can also do it by accident, and the next twenty actions
+    # would land on the wrong app while every one of them reported success.
+    command -v jq >/dev/null 2>&1 || { printf 'jq is required\n' >&2; exit 2; }
+
+    if [ -n "${DEVICETOOLS_CONFIG:-}" ]; then
+      cfile="$DEVICETOOLS_CONFIG"
+    elif p="$(project_dir)"; then
+      cfile="$p/config.json"
+    else
+      cfile="$HOME_DIR/config.json"
+    fi
+    [ -f "$cfile" ] || { printf 'no config at %s\n' "$cfile" >&2; exit 2; }
+    jq -e . "$cfile" >/dev/null 2>&1 || { printf '%s is not valid JSON\n' "$cfile" >&2; exit 2; }
+
+    # A dotted key as a jq path expression. Refused rather than escaped when it
+    # holds anything but names and dots: the value goes into a jq program, and a
+    # key is not the place to accept punctuation.
+    jqpath() {
+      case "$1" in
+        ""|*[!a-zA-Z0-9_.]*|.*|*.) printf 'bad key: %s (use dotted names, e.g. app.bundle_id)\n' "$1" >&2; return 1 ;;
+      esac
+      printf '.%s' "$1"
+    }
+
+    action="${1-}"
+    [ $# -gt 0 ] && shift || true
+
+    case "$action" in
+      ""|show) jq . "$cfile"; exit 0 ;;
+
+      get)
+        [ $# -ge 1 ] || { printf 'usage: devicetools config get <key>\n' >&2; exit 1; }
+        path="$(jqpath "$1")" || exit 1
+        jq -r "$path // empty" "$cfile"
+        exit 0
+        ;;
+
+      set)
+        [ $# -ge 2 ] || { printf 'usage: devicetools config set <key> <value>\n' >&2; exit 1; }
+        key="$1"; val="$2"
+        path="$(jqpath "$key")" || exit 1
+
+        # A KEY THAT DOES NOT EXIST YET IS A TYPO UNTIL PROVEN OTHERWISE.
+        #
+        # `set app.bundleid` would otherwise write a key nothing reads, report
+        # success, and leave someone looking at the device wondering why the
+        # app never changed. --new is how you say you meant it.
+        if [ "$(jq -r "$path | type" "$cfile" 2>/dev/null || printf 'null')" = null ] \
+           && [ "${3-}" != --new ] && [ "${2-}" != --new ]; then
+          printf 'no such key: %s\n' "$key" >&2
+          printf 'existing keys under %s:\n' "${key%.*}" >&2
+          jq -r --arg p "${key%.*}" '
+            getpath($p | split(".")) // {} | if type == "object" then keys[] else empty end
+          ' "$cfile" 2>/dev/null | sed 's/^/  /' >&2
+          printf "pass --new to create it anyway\n" >&2
+          exit 1
+        fi
+
+        # The existing value decides the type of the new one. Writing "30" as a
+        # string where a number lived produces a config that still parses and a
+        # comparison that quietly stops working.
+        was="$(jq -r "$path | type" "$cfile" 2>/dev/null || printf 'null')"
+        case "$was" in
+          number) case "$val" in ''|*[!0-9]*) printf '%s holds a number, got: %s\n' "$key" "$val" >&2; exit 1 ;; esac
+                  new="$(jq --argjson v "$val" "setpath(\"$key\" | split(\".\"); \$v)" "$cfile")" ;;
+          boolean) case "$val" in true|false) ;; *) printf '%s holds a boolean, got: %s\n' "$key" "$val" >&2; exit 1 ;; esac
+                  new="$(jq --argjson v "$val" "setpath(\"$key\" | split(\".\"); \$v)" "$cfile")" ;;
+          *)      new="$(jq --arg v "$val" "setpath(\"$key\" | split(\".\"); \$v)" "$cfile")" ;;
+        esac
+        [ -n "$new" ] || { printf 'could not set %s\n' "$key" >&2; exit 2; }
+
+        # Written beside the original and moved into place, so an interrupted
+        # write cannot leave a half-file where the config was.
+        tmp="$cfile.tmp.$$"
+        printf '%s\n' "$new" > "$tmp" || { rm -f "$tmp"; printf 'could not write %s\n' "$tmp" >&2; exit 2; }
+        mv "$tmp" "$cfile" || { rm -f "$tmp"; printf 'could not replace %s\n' "$cfile" >&2; exit 2; }
+        printf '%-24s %s\n' "$key" "$(jq -r "$path" "$cfile")"
+
+        # BOTH APP KEYS EXIST IN EVERY CONFIG, AND ONLY ONE OF THEM IS READ.
+        #
+        # So `set app.package` against an iOS config succeeds, prints the value
+        # back, and changes nothing about which app gets driven — the "no such
+        # key" guard cannot catch it, because the key is there. Said out loud
+        # here, while the person who typed it is still looking.
+        plat="$(jq -r '.platform // "ios"' "$cfile")"
+        case "$plat:$key" in
+          android:app.bundle_id) printf 'note: platform is android, which reads app.package\n' >&2 ;;
+          ios:app.package)       printf 'note: platform is ios, which reads app.bundle_id\n' >&2 ;;
+        esac
+        exit 0
+        ;;
+
+      *) printf 'usage: devicetools config [get <key> | set <key> <value>]\n' >&2; exit 1 ;;
+    esac
+    ;;
+esac
+
+# Everything else is a verb. Reject anything that is not one by name rather than
+# letting a typo become a path.
+case "$cmd" in
+  */*|.*|-*) printf 'not a verb: %s\n' "$cmd" >&2; exit 1 ;;
+esac
+
+target="$HOME_DIR/scripts/${cmd%.sh}.sh"
+if [ ! -x "$target" ]; then
+  printf 'no such command: %s\n' "$cmd" >&2
+  printf "run 'devicetools help' for the list\n" >&2
+  exit 1
+fi
+
+exec "$target" "$@"

package/config.example.json

@@ -0,0 +1,63 @@
+{
+  "_comment": "Copy to config.json and edit. `platform` selects which adapter runs; the device, wda and ua2 blocks belonging to the other platform are ignored. `device.kind` is auto, device, simulator (iOS) or emulator (Android).",
+  "platform": "ios",
+  "device": {
+    "udid": "00000000-0000000000000000",
+    "name": "iPhone",
+    "ios_version": "15.1.1",
+    "serial": "emulator-5554",
+    "kind": "auto"
+  },
+  "wda": {
+    "project": "~/tools/WebDriverAgent/WebDriverAgent.xcodeproj",
+    "scheme": "WebDriverAgentRunner",
+    "derived_data": "~/tools/wda-derived",
+    "team_id": "XXXXXXXXXX",
+    "bundle_id_prefix": "com.example",
+    "runner_bundle_id": "com.example.WebDriverAgentRunner.xctrunner",
+    "host": "127.0.0.1",
+    "local_port": 8100,
+    "device_port": 8100
+  },
+  "ua2": {
+    "version": "v10.6.2",
+    "host": "127.0.0.1",
+    "local_port": 6790,
+    "device_port": 6790,
+    "apk_dir": "~/tools/uiautomator2"
+  },
+  "app": {
+    "bundle_id": "",
+    "project": "",
+    "workspace": "",
+    "scheme": "",
+    "configuration": "Debug",
+    "build_command": "",
+    "package": "",
+    "activity": "",
+    "apk": ""
+  },
+  "paths": {
+    "runs_dir": ".runs",
+    "state_dir": ".state",
+    "flows_dir": "flows"
+  },
+  "tree": {
+    "max_lines": 60
+  },
+  "timeouts": {
+    "http_seconds": 10,
+    "wait_seconds": 15,
+    "poll_ms": 400,
+    "app_seconds": 90
+  },
+  "logs": {
+    "max_lines": 50,
+    "max_lines_kept": 200000,
+    "network_pattern": "(^|[^A-Za-z0-9_])(GET|POST|PUT|PATCH|DELETE)[[:space:]]+(https?://|/)|HTTP/[0-9]",
+    "exclude_subsystems": "AXRuntime|UIAccessibility|AccessibilityUtilities|CoreMotion|UIKitCore|RunningBoardServices|CoreFoundation|CoreBrightness|CoreBluetooth|CoreTelephony|WirelessProximity|BackBoardHIDEventProcessors|MediaSafetyNet|WPDaemon|libsystem_network"
+  },
+  "scroll": {
+    "max_swipes": 15
+  }
+}

package/integrations/agent-pointer.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# agent-pointer.sh — put a pointer to DeviceTools into another repository.
+#
+#   integrations/agent-pointer.sh <target-repo> [claude|cursor|gemini|codex|mcp|all] [--force]
+#
+# Each pointer says where AGENTS.md is and nothing else, so there is nothing
+# here that can drift out of date with the contract. {{DEVICETOOLS}} is replaced
+# with this checkout's absolute path, so the pointer resolves from anywhere.
+#
+# `mcp` is deliberately not part of `all`. A host that can run shell commands
+# already has everything through the pointer; adding the MCP server as well
+# gives it two ways to do the same thing and a decision to make on every step.
+# Install it for the hosts that have no shell.
+#
+# An existing file is never overwritten without --force: the Codex pointer lands
+# on AGENTS.md, and a repository may well already have one of its own.
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$HERE/.." && pwd)"
+TARGET="${1-}"; HOST="${2-all}"; FORCE=0
+[ "${3-}" = --force ] && FORCE=1
+[ "$HOST" = --force ] && { HOST=all; FORCE=1; }
+
+usage() { echo "usage: agent-pointer.sh <target-repo> [claude|cursor|gemini|codex|mcp|all] [--force]" >&2; exit 1; }
+[ -n "$TARGET" ] || usage
+[ -d "$TARGET" ] || { echo "no such directory: $TARGET" >&2; exit 1; }
+
+place() {  # place <template> <destination-relative-to-target>
+  local dest="$TARGET/$2"
+  if [ -e "$dest" ] && [ "$FORCE" -eq 0 ]; then
+    echo "SKIP $2 — already exists (--force to replace)"
+    return 0
+  fi
+  mkdir -p "$(dirname "$dest")"
+  sed "s|{{DEVICETOOLS}}|$ROOT|g" "$HERE/$1" > "$dest"
+  echo "OK $2"
+}
+
+did=0
+case "$HOST" in claude|all) place claude/SKILL.md    .claude/skills/devicetools/SKILL.md; did=1 ;; esac
+case "$HOST" in cursor|all) place cursor/devicetools.mdc .cursor/rules/devicetools.mdc;       did=1 ;; esac
+case "$HOST" in gemini|all) place gemini/GEMINI.md   GEMINI.md;                       did=1 ;; esac
+# Codex, Zed, Copilot and Jules all read AGENTS.md natively.
+case "$HOST" in codex|all)  place gemini/GEMINI.md   AGENTS.md;                       did=1 ;; esac
+case "$HOST" in mcp)        place mcp/mcp.json      .mcp.json;                        did=1 ;; esac
+
+[ "$did" -eq 1 ] || { echo "unknown host: $HOST" >&2; usage; }

package/integrations/claude/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: devicetools
+description: Operate and inspect a real iOS or Android app on a physical device — read the screen with its geometry, tap, type, watch what the app logs. Use when asked to check how something looks or behaves in the app, to reproduce a UI bug, or to verify a change on the device after building it.
+---
+
+Read `{{DEVICETOOLS}}/AGENTS.md`. It is the contract and it is complete.
+
+Then run `{{DEVICETOOLS}}/scripts/doctor.sh` before your first action.

package/integrations/cursor/devicetools.mdc

@@ -0,0 +1,8 @@
+---
+description: Drive and inspect a real mobile app on a physical device — read the screen, tap, type, watch the logs.
+alwaysApply: false
+---
+
+Read `{{DEVICETOOLS}}/AGENTS.md`. It is the contract and it is complete.
+
+Then run `{{DEVICETOOLS}}/scripts/doctor.sh` before your first action.

package/integrations/gemini/GEMINI.md

@@ -0,0 +1,5 @@
+# DeviceTools
+
+Read `{{DEVICETOOLS}}/AGENTS.md`. It is the contract and it is complete.
+
+Then run `{{DEVICETOOLS}}/scripts/doctor.sh` before your first action.

package/integrations/mcp/README.md

@@ -0,0 +1,184 @@
+# DeviceTools over MCP
+
+`server.sh` exposes the verbs to any host that speaks MCP over stdio. It is a
+wrapper and nothing else: it runs `scripts/<verb>.sh` and hands back stdout and
+the exit code, unchanged.
+
+**If your host can run shell commands, you may not need this.** Point it at
+`AGENTS.md` with `integrations/agent-pointer.sh` and it will drive DeviceTools directly,
+with one less process in the way. MCP is for hosts that cannot: a desktop chat
+client, an IDE panel, an agent framework with no shell — and for the one thing
+the shell cannot do, which is hand back an image.
+
+## Registering it
+
+Claude Code, from the repository you are working in:
+
+```sh
+claude mcp add devicetools -- /path/to/devicetools/integrations/mcp/server.sh
+```
+
+Or write a project-scoped `.mcp.json` — the same file, filled in for you:
+
+```sh
+integrations/agent-pointer.sh /path/to/your/repo mcp
+```
+
+Claude Desktop, Cursor and anything else that reads an `mcpServers` block take
+the same shape; `mcp.json` in this directory is the template.
+
+```json
+{
+  "mcpServers": {
+    "devicetools": {
+      "command": "/path/to/devicetools/integrations/mcp/server.sh",
+      "env": { "DEVICETOOLS_CONFIG": "/path/to/devicetools/config.json" }
+    }
+  }
+}
+```
+
+## Eighteen tools
+
+Each one's schema, generated from this server: [`docs/tool-reference.md`](../../docs/tool-reference.md).
+
+| Tool | What it is for |
+| --- | --- |
+| `doctor` | device, driver and app all reachable. First call of every session |
+| `devices` | what is attached, and which one the config selects |
+| `open` | launch, relaunch, kill or reset the app, or open a URL in it |
+| `snapshot` | **the default way to see.** Numbered elements with rectangles, plus geometry warnings |
+| `screenshot` | an image, for what a tree cannot say — icon, colour, gradient |
+| `measure` | one element in full: parent, neighbours, gaps, overlaps, hit area |
+| `tap` | a uid, or a selector. Refuses rather than guesses |
+| `type` | type into the focused field, and verify something changed |
+| `swipe` / `scroll` | gestures; `scroll` can run until something appears |
+| `key` | put the keyboard away, so `tap` stops refusing |
+| `back` | one screen back; fails if the screen does not move |
+| `wait` | until something appears or disappears |
+| `logs` | the Console panel. `action=start` once per session to begin collecting |
+| `waypoint` | mark where you are; `goto` walks back after a reinstall |
+| `settings` | appearance, text size, orientation — conditions invisible in the tree |
+| `permission` | grant, revoke or reset a system permission |
+
+`setup` is deliberately absent. It needs an Xcode sign-in and a device
+registration that must not be faked, and an agent should not be running it
+unattended. Run it from a terminal, once.
+
+### A tool's name is its script's name
+
+`snapshot` runs `scripts/snapshot.sh`. There is no mapping table anywhere in
+this directory, because a mapping table is a second list to keep in sync and it
+would not be kept in sync. A verb that does not exist as a script is not a tool.
+
+### Why eighteen, when it used to be two
+
+The earlier design sent one `devicetools` tool with the verb as an enum, plus a
+`devicetools_docs` tool, and the reasoning was sound: a schema is billed on every
+request, and the whole surface fitted in 1.8 KB against roughly 10 KB for
+per-verb tools.
+
+It was right for the job at the time — a long authoring session that could
+afford to read a 30 KB contract before its first action. It is wrong for this
+one. The job now is a handful of calls in the middle of somebody's debugging,
+where fetching documentation before acting is a wasted round trip, and where a
+verb passed as a bare enum string invites wrong arguments with no schema to
+catch them.
+
+Measured, not estimated: the eighteen schemas come to **8,730 bytes**, about
+1,700 tokens, on every request. That is the price of the agent being right on
+its first call.
+
+`devicetools_docs` and the `devicetools://agents.md` resource went with the enum. They
+existed to compensate for a surface that did not describe itself.
+
+## Arguments are an object
+
+```json
+{"name": "tap", "arguments": {"target": "7"}}
+{"name": "snapshot", "arguments": {"grep": "Đăng nhập"}}
+{"name": "screenshot", "arguments": {"full": true}}
+```
+
+The server turns that into a command line. `action`, `name`, `uid`, `target`,
+`text`, `direction`, `key` and `value` are positional, in that order, because
+that is the order the scripts read them in; everything else becomes
+`--key value`. A boolean becomes the presence or absence of `--key` — never
+`--key false`, which every one of these scripts would read as a stray positional
+argument and refuse.
+
+Nothing passes through a shell. Arguments are emitted NUL-separated and read
+straight into an array, so an argument is an argument whatever is in it: no
+quoting to satisfy, none to get wrong, and no command injection surface. The app
+on the other end of this is somebody's production app.
+
+## What comes back
+
+stdout, verbatim. On a non-zero exit, stderr and a final line naming the code:
+
+```
+uid 999 was never assigned — the last snapshot printed 41 element(s)
+EXIT 4 — the command ran but the screen did not satisfy it
+```
+
+`isError` is set for every non-zero exit, including 4. Those are ordinary
+outcomes rather than faults — the host marks them, and the model reads the text
+and decides what they mean.
+
+| Code | Meaning |
+| --- | --- |
+| 0 | done |
+| 1 | usage error |
+| 2 | environment or configuration problem |
+| 3 | device unreachable — run `doctor` |
+| 4 | the command ran but the screen did not satisfy it |
+| 124 | the verb was killed after `DEVICETOOLS_MCP_TIMEOUT` (default 300s) |
+
+124 is the one code that does not exist on the command line. macOS ships no
+`timeout`, so the server carries its own: a hung verb is killed along with
+whatever it spawned, rather than wedging the host until someone notices.
+
+There is no 5.
+
+### An image comes back as an image
+
+`screenshot` prints a filesystem path, which is a string a model cannot open.
+When a verb's entire output is one line naming a readable `.png`, the server
+sends MCP `image` content instead of the path.
+
+The rule is written against the output rather than against the verb's name, so
+there is no second list of "verbs that produce images" to fall out of date.
+
+## Checking it without a device
+
+```sh
+integrations/mcp/selftest.sh config.json
+```
+
+Sixteen checks over the handshake, the tool list, the argument mapping, the
+exit-code contract and the ways a request can be malformed. The two verbs it
+runs touch nothing: `waypoint list` reads a file, and `measure abc` fails on its
+argument before it loads a config. Both answer the same on a machine with no
+phone attached, which is what lets this run in CI.
+
+Run it after touching anything in this directory — the protocol layer is the one
+part of DeviceTools that a device cannot tell you is broken.
+
+## Requests are handled one at a time
+
+There is one device on the other end. Two verbs touching one screen at once is a
+race with a real tap in it, so the loop is serial by construction.
+
+## Diagnostics
+
+stdout carries JSON-RPC and nothing else. Everything else goes to stderr, which
+the host keeps in its MCP log:
+
+```
+device-devtools-mcp: ready — /path/to/devicetools, config config.json, timeout 300s
+device-devtools-mcp: tap (1 args) -> 0
+device-devtools-mcp: screenshot -> image, 110856 bytes
+```
+
+The count, not the arguments. `type` carries whatever is typed, and on this app
+that is a credential.

package/integrations/mcp/mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "devicetools": {
+      "command": "{{DEVICETOOLS}}/integrations/mcp/server.sh",
+      "env": {
+        "DEVICETOOLS_CONFIG": "{{DEVICETOOLS}}/config.json"
+      }
+    }
+  }
+}