mobile-debug-mcp 0.29.0 → 0.30.1

package/src/observe/snapshot-metadata.ts

@@ -1,9 +1,10 @@
 import crypto from 'crypto'
-import type { GetUITreeResponse, LoadingState, UIElement } from '../types.js'
+import type { GetUITreeResponse, LoadingState, SnapshotDelta, UIElement } from '../types.js'
 
 interface SnapshotState {
   revision: number
   signature: string | null
+  elementSignatures: Map<string, string>
 }
 
 const snapshotStateByDevice = new Map<string, SnapshotState>()
@@ -38,6 +39,63 @@ function stableElementSignature(element: UIElement) {
   }
 }
 
+function stableElementIdentity(element: UIElement, index: number) {
+  const stableId = normalize(element.stable_id)
+  if (stableId) return `stable:${stableId}`
+
+  return `fallback:${crypto.createHash('sha1').update(JSON.stringify({
+    text: normalize(element.text),
+    contentDescription: normalize(element.contentDescription),
+    resourceId: normalize(element.resourceId),
+    type: normalize(element.type),
+    bounds: normalizeBounds(element.bounds),
+    index
+  })).digest('hex')}`
+}
+
+function buildElementSignatures(tree: Pick<GetUITreeResponse, 'elements'> | null | undefined) {
+  const signatures = new Map<string, string>()
+  const elements = Array.isArray(tree?.elements) ? tree!.elements! : []
+
+  for (let index = 0; index < elements.length; index++) {
+    const element = elements[index]
+    if (!element) continue
+    const identity = stableElementIdentity(element, index)
+    signatures.set(identity, crypto.createHash('sha1').update(JSON.stringify(stableElementSignature(element))).digest('hex'))
+  }
+
+  return signatures
+}
+
+function summarizeSnapshotDelta(previous: SnapshotState | undefined, currentElements: Map<string, string>): SnapshotDelta | null {
+  if (!previous) return null
+
+  let added = 0
+  let removed = 0
+  let mutated = 0
+
+  for (const [identity, signature] of currentElements.entries()) {
+    const previousSignature = previous.elementSignatures.get(identity)
+    if (previousSignature === undefined) {
+      added++
+    } else if (previousSignature !== signature) {
+      mutated++
+    }
+  }
+
+  for (const identity of previous.elementSignatures.keys()) {
+    if (!currentElements.has(identity)) removed++
+  }
+
+  return {
+    previous_snapshot_revision: previous.revision,
+    added_elements: added,
+    removed_elements: removed,
+    mutated_elements: mutated,
+    total_elements: currentElements.size
+  }
+}
+
 export function computeSnapshotSignature(tree: Pick<GetUITreeResponse, 'elements' | 'screen' | 'resolution' | 'error'> | null | undefined): string | null {
   if (!tree || tree.error) return null
 
@@ -83,6 +141,10 @@ export function deriveSnapshotMetadata(
 ) {
   const signature = signatureOverride ?? computeSnapshotSignature(tree)
   const previous = snapshotStateByDevice.get(deviceKey)
+  const hasValidTree = !!tree && !tree.error
+  const currentElementSignatures = hasValidTree
+    ? buildElementSignatures(tree)
+    : previous?.elementSignatures ?? new Map<string, string>()
 
   let revision = 1
   if (previous) {
@@ -93,11 +155,16 @@ export function deriveSnapshotMetadata(
     }
   }
 
-  snapshotStateByDevice.set(deviceKey, { revision, signature })
+  snapshotStateByDevice.set(deviceKey, {
+    revision,
+    signature,
+    elementSignatures: currentElementSignatures
+  })
 
   return {
     snapshot_revision: revision,
     captured_at_ms: Date.now(),
+    snapshot_delta: hasValidTree ? summarizeSnapshotDelta(previous, currentElementSignatures) : null,
     loading_state: detectLoadingState(tree, source)
   }
 }

package/src/server/tool-definitions.ts

@@ -244,7 +244,7 @@ Failure Handling:
   },
   {
     name: 'capture_debug_snapshot',
-    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.',
+    description: 'Capture a complete debug snapshot (raw observation layer plus optional derived semantic layer). Returns structured JSON with snapshot_revision, captured_at_ms, snapshot_delta, and loading_state when detectable.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -295,7 +295,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 with snapshot metadata when available.',
+    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 and incremental delta signals when available.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -376,11 +376,14 @@ Inputs:
 - expected_change (optional): hierarchy_diff, text_change, or state_change
 - timeout_ms (optional)
 - stability_window_ms (optional)
+- scope (optional): screen or subtree
+- target (optional): element_id when scope=subtree
 
 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.
+- Scoped waits return scope-aware stability metadata and a lightweight change summary.
 
 Failure Handling:
 - TIMEOUT means the UI did not change in a stable way within the allotted time.`,
@@ -390,8 +393,10 @@ Failure Handling:
         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' },
+        scope: { type: 'string', enum: ['screen', 'subtree'], default: 'screen', description: 'Synchronization scope for the wait' },
+        target: { type: 'string', description: 'Target element_id when scope is subtree' },
         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 }
+        stability_window_ms: { type: 'number', description: 'How long the change must remain stable before success (default 300)', default: 300 }
       }
     }
   },

package/src/server/tool-handlers.ts

@@ -319,9 +319,11 @@ 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 stability_window_ms = getNumberArg(args, 'stability_window_ms') ?? 300
   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 })
+  const scope = getStringArg(args, 'scope') as 'screen' | 'subtree' | undefined
+  const target = getStringArg(args, 'target')
+  const res = await ToolsInteract.waitForUIChangeHandler({ platform, deviceId, timeout_ms, stability_window_ms, expected_change, scope, target })
   return wrapResponse(res)
 }
 

package/src/server-core.ts

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

package/src/types.ts

@@ -152,6 +152,14 @@ export interface LoadingState {
   source: string;
 }
 
+export interface SnapshotDelta {
+  previous_snapshot_revision: number | null;
+  added_elements: number;
+  removed_elements: number;
+  mutated_elements: number;
+  total_elements: number;
+}
+
 export interface CaptureAndroidScreenResponse {
   device: DeviceInfo;
   screenshot: string; // base64 encoded string
@@ -207,6 +215,7 @@ export interface GetUITreeResponse {
   elements: UIElement[];
   snapshot_revision: number;
   captured_at_ms: number;
+  snapshot_delta?: SnapshotDelta | null;
   loading_state?: LoadingState | null;
   error?: string;
 }
@@ -231,6 +240,7 @@ export interface CaptureDebugSnapshotRawResponse {
   timestamp: number;
   snapshot_revision: number;
   captured_at_ms: number;
+  snapshot_delta?: SnapshotDelta | null;
   reason: string;
   activity: string | null;
   fingerprint: string | null;
@@ -497,11 +507,25 @@ export interface WaitForUIChangeResponse {
   success: boolean;
   observed_change: 'hierarchy_diff' | 'text_change' | 'state_change' | null;
   snapshot_revision?: number;
+  snapshot_freshness_ms?: number | null;
+  scope?: 'screen' | 'subtree';
+  target?: string | null;
+  stability_state?: 'transient' | 'stable';
+  change_summary?: {
+    total_elements: number;
+    added_elements: number;
+    removed_elements: number;
+    mutated_elements: number;
+  } | null;
   timeout: boolean;
   elapsed_ms: number;
   expected_change?: 'hierarchy_diff' | 'text_change' | 'state_change';
   reason?: string;
   loading_state?: LoadingState | null;
+  error?: {
+    code: 'INVALID_SCOPE' | 'ELEMENT_NOT_FOUND';
+    message: string;
+  };
 }
 
 export interface SwipeResponse {

package/test/unit/interact/adjust_control.test.ts

@@ -263,6 +263,110 @@ async function run() {
     assert.strictEqual(swipeCalls.length, 0)
     assert.ok(tapCalls[3].x > 2750, 'wide, high-range control should not be clamped to a 3% endpoint margin')
 
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock-device', osVersion: '14', model: 'Pixel', simulator: true },
+      screen: '',
+      resolution: { width: 1080, height: 2400 },
+      elements: [
+        {
+          text: 'Duration',
+          type: 'android.widget.SeekBar',
+          contentDescription: null,
+          clickable: true,
+          enabled: false,
+          visible: true,
+          bounds: [0, 0, 200, 40],
+          resourceId: 'seek_duration',
+          state: {
+            value: 10,
+            raw_value: 10,
+            value_range: { min: 0, max: 20 }
+          }
+        }
+      ]
+    })
+
+    const disabledAdjust = await ToolsInteract.adjustControlHandler({
+      element_id: wait.element.elementId,
+      property: 'value',
+      targetValue: 8,
+      tolerance: 0.5,
+      maxAttempts: 1,
+      platform: 'android'
+    })
+
+    assert.strictEqual(disabledAdjust.success, false)
+    assert.strictEqual(disabledAdjust.failure_code, 'ELEMENT_NOT_INTERACTABLE')
+
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock-device', osVersion: '14', model: 'Pixel', simulator: true },
+      screen: '',
+      resolution: { width: 1080, height: 2400 },
+      elements: [
+        {
+          text: 'Stable slider',
+          type: 'android.widget.SeekBar',
+          contentDescription: null,
+          clickable: true,
+          enabled: true,
+          visible: true,
+          bounds: [0, 0, 200, 40],
+          resourceId: 'seek_stable',
+          stable_id: 'stable-1',
+          state: {
+            value: 4,
+            raw_value: 4,
+            value_range: { min: 0, max: 10 }
+          }
+        }
+      ]
+    })
+
+    const stableWait = await ToolsInteract.waitForUIHandler({
+      selector: { text: 'Stable slider' },
+      condition: 'clickable',
+      timeout_ms: 200,
+      poll_interval_ms: 50,
+      platform: 'android'
+    })
+    assert.strictEqual(stableWait.status, 'success')
+
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock-device', osVersion: '14', model: 'Pixel', simulator: true },
+      screen: '',
+      resolution: { width: 1080, height: 2400 },
+      elements: [
+        {
+          text: 'Stable slider',
+          type: 'android.widget.SeekBar',
+          contentDescription: null,
+          clickable: true,
+          enabled: true,
+          visible: true,
+          bounds: [0, 0, 200, 40],
+          resourceId: 'seek_stable',
+          stable_id: 'stable-2',
+          state: {
+            value: 4,
+            raw_value: 4,
+            value_range: { min: 0, max: 10 }
+          }
+        }
+      ]
+    })
+
+    const staleAdjust = await ToolsInteract.adjustControlHandler({
+      element_id: stableWait.element.elementId,
+      property: 'value',
+      targetValue: 6,
+      tolerance: 0.5,
+      maxAttempts: 1,
+      platform: 'android'
+    })
+
+    assert.strictEqual(staleAdjust.success, false)
+    assert.strictEqual(staleAdjust.failure_code, 'STALE_REFERENCE')
+
     let treeFetches = 0
     let retryVerificationCount = 0
     ;(Observe as any).ToolsObserve.getUITreeHandler = async () => {

package/test/unit/interact/subtree_collection.test.ts

@@ -0,0 +1,24 @@
+import assert from 'assert'
+import { ToolsInteract } from '../../../src/interact/index.js'
+
+async function run() {
+  console.log('Starting subtree_collection unit tests...')
+
+  const elements = [
+    { text: 'Root', resourceId: 'root-node', stable_id: 'root-stable', bounds: [0, 0, 100, 100], visible: true, enabled: true, clickable: true },
+    { text: 'Numeric child', parentId: '0', stable_id: 'numeric-child', bounds: [0, 0, 50, 50], visible: true, enabled: true, clickable: true },
+    { text: 'Resource child', parentId: 'root-node', stable_id: 'resource-child', bounds: [0, 50, 50, 100], visible: true, enabled: true, clickable: true },
+    { text: 'Stable child', parentId: 'root-stable', stable_id: 'stable-child', bounds: [50, 0, 100, 50], visible: true, enabled: true, clickable: true },
+    { text: 'Grandchild', parentId: 'resource-child', bounds: [50, 50, 100, 100], visible: true, enabled: true, clickable: true }
+  ] as any[]
+
+  const indices = (ToolsInteract as any)._collectSubtreeIndices(elements, 0)
+  assert.deepStrictEqual(indices, [0, 1, 2, 3, 4])
+
+  console.log('subtree_collection unit tests passed')
+}
+
+run().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})

package/test/unit/interact/tap_element.test.ts

@@ -84,6 +84,77 @@ async function run() {
     assert.strictEqual(disabledResult.success, false)
     assert.strictEqual(disabledResult.failure_code, 'ELEMENT_NOT_INTERACTABLE')
 
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock-device' },
+      elements: [
+        { text: 'Plain label', resourceId: 'txt_plain', bounds: [0, 0, 20, 20], visible: true, enabled: true, clickable: false }
+      ]
+    })
+    const waitPlain = await ToolsInteract.waitForUIHandler({
+      selector: { text: 'Plain label' },
+      condition: 'exists',
+      timeout_ms: 200,
+      poll_interval_ms: 50,
+      platform: 'android'
+    })
+    const plainResult = await ToolsInteract.tapElementHandler({ elementId: waitPlain.element.elementId })
+    assert.strictEqual(plainResult.success, false)
+    assert.strictEqual(plainResult.failure_code, 'ELEMENT_NOT_INTERACTABLE')
+
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
+      device: { platform: 'ios', id: 'ios-mock' },
+      elements: [
+        {
+          text: 'Semantic tap',
+          resourceId: 'ios_semantic_tap',
+          bounds: [10, 10, 30, 30],
+          visible: true,
+          enabled: true,
+          clickable: false,
+          semantic: {
+            is_clickable: true,
+            is_container: false,
+            supported_actions: ['tap']
+          }
+        }
+      ]
+    })
+    const iosSemanticWait = await ToolsInteract.waitForUIHandler({
+      selector: { text: 'Semantic tap' },
+      condition: 'exists',
+      timeout_ms: 200,
+      poll_interval_ms: 50,
+      platform: 'ios'
+    })
+    const iosSemanticTap = await ToolsInteract.tapElementHandler({ elementId: iosSemanticWait.element.elementId })
+    assert.strictEqual(iosSemanticTap.success, true)
+    assert.strictEqual(iosSemanticTap.target.resolved?.elementId, iosSemanticWait.element.elementId)
+    assert.deepStrictEqual(tapped, { platform: 'ios', x: 20, y: 20, deviceId: 'ios-mock' })
+
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock-device' },
+      elements: [
+        { text: 'Stable target', resourceId: 'btn_stable', bounds: [0, 0, 20, 20], visible: true, enabled: true, clickable: true, stable_id: 'stable-1' }
+      ]
+    })
+    const waitStable = await ToolsInteract.waitForUIHandler({
+      selector: { text: 'Stable target' },
+      condition: 'exists',
+      timeout_ms: 200,
+      poll_interval_ms: 50,
+      platform: 'android'
+    })
+
+    ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
+      device: { platform: 'android', id: 'mock-device' },
+      elements: [
+        { text: 'Stable target', resourceId: 'btn_stable', bounds: [0, 0, 20, 20], visible: true, enabled: true, clickable: true, stable_id: 'stable-2' }
+      ]
+    })
+    const stableMismatchResult = await ToolsInteract.tapElementHandler({ elementId: waitStable.element.elementId })
+    assert.strictEqual(stableMismatchResult.success, false)
+    assert.strictEqual(stableMismatchResult.failure_code, 'STALE_REFERENCE')
+
     ;(Observe as any).ToolsObserve.getUITreeHandler = async () => ({
       device: { platform: 'android', id: 'mock-device' },
       elements: []