device-devtools-mcp 0.1.0

package/integrations/mcp/reference.sh

@@ -0,0 +1,119 @@
+#!/usr/bin/env bash
+# reference.sh — docs/tool-reference.md, from the schemas the server sends.
+#
+#   integrations/mcp/reference.sh            print it
+#   integrations/mcp/reference.sh --write    write docs/tool-reference.md
+#
+# THE DOCUMENT WAS BEING KEPT BY HAND, WHICH IS THE SAME AS NOT BEING KEPT.
+#
+# It was generated once and edited afterwards, so every schema change since has
+# had to be copied into it by somebody remembering to. The MCP self-test could
+# only catch a tool with no section at all — a description that had moved on, or
+# a parameter added to a tool that already had a heading, went through silently.
+# Now the file is output, the self-test diffs it against this, and a stale
+# reference fails the suite the way a stale test would.
+#
+# The groups below are the one thing not derivable from a schema: which tools
+# belong together is an editorial judgement, and it is the same judgement README
+# makes. A tool missing from every group still appears — under "Everything else",
+# where it is impossible not to notice.
+#
+# exit 0  printed, or written
+# exit 1  usage error
+# exit 2  the server would not answer
+
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$HERE/../.." && pwd)"
+OUT="$ROOT/docs/tool-reference.md"
+
+WRITE=0
+case "${1-}" in
+  --write) WRITE=1 ;;
+  -h|--help) awk 'NR > 1 { if (!/^#/) exit; sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;;
+  "") ;;
+  *) printf 'unknown argument: %s\n' "$1" >&2; exit 1 ;;
+esac
+
+# NOT `GROUPS`. That is a bash built-in array of the current user's group ids,
+# and assigning to it is ignored: "$GROUPS" expanded to 20 — the gid of staff on
+# macOS — so the loop below read one line, matched no tool, and quietly filed
+# every tool under "Everything else". Nothing errored.
+TOOL_GROUPS="Reading the screen:snapshot screenshot measure
+Input automation:tap type swipe scroll back key wait
+Batches and flows:run flow
+The app:app open
+The device:doctor devices logs settings permission
+The project:init
+Getting back:waypoint"
+
+TOOLS="$( { printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26"}}'
+            printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
+          } | "$HERE/server.sh" 2>/dev/null | jq -c 'select(.id==2) | .result.tools' | head -1)"
+[ -n "$TOOLS" ] || { printf 'the server did not answer tools/list\n' >&2; exit 2; }
+
+render() {
+  cat <<'HEAD'
+# Tool reference
+
+Generated by `integrations/mcp/reference.sh` from the schemas the server sends
+at handshake time. Do not edit it by hand: the self-test regenerates it and
+fails on a difference. Every tool is `scripts/<name>.sh` on the command line,
+with positional arguments in place of `key=value`.
+HEAD
+
+  local listed=""
+  while IFS= read -r line; do
+    [ -n "$line" ] || continue
+    local title names any
+    title="${line%%:*}"
+    names="${line#*:}"
+    any=0
+    for n in $names; do
+      printf '%s' "$TOOLS" | jq -e --arg n "$n" 'any(.name == $n)' >/dev/null 2>&1 || continue
+      [ "$any" -eq 1 ] || { printf '\n## %s\n' "$title"; any=1; }
+      section "$n"
+      listed="$listed $n"
+    done
+  done <<< "$TOOL_GROUPS"
+
+  # A `case` inside a command substitution inside this function is a bash 3.2
+  # parse error, so the leftovers are collected with a plain loop.
+  local rest="" n
+  for n in $(printf '%s' "$TOOLS" | jq -r '.[].name'); do
+    case " $listed " in *" $n "*) continue ;; esac
+    rest="$rest $n"
+  done
+  if [ -n "$rest" ]; then
+    printf '\n## Everything else\n'
+    for n in $rest; do section "$n"; done
+  fi
+}
+
+section() {
+  printf '%s' "$TOOLS" | jq -r --arg n "$1" '
+    .[] | select(.name == $n)
+    | "\n### `\(.name)`\n\n\(.description)\n"
+      + ( (.inputSchema.properties // {})
+          | to_entries
+          | if length == 0 then ""
+            else "\n| Parameter | Type | |\n| --- | --- | --- |\n"
+                 + ( map( "| `\(.key)` | "
+                          # An enum says more than "string" does, and the hand-kept
+                          # version of this file printed it. Escaped, because a bare
+                          # pipe would end the table cell.
+                          + ( if (.value.enum // null) != null
+                              then (.value.enum | map("`\(.)`") | join(" \\| "))
+                              else "`\(.value.type)`" end )
+                          + " | \(.value.description // "") |" )
+                     | join("\n") )
+            end )'
+}
+
+if [ "$WRITE" -eq 1 ]; then
+  render > "$OUT.new" && mv "$OUT.new" "$OUT" || { rm -f "$OUT.new"; exit 2; }
+  printf 'wrote %s\n' "$OUT"
+else
+  render
+fi

package/integrations/mcp/selftest.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# selftest.sh — check the MCP layer without a device.
+#
+#   integrations/mcp/selftest.sh [config.json]
+#
+# Everything here is protocol: the handshake, the tool list, how a tool's
+# arguments become a command line, the exit-code contract, and the ways a
+# request can be malformed.
+#
+# THE VERBS IT RUNS TOUCH NOTHING. `waypoint list` reads a file in the state
+# directory. `measure abc` fails on its argument before it ever loads a config.
+# Both answer the same way on a machine with no phone attached as on one with,
+# which is the property this file needs and the reason it can run in CI.
+#
+# An earlier version ran `repair stats`, chosen because the log was empty and an
+# empty log exits 4 — so the check proved a non-zero exit was reported. Then the
+# log got its first entries, `stats` started succeeding, and a check about the
+# protocol went red because of data somebody added to the project. A test whose
+# result depends on a file that is supposed to grow is a test with a fuse in it.
+#
+# exit 0  every check passed
+# exit 1  a check failed — the failing line says what was expected
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$HERE/../.." && pwd)"
+CONFIG="${1:-$ROOT/config.json}"
+[ -f "$CONFIG" ] || { echo "no config at $CONFIG" >&2; exit 1; }
+
+OUT="$(mktemp "${TMPDIR:-/tmp}/devicetools-selftest.XXXXXX")"
+trap 'rm -f "$OUT"' EXIT
+
+{
+  echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26"}}'
+  echo '{"jsonrpc":"2.0","method":"notifications/initialized"}'
+  echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
+  echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"waypoint","arguments":{"action":"list"}}}'
+  echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"measure","arguments":{"uid":"abc"}}}'
+  echo '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"nope","arguments":{}}}'
+  echo '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"../../etc/passwd","arguments":{}}}'
+  echo '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"waypoint","arguments":{"action":"goto","name":"one two","dry":false}}}'
+  echo 'not json at all'
+  echo '{"jsonrpc":"2.0","id":8,"method":"ping"}'
+} | DEVICETOOLS_CONFIG="$CONFIG" "$HERE/server.sh" > "$OUT" 2>/dev/null
+
+fails=0
+check() {  # check <description> <jq-filter> <expected>
+  local got
+  got="$(jq -r "$2" < "$OUT" 2>/dev/null || true)"
+  if [ "$got" = "$3" ]; then
+    printf 'OK   %s\n' "$1"
+  else
+    printf 'FAIL %s — expected %s, got %s\n' "$1" "$3" "$got"
+    fails=$(( fails + 1 ))
+  fi
+}
+
+# Ten lines went in: eight requests, one unparseable, and one notification. A
+# notification carries no id and must never be answered, not even to say the
+# method was unknown — so nine replies come back, not ten.
+check "one reply per request, none for the notification" \
+      '[., inputs] | length' '9'
+check "handshake echoes the version the client asked for" \
+      'select(.id==1) | .result.protocolVersion' '2025-03-26'
+
+# --- the documentation cannot fall behind the schema ---------------------------
+#
+# docs/tool-reference.md is generated from these schemas and README lists the
+# same names. Both are hand-edited afterwards, so both can drift, and a tool
+# missing from the reference is a link in README that goes nowhere.
+
+REF="$ROOT/docs/tool-reference.md"
+RM="$ROOT/README.md"
+missing_readme=""
+for t in $(jq -r 'select(.id==2) | .result.tools[].name' < "$OUT" 2>/dev/null | sort); do
+  grep -q "(docs/tool-reference.md#$t)" "$RM" 2>/dev/null || missing_readme="$missing_readme $t"
+done
+check "every tool is linked from README" \
+      'empty' "$(printf '%s' "$missing_readme")"
+
+# THE REFERENCE IS OUTPUT, NOT A DOCUMENT SOMEBODY MAINTAINS.
+#
+# The check this replaces only asked whether each tool had a heading. A
+# description that had moved on, or a parameter added to a tool that already had
+# one, went through in silence — and both had. Regenerating and diffing is the
+# same rule the fixtures live under: the recorded thing either still matches
+# what the code produces or the suite is red.
+if diff "$REF" <(DEVICETOOLS_CONFIG="$CONFIG" "$HERE/reference.sh" 2>/dev/null) >/dev/null 2>&1; then
+  printf 'OK   docs/tool-reference.md is what reference.sh produces\n'
+else
+  printf 'FAIL docs/tool-reference.md is stale — run integrations/mcp/reference.sh --write\n'
+  fails=$(( fails + 1 ))
+fi
+
+# THE SURFACE. Twenty-one named tools, and the list is sorted here so that adding
+# one in the middle of the table does not fail this check for the wrong reason.
+check "twenty-one named tools, and these twenty-one" \
+      'select(.id==2) | .result.tools | map(.name) | sort | join(" ")' \
+      'app back devices doctor flow init key logs measure open permission run screenshot scroll settings snapshot swipe tap type wait waypoint'
+
+# THE RULE THE WHOLE TABLE RESTS ON. A tool's name is its script's name, so
+# there is no mapping table to keep in sync — and a mapping table is exactly the
+# kind of second list that does not get kept in sync.
+check "every tool name is a script that exists" \
+      'select(.id==2) | .result.tools | map(.name) | join("\n")' \
+      "$(jq -r 'select(.id==2) | .result.tools[].name' < "$OUT" 2>/dev/null \
+         | while read -r t; do [ -e "$ROOT/scripts/$t.sh" ] && printf '%s\n' "$t"; done \
+         | sed '$!s/$//' | paste -sd '\n' -)"
+
+# Real schemas, not a verb enum. This is the whole reason the two-tool design was
+# reversed: an agent should be able to act correctly on its first call without
+# fetching a document first.
+check "snapshot has named properties" \
+      'select(.id==2) | .result.tools[] | select(.name=="snapshot") | .inputSchema.properties | keys | sort | join(",")' \
+      'all,grep'
+check "no tool takes a free-form verb any more" \
+      'select(.id==2) | [.result.tools[] | select(.inputSchema.properties.verb != null)] | length' '0'
+check "the documentation tool is gone with the enum that needed it" \
+      'select(.id==2) | [.result.tools[] | select(.name | test("docs"))] | length' '0'
+
+# Arguments. An object has to become a command line, and the positional ones
+# have to arrive as positions.
+check "a verb runs and reports success" \
+      'select(.id==3) | .result.isError' 'false'
+check "a usage error is reported as an error with its code" \
+      'select(.id==4) | .result.content[0].text | test("EXIT 1")' 'true'
+check "a positional argument arrives as a position" \
+      'select(.id==4) | .result.content[0].text | test("got .abc.")' 'true'
+# The space inside the value must survive. If the arguments were joined into one
+# string and re-split, waypoint would see two arguments and say so.
+#
+# THE VERB HERE MATTERS. An earlier version of this check used
+# `snapshot --grep "one two"`, which passed for a week and then failed the
+# moment nobody had a phone plugged in: snapshot exits 3 before it ever looks at
+# its arguments. That is the fuse this file's own header warns about, and it had
+# one in it. `waypoint goto` refuses an unknown name before it touches anything,
+# and quotes the name back.
+check "a value containing a space stays one argument" \
+      'select(.id==7) | .result.content[0].text | test("no waypoint called .one two.")' 'true'
+# A false boolean is an absent flag, not "--dry false", which every one of these
+# scripts would read as a stray positional argument and refuse.
+check "a false boolean sends no flag" \
+      'select(.id==7) | .result.content[0].text | test("too many arguments") | not' 'true'
+
+check "unknown tool is a protocol error" \
+      'select(.id==5) | .error.code' '-32602'
+check "a path is not a tool name" \
+      'select(.id==6) | .error.code' '-32602'
+check "unparseable input answers with a null id" \
+      'select(.error.code==-32700) | .id' 'null'
+check "ping" 'select(.id==8) | .result | length' '0'
+
+if [ "$fails" -eq 0 ]; then
+  printf 'RESULT PASS mcp selftest\n'
+else
+  printf 'RESULT FAIL mcp selftest — %d check(s)\n' "$fails" >&2
+  exit 1
+fi

package/integrations/mcp/server.sh

@@ -0,0 +1,343 @@
+#!/usr/bin/env bash
+# server.sh — DeviceTools as an MCP server, over stdio.
+#
+#   integrations/mcp/server.sh
+#
+# It speaks JSON-RPC 2.0 on stdin/stdout, one message per line, and does exactly
+# one thing: run a script in scripts/ and hand back its stdout and its exit code.
+# There is no logic here. A verb the scripts cannot do is a verb this cannot do,
+# and a verb added to scripts/ appears here without an edit — the tool's enum is
+# read from the directory, not from a list kept in this file.
+#
+# WHY IT IS A WRAPPER AND NOTHING MORE. Everything downstream — the runner, the
+# recorder, diagnose — reads the same one-line stdout contract. The moment this
+# layer starts reformatting, retrying or summarising, an agent driving over MCP
+# and an engineer driving over the shell are running two different products, and
+# the difference surfaces as a bug in whichever is used less.
+#
+# The surface is twenty named tools; see the note above TOOLS below for why that
+# is not the two it started as.
+#
+# Environment:
+#   DEVICETOOLS_CONFIG        config file to use (default: the repo's config.json)
+#   DEVICETOOLS_MCP_TIMEOUT   seconds before a verb is killed (default: 300)
+#   DEVICETOOLS_VAR_*         test variables; passed through to the scripts as-is
+#
+# Diagnostics go to stderr, which the host shows in its MCP log. Nothing but
+# JSON-RPC ever goes to stdout.
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$HERE/../.." && pwd)"
+SERVER_VERSION="0.1.0"
+TIMEOUT="${DEVICETOOLS_MCP_TIMEOUT:-300}"
+
+# Protocol revisions this server can hold a conversation in, newest first. A
+# client asking for one of them gets that one back; a client asking for anything
+# else gets the newest, which is what the specification says to do.
+SUPPORTED="2025-06-18 2025-03-26 2024-11-05"
+
+log() { printf 'device-devtools-mcp: %s\n' "$*" >&2; }
+
+command -v jq >/dev/null 2>&1 || { log "jq is not installed — DeviceTools needs it"; exit 2; }
+
+# A verb reached this way must spell its remedies as tool names. "run
+# scripts/snapshot.sh" is a path a model cannot call.
+export DT_MCP=1
+
+# The same four places, in the same order, as scripts/lib.sh — see the note
+# there. Repeated rather than shared because this file deliberately sources
+# nothing: lib.sh installs EXIT and USR1 traps, and this process owns its own.
+# A self-test asserts the two agree.
+USER_CONFIG="${XDG_CONFIG_HOME:-$HOME/.config}/devicetools/config.json"
+if   [ -n "${DEVICETOOLS_CONFIG:-}" ];                 then CONFIG="$DEVICETOOLS_CONFIG"
+elif [ -n "${DEVICETOOLS_PROJECT:-}" ] && [ -f "$DEVICETOOLS_PROJECT/config.json" ]
+                                                       then CONFIG="$DEVICETOOLS_PROJECT/config.json"
+elif [ -f "$ROOT/config.json" ];                       then CONFIG="$ROOT/config.json"
+else                                                        CONFIG="$USER_CONFIG"
+fi
+[ -f "$CONFIG" ] || {
+  log "no config — looked in $ROOT/config.json and $USER_CONFIG"
+  log "make one:  npx device-devtools-mcp init <the repository holding your app>"
+  log "then point this server at it with project=<that path> on any tool, or"
+  log "set DEVICETOOLS_CONFIG in this server's env"
+  exit 2
+}
+jq -e . "$CONFIG" >/dev/null 2>&1 || { log "$CONFIG is not valid JSON"; exit 2; }
+export DEVICETOOLS_CONFIG="$CONFIG"
+
+WORK="$(mktemp -d "${TMPDIR:-/tmp}/device-devtools-mcp.XXXXXX")"
+cleanup() { rm -rf "$WORK"; }
+trap cleanup EXIT
+
+# ---------------------------------------------------------------- the surface
+
+
+# TWENTY TOOLS, NOT TWO — AND WHY THAT REVERSED.
+#
+# The earlier design sent one `devicetools` tool with the verb as an enum, plus a
+# documentation tool, because a schema is billed on every request and the whole
+# surface fitted in 1.8 KB. That was right when the job was a long authoring
+# session which could afford to read a 30 KB contract before its first action.
+#
+# The job is now a handful of calls in the middle of somebody's debugging.
+# There, fetching documentation before acting is a wasted round trip, and a verb
+# passed as a bare enum string invites wrong arguments with no schema to catch
+# them. The schemas are a couple of thousand tokens on every request. That is
+# the price of the agent being right on its first call, and against a debugging
+# session it is worth paying.
+#
+# `run` and `flow` earn their place differently from the rest: they are the two
+# tools that reduce how many times any of the others are called.
+#
+# A TOOL'S NAME IS ITS SCRIPT'S NAME. There is no mapping table, because a
+# mapping table is a second list to keep in sync and it would not be kept in
+# sync. `snapshot` runs scripts/snapshot.sh and nothing else.
+#
+# `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.
+
+tool() {  # tool <name> <description> <properties-json>
+  jq -nc --arg n "$1" --arg d "$2" --argjson p "$3" \
+    '{name:$n, description:$d, inputSchema:{type:"object", properties:$p, additionalProperties:false}}'
+}
+
+TOOLS="$(jq -sc '.' <<TOOLS_END
+$(tool doctor "Check that the device, the driver and the app are all reachable. Run this first in every session, and again the moment any tool exits 3." '{}')
+$(tool devices "List the attached devices and simulators, and say which one the config selects." '{}')
+$(tool app "The app under test: get it in front of you, restart it, or put a new build on the phone. Launching asks the operating system by bundle id, so it works from the home screen or from another app — no icon has to be found or tapped. Start every session with launch. install goes to the device this config selects and to no other." '{"action":{"type":"string","enum":["launch","relaunch","kill","reset","state","install","uninstall"],"description":"launch brings it to the front. relaunch kills and launches, keeping stored data. reset uninstalls and reinstalls, discarding it. kill terminates it. state reports whether it is running. install puts a built bundle on the phone. uninstall removes it."},"path":{"type":"string","description":"For install: the .app bundle to put on the phone. DeviceTools does not build — give it what your build produced."},"bundle-id":{"type":"string","description":"For launch and uninstall: act on this app instead of the one in the config."},"launch":{"type":"boolean","description":"For install and reset: bring the app up once it is on."},"snapshot":{"type":"boolean","description":"Print the screen this left behind and renumber the uids, in the same call. Ask for it whenever the next thing you would do is read the screen — it halves the round trips of finding your way."}}')
+$(tool open "Open a deep link on the device and report which app came to the front. The URL needs a scheme: myapp://path, or https://. Not the app lifecycle — that is the app tool." '{"target":{"type":"string","description":"The URL to open, scheme included."},"expect-app":{"type":"string","description":"Fail unless this bundle id or package is the app that answered."},"snapshot":{"type":"boolean","description":"Print the screen this left behind and renumber the uids, in the same call. Ask for it whenever the next thing you would do is read the screen — it halves the round trips of finding your way."}}')
+$(tool snapshot "Read the screen: every element that can be acted on or carries text, with its rectangle, plus warnings — overlap, escaping a parent, off screen, a hit area below the platform minimum, text the OS truncated, and a control with no accessibility identifier. The number in brackets is a uid, valid only until the next snapshot; #name beside it is the identifier, which is the one selector that survives a change of copy or of language, so prefer id: over label: wherever the screen offers one. THIS IS THE DEFAULT WAY TO SEE. It costs about a third of a screenshot and, unlike one, it can be measured." '{"all":{"type":"boolean","description":"Every element, not just what can be acted on or carries text."},"grep":{"type":"string","description":"Case-insensitive substring of type, identifier, label or value. Searches the whole tree, including what the filter hides."}}')
+$(tool screenshot "The screen as an image. Use this only for what a tree cannot say: a wrong icon, a blurry asset, a colour, a contrast, a gradient. For anything about position, size or text, snapshot is cheaper and exact." '{"scale":{"type":"integer","description":"Longest edge in pixels. Default 768, about 360 tokens."},"full":{"type":"boolean","description":"Device resolution, no downscale — about 1500 tokens."},"name":{"type":"string","description":"Optional file name; re-using one overwrites it."}}')
+$(tool measure "Everything about one element: its rectangle, what contains it, what is above and below and how far, whether its text was truncated, which siblings it overlaps and by how much, whether its hit area meets the platform minimum. snapshot groups its warnings; this is how you find out which sibling." '{"uid":{"type":"integer","description":"The bracketed number from the last snapshot."}}')
+$(tool tap "Tap one element. Pass a uid from the last snapshot, or a selector: id:, label:, text:, kind:<Type>, xy:x,y, or a plain string matched against id, label and value. kind: is the escape hatch for a control that snapshot flags as having no identifier and that also has no label — use it with index rather than falling back to raw coordinates, which break the moment the layout moves. Refuses rather than guesses when a selector matches more than one element, or when a uid no longer names what it named." '{"target":{"type":"string","description":"A uid such as \"7\", or a selector: id:, label:, text:, kind:<Type> for a control with no name at all, xy:x,y, or a plain string matched against id, label and value. Every selector matches a value WHOLE — text:OTP does not find a label containing OTP; snapshot grep searches inside."},"index":{"type":"integer","description":"Act on the Nth match, zero-based, when a selector deliberately matches several."},"count":{"type":"integer","description":"Tap the same point this many times, up to 20. Resolved once. Use this for a keypad — six digits is one call, not six."},"snapshot":{"type":"boolean","description":"Print the screen this left behind and renumber the uids, in the same call. Ask for it whenever the next thing you would do is read the screen — it halves the round trips of finding your way."}}')
+$(tool type "Type into whatever has keyboard focus, and verify that something changed. Tap the field first." '{"text":{"type":"string","description":"What to type."},"snapshot":{"type":"boolean","description":"Print the screen this left behind and renumber the uids, in the same call. Ask for it whenever the next thing you would do is read the screen — it halves the round trips of finding your way."}}')
+$(tool swipe "Swipe. Either a direction, or between two elements." '{"direction":{"type":"string","enum":["up","down","left","right"],"description":"Which way the content moves."},"from":{"type":"string","description":"Start point: a uid, a selector, or xy:x,y. Use with to, instead of direction."},"to":{"type":"string","description":"End point, same spellings as from."},"duration":{"type":"integer","description":"Milliseconds. Longer is slower; a slow drag is how some controls tell a swipe from a fling."},"snapshot":{"type":"boolean","description":"Print the screen this left behind and renumber the uids, in the same call. Ask for it whenever the next thing you would do is read the screen — it halves the round trips of finding your way."}}')
+$(tool scroll "Scroll, optionally until something appears." '{"direction":{"type":"string","description":"up, down, left or right."},"until":{"type":"string","description":"Optional selector to stop at."},"times":{"type":"integer","description":"How many swipes, when there is no --until."},"snapshot":{"type":"boolean","description":"Print the screen this left behind and renumber the uids, in the same call. Ask for it whenever the next thing you would do is read the screen — it halves the round trips of finding your way."}}')
+$(tool key "Put the on-screen keyboard away. tap refuses when the keyboard stands between it and a control; this is how you clear it." '{"action":{"type":"string","enum":["hide"],"description":"hide"},"snapshot":{"type":"boolean","description":"Print the screen this left behind and renumber the uids, in the same call. Ask for it whenever the next thing you would do is read the screen — it halves the round trips of finding your way."}}')
+$(tool back "Go back one screen. Fails if the screen does not change." '{"snapshot":{"type":"boolean","description":"Print the screen this left behind and renumber the uids, in the same call. Ask for it whenever the next thing you would do is read the screen — it halves the round trips of finding your way."}}')
+$(tool wait "Wait until an element appears, or disappears, then report which happened." '{"target":{"type":"string","description":"A uid or a selector."},"gone":{"type":"boolean","description":"Wait for it to disappear instead of appear."},"timeout":{"type":"integer","description":"Seconds. Defaults to the config."},"snapshot":{"type":"boolean","description":"Print the screen this left behind and renumber the uids, in the same call. Ask for it whenever the next thing you would do is read the screen — it halves the round trips of finding your way."}}')
+$(tool logs "What the app under test printed. This is the Console panel. Only the app's own lines: the OS logs a great deal on an app's behalf under its process name, and none of it is the app talking. Pass action=start once per session to begin collecting; until then actions carry no log lines." '{"action":{"type":"string","description":"start, stop or status. Omit to read."},"grep":{"type":"string","description":"Only lines containing this."},"since":{"type":"string","description":"Seconds, e.g. 30."},"network":{"type":"boolean","description":"Only request- and response-shaped lines from the app. NOT a proxy: this filters the app'"'"'s own logging, so it shows nothing from an app that does not print its traffic."},"raw":{"type":"boolean","description":"Every line the device logged, not just the app'"'"'s. Thousands of lines from other processes — use only when the default returns nothing and you need to know why."},"lines":{"type":"integer","description":"How many lines at most."}}')
+$(tool init "Make a directory into a DeviceTools project, so that config.json, flows/ and .state/ live in the repository holding the app instead of in the DeviceTools checkout. Run this once per app, then pass project=<that path> to everything else. Nothing is overwritten: an existing .devicetools, config.json or .gitignore entry is reported and left alone." '{"path":{"type":"string","description":"Absolute path of the repository. Required — there is no working directory on this side of the connection, and a default would make the DeviceTools checkout itself the project."}}')
+$(tool run "Several steps in one call. Each step is an object with exactly one verb in it — {\"tap\":\"label:X\"}, {\"type\":\"...\"}, {\"wait\":\"screen:Home\"} — and any other key becomes a flag for that verb. USE THIS INSTEAD OF CALLING tap, type AND tap AGAIN: what a person does as one continuous act costs one call here, not four, and the number of calls is what this loop costs. It stops at the first failing step and shows you the screen it stopped on. Selectors only: a uid means a position on a screen that is already stale by the next step, so uids are refused." '{"steps":{"type":"array","items":{"type":"object"},"description":"The steps, in order. One verb per object; extra keys are that verb'"'"'s flags — including snapshot:true, which is a flag here and not a second verb. {\"expect\":\"screen:Auth.LoginView\"} is a wait with a short deadline: put one first so a batch fails at the door when the app is not where it was written to start."},"vars":{"type":"object","description":"Values for the {{ name }} placeholders in the steps. Put credentials here rather than in the steps, and they are masked back to {{ name }} in everything this prints."},"dry-run":{"type":"boolean","description":"Check every step and print what would run, without touching the device."},"logs":{"type":"boolean","description":"Keep the LOG block on every step. By default only the step that FAILED keeps its own — in a batch of eight, system log lines outweighed everything the batch actually said."},"project":{"type":"string","description":"Absolute path of the repository holding the app under test. Everything this call resolves — the config, flows/, .state/ — lands there instead of in the DeviceTools checkout. THERE IS NO WORKING DIRECTORY ON THIS SIDE OF THE CONNECTION: the walk-up rule that finds a project from a shell cannot see where you are, so name it. Every tool takes this."}}')
+$(tool flow "A batch worth keeping, under a name — saved in the project as flows/<name>.json, so it is shared and reviewed like code. Every flow in an app starts by logging in; save that once and the next twenty sessions say flow run login. A step of {\"flow\":\"login\"} runs a saved flow inside another, so nothing has to repeat it. Credentials stay as {{ name }} and are supplied at run time." '{"action":{"type":"string","enum":["save","run","list","show","delete"],"description":"save writes one, run plays it, list names them, show prints one, delete removes it."},"name":{"type":"string","description":"The flow'"'"'s name."},"steps":{"type":"array","items":{"type":"object"},"description":"For save: the steps, in the same shape the run tool takes."},"description":{"type":"string","description":"For save: one line about what this flow does, shown by list."},"vars":{"type":"object","description":"For run: values for the {{ name }} placeholders the flow declares."},"dry-run":{"type":"boolean","description":"For run: check every step and print what would run, without touching the device."},"project":{"type":"string","description":"Absolute path of the repository holding the app under test. Everything this call resolves — the config, flows/, .state/ — lands there instead of in the DeviceTools checkout. THERE IS NO WORKING DIRECTORY ON THIS SIDE OF THE CONNECTION: the walk-up rule that finds a project from a shell cannot see where you are, so name it. Every tool takes this."}}')
+$(tool waypoint "Mark where the app is now, or walk back to a place marked earlier. Use goto after reinstalling a build, which puts the app back on its first screen." '{"action":{"type":"string","description":"mark, goto, list or forget."},"name":{"type":"string","description":"The waypoint name, for mark, goto and forget."}}')
+$(tool settings "Change a device condition that is invisible in the tree: light or dark appearance, text size, orientation. Not available on a physical iPhone, which exits 2 and says so." '{"key":{"type":"string","description":"appearance, textsize or orientation."},"value":{"type":"string","description":"The value to set."}}')
+$(tool permission "Grant, revoke or reset a system permission for the app under test." '{"action":{"type":"string","description":"allow, deny or reset."},"name":{"type":"string","description":"The permission, e.g. camera, notifications, location."}}')
+TOOLS_END
+)"
+
+
+# ------------------------------------------------------------------- running
+
+# run_child — run a command with a deadline, without GNU timeout, which macOS
+# does not ship.
+#
+# `set -m` puts the child in its own process group so the kill reaches what it
+# spawned. A verb that hangs is usually hanging inside curl or adb, and killing
+# only the shell that started them leaves them holding the device.
+#
+# STDIN COMES FROM /dev/null, AND THAT IS NOT TIDINESS. This server's stdin is
+# the JSON-RPC stream. A child that reads stdin — `adb shell` does, always —
+# would swallow the next request off the wire and the session would hang with no
+# error anywhere.
+CHILD_RC=0
+CHILD_TIMED_OUT=0
+run_child() {
+  local out="$1" err="$2"; shift 2
+  local pid ticks=0 limit=$(( TIMEOUT * 4 ))
+  CHILD_RC=0
+  CHILD_TIMED_OUT=0
+  set -m
+  "$@" >"$out" 2>"$err" </dev/null &
+  pid=$!
+  set +m
+  while kill -0 "$pid" 2>/dev/null; do
+    if [ "$ticks" -ge "$limit" ]; then
+      kill -TERM -"$pid" 2>/dev/null || kill -TERM "$pid" 2>/dev/null || true
+      sleep 1
+      kill -KILL -"$pid" 2>/dev/null || kill -KILL "$pid" 2>/dev/null || true
+      CHILD_TIMED_OUT=1
+      break
+    fi
+    sleep 0.25
+    ticks=$(( ticks + 1 ))
+  done
+  wait "$pid" 2>/dev/null || CHILD_RC=$?
+  [ "$CHILD_TIMED_OUT" -eq 0 ] || CHILD_RC=124
+}
+
+rc_meaning() {
+  case "$1" in
+    0)   printf 'done' ;;
+    1)   printf 'usage error' ;;
+    2)   printf 'environment or configuration problem' ;;
+    3)   printf 'device unreachable — run doctor' ;;
+    4)   printf 'the command ran but the screen did not satisfy it' ;;
+    124) printf 'killed after %ss — set DEVICETOOLS_MCP_TIMEOUT to allow longer' "$TIMEOUT" ;;
+    *)   printf 'unexpected exit code' ;;
+  esac
+}
+
+# ------------------------------------------------------------------ protocol
+
+emit() { printf '%s\n' "$1"; }
+
+reply() {  # reply <id-json> <result-json>
+  emit "$(jq -cn --argjson id "$1" --argjson result "$2" '{jsonrpc:"2.0", id:$id, result:$result}')"
+}
+
+fail() {  # fail <id-json> <code> <message>
+  emit "$(jq -cn --argjson id "$1" --argjson code "$2" --arg msg "$3" \
+    '{jsonrpc:"2.0", id:$id, error:{code:$code, message:$msg}}')"
+}
+
+# A tool result. isError is set for any non-zero exit, including 4 and 5, which
+# are ordinary outcomes rather than faults — the host marks them, and the model
+# still reads the text and decides what they mean.
+tool_text() {  # tool_text <id-json> <text> <is-error>
+  reply "$1" "$(jq -cn --arg t "$2" --argjson e "$3" '{content:[{type:"text",text:$t}], isError:$e}')"
+}
+
+# argv_from <arguments-json> — an object becomes a command line.
+#
+# NOTHING GOES THROUGH A SHELL. Arguments come out NUL-separated and are 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 injection surface. The app on
+# the other end of this is somebody's production app. NUL and not newline,
+# because `type` sends whatever text it is given and that can contain one.
+#
+# The positional list is the order the scripts read their arguments in. Anything
+# not on it 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.
+argv_from() {
+  printf '%s' "$1" | jq -j '
+    ["action","path","bundle-id","name","uid","target","text","direction","from","to","key","value"] as $pos
+    | . as $a
+
+    # EVERY REFERENCE IS BOUND TO A NAME, and that is not style. Inside
+    # `$a | has(.)` the dot is $a, not the key being tested, so the whole
+    # positional branch silently produced nothing and every tool was called
+    # with no arguments at all.
+    | ( $pos[] as $k
+        | select($a | has($k))
+        | ($a[$k] | tostring) + "\u0000" ),
+      ( $a | to_entries[] as $e
+        | select(($pos | index($e.key)) == null)
+        | if ($e.value | type) == "boolean"
+          then (if $e.value then "--" + $e.key + "\u0000" else empty end)
+          else "--" + $e.key + "\u0000" + ($e.value | tostring) + "\u0000"
+          end )
+  '
+}
+
+handle_verb() {  # handle_verb <id-json> <verb> <arguments-json>
+  local id="$1" verb="$2" a="$3" args=() out err text rc p
+  while IFS= read -r -d '' one; do args+=("$one"); done < <(argv_from "$a")
+
+  out="$WORK/out"; err="$WORK/err"
+  run_child "$out" "$err" "$ROOT/scripts/$verb.sh" ${args[@]+"${args[@]}"}
+  rc="$CHILD_RC"
+
+  # A VERB WHOSE WHOLE OUTPUT IS A PATH TO AN IMAGE SENDS THE IMAGE.
+  #
+  # screenshot prints a filesystem path, which is a string the model cannot
+  # open, and the point of that verb is that somebody looks at the picture. The
+  # rule is written against the output rather than the verb's name, so there is
+  # no second list of "verbs that produce images" to fall out of date.
+  if [ "$rc" -eq 0 ]; then
+    p="$(cat "$out")"
+    case "$p" in
+      /*.png)
+        if [ -f "$p" ] && [ "$(wc -l < "$out" | tr -d ' ')" -le 1 ]; then
+          log "$verb -> image, $(wc -c < "$p" | tr -d ' ') bytes"
+          reply "$id" "$(jq -cn --arg d "$(base64 < "$p" | tr -d '\n')" \
+            '{content:[{type:"image",data:$d,mimeType:"image/png"}],isError:false}')"
+          return 0
+        fi ;;
+    esac
+  fi
+
+  text="$(cat "$out")"
+  if [ "$rc" -ne 0 ]; then
+    [ -z "$text" ] || text="$text
+"
+    text="$text$(cat "$err")
+EXIT $rc — $(rc_meaning "$rc")"
+  fi
+  [ -n "$text" ] || text="OK"
+
+  # THE ARGUMENTS ARE NOT LOGGED. `type` carries whatever the test types, and on
+  # this app that is a credential. The host writes stderr to a file.
+  log "$verb (${#args[@]} args) -> $rc"
+  tool_text "$id" "$text" "$( [ "$rc" -eq 0 ] && echo false || echo true )"
+}
+
+
+handle() {  # handle <request-line>
+  local req="$1" method id has_id
+
+  if ! printf '%s' "$req" | jq -e . >/dev/null 2>&1; then
+    fail null -32700 "parse error"
+    return 0
+  fi
+
+  method="$(printf '%s' "$req" | jq -r '.method // empty')"
+  has_id="$(printf '%s' "$req" | jq -r 'has("id")')"
+  id="$(printf '%s' "$req" | jq -c '.id // null')"
+
+  # A notification carries no id and must never be answered, not even to say the
+  # method was unknown.
+  if [ "$has_id" != true ]; then
+    log "notification $method"
+    return 0
+  fi
+
+  case "$method" in
+    initialize)
+      local want got
+      want="$(printf '%s' "$req" | jq -r '.params.protocolVersion // empty')"
+      got="${SUPPORTED%% *}"
+      for v in $SUPPORTED; do [ "$v" = "$want" ] && got="$v"; done
+      log "initialize — client asked for ${want:-nothing}, answering $got"
+      reply "$id" "$(jq -cn --arg p "$got" --arg v "$SERVER_VERSION" '{
+        protocolVersion: $p,
+        capabilities: { tools: {} },
+        serverInfo: { name: "devicetools", version: $v },
+        instructions: "DeviceTools is DevTools for a phone attached to this machine. Call doctor first, then app launch — it opens the app under test by bundle id from wherever the phone happens to be, so you never have to find an icon. snapshot reads the screen: numbered elements with their rectangles, layout faults, and #name where the app supplies an accessibility identifier. Prefer id: over label: when there is one; a label changes with the copy. Act on the numbers — tap 7, measure 7 — but a number is only valid until the next snapshot. TWO THINGS DECIDE WHAT THIS COSTS YOU, AND BOTH ARE THE NUMBER OF CALLS. Pass snapshot=true to any action and it hands back the screen it produced, renumbered, in the same call — that is free, because the action reads the tree anyway. And when you already know several steps, send them as one run: run with steps [{\"tap\":\"label:X\"},{\"type\":\"...\"},{\"wait\":\"screen:Home\"}] does in one call what four calls did, stops at the first failure and shows you the screen it stopped on. Selectors only inside a run — a uid is stale by the next step. If you work out a sequence worth keeping, flow save puts it in the project under a name. Use screenshot only for what a tree cannot say: a wrong icon, a colour, a gradient. If the person is working in a repository, call init with its path once and then pass project=<that path> to everything: you have no working directory, so a saved flow otherwise lands in the DeviceTools checkout where every app on the machine shares it. After you reinstall a build, app relaunch then waypoint goto returns you to where you were."
+      }')" ;;
+
+    ping) reply "$id" '{}' ;;
+
+    tools/list) reply "$id" "$(jq -cn --argjson t "$TOOLS" '{tools:$t}')" ;;
+
+    tools/call)
+      local name a
+      name="$(printf '%s' "$req" | jq -r '.params.name // empty')"
+      a="$(printf '%s' "$req" | jq -c '.params.arguments // {}')"
+      case "$name" in
+        */*|.*|"") fail "$id" -32602 "not a tool name: $name" ;;
+        *)
+          if [ -x "$ROOT/scripts/$name.sh" ]; then
+            handle_verb "$id" "$name" "$a"
+          else
+            fail "$id" -32602 "unknown tool: $name"
+          fi ;;
+      esac ;;
+
+
+    *) fail "$id" -32601 "unknown method: $method" ;;
+  esac
+}
+
+log "ready — $ROOT, config $CONFIG, timeout ${TIMEOUT}s"
+
+# One request at a time, deliberately. There is one device on the other end of
+# this, and two verbs touching one screen at once is a race with a real tap in
+# it. Serial is the correct semantics here, not a limitation of the loop.
+while IFS= read -r line; do
+  [ -n "$line" ] || continue
+  handle "$line"
+done