mobile-debug-mcp 0.24.8 → 0.25.1

package/docs/tools/observe.md

@@ -83,11 +83,13 @@ Input:
 Response (example):
 
 ```json
-{ "device": { "platform": "android", "id": "emulator-5554" }, "screen": "", "resolution": { "width": 1080, "height": 2400 }, "elements": [ { "text": "Sign in", "type": "android.widget.Button", "resourceId": "com.example:id/signin", "clickable": true, "bounds": [0,0,100,50] } ] }
+{ "device": { "platform": "android", "id": "emulator-5554" }, "screen": "", "resolution": { "width": 1080, "height": 2400 }, "elements": [ { "text": "Sign in", "type": "android.widget.Button", "resourceId": "com.example:id/signin", "clickable": true, "bounds": [0,0,100,50], "state": { "enabled": true }, "stable_id": "com.example:id/signin", "role": "button", "test_tag": "com.example:id/signin", "selector": { "value": "com.example:id/signin", "confidence": { "score": 1, "reason": "resource_id" } }, "semantic": { "is_clickable": true, "is_container": false } } ] }
 ```
 
 Notes:
 - Useful for inspection, selector development, and fallback debugging.
+- Elements may include a normalized `state` object when the platform exposes readable state such as checked, selected, focused, expanded, text input, or slider values.
+- Elements may also include platform-native identity hints such as `stable_id`, `role`, `test_tag`, `selector`, and `semantic`.
 - Prefer `wait_for_ui` for deterministic element resolution in interactive flows.
 
 ---

package/package.json

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

package/src/interact/index.ts

@@ -10,7 +10,9 @@ import type {
   ActionFailureCode,
   ActionTargetResolved,
   ExpectElementVisibleResponse,
+  ExpectStateResponse,
   ExpectScreenResponse,
+  UIElementState,
   TapElementResponse
 } from '../types.js'
 
@@ -37,6 +39,12 @@ interface UiElement {
   _index?: number
   _interactable?: boolean
   _sliderLike?: boolean
+  state?: UIElementState | null
+  stable_id?: string | null
+  role?: string | null
+  test_tag?: string | null
+  selector?: { value: string | null, confidence: { score: number, reason: string } | null } | null
+  semantic?: { is_clickable: boolean, is_container: boolean } | null
 }
 
 interface ResolvedUiElementContext {
@@ -77,6 +85,45 @@ export class ToolsInteract {
     return normalized as [number, number, number, number]
   }
 
+  private static _matchesSelector(el: UiElement, selector?: { text?: string, resource_id?: string, accessibility_id?: string, contains?: boolean }): boolean {
+    if (!selector) return false
+    const normalize = ToolsInteract._normalize
+    const containsFlag = !!selector.contains
+    const text = normalize(el.text ?? el.label ?? el.value ?? '')
+    const resourceId = normalize(el.resourceId ?? el.resourceID ?? el.id ?? '')
+    const accessibilityId = normalize(el.contentDescription ?? el.contentDesc ?? el.accessibilityLabel ?? el.label ?? '')
+
+    if (selector.text !== undefined && selector.text !== null) {
+      const q = normalize(selector.text)
+      if (containsFlag ? !text.includes(q) : text !== q) return false
+    }
+
+    if (selector.resource_id !== undefined && selector.resource_id !== null) {
+      const q = normalize(selector.resource_id)
+      if (containsFlag ? !resourceId.includes(q) : resourceId !== q) return false
+    }
+
+    if (selector.accessibility_id !== undefined && selector.accessibility_id !== null) {
+      const q = normalize(selector.accessibility_id)
+      if (containsFlag ? !accessibilityId.includes(q) : accessibilityId !== q) return false
+    }
+
+    return true
+  }
+
+  private static _findFirstMatchingElement(
+    elements: UiElement[],
+    selector?: { text?: string, resource_id?: string, accessibility_id?: string, contains?: boolean }
+  ): { el: UiElement, idx: number } | null {
+    if (!selector) return null
+    for (let i = 0; i < elements.length; i++) {
+      const el = elements[i]
+      if (!el) continue
+      if (ToolsInteract._matchesSelector(el, selector)) return { el, idx: i }
+    }
+    return null
+  }
+
   private static _isVisibleElement(el: UiElement): boolean {
     const bounds = ToolsInteract._normalizeBounds(el.bounds)
     return !!el.visible && !!bounds && bounds[2] > bounds[0] && bounds[3] > bounds[1]
@@ -115,7 +162,13 @@ export class ToolsInteract {
       class: el.type ?? el.class ?? null,
       bounds,
       index,
-      elementId
+      elementId,
+      state: el.state ?? null,
+      stable_id: el.stable_id ?? null,
+      role: el.role ?? null,
+      test_tag: el.test_tag ?? null,
+      selector: el.selector ?? null,
+      semantic: el.semantic ?? null
     }
   }
 
@@ -154,7 +207,13 @@ export class ToolsInteract {
       accessibility_id: element.contentDescription ?? element.contentDesc ?? element.accessibilityLabel ?? element.label ?? null,
       class: element.type ?? element.class ?? null,
       bounds: ToolsInteract._normalizeBounds(element.bounds),
-      index
+      index,
+      state: element.state ?? null,
+      stable_id: element.stable_id ?? null,
+      role: element.role ?? null,
+      test_tag: element.test_tag ?? null,
+      selector: element.selector ?? null,
+      semantic: element.semantic ?? null
     }
   }
 
@@ -578,6 +637,11 @@ export class ToolsInteract {
       bounds: boundsObj,
       clickable: !!best.clickable,
       enabled: !!best.enabled,
+      stable_id: best.stable_id ?? null,
+      role: best.role ?? null,
+      test_tag: best.test_tag ?? null,
+      selector: best.selector ?? null,
+      semantic: best.semantic ?? null,
       tapCoordinates,
       telemetry: {
         matchedIndex: best?._index ?? null,
@@ -996,7 +1060,13 @@ export class ToolsInteract {
           accessibility_id: result.element.accessibility_id ?? null,
           class: result.element.class ?? null,
           bounds: result.element.bounds ?? null,
-          index: typeof result.element.index === 'number' ? result.element.index : null
+          index: typeof result.element.index === 'number' ? result.element.index : null,
+          state: (result.element as any).state ?? null,
+          stable_id: (result.element as any).stable_id ?? null,
+          role: (result.element as any).role ?? null,
+          test_tag: (result.element as any).test_tag ?? null,
+          selector: (result.element as any).selector ?? null,
+          semantic: (result.element as any).semantic ?? null
         },
         observed: {
           status: result.status,
@@ -1010,7 +1080,13 @@ export class ToolsInteract {
             accessibility_id: result.element.accessibility_id ?? null,
             class: result.element.class ?? null,
             bounds: result.element.bounds ?? null,
-            index: typeof result.element.index === 'number' ? result.element.index : null
+            index: typeof result.element.index === 'number' ? result.element.index : null,
+            state: (result.element as any).state ?? null,
+            stable_id: (result.element as any).stable_id ?? null,
+            role: (result.element as any).role ?? null,
+            test_tag: (result.element as any).test_tag ?? null,
+            selector: (result.element as any).selector ?? null,
+            semantic: (result.element as any).semantic ?? null
           }
         },
         reason: 'selector is visible'
@@ -1036,6 +1112,198 @@ export class ToolsInteract {
     }
   }
 
+  static async expectStateHandler({
+    selector,
+    element_id,
+    property,
+    expected,
+    platform,
+    deviceId
+  }: {
+    selector?: { text?: string, resource_id?: string, accessibility_id?: string, contains?: boolean },
+    element_id?: string,
+    property: string,
+    expected: boolean | number | string | Record<string, unknown>,
+    platform?: 'android' | 'ios',
+    deviceId?: string
+  }): Promise<ExpectStateResponse> {
+    const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId }) as any
+    const elements = Array.isArray(tree?.elements) ? tree.elements as UiElement[] : []
+    const treePlatform = tree?.device?.platform === 'ios' ? 'ios' : (platform || 'android')
+    const treeDeviceId = tree?.device?.id || deviceId
+
+    let matched: { el: UiElement, idx: number } | null = null
+
+    if (element_id) {
+      const resolved = ToolsInteract._resolvedUiElements.get(element_id)
+      if (resolved) {
+        const current = ToolsInteract._findCurrentResolvedElement(elements, treePlatform, treeDeviceId, resolved)
+        if (current) matched = { el: current.el, idx: current.index }
+      }
+    }
+
+    if (!matched && selector) {
+      matched = ToolsInteract._findFirstMatchingElement(elements, selector)
+    }
+
+    if (!matched) {
+      return {
+        success: false,
+        selector,
+        element_id: element_id ?? null,
+        expected_state: { property, expected },
+        reason: 'element not found',
+        failure_code: 'ELEMENT_NOT_FOUND',
+        retryable: true
+      }
+    }
+
+    const resolvedElement = ToolsInteract._resolvedTargetFromElement(
+      ToolsInteract._computeElementId(treePlatform, treeDeviceId, matched.el, matched.idx),
+      matched.el,
+      matched.idx
+    )
+    const observedState = matched.el.state ?? null
+    const actual = observedState?.[property as keyof UIElementState] ?? null
+
+    const compareBoolean = (value: unknown) => typeof value === 'boolean' ? value : null
+    const compareString = (value: unknown) => typeof value === 'string' ? value : null
+    const compareNumber = (value: unknown) => typeof value === 'number' && Number.isFinite(value) ? value : null
+
+    let success = false
+    let reason = ''
+    let rawValue: boolean | number | string | null = null
+    let observedValue: boolean | number | string | Record<string, unknown> | null = actual as any
+
+    switch (property) {
+      case 'checked':
+      case 'focused':
+      case 'expanded':
+      case 'enabled': {
+        const expectedBool = compareBoolean(expected)
+        const actualBool = compareBoolean(actual)
+        if (expectedBool === null) {
+          reason = `expected ${property} must be boolean`
+        } else if (actualBool === null) {
+          reason = `${property} state unavailable`
+        } else {
+          rawValue = actualBool
+          success = actualBool === expectedBool
+          reason = success ? `${property} matches expected value` : `expected ${property}=${expectedBool} but observed ${actualBool}`
+        }
+        observedValue = actualBool
+        break
+      }
+      case 'value':
+      case 'raw_value': {
+        const expectedNumber = compareNumber(expected)
+        const actualNumber = compareNumber(actual)
+        if (expectedNumber !== null && actualNumber !== null) {
+          success = actualNumber === expectedNumber
+          rawValue = actualNumber
+          observedValue = actualNumber
+          reason = success ? 'value matches expected value' : `expected value=${expectedNumber} but observed ${actualNumber}`
+          break
+        }
+        const expectedString = typeof expected === 'string' ? expected : null
+        const actualString = compareString(actual)
+        if (expectedString !== null && actualString !== null) {
+          success = actualString === expectedString
+          rawValue = actualString
+          observedValue = actualString
+          reason = success ? 'value matches expected value' : `expected value=${expectedString} but observed ${actualString}`
+        } else {
+          reason = 'value state unavailable'
+        }
+        break
+      }
+      case 'selected': {
+        const expectedBool = typeof expected === 'boolean' ? expected : null
+        const expectedString = typeof expected === 'string'
+          ? expected
+          : expected && typeof expected === 'object'
+            ? String((expected as { id?: unknown; label?: unknown }).id ?? (expected as { id?: unknown; label?: unknown }).label ?? '')
+            : null
+        if (!observedState || observedState.selected === undefined || observedState.selected === null) {
+          reason = 'selected state unavailable'
+          break
+        }
+        if (expectedBool !== null) {
+          const actualBool = typeof observedState.selected === 'boolean' ? observedState.selected : null
+          if (actualBool === null) {
+            reason = 'selected state is not boolean'
+            break
+          }
+          rawValue = actualBool
+          observedValue = actualBool
+          success = actualBool === expectedBool
+          reason = success ? 'selected matches expected value' : `expected selected=${expectedBool} but observed ${actualBool}`
+          break
+        }
+        const actualSelected = typeof observedState.selected === 'object' && observedState.selected !== null
+          ? String((observedState.selected as { id?: unknown; label?: unknown }).id ?? (observedState.selected as { id?: unknown; label?: unknown }).label ?? '')
+          : String(observedState.selected)
+        const actualString = actualSelected.trim()
+        if (!expectedString) {
+          reason = 'expected selected must be boolean, string, or object with id/label'
+          break
+        }
+        rawValue = actualString
+        observedValue = actualString
+        success = actualString === expectedString
+        reason = success ? 'selected matches expected value' : `expected selected=${expectedString} but observed ${actualString}`
+        break
+      }
+      case 'text_value': {
+        const expectedString = typeof expected === 'string' ? expected : null
+        const actualString = compareString(actual)
+        if (!expectedString) {
+          reason = 'expected text_value must be string'
+        } else if (!actualString) {
+          reason = 'text_value state unavailable'
+        } else {
+          success = actualString === expectedString
+          rawValue = actualString
+          observedValue = actualString
+          reason = success ? 'text_value matches expected value' : `expected text_value=${expectedString} but observed ${actualString}`
+        }
+        break
+      }
+      default: {
+        if (actual !== null && actual !== undefined) {
+          success = actual === expected
+          observedValue = actual as any
+          rawValue = typeof actual === 'string' || typeof actual === 'number' || typeof actual === 'boolean' ? actual : null
+          reason = success ? `${property} matches expected value` : `expected ${property} to match but observed ${String(actual)}`
+        } else {
+          reason = `unsupported or unavailable state property: ${property}`
+        }
+      }
+    }
+
+    if (!success && !reason) {
+      reason = `${property} did not match expected value`
+    }
+
+    return {
+      success,
+      selector,
+      element_id: element_id ?? resolvedElement.elementId,
+      expected_state: { property, expected },
+      element: {
+        ...resolvedElement,
+        state: observedState
+      },
+      observed_state: {
+        property,
+        value: observedValue,
+        ...(rawValue !== null ? { raw_value: rawValue } : {})
+      },
+      reason,
+      ...(success ? {} : { failure_code: 'UNKNOWN', retryable: false })
+    }
+  }
+
   static async waitForUICore({ type = 'ui', query, timeoutMs = 30000, pollIntervalMs = 300, includeSnapshotOnFailure = true, match = 'present', stability_ms = 700, observationDelayMs = 0, platform, deviceId }: { type?: 'ui' | 'log' | 'screen' | 'idle', query?: string, timeoutMs?: number, pollIntervalMs?: number, includeSnapshotOnFailure?: boolean, match?: 'present'|'absent', stability_ms?: number, observationDelayMs?: number, platform?: 'android' | 'ios', deviceId?: string }) {
     const start = Date.now()
     const deadline = start + (timeoutMs || 0)

package/src/observe/index.ts

@@ -21,6 +21,12 @@ interface SnapshotTreeElementLike {
   clickable?: boolean
   enabled?: boolean
   visible?: boolean
+  state?: unknown
+  stable_id?: string | null
+  role?: string | null
+  test_tag?: string | null
+  selector?: unknown
+  semantic?: unknown
 }
 
 interface SnapshotTreeLike {

package/src/observe/ios.ts

@@ -1,6 +1,6 @@
 import { spawn } from "child_process"
 import { promises as fs } from "fs"
-import { GetLogsResponse, CaptureIOSScreenshotResponse, GetUITreeResponse, UIElement, DeviceInfo } from "../types.js"
+import { GetLogsResponse, CaptureIOSScreenshotResponse, GetUITreeResponse, UIElement, DeviceInfo, UIElementSemanticMetadata, UIElementState, UIResolutionSelector, SelectorConfidence } from "../types.js"
 import { execCommand, getIOSDeviceMetadata, validateBundleId, getIdbCmd, getXcrunCmd, isIDBInstalled } from "../utils/ios/utils.js"
 import { createWriteStream, promises as fsPromises } from 'fs'
 import path from 'path'
@@ -22,6 +22,9 @@ export function _resetIOSExecCommandForTests() {
 interface IDBElement {
   AXFrame?: { x: number | string, y: number | string, width: number | string, height: number | string, w?: number | string, h?: number | string };
   frame?: { x: number | string, y: number | string, width: number | string, height: number | string, w?: number | string, h?: number | string };
+  AXIdentifier?: string;
+  accessibilityIdentifier?: string;
+  identifier?: string;
   AXUniqueId?: string;
   AXLabel?: string;
   AXValue?: string;
@@ -56,7 +59,117 @@ function getCenter(bounds: [number, number, number, number]): [number, number] {
   return [Math.floor((x1 + x2) / 2), Math.floor((y1 + y2) / 2)];
 }
 
-function traverseIDBNode(node: IDBElement, elements: UIElement[], parentIndex: number = -1, depth: number = 0): number {
+function parseIOSNumber(value: unknown): number | null {
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value !== 'string') return null
+  const parsed = Number(value)
+  return Number.isFinite(parsed) ? parsed : null
+}
+
+function normalizeIOSType(value: unknown): string {
+  return typeof value === 'string' ? value.trim().toLowerCase() : ''
+}
+
+function inferIOSRole(type: string, traits: string[]): string | null {
+  if (/slider|adjustable/.test(type) || traits.some((trait) => /adjustable|slider/.test(trait))) return 'slider'
+  if (/button/.test(type) || traits.some((trait) => /button/.test(trait))) return 'button'
+  if (/cell/.test(type)) return 'cell'
+  if (/switch/.test(type)) return 'switch'
+  if (/text field|textfield|search field/.test(type)) return 'text_field'
+  if (/image/.test(type)) return 'image'
+  if (/window|application|group|scroll view|collection view/.test(type)) return 'container'
+  return null
+}
+
+function getIOSStableId(node: IDBElement): string | null {
+  const candidates = [node.AXIdentifier, node.accessibilityIdentifier, node.identifier, node.AXUniqueId]
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.trim().length > 0) return candidate
+  }
+  return null
+}
+
+function buildIOSSelectorConfidence(source: 'identifier' | 'label' | 'value' | 'type' | 'none'): SelectorConfidence | null {
+  switch (source) {
+    case 'identifier':
+      return { score: 1, reason: 'accessibility_identifier' }
+    case 'label':
+      return { score: 0.9, reason: 'label_match' }
+    case 'value':
+      return { score: 0.75, reason: 'value_match' }
+    case 'type':
+      return { score: 0.35, reason: 'type_match' }
+    default:
+      return null
+  }
+}
+
+function buildIOSSelector(type: string, label: string | null, value: string | null, stableId: string | null): UIResolutionSelector | null {
+  if (stableId) return { value: stableId, confidence: buildIOSSelectorConfidence('identifier') }
+  if (label) return { value: label, confidence: buildIOSSelectorConfidence('label') }
+  if (value) return { value: value, confidence: buildIOSSelectorConfidence('value') }
+  if (type) return { value: type, confidence: buildIOSSelectorConfidence('type') }
+  return null
+}
+
+function buildIOSSemantic(type: string, traits: string[]): UIElementSemanticMetadata {
+  return {
+    is_clickable: traits.includes("UIAccessibilityTraitButton") || /adjustable|slider/.test(type) || type === "Button" || type === "Cell",
+    is_container: /window|application|group|scroll view|collection view/.test(type)
+  }
+}
+
+function isIOSAdjustable(node: IDBElement, type: string, traits: string[]): boolean {
+  return /slider|adjustable|stepper|progress/i.test(type) || traits.some((trait) => /adjustable|slider|progress/i.test(trait))
+}
+
+function extractIOSState(node: IDBElement, type: string, label: string | null, value: string | null, traits: string[]): UIElementState | null {
+  const state: UIElementState = {}
+  const normalizedTraits = traits.map((trait) => String(trait).toLowerCase())
+
+  if (normalizedTraits.some((trait) => /selected/.test(trait))) {
+    state.selected = label || value || true
+  }
+
+  if (normalizedTraits.some((trait) => /focused/.test(trait))) {
+    state.focused = true
+  }
+
+  if (normalizedTraits.some((trait) => /enabled/.test(trait))) {
+    state.enabled = true
+  }
+
+  if (normalizedTraits.some((trait) => /disabled/.test(trait))) {
+    state.enabled = false
+  }
+
+  if (value && /textfield|search|text/i.test(type)) {
+    state.text_value = value
+  }
+
+  if (isIOSAdjustable(node, type, traits)) {
+    const rawValue = parseIOSNumber(value)
+    if (rawValue !== null) {
+      state.raw_value = rawValue
+      state.value = rawValue >= 0 && rawValue <= 1 ? Math.round(rawValue * 100) : rawValue
+    } else if (value) {
+      state.raw_value = value
+      state.value = value
+    }
+  } else if (value) {
+    const numericValue = parseIOSNumber(value)
+    if (numericValue !== null) {
+      state.value = numericValue
+      state.raw_value = numericValue
+    } else {
+      state.value = value
+    }
+  }
+
+  return Object.keys(state).length > 0 ? state : null
+}
+
+export function traverseIDBNode(node: IDBElement, elements: UIElement[], parentIndex: number = -1, depth: number = 0): number {
   if (!node) return -1;
 
   let currentIndex = -1;
@@ -66,6 +179,12 @@ function traverseIDBNode(node: IDBElement, elements: UIElement[], parentIndex: n
   const value = node.AXValue || null;
   const frame = node.AXFrame || node.frame;
   const traits = node.AXTraits || [];
+  const state = extractIOSState(node, type, label, value, traits);
+  const normalizedType = normalizeIOSType(type)
+  const stableId = getIOSStableId(node)
+  const selector = buildIOSSelector(type, label, value, stableId)
+  const semantic = buildIOSSemantic(normalizedType, traits)
+  const role = inferIOSRole(normalizedType, traits)
   
   const clickable = traits.includes("UIAccessibilityTraitButton") || type === "Button" || type === "Cell";
   
@@ -77,13 +196,19 @@ function traverseIDBNode(node: IDBElement, elements: UIElement[], parentIndex: n
       text: label,
       contentDescription: value,
       type: type,
-      resourceId: node.AXUniqueId || null,
+      resourceId: stableId,
       clickable: clickable,
       enabled: true,
       visible: true,
       bounds: bounds,
       center: getCenter(bounds),
-      depth: depth
+      depth: depth,
+      state,
+      stable_id: stableId,
+      role,
+      test_tag: stableId,
+      selector,
+      semantic
     };
 
     if (parentIndex !== -1) {

package/src/server/common.ts

@@ -96,7 +96,8 @@ export function normalizeResolvedTarget(value: Partial<ActionTargetResolved> | n
     accessibility_id: value.accessibility_id ?? null,
     class: value.class ?? null,
     bounds: value.bounds ?? null,
-    index: value.index ?? null
+    index: value.index ?? null,
+    state: value.state ?? null
   }
 }
 

package/src/server/tool-definitions.ts

@@ -468,6 +468,61 @@ Failure Handling:
       required: ['selector']
     }
   },
+  {
+    name: 'expect_state',
+    description: `Purpose:
+Verify a readable UI state property on the currently visible element.
+
+Inputs:
+- selector or element_id
+- property
+- expected
+- platform/deviceId (optional)
+
+Supported properties:
+- checked, selected, focused, expanded, enabled, text_value, value, raw_value
+
+Verification Guidance:
+- Use this when the UI element is visible but its state must also be confirmed
+- Prefer the canonical property names above
+- The tool compares the normalized readable state and returns the observed value when available
+
+Constraints:
+- Returns structured success/failure only
+- Does not infer a state when the property is unavailable
+
+Failure Handling:
+- ELEMENT_NOT_FOUND → re-resolve the element or wait for UI stabilization
+- UNKNOWN → capture a snapshot and stop`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        selector: {
+          type: 'object',
+          properties: {
+            text: { type: 'string' },
+            resource_id: { type: 'string' },
+            accessibility_id: { type: 'string' },
+            contains: { type: 'boolean', default: false }
+          }
+        },
+        element_id: { type: 'string', description: 'Optional previously resolved element identifier.' },
+        property: { type: 'string', description: 'Readable state property to verify.' },
+        expected: {
+          description: 'Expected normalized state value.',
+          oneOf: [
+            { type: 'boolean' },
+            { type: 'number' },
+            { type: 'string' },
+            { type: 'object' }
+          ]
+        },
+        platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override' },
+        deviceId: { type: 'string', description: 'Optional device serial/udid' }
+      },
+      required: ['property', 'expected']
+    }
+  },
   {
     name: 'wait_for_ui',
     description: `Purpose:

package/src/server/tool-handlers.ts

@@ -258,6 +258,23 @@ async function handleExpectElementVisible(args: ToolCallArgs) {
   return wrapResponse(res)
 }
 
+async function handleExpectState(args: ToolCallArgs) {
+  const selector = getObjectArg<ExpectElementSelectorArg>(args, 'selector')
+  const element_id = getStringArg(args, 'element_id')
+  const property = requireStringArg(args, 'property')
+  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 (!Object.prototype.hasOwnProperty.call(args, 'expected')) {
+    throw new Error('Missing expected argument')
+  }
+  const expected = args.expected as boolean | number | string | Record<string, unknown>
+  const res = await ToolsInteract.expectStateHandler({ selector: selector ?? undefined, element_id: element_id ?? undefined, property, expected, platform, deviceId })
+  return wrapResponse(res)
+}
+
 async function handleWaitForUI(args: ToolCallArgs) {
   const selector = getObjectArg<ExpectElementSelectorArg>(args, 'selector')
   const condition = (getStringArg(args, 'condition') as 'exists' | 'not_exists' | 'visible' | 'clickable' | undefined) ?? 'exists'
@@ -458,6 +475,7 @@ export const toolHandlers: Record<string, ToolHandler> = {
   wait_for_screen_change: handleWaitForScreenChange,
   expect_screen: handleExpectScreen,
   expect_element_visible: handleExpectElementVisible,
+  expect_state: handleExpectState,
   wait_for_ui: handleWaitForUI,
   find_element: handleFindElement,
   tap: handleTap,

package/src/server-core.ts

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