mobile-debug-mcp 0.30.0 → 0.30.2

package/src/observe/index.ts

@@ -358,6 +358,7 @@ export class ToolsObserve {
 
     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.snapshot_delta = raw.ui_tree?.snapshot_delta ?? snapshotMetadata.snapshot_delta ?? null
     raw.loading_state = raw.ui_tree?.loading_state ?? snapshotMetadata.loading_state
 
     const semantic = deriveSnapshotSemantic(raw)

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,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 }
       }
@@ -563,11 +568,11 @@ Adjust a numeric control value with verification.
 This is the initial adjustable-control surface for slider-like controls and other controls that expose a numeric value or value_range.
 
 Inputs:
-- selector or element_id
+- exactly one of selector or element_id
 - property (defaults to "value")
 - targetValue
-- tolerance (optional)
-- maxAttempts (optional)
+- tolerance (optional; discrete default is 0, continuous default is max(step / 2, 1% of range) when omitted)
+- maxAttempts (optional; defaults to 5)
 - platform/deviceId (optional)
 
 Output Structure:
@@ -579,14 +584,14 @@ Output Structure:
 - success = true when the control converges within tolerance
 
 Verification Guidance:
-- Prefer direct target placement when value_range is available; fall back to a drag only if the direct tap does not converge
+- Prefer direct platform adjustment when the runtime exposes it; then verified increment/decrement actions; use coordinate fallback only as degraded mode
 - Use expect_state for the control value readback
-- Treat coordinate fallback as degraded mode
+- Do not use derived semantic metadata as proof of success
 
 Failure Handling:
 - ELEMENT_NOT_FOUND → re-resolve the control
 - ELEMENT_NOT_INTERACTABLE → the control cannot be adjusted through the current runtime
-- TIMEOUT → the control did not converge within bounded retries
+- CONTROL_CONVERGENCE_FAILED → the control did not converge within bounded retries or the requested value is out of range
 - UNKNOWN → capture a snapshot and stop`,
     inputSchema: {
       type: 'object',
@@ -603,12 +608,16 @@ Failure Handling:
         element_id: { type: 'string', description: 'Optional previously resolved element identifier.' },
         property: { type: 'string', description: 'Readable numeric state property to adjust.', default: 'value' },
         targetValue: { type: 'number', description: 'Target numeric value.' },
-        tolerance: { type: 'number', description: 'Accepted numeric tolerance around the target value.', default: 0 },
-        maxAttempts: { type: 'number', description: 'Maximum adjustment attempts.', default: 3 },
+        tolerance: { type: 'number', description: 'Accepted numeric tolerance around the target value. Defaults are derived from the readable control domain.' },
+        maxAttempts: { type: 'number', description: 'Maximum adjustment attempts.', default: 5 },
         platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override' },
         deviceId: { type: 'string', description: 'Optional device serial/udid' }
       },
-      required: ['targetValue']
+      required: ['targetValue'],
+      oneOf: [
+        { required: ['selector'] },
+        { required: ['element_id'] }
+      ]
     }
   },
   {

package/src/server/tool-handlers.ts

@@ -282,12 +282,12 @@ async function handleAdjustControl(args: ToolCallArgs) {
   const element_id = getStringArg(args, 'element_id')
   const property = getStringArg(args, 'property') ?? 'value'
   const targetValue = requireNumberArg(args, 'targetValue')
-  const tolerance = getNumberArg(args, 'tolerance') ?? 0
-  const maxAttempts = getNumberArg(args, 'maxAttempts') ?? 3
+  const tolerance = getNumberArg(args, 'tolerance')
+  const maxAttempts = getNumberArg(args, 'maxAttempts')
   const platform = getStringArg(args, 'platform') as PlatformArg | undefined
   const deviceId = getStringArg(args, 'deviceId')
-  if (!selector && !element_id) {
-    throw new Error('Missing selector or element_id argument')
+  if ((!selector && !element_id) || (selector && element_id)) {
+    throw new Error('Exactly one of selector or element_id argument is required')
   }
   const res = await ToolsInteract.adjustControlHandler({
     selector: selector ?? undefined,
@@ -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.2'
 }
 
 export function createServer() {

package/src/types.ts

@@ -91,7 +91,9 @@ export interface UIElementState {
   value_range?: {
     min: number;
     max: number;
+    step?: number | null;
   } | null;
+  step?: number | null;
 }
 
 export interface SelectorConfidence {
@@ -152,6 +154,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 +217,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 +242,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 +509,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 {