mobile-debug-mcp 0.30.0 → 0.30.1

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,6 +393,8 @@ 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 300)', default: 300 }
       }

package/src/server/tool-handlers.ts

@@ -321,7 +321,9 @@ async function handleWaitForUIChange(args: ToolCallArgs) {
   const timeout_ms = getNumberArg(args, 'timeout_ms') ?? 60000
   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.30.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: []

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

@@ -6,7 +6,18 @@ type UiTree = {
   device: { platform: 'android', id: string, osVersion: string, model: string, simulator: boolean }
   screen: string
   resolution: { width: number, height: number }
-  elements: Array<{ text: string, type: string, bounds: number[], visible: boolean }>
+  elements: Array<{
+    text: string
+    type: string
+    bounds: number[]
+    visible: boolean
+    enabled?: boolean
+    clickable?: boolean
+    stable_id?: string
+    parentId?: number
+    children?: number[]
+    state?: Record<string, unknown> | null
+  }>
   snapshot_revision: number
   captured_at_ms: number
 }
@@ -22,6 +33,21 @@ function makeTree(screen: string, revision: number): UiTree {
   }
 }
 
+function makeScopedTree(title: string, status: string, revision: number): UiTree {
+  return {
+    device: { platform: 'android', id: 'mock', osVersion: '14', model: 'Pixel', simulator: true },
+    screen: 'Scoped',
+    resolution: { width: 1080, height: 2400 },
+    elements: [
+      { text: 'Root', type: 'FrameLayout', bounds: [0, 0, 1080, 2400], visible: true, enabled: true, stable_id: 'root', children: [1, 2] },
+      { text: title, type: 'TextView', bounds: [0, 0, 1080, 200], visible: true, enabled: true, stable_id: 'title', parentId: 0, state: { text_value: title } },
+      { text: status, type: 'TextView', bounds: [0, 200, 1080, 260], visible: true, enabled: true, stable_id: 'status', parentId: 0, state: { text_value: status } }
+    ],
+    snapshot_revision: revision,
+    captured_at_ms: 1000 + revision
+  }
+}
+
 async function runScenario({
   snapshots,
   expectedChange,
@@ -72,6 +98,62 @@ async function runScenario({
   }
 }
 
+async function runScopedScenario() {
+  const snapshots = [
+    makeScopedTree('Title', 'Status 1', 1),
+    makeScopedTree('Title', 'Status 2', 2),
+    makeScopedTree('Title Ready', 'Status 2', 3),
+    makeScopedTree('Title Ready', 'Status 2', 4)
+  ]
+
+  const originalGetUITreeHandler = (ToolsObserve as any).getUITreeHandler
+  const originalSetTimeout = globalThis.setTimeout
+  const originalDateNow = Date.now
+  let now = 0
+  let calls = 0
+
+  try {
+    ;(Date as any).now = () => now
+    ;(globalThis as any).setTimeout = (callback: (...args: any[]) => void) => {
+      now += 1
+      callback()
+      return 0
+    }
+
+    ;(ToolsObserve as any).getUITreeHandler = async () => snapshots[Math.min(calls++, snapshots.length - 1)]
+
+    const resolution = await ToolsInteract.waitForUIHandler({
+      selector: { text: 'Title' },
+      condition: 'exists',
+      timeout_ms: 1000,
+      poll_interval_ms: 1,
+      platform: 'android',
+      deviceId: 'mock'
+    })
+
+    const targetId = resolution?.element?.elementId
+    assert.ok(targetId)
+
+    calls = 0
+    now = 0
+    const result = await ToolsInteract.waitForUIChangeHandler({
+      platform: 'android',
+      deviceId: 'mock',
+      expected_change: 'text_change',
+      scope: 'subtree',
+      target: targetId,
+      timeout_ms: 2000,
+      stability_window_ms: 1
+    })
+
+    return { result, targetId, calls }
+  } finally {
+    ;(ToolsObserve as any).getUITreeHandler = originalGetUITreeHandler
+    ;(globalThis as any).setTimeout = originalSetTimeout
+    ;(Date as any).now = originalDateNow
+  }
+}
+
 async function run() {
   const success = await runScenario({
     snapshots: [makeTree('Loading', 1), makeTree('Loaded', 2)],
@@ -109,6 +191,15 @@ async function run() {
   assert.strictEqual(defaultWindow.calls, 4)
   assert.deepStrictEqual(defaultWindow.delays, [300, 300, 300])
 
+  const scoped = await runScopedScenario()
+  assert.strictEqual(scoped.result.success, true)
+  assert.strictEqual(scoped.result.scope, 'subtree')
+  assert.strictEqual(scoped.result.target, scoped.targetId)
+  assert.strictEqual(scoped.result.observed_change, 'text_change')
+  assert.strictEqual(scoped.result.change_summary?.added_elements, 0)
+  assert.strictEqual(scoped.result.change_summary?.removed_elements, 0)
+  assert.strictEqual(scoped.result.stability_state, 'stable')
+
   const resetWindow = await runScenario({
     snapshots: [makeTree('Loading', 1), makeTree('Loaded', 2), makeTree('Loaded-again', 3), makeTree('Loaded-again', 4), makeTree('Loaded-again', 5)],
     expectedChange: 'text_change',

package/test/unit/observe/snapshot_metadata.test.ts

@@ -0,0 +1,67 @@
+import assert from 'assert'
+import { deriveSnapshotMetadata, resetSnapshotMetadataForTests } from '../../../src/observe/snapshot-metadata.js'
+
+async function run() {
+  console.log('Starting snapshot_metadata unit tests...')
+
+  resetSnapshotMetadataForTests()
+
+  const deviceKey = 'android:mock'
+  const first = deriveSnapshotMetadata(deviceKey, {
+    screen: 'Home',
+    resolution: { width: 100, height: 200 },
+    elements: [
+      {
+        text: 'Alpha',
+        contentDescription: null,
+        resourceId: 'row_1',
+        type: 'TextView',
+        clickable: false,
+        enabled: true,
+        visible: true,
+        bounds: [0, 0, 10, 10],
+        state: null,
+        stable_id: 'stable-row'
+      }
+    ]
+  }, 'ui_tree')
+
+  assert.strictEqual(first.snapshot_revision, 1)
+  assert.strictEqual(first.snapshot_delta, null)
+
+  const second = deriveSnapshotMetadata(deviceKey, {
+    screen: 'Home',
+    resolution: { width: 100, height: 200 },
+    elements: [
+      {
+        text: 'Beta',
+        contentDescription: null,
+        resourceId: 'row_1',
+        type: 'TextView',
+        clickable: false,
+        enabled: true,
+        visible: true,
+        bounds: [0, 0, 10, 10],
+        state: null,
+        stable_id: 'stable-row'
+      }
+    ]
+  }, 'ui_tree')
+
+  assert.strictEqual(second.snapshot_revision, 2)
+  assert.deepStrictEqual(second.snapshot_delta, {
+    previous_snapshot_revision: 1,
+    added_elements: 0,
+    removed_elements: 0,
+    mutated_elements: 1,
+    total_elements: 1
+  })
+
+  resetSnapshotMetadataForTests()
+  console.log('snapshot_metadata unit tests passed')
+}
+
+run().catch((error) => {
+  console.error(error)
+  process.exit(1)
+})