mobile-debug-mcp 0.32.1 → 0.32.2

package/dist/observe/android-tree-bridge.js

@@ -10,6 +10,7 @@ const devicePort = 39019;
 const active = new Map();
 const starting = new Map();
 const stopping = new Map();
+const bridgeSupport = new Map();
 export function androidTreeBridgeEnabled() {
     return Boolean(process.env.MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK);
 }
@@ -168,6 +169,15 @@ export async function readAndroidTreeFromBridge(deviceId) {
         return null;
     let bridge;
     try {
+        let supported = bridgeSupport.get(deviceId);
+        if (supported === undefined) {
+            const sdkLevel = Number(await execAdb(['shell', 'getprop', 'ro.build.version.sdk'], deviceId));
+            supported = Number.isInteger(sdkLevel) && sdkLevel >= 34;
+            if (supported)
+                bridgeSupport.set(deviceId, true);
+        }
+        if (!supported)
+            return null;
         bridge = await ensure(deviceId, apk);
         const output = await request(bridge, 'TREE', remainingBudget(10000));
         if (!output.startsWith('OK\n') || !output.includes('<hierarchy'))

package/dist/server-core.js

@@ -6,7 +6,7 @@ import { handleToolCall } from './server/tool-handlers.js';
 export { wrapResponse, toolDefinitions, handleToolCall };
 export const serverInfo = {
     name: 'mobile-debug-mcp',
-    version: '0.32.1'
+    version: '0.32.2'
 };
 export function createServer() {
     const server = new Server(serverInfo, {

package/docs/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.32.2]
+- bug fix
+
 ## [0.32.1]
 - Further performance enhancements
 

package/docs/benchmarks/ui-tree-performance/README.md

@@ -49,3 +49,10 @@ network failures; see `comparison.md` for the outcome and limitation.
 The report commit SHAs are available locally as `codex/spec-019-baseline` and
 `codex/spec-019-candidate`; create clean, built checkouts of those refs to
 reproduce the paired measurement.
+
+For the opt-in Android bridge, run
+`LATENCY_DEVICE_ID=emulator-5554 node --import tsx test/device/automated/ui-tree-performance/bridge-probe.ts`.
+Its `bridge-probe.json` compares ten bridge and legacy reads, checks a network
+update, and checks a timer that changes visually without emitting an
+accessibility event. The timer check catches a stale accessibility cache even
+when every bridge request calls `getRootInActiveWindow()`.

package/docs/benchmarks/ui-tree-performance/bridge-probe.json

@@ -3,13 +3,14 @@
   "device_id": "[redacted]",
   "fixture": "latency-journey-app",
   "network_freshness_passed": true,
+  "silent_timer_freshness_passed": true,
   "bridge": {
     "samples": {
       "count": 10,
-      "p50": 6.830375,
-      "p95": 14.933042,
-      "min": 5.825959,
-      "max": 14.933042
+      "p50": 3.122458,
+      "p95": 4.390417,
+      "min": 2.858792,
+      "max": 4.390417
     },
     "node_count": 7,
     "identified_nodes": 4
@@ -17,10 +18,10 @@
   "legacy": {
     "samples": {
       "count": 10,
-      "p50": 2115.17675,
-      "p95": 2611.298541,
-      "min": 2042.091,
-      "max": 2611.298541
+      "p50": 2101.953208,
+      "p95": 2257.736083,
+      "min": 2021.97375,
+      "max": 2257.736083
     },
     "node_count": 7,
     "identified_nodes": 4

package/docs/tools/observe.md

@@ -92,7 +92,8 @@ Notes:
 - Elements may also include platform-native identity hints such as `stable_id`, `role`, `test_tag`, `selector`, and `semantic`.
 - The tree response may include `snapshot_revision`, `captured_at_ms`, and `loading_state` when a reliable signal is available.
 - Prefer `wait_for_ui` for deterministic element resolution in interactive flows.
-- Android can use the experimental persistent hierarchy reader by setting `MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK` to the absolute path of a locally built bridge APK before starting the server. Build it with `npx tsx test/fixtures/ui-tree-bridge/build.ts`. The server installs the helper on first use, reads a fresh accessibility root for every request, and falls back to `uiautomator dump` after stopping the helper if the bridge fails. The helper holds Android's UiAutomation connection while the server runs, so other `uiautomator dump` clients may fail during that time. Leave the variable unset for the default reader. To reproduce the device probe, set `LATENCY_DEVICE_ID` and run `npx tsx test/device/automated/ui-tree-performance/bridge-probe.ts`.
+- Android 14+ can use the experimental persistent hierarchy reader. Build its APK with `npx tsx test/fixtures/ui-tree-bridge/build.ts`, then set `MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK` to its absolute path before starting the server. The reader clears Android's accessibility cache before every tree read, including when a screen changes without an accessibility event. Older Android versions use `uiautomator dump`.
+- If the bridge fails, the server stops it before falling back to `uiautomator dump`. While running, the bridge holds Android's UiAutomation connection, so other `uiautomator dump` clients may fail. Leave the variable unset for the default reader. To reproduce the device probe, set `LATENCY_DEVICE_ID` and run `npx tsx test/device/automated/ui-tree-performance/bridge-probe.ts`.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.32.1",
+  "version": "0.32.2",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {

package/src/observe/android-tree-bridge.ts

@@ -20,6 +20,7 @@ interface Bridge {
 const active = new Map<string, Bridge>()
 const starting = new Map<string, Promise<Bridge>>()
 const stopping = new Map<string, Promise<void>>()
+const bridgeSupport = new Map<string, boolean>()
 
 export function androidTreeBridgeEnabled(): boolean {
   return Boolean(process.env.MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK)
@@ -150,6 +151,13 @@ export async function readAndroidTreeFromBridge(deviceId: string): Promise<strin
   if (!apk) return null
   let bridge: Bridge | undefined
   try {
+    let supported = bridgeSupport.get(deviceId)
+    if (supported === undefined) {
+      const sdkLevel = Number(await execAdb(['shell', 'getprop', 'ro.build.version.sdk'], deviceId))
+      supported = Number.isInteger(sdkLevel) && sdkLevel >= 34
+      if (supported) bridgeSupport.set(deviceId, true)
+    }
+    if (!supported) return null
     bridge = await ensure(deviceId, apk)
     const output = await request(bridge, 'TREE', remainingBudget(10000))
     if (!output.startsWith('OK\n') || !output.includes('<hierarchy')) throw new Error('Android UI tree bridge returned invalid hierarchy output')

package/src/server-core.ts

@@ -16,7 +16,7 @@ export { wrapResponse, toolDefinitions, handleToolCall }
 
 export const serverInfo = {
   name: 'mobile-debug-mcp',
-  version: '0.32.1'
+  version: '0.32.2'
 }
 
 export function createServer() {

package/test/device/automated/ui-tree-performance/bridge-probe.ts

@@ -111,6 +111,19 @@ async function main() {
     await readyBridge()
     bridgeStarted = true
     adb('shell', 'am', 'force-stop', fixturePackage)
+    adb('shell', 'am', 'start', '-n', `${fixturePackage}/.MainActivity`, '--ez', 'silentTimer', 'true')
+    const initialDeadline = Date.now() + 5000
+    let initialTimer = false
+    while (Date.now() < initialDeadline) {
+      initialTimer = nodes((await bridgeRead()).xml).some((node) => node['@_content-desc'] === 'silent timer 0:00')
+      if (initialTimer) break
+      await sleep(50)
+    }
+    if (!initialTimer) throw new Error('Bridge did not observe the initial silent timer')
+    await sleep(2300)
+    const updatedTimer = nodes((await bridgeRead()).xml).some((node) => node['@_content-desc'] === 'silent timer 0:01')
+    if (!updatedTimer) throw new Error('Bridge reused a cached timer node after a visible update without an accessibility event')
+    adb('shell', 'am', 'force-stop', fixturePackage)
     adb('shell', 'pm', 'clear', fixturePackage)
     adb('shell', 'am', 'start', '-n', `${fixturePackage}/.MainActivity`, '--es', 'networkBaseUrl', `http://10.0.2.2:${address.port}`, '--es', 'networkRunId', runId)
     await Promise.race([requestPromise, sleep(10000).then(() => { throw new Error('Fixture request timed out') })])
@@ -164,6 +177,7 @@ async function main() {
     const report = {
       platform: 'android', device_id: '[redacted]', fixture: 'latency-journey-app',
       network_freshness_passed: true,
+      silent_timer_freshness_passed: true,
       bridge: { samples: summarize(bridgeSamples.map((sample) => sample.elapsed_ms)), node_count: bridgeNodes.length, identified_nodes: countIdentifiers(bridgeNodes) },
       legacy: { samples: summarize(legacySamples.map((sample) => sample.elapsed_ms)), node_count: legacyNodes.length, identified_nodes: countIdentifiers(legacyNodes) }
     }

package/test/fixtures/latency-journey-app/src/MainActivity.java

@@ -2,7 +2,12 @@ package dev.mobiledebugmcp.latencyfixture;
 
 import android.app.Activity;
 import android.content.Intent;
+import android.graphics.Canvas;
+import android.graphics.Color;
+import android.graphics.Paint;
 import android.os.Bundle;
+import android.view.View;
+import android.view.accessibility.AccessibilityNodeInfo;
 import android.widget.Button;
 import android.widget.LinearLayout;
 import android.widget.TextView;
@@ -30,9 +35,35 @@ public final class MainActivity extends Activity {
         super.onCreate(state);
         String networkBaseUrl = getIntent().getStringExtra("networkBaseUrl");
         String networkRunId = getIntent().getStringExtra("networkRunId");
-        if (networkBaseUrl != null && networkRunId != null) networkScreen(networkBaseUrl, networkRunId);
+        if (getIntent().getBooleanExtra("silentTimer", false)) silentTimerScreen();
+        else if (networkBaseUrl != null && networkRunId != null) networkScreen(networkBaseUrl, networkRunId);
         else home();
     }
+    private void silentTimerScreen() {
+        layout = new LinearLayout(this);
+        layout.setPadding(32, 100, 32, 32);
+        setContentView(layout);
+        SilentTimerView timer = new SilentTimerView();
+        layout.addView(timer, new LinearLayout.LayoutParams(-1, 200));
+        timer.postDelayed(() -> timer.setValue("0:01"), 2000);
+    }
+    private final class SilentTimerView extends View {
+        private final Paint paint = new Paint(Paint.ANTI_ALIAS_FLAG);
+        private String value = "0:00";
+        SilentTimerView() {
+            super(MainActivity.this);
+            setImportantForAccessibility(IMPORTANT_FOR_ACCESSIBILITY_YES);
+            paint.setColor(Color.BLACK);
+            paint.setTextSize(72);
+        }
+        // Deliberately redraw without an accessibility event to expose stale node caches.
+        void setValue(String next) { value = next; invalidate(); }
+        @Override protected void onDraw(Canvas canvas) { canvas.drawText(value, 20, 110, paint); }
+        @Override public void onInitializeAccessibilityNodeInfo(AccessibilityNodeInfo info) {
+            super.onInitializeAccessibilityNodeInfo(info);
+            info.setContentDescription("silent timer " + value);
+        }
+    }
     private void networkScreen(String baseUrl, String runId) {
         layout = new LinearLayout(this);
         layout.setOrientation(LinearLayout.VERTICAL);

package/test/fixtures/ui-tree-bridge/src/TreeInstrumentation.java

@@ -4,6 +4,7 @@ import android.app.Instrumentation;
 import android.app.UiAutomation;
 import android.graphics.Rect;
 import android.os.Bundle;
+import android.os.Build;
 import android.util.Xml;
 import android.util.Log;
 import android.view.accessibility.AccessibilityNodeInfo;
@@ -47,13 +48,19 @@ public final class TreeInstrumentation extends Instrumentation {
           if (!"TREE".equals(command)) {
             output.write("ERROR invalid_command\n");
           } else {
-            AccessibilityNodeInfo root = automation.getRootInActiveWindow();
-            if (root == null) {
-              output.write("ERROR null_root\n");
+            if (Build.VERSION.SDK_INT < 34) {
+              output.write("ERROR cache_clear_unavailable\n");
+            } else if (!automation.clearCache()) {
+              output.write("ERROR cache_clear_failed\n");
             } else {
-              output.write("OK\n");
-              output.write(serialize(root));
-              root.recycle();
+              AccessibilityNodeInfo root = automation.getRootInActiveWindow();
+              if (root == null) {
+                output.write("ERROR null_root\n");
+              } else {
+                output.write("OK\n");
+                output.write(serialize(root));
+                root.recycle();
+              }
             }
           }
           output.flush();

package/test/unit/observe/android_tree_bridge_cleanup.test.ts

@@ -11,7 +11,8 @@ async function run() {
   const adbPath = path.join(directory, 'adb')
   const apkPath = path.join(directory, 'bridge.apk')
   const launchesPath = path.join(directory, 'launches')
-  const previous = new Map(['ADB_PATH', 'MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK', 'MCP_FAKE_BRIDGE_PORT', 'MCP_FAKE_BRIDGE_LAUNCHES', 'MCP_FAKE_FORCE_STOP_FAIL'].map((key) => [key, process.env[key]]))
+  const getpropsPath = path.join(directory, 'getprops')
+  const previous = new Map(['ADB_PATH', 'MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK', 'MCP_FAKE_BRIDGE_PORT', 'MCP_FAKE_BRIDGE_LAUNCHES', 'MCP_FAKE_BRIDGE_GETPROPS', 'MCP_FAKE_FORCE_STOP_FAIL', 'MCP_FAKE_SDK'].map((key) => [key, process.env[key]]))
   let invalidTree = false
   const sockets = new Set<Socket>()
   const server = createServer((socket) => {
@@ -26,6 +27,7 @@ async function run() {
   })
   writeFileSync(apkPath, '')
   writeFileSync(launchesPath, '')
+  writeFileSync(getpropsPath, '')
   writeFileSync(adbPath, `#!/usr/bin/env node
 const fs = require('node:fs')
 const args = process.argv.slice(2).join(' ')
@@ -36,6 +38,9 @@ if (args.includes('am instrument')) {
   process.exit(1)
 } else if (args.includes('forward tcp:0')) {
   console.log(process.env.MCP_FAKE_BRIDGE_PORT)
+} else if (args.includes('getprop ro.build.version.sdk')) {
+  fs.appendFileSync(process.env.MCP_FAKE_BRIDGE_GETPROPS, 'getprop\\n')
+  console.log(process.env.MCP_FAKE_SDK || '36')
 }
 `)
   chmodSync(adbPath, 0o755)
@@ -46,6 +51,7 @@ if (args.includes('am instrument')) {
   process.env.MOBILE_DEBUG_MCP_ANDROID_TREE_BRIDGE_APK = apkPath
   process.env.MCP_FAKE_BRIDGE_PORT = String(address.port)
   process.env.MCP_FAKE_BRIDGE_LAUNCHES = launchesPath
+  process.env.MCP_FAKE_BRIDGE_GETPROPS = getpropsPath
   try {
     assert.match(await readAndroidTreeFromBridge('test-device') ?? '', /<hierarchy>/)
     invalidTree = true
@@ -62,6 +68,19 @@ if (args.includes('am instrument')) {
     assert.equal(readFileSync(launchesPath, 'utf8').trim().split('\n').length, 2)
     invalidTree = true
     assert.equal(await readAndroidTreeFromBridge('test-device'), null, 'clean shutdown permits legacy fallback')
+    process.env.MCP_FAKE_SDK = '33'
+    assert.equal(await readAndroidTreeFromBridge('old-device'), null, 'older Android versions use the legacy reader')
+    assert.equal(await readAndroidTreeFromBridge('old-device'), null)
+    assert.equal(readFileSync(getpropsPath, 'utf8').trim().split('\n').length, 3, 'unsupported devices recheck SDK support')
+    process.env.MCP_FAKE_SDK = '36'
+    invalidTree = false
+    assert.match(await readAndroidTreeFromBridge('old-device') ?? '', /<hierarchy>/, 'a newly supported device can start the bridge')
+    for (let attempt = 0; attempt < 20 && readFileSync(launchesPath, 'utf8').trim().split('\n').length < 3; attempt++) {
+      await new Promise((resolve) => setTimeout(resolve, 50))
+    }
+    assert.equal(readFileSync(launchesPath, 'utf8').trim().split('\n').length, 3)
+    invalidTree = true
+    assert.equal(await readAndroidTreeFromBridge('old-device'), null, 'the new bridge shuts down before fallback')
   } finally {
     for (const [key, value] of previous) {
       if (value === undefined) delete process.env[key]