mobile-debug-mcp 0.25.1 → 0.26.0

package/src/observe/android.ts

@@ -7,6 +7,7 @@ import { promises as fsPromises } from "fs"
 import path from "path"
 import { computeScreenFingerprint } from "../utils/ui/index.js"
 import { parsePngSize } from "../utils/image.js"
+import { deriveSnapshotMetadata } from "./snapshot-metadata.js"
 
 const activeLogStreams: Map<string, { proc: any, file: string }> = new Map()
 
@@ -74,20 +75,29 @@ export class AndroidObserve {
           }
       }
 
+      const snapshotMetadata = deriveSnapshotMetadata(`android:${deviceInfo.id}`, {
+        screen: "",
+        resolution,
+        elements
+      }, 'ui_tree')
+
       return {
         device: deviceInfo,
         screen: "",
         resolution,
-        elements
+        elements,
+        ...snapshotMetadata
       };
     } catch (e) {
       const errorMessage = `Failed to get UI tree. ADB Path: '${getAdbCmd()}'. Error: ${e instanceof Error ? e.message : String(e)}`;
       console.error(errorMessage);
+      const snapshotMetadata = deriveSnapshotMetadata(`android:${deviceInfo.id}`, null, 'ui_tree')
       return {
           device: deviceInfo,
           screen: "",
           resolution: { width: 0, height: 0 },
           elements: [],
+          ...snapshotMetadata,
           error: errorMessage
       };
     }

package/src/observe/index.ts

@@ -5,6 +5,7 @@ import type {
   CaptureDebugSnapshotRawResponse,
   SnapshotSemanticResponse
 } from '../types.js'
+import { deriveSnapshotMetadata } from './snapshot-metadata.js'
 
 export { AndroidObserve } from './android.js'
 export { iOSObserve } from './ios.js'
@@ -245,7 +246,17 @@ export class ToolsObserve {
 
   static async captureDebugSnapshotHandler({ reason, includeLogs = true, logLines = 200, platform, appId, deviceId, sessionId }: { reason?: string; includeLogs?: boolean; logLines?: number; platform?: 'android' | 'ios'; appId?: string; deviceId?: string; sessionId?: string } = {}) {
     const timestamp = Date.now()
-    const raw: CaptureDebugSnapshotRawResponse = { timestamp, reason: reason || '', activity: null, fingerprint: null, screenshot: null, ui_tree: null, logs: [] }
+    const raw: CaptureDebugSnapshotRawResponse = {
+      timestamp,
+      snapshot_revision: 0,
+      captured_at_ms: timestamp,
+      reason: reason || '',
+      activity: null,
+      fingerprint: null,
+      screenshot: null,
+      ui_tree: null,
+      logs: []
+    }
 
     // Parallel fetches for performance: screenshot, current screen, fingerprint, ui tree, and log stream/get logs
     const sid = sessionId || 'default'
@@ -335,6 +346,20 @@ export class ToolsObserve {
       }
     }
 
+    const snapshotDeviceKey = raw.ui_tree?.device
+      ? `${raw.ui_tree.device.platform}:${raw.ui_tree.device.id}`
+      : `${platform || 'unknown'}:${deviceId || 'default'}`
+    const snapshotMetadata = deriveSnapshotMetadata(
+      snapshotDeviceKey,
+      raw.ui_tree,
+      'snapshot',
+      raw.ui_tree?.snapshot_revision ? null : (raw.fingerprint || raw.activity || null)
+    )
+
+    raw.snapshot_revision = raw.ui_tree?.snapshot_revision ?? snapshotMetadata.snapshot_revision
+    raw.captured_at_ms = raw.ui_tree?.captured_at_ms ?? snapshotMetadata.captured_at_ms
+    raw.loading_state = raw.ui_tree?.loading_state ?? snapshotMetadata.loading_state
+
     const semantic = deriveSnapshotSemantic(raw)
     return semantic ? { raw, semantic } : { raw }
   }

package/src/observe/ios.ts

@@ -7,6 +7,7 @@ import path from 'path'
 import { parseLogLine } from '../utils/android/utils.js'
 import { computeScreenFingerprint } from '../utils/ui/index.js'
 import { parsePngSize } from '../utils/image.js'
+import { deriveSnapshotMetadata } from './snapshot-metadata.js'
 
 const delay = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));
 let iosExecCommand = execCommand
@@ -485,16 +486,19 @@ export class iOSObserve {
 
   async getUITree(deviceId: string = "booted"): Promise<GetUITreeResponse> {
     const device = await getIOSDeviceMetadata(deviceId);
+    const deviceKey = `ios:${device.id}`
     
     const idbExists = await isIDBInstalled();
     if (!idbExists) {
+       const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree')
        return {
           device,
           screen: "",
           resolution: { width: 0, height: 0 },
           elements: [],
+          ...snapshotMetadata,
           error: "iOS UI tree retrieval requires 'idb' (iOS Device Bridge). Please install it via Homebrew: `brew tap facebook/fb && brew install idb-companion` and `pip3 install fb-idb`."
-       };
+        };
     }
 
     const targetUdid = (device.id && device.id !== 'booted') ? device.id : undefined;
@@ -540,15 +544,17 @@ export class iOSObserve {
          console.error(`Attempt ${attempts} failed: ${e}`);
       }
       
-      if (attempts === maxAttempts) {
-          return {
-              device,
-              screen: "",
-              resolution: { width: 0, height: 0 },
-              elements: [],
-              error: `Failed to retrieve valid UI dump after ${maxAttempts} attempts.`
-          };
-      }
+       if (attempts === maxAttempts) {
+           const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree')
+           return {
+               device,
+               screen: "",
+               resolution: { width: 0, height: 0 },
+               elements: [],
+               ...snapshotMetadata,
+               error: `Failed to retrieve valid UI dump after ${maxAttempts} attempts.`
+           };
+       }
     }
 
     try {
@@ -569,20 +575,29 @@ export class iOSObserve {
             height = rootBounds[3] - rootBounds[1];
         }
 
+        const snapshotMetadata = deriveSnapshotMetadata(deviceKey, {
+          screen: "",
+          resolution: { width, height },
+          elements
+        }, 'ui_tree')
+
         return {
             device,
             screen: "",
             resolution: { width, height },
-            elements
+            elements,
+            ...snapshotMetadata
         };
     } catch (e) {
-         return {
+         const snapshotMetadata = deriveSnapshotMetadata(deviceKey, null, 'ui_tree')
+          return {
             device,
             screen: "",
             resolution: { width: 0, height: 0 },
             elements: [],
+            ...snapshotMetadata,
             error: `Failed to parse idb output: ${e instanceof Error ? e.message : String(e)}`
-         };
+          };
     }
   }
 

package/src/observe/snapshot-metadata.ts

@@ -0,0 +1,107 @@
+import crypto from 'crypto'
+import type { GetUITreeResponse, LoadingState, UIElement } from '../types.js'
+
+interface SnapshotState {
+  revision: number
+  signature: string | null
+}
+
+const snapshotStateByDevice = new Map<string, SnapshotState>()
+
+function normalize(value: unknown): string {
+  if (value === null || value === undefined) return ''
+  return String(value).trim().toLowerCase()
+}
+
+function normalizeBounds(bounds: unknown): [number, number, number, number] | null {
+  if (!Array.isArray(bounds) || bounds.length < 4) return null
+  const normalized = bounds.slice(0, 4).map((value) => Number(value))
+  if (normalized.some((value) => Number.isNaN(value))) return null
+  return normalized as [number, number, number, number]
+}
+
+function stableElementSignature(element: UIElement) {
+  return {
+    text: normalize(element.text),
+    contentDescription: normalize(element.contentDescription),
+    resourceId: normalize(element.resourceId),
+    type: normalize(element.type),
+    stable_id: normalize(element.stable_id),
+    role: normalize(element.role),
+    test_tag: normalize(element.test_tag),
+    selector: normalize(element.selector?.value),
+    clickable: !!element.clickable,
+    enabled: !!element.enabled,
+    visible: !!element.visible,
+    state: element.state ?? null,
+    bounds: normalizeBounds(element.bounds)
+  }
+}
+
+export function computeSnapshotSignature(tree: Pick<GetUITreeResponse, 'elements' | 'screen' | 'resolution' | 'error'> | null | undefined): string | null {
+  if (!tree || tree.error) return null
+
+  const payload = {
+    screen: normalize(tree.screen),
+    resolution: tree.resolution || { width: 0, height: 0 },
+    elements: Array.isArray(tree.elements) ? tree.elements.map((element) => stableElementSignature(element)) : []
+  }
+
+  return crypto.createHash('sha256').update(JSON.stringify(payload)).digest('hex')
+}
+
+export function detectLoadingState(tree: Pick<GetUITreeResponse, 'elements' | 'error'> | null | undefined, source: string): LoadingState | null {
+  if (!tree || tree.error || !Array.isArray(tree.elements)) return null
+
+  for (const element of tree.elements) {
+    if (!element?.visible) continue
+    const text = normalize(element?.text ?? element?.contentDescription ?? '')
+    const type = normalize(element?.type ?? '')
+    const combined = `${type} ${text}`
+    if (/progress|spinner|loading|please wait|busy|loading indicator|skeleton|pending/.test(combined)) {
+      const signal = /progress/.test(combined)
+        ? 'progress_indicator'
+        : /spinner/.test(combined)
+          ? 'spinner'
+          : /busy/.test(combined)
+            ? 'busy_indicator'
+            : /skeleton/.test(combined)
+              ? 'skeleton'
+              : 'loading_indicator'
+      return { active: true, signal, source }
+    }
+  }
+
+  return null
+}
+
+export function deriveSnapshotMetadata(
+  deviceKey: string,
+  tree: Pick<GetUITreeResponse, 'elements' | 'screen' | 'resolution' | 'error'> | null | undefined,
+  source: string,
+  signatureOverride?: string | null
+) {
+  const signature = signatureOverride ?? computeSnapshotSignature(tree)
+  const previous = snapshotStateByDevice.get(deviceKey)
+
+  let revision = 1
+  if (previous) {
+    if (signature === null) {
+      revision = previous.revision
+    } else {
+      revision = previous.signature === signature ? previous.revision : previous.revision + 1
+    }
+  }
+
+  snapshotStateByDevice.set(deviceKey, { revision, signature })
+
+  return {
+    snapshot_revision: revision,
+    captured_at_ms: Date.now(),
+    loading_state: detectLoadingState(tree, source)
+  }
+}
+
+export function resetSnapshotMetadataForTests() {
+  snapshotStateByDevice.clear()
+}

package/src/server/tool-definitions.ts

@@ -240,7 +240,7 @@ Failure Handling:
   },
   {
     name: 'capture_debug_snapshot',
-    description: 'Capture a complete debug snapshot (raw observation layer plus optional derived semantic layer). Returns structured JSON.',
+    description: 'Capture a complete debug snapshot (raw observation layer plus optional derived semantic layer). Returns structured JSON with snapshot_revision, captured_at_ms, and loading_state when detectable.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -291,7 +291,7 @@ Failure Handling:
   },
   {
     name: 'get_ui_tree',
-    description: 'Get the current UI hierarchy from an Android device or iOS simulator. Returns a structured JSON representation of the screen content.',
+    description: 'Get the current UI hierarchy from an Android device or iOS simulator. Returns a structured JSON representation of the screen content with snapshot metadata when available.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -363,6 +363,34 @@ Recommended Usage:
       required: ['previousFingerprint']
     }
   },
+  {
+    name: 'wait_for_ui_change',
+    description: `Purpose:
+Wait for a non-navigation UI mutation or in-place update to become stable.
+
+Inputs:
+- expected_change (optional): hierarchy_diff, text_change, or state_change
+- timeout_ms (optional)
+- stability_window_ms (optional)
+
+Guidance:
+- Prefer wait_for_screen_change for navigation transitions.
+- Prefer wait_for_ui_change for in-place mutations and non-navigation updates.
+- Use the returned snapshot_revision as the observed synchronization point when available.
+
+Failure Handling:
+- TIMEOUT means the UI did not change in a stable way within the allotted time.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override (android|ios)' },
+        deviceId: { type: 'string', description: 'Optional device id/udid to target' },
+        expected_change: { type: 'string', enum: ['hierarchy_diff', 'text_change', 'state_change'], description: 'Optional type of UI change to wait for' },
+        timeout_ms: { type: 'number', description: 'Timeout in ms to wait for change (default 60000)', default: 60000 },
+        stability_window_ms: { type: 'number', description: 'How long the change must remain stable before success (default 250)', default: 250 }
+      }
+    }
+  },
   {
     name: 'expect_screen',
     description: `Purpose:

package/src/server/tool-handlers.ts

@@ -288,6 +288,16 @@ async function handleWaitForUI(args: ToolCallArgs) {
   return wrapResponse(res)
 }
 
+async function handleWaitForUIChange(args: ToolCallArgs) {
+  const platform = getStringArg(args, 'platform') as PlatformArg | undefined
+  const deviceId = getStringArg(args, 'deviceId')
+  const timeout_ms = getNumberArg(args, 'timeout_ms') ?? 60000
+  const stability_window_ms = getNumberArg(args, 'stability_window_ms') ?? 250
+  const expected_change = getStringArg(args, 'expected_change') as 'hierarchy_diff' | 'text_change' | 'state_change' | undefined
+  const res = await ToolsInteract.waitForUIChangeHandler({ platform, deviceId, timeout_ms, stability_window_ms, expected_change })
+  return wrapResponse(res)
+}
+
 async function handleFindElement(args: ToolCallArgs) {
   const query = requireStringArg(args, 'query')
   const exact = getBooleanArg(args, 'exact') ?? false
@@ -473,6 +483,7 @@ export const toolHandlers: Record<string, ToolHandler> = {
   get_current_screen: handleGetCurrentScreen,
   get_screen_fingerprint: handleGetScreenFingerprint,
   wait_for_screen_change: handleWaitForScreenChange,
+  wait_for_ui_change: handleWaitForUIChange,
   expect_screen: handleExpectScreen,
   expect_element_visible: handleExpectElementVisible,
   expect_state: handleExpectState,

package/src/server-core.ts

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

package/src/types.ts

@@ -109,6 +109,12 @@ export interface UIElementSemanticMetadata {
   is_container: boolean;
 }
 
+export interface LoadingState {
+  active: boolean;
+  signal: string;
+  source: string;
+}
+
 export interface CaptureAndroidScreenResponse {
   device: DeviceInfo;
   screenshot: string; // base64 encoded string
@@ -162,6 +168,9 @@ export interface GetUITreeResponse {
     height: number;
   };
   elements: UIElement[];
+  snapshot_revision: number;
+  captured_at_ms: number;
+  loading_state?: LoadingState | null;
   error?: string;
 }
 
@@ -183,12 +192,15 @@ export interface SnapshotSemanticResponse {
 
 export interface CaptureDebugSnapshotRawResponse {
   timestamp: number;
+  snapshot_revision: number;
+  captured_at_ms: number;
   reason: string;
   activity: string | null;
   fingerprint: string | null;
   screenshot: string | null;
   ui_tree: GetUITreeResponse | null;
   logs: StructuredLogEntry[];
+  loading_state?: LoadingState | null;
   device?: DeviceInfo;
   screenshot_error?: string;
   activity_error?: string;
@@ -326,6 +338,17 @@ export interface ExpectStateResponse {
   retryable?: boolean;
 }
 
+export interface WaitForUIChangeResponse {
+  success: boolean;
+  observed_change: 'hierarchy_diff' | 'text_change' | 'state_change' | null;
+  snapshot_revision?: number;
+  timeout: boolean;
+  elapsed_ms: number;
+  expected_change?: 'hierarchy_diff' | 'text_change' | 'state_change';
+  reason?: string;
+  loading_state?: LoadingState | null;
+}
+
 export interface SwipeResponse {
   device: DeviceInfo;
   success: boolean;

package/test/unit/interact/wait_for_ui_change.test.ts

@@ -0,0 +1,76 @@
+import assert from 'assert'
+import { ToolsInteract } from '../../../src/interact/index.js'
+import { ToolsObserve } from '../../../src/observe/index.js'
+
+async function run() {
+  const originalGetUITreeHandler = (ToolsObserve as any).getUITreeHandler
+
+  try {
+    let calls = 0
+    ;(ToolsObserve as any).getUITreeHandler = async () => {
+      calls++
+      if (calls === 1) {
+        return {
+          device: { platform: 'android', id: 'mock', osVersion: '14', model: 'Pixel', simulator: true },
+          screen: 'Loading',
+          resolution: { width: 1080, height: 2400 },
+          elements: [{ text: 'Loading', type: 'TextView', bounds: [0, 0, 100, 40], visible: true }],
+          snapshot_revision: 1,
+          captured_at_ms: 1000
+        }
+      }
+
+      return {
+        device: { platform: 'android', id: 'mock', osVersion: '14', model: 'Pixel', simulator: true },
+        screen: 'Loaded',
+        resolution: { width: 1080, height: 2400 },
+        elements: [{ text: 'Loaded', type: 'TextView', bounds: [0, 0, 100, 40], visible: true }],
+        snapshot_revision: 2,
+        captured_at_ms: 2000
+      }
+    }
+
+    const success = await ToolsInteract.waitForUIChangeHandler({
+      platform: 'android',
+      deviceId: 'mock',
+      expected_change: 'text_change',
+      timeout_ms: 1500,
+      stability_window_ms: 1
+    })
+
+    assert.strictEqual(success.success, true)
+    assert.strictEqual(success.observed_change, 'text_change')
+    assert.strictEqual(success.snapshot_revision, 2)
+    assert.strictEqual(success.timeout, false)
+
+    ;(ToolsObserve as any).getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock', osVersion: '14', model: 'Pixel', simulator: true },
+      screen: 'Static',
+      resolution: { width: 1080, height: 2400 },
+      elements: [{ text: 'Static', type: 'TextView', bounds: [0, 0, 100, 40], visible: true }],
+      snapshot_revision: 9,
+      captured_at_ms: 3000
+    })
+
+    const timeout = await ToolsInteract.waitForUIChangeHandler({
+      platform: 'android',
+      deviceId: 'mock',
+      expected_change: 'state_change',
+      timeout_ms: 700,
+      stability_window_ms: 1
+    })
+
+    assert.strictEqual(timeout.success, false)
+    assert.strictEqual(timeout.observed_change, null)
+    assert.strictEqual(timeout.timeout, true)
+
+    console.log('wait_for_ui_change tests passed')
+  } finally {
+    ;(ToolsObserve as any).getUITreeHandler = originalGetUITreeHandler
+  }
+}
+
+run().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/test/unit/server/response_shapes.test.ts

@@ -8,6 +8,7 @@ import { ToolsObserve } from '../../../src/observe/index.js'
 async function run() {
   const originalInstallAppHandler = (ToolsManage as any).installAppHandler
   const originalWaitForUIHandler = (ToolsInteract as any).waitForUIHandler
+  const originalWaitForUIChangeHandler = (ToolsInteract as any).waitForUIChangeHandler
   const originalTapElementHandler = (ToolsInteract as any).tapElementHandler
   const originalTapHandler = (ToolsInteract as any).tapHandler
   const originalExpectScreenHandler = (ToolsInteract as any).expectScreenHandler
@@ -145,12 +146,16 @@ async function run() {
     ;(ToolsObserve as any).getUITreeHandler = async () => ({
       device: { platform: 'android', id: 'mock', osVersion: '14', model: 'Pixel', simulator: true },
       resolution: { width: 1080, height: 2400 },
+      screen: 'Notifications',
       elements: [{
         text: 'Notifications',
         depth: 0,
         center: { x: 50, y: 20 },
         state: { checked: true, selected: 'Notifications' }
-      }]
+      }],
+      snapshot_revision: 12,
+      captured_at_ms: 1710000000123,
+      loading_state: { active: true, signal: 'progress_indicator', source: 'ui_tree' }
     })
 
     ;(ToolsInteract as any).expectStateHandler = async () => ({
@@ -227,8 +232,12 @@ async function run() {
 
     ;(ToolsObserve as any).getUITreeHandler = async () => ({
       device: { platform: 'android', id: 'mock', osVersion: '14', model: 'Pixel', simulator: true },
+      screen: 'Login',
       resolution: { width: 1080, height: 2400 },
-      elements: [{ text: 'Login', depth: 0, center: { x: 50, y: 20 } }]
+      elements: [{ text: 'Login', depth: 0, center: { x: 50, y: 20 } }],
+      snapshot_revision: 12,
+      captured_at_ms: 1710000000123,
+      loading_state: { active: true, signal: 'progress_indicator', source: 'ui_tree' }
     })
 
     const uiTreeResponse = await handleToolCall('get_ui_tree', { platform: 'android' })
@@ -236,16 +245,21 @@ async function run() {
     assert.strictEqual(uiTreePayload.elements.length, 1)
     assert.strictEqual(uiTreePayload.resolution.height, 2400)
     assert.strictEqual(uiTreePayload.elements[0].text, 'Login')
+    assert.strictEqual(uiTreePayload.snapshot_revision, 12)
+    assert.strictEqual(uiTreePayload.loading_state.signal, 'progress_indicator')
 
     ;(ToolsObserve as any).captureDebugSnapshotHandler = async () => ({
       raw: {
         timestamp: 1710000000000,
+        snapshot_revision: 12,
+        captured_at_ms: 1710000000123,
         reason: 'manual',
         activity: 'com.example.MainActivity',
         fingerprint: 'fp_raw',
         screenshot: 'base64',
-        ui_tree: { screen: 'Home', elements: [] },
+        ui_tree: { screen: 'Home', elements: [], snapshot_revision: 12, captured_at_ms: 1710000000123, loading_state: { active: true, signal: 'spinner', source: 'snapshot' } },
         logs: [],
+        loading_state: { active: true, signal: 'spinner', source: 'snapshot' },
         device: { platform: 'android', id: 'mock', osVersion: '14', model: 'Pixel', simulator: true }
       },
       semantic: {
@@ -260,13 +274,33 @@ async function run() {
     const snapshotResponse = await handleToolCall('capture_debug_snapshot', { platform: 'android' })
     const snapshotPayload = JSON.parse((snapshotResponse as any).content[0].text)
     assert.strictEqual(snapshotPayload.raw.fingerprint, 'fp_raw')
+    assert.strictEqual(snapshotPayload.raw.snapshot_revision, 12)
+    assert.strictEqual(snapshotPayload.raw.loading_state.signal, 'spinner')
     assert.strictEqual(snapshotPayload.semantic.screen, 'Home')
     assert.strictEqual(snapshotPayload.semantic.confidence, 0.8)
 
+    ;(ToolsInteract as any).waitForUIChangeHandler = async () => ({
+      success: true,
+      observed_change: 'text_change',
+      snapshot_revision: 13,
+      timeout: false,
+      elapsed_ms: 1550,
+      expected_change: 'text_change',
+      loading_state: { active: false, signal: 'spinner', source: 'ui_tree' },
+      reason: 'UI change observed'
+    })
+
+    const waitForUIChangeResponse = await handleToolCall('wait_for_ui_change', { expected_change: 'text_change' })
+    const waitForUIChangePayload = JSON.parse((waitForUIChangeResponse as any).content[0].text)
+    assert.strictEqual(waitForUIChangePayload.success, true)
+    assert.strictEqual(waitForUIChangePayload.observed_change, 'text_change')
+    assert.strictEqual(waitForUIChangePayload.snapshot_revision, 13)
+
     console.log('server response-shape tests passed')
   } finally {
     ;(ToolsManage as any).installAppHandler = originalInstallAppHandler
     ;(ToolsInteract as any).waitForUIHandler = originalWaitForUIHandler
+    ;(ToolsInteract as any).waitForUIChangeHandler = originalWaitForUIChangeHandler
     ;(ToolsInteract as any).tapElementHandler = originalTapElementHandler
     ;(ToolsInteract as any).tapHandler = originalTapHandler
     ;(ToolsInteract as any).expectScreenHandler = originalExpectScreenHandler