mobile-debug-mcp 0.24.7 → 0.25.0

package/src/interact/index.ts

@@ -10,7 +10,9 @@ import type {
   ActionFailureCode,
   ActionTargetResolved,
   ExpectElementVisibleResponse,
+  ExpectStateResponse,
   ExpectScreenResponse,
+  UIElementState,
   TapElementResponse
 } from '../types.js'
 
@@ -36,6 +38,8 @@ interface UiElement {
   parentId?: number | string | null
   _index?: number
   _interactable?: boolean
+  _sliderLike?: boolean
+  state?: UIElementState | null
 }
 
 interface ResolvedUiElementContext {
@@ -46,9 +50,22 @@ interface ResolvedUiElementContext {
   index: number
 }
 
+interface UiResolution {
+  width?: number
+  height?: number
+}
+
 
 export class ToolsInteract {
   private static readonly _maxResolvedUiElements = 256
+  private static readonly _sliderSearchLookahead = 8
+  private static readonly _sliderNegativeGapTolerancePx = 32
+  private static readonly _sliderPositiveGapLimitPx = 640
+  private static readonly _sliderTrackMinLengthPx = 220
+  private static readonly _sliderTrackMaxThicknessPx = 180
+  private static readonly _sliderTrackLengthRatio = 0.18
+  private static readonly _sliderTrackThicknessRatio = 0.08
+  private static readonly _sliderLabelWidthRatio = 1.5
   private static _resolvedUiElements = new Map<string, ResolvedUiElementContext>()
 
   private static _normalize(s: any): string {
@@ -63,6 +80,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]
@@ -140,7 +196,8 @@ 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
     }
   }
 
@@ -240,6 +297,78 @@ export class ToolsInteract {
     return best
   }
 
+  private static _resolveNearbyActionableControl(
+    elements: UiElement[],
+    chosen: { el: UiElement, idx: number } | null,
+    screen?: UiResolution | null
+  ): { el: UiElement, idx: number, sliderLike?: boolean } | null {
+    if (!chosen) return null
+
+    const labelBounds = ToolsInteract._normalizeBounds(chosen.el.bounds)
+    if (!labelBounds) return null
+
+    const [labelLeft, labelTop, labelRight, labelBottom] = labelBounds
+    const labelWidth = labelRight - labelLeft
+    const labelHeight = labelBottom - labelTop
+    const screenWidth = Number(screen?.width) > 0 ? Number(screen?.width) : 0
+    const screenHeight = Number(screen?.height) > 0 ? Number(screen?.height) : 0
+    const minTrackLengthPx = Math.max(
+      ToolsInteract._sliderTrackMinLengthPx,
+      screenWidth > 0 ? Math.floor(screenWidth * ToolsInteract._sliderTrackLengthRatio) : 0,
+      screenHeight > 0 ? Math.floor(screenHeight * ToolsInteract._sliderTrackLengthRatio) : 0
+    )
+    const maxTrackThicknessPx = Math.max(
+      ToolsInteract._sliderTrackMaxThicknessPx,
+      screenWidth > 0 ? Math.floor(screenWidth * ToolsInteract._sliderTrackThicknessRatio) : 0,
+      screenHeight > 0 ? Math.floor(screenHeight * ToolsInteract._sliderTrackThicknessRatio) : 0
+    )
+
+    let best: { el: UiElement, idx: number, sliderLike?: boolean } | null = null
+    let bestScore = Infinity
+
+    for (let i = chosen.idx + 1; i < Math.min(elements.length, chosen.idx + ToolsInteract._sliderSearchLookahead); i++) {
+      const candidate = elements[i]
+      if (!candidate || !(candidate.clickable || candidate.focusable) || candidate.visible === false) continue
+
+      const candidateBounds = ToolsInteract._normalizeBounds(candidate.bounds)
+      if (!candidateBounds) continue
+
+      const [left, top, right] = candidateBounds
+      const width = right - left
+      const height = candidateBounds[3] - top
+      const verticalGap = top - labelBottom
+      if (verticalGap < -ToolsInteract._sliderNegativeGapTolerancePx || verticalGap > ToolsInteract._sliderPositiveGapLimitPx) continue
+
+      const horizontalOverlap = Math.min(labelRight, right) - Math.max(labelLeft, left)
+      if (horizontalOverlap < -ToolsInteract._sliderNegativeGapTolerancePx) continue
+
+      const candidateText = ToolsInteract._normalize(candidate.text ?? candidate.label ?? candidate.value ?? '')
+      const candidateContent = ToolsInteract._normalize(candidate.contentDescription ?? candidate.contentDesc ?? candidate.accessibilityLabel ?? '')
+      const candidateClass = ToolsInteract._normalize(candidate.type ?? candidate.class ?? '')
+
+      let score = verticalGap
+      const horizontalTrackLike =
+        width >= Math.max(minTrackLengthPx, Math.floor(labelWidth * ToolsInteract._sliderLabelWidthRatio)) &&
+        height <= maxTrackThicknessPx
+      const verticalTrackLike =
+        height >= Math.max(minTrackLengthPx, Math.floor(labelHeight * ToolsInteract._sliderLabelWidthRatio)) &&
+        width <= maxTrackThicknessPx
+      const trackLike = /slider|seek|range/i.test(candidateClass) || horizontalTrackLike || verticalTrackLike
+      if (!candidateText && !candidateContent) score -= 18
+      if (trackLike) score -= 30
+      if (/view|layout|group|frame/i.test(candidateClass)) score -= 10
+      if (width > labelWidth * ToolsInteract._sliderLabelWidthRatio) score -= 8
+      if (candidateText || candidateContent) score += 20
+
+      if (score < bestScore) {
+        bestScore = score
+        best = { el: candidate, idx: i, sliderLike: trackLike }
+      }
+    }
+
+    return best
+  }
+
 
   private static async getInteractionService(platform?: 'android' | 'ios', deviceId?: string) {
     const effectivePlatform = platform || 'android'
@@ -347,6 +476,7 @@ export class ToolsInteract {
 
     let best: UiElement | null = null
     let bestScore = 0
+    let lastTree: any = null
 
     const scoreElement = (el: UiElement | null) => {
       if (!el || !el.visible) return 0
@@ -380,7 +510,8 @@ export class ToolsInteract {
 
     while (Date.now() <= deadline) {
       try {
-        const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId })
+      const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId })
+      lastTree = tree
         if (tree && Array.isArray((tree as any).elements)) {
           const elements = ((tree as any).elements as UiElement[])
           for (let i = 0; i < elements.length; i++) {
@@ -407,8 +538,8 @@ export class ToolsInteract {
 
     // If the best match is not interactable, try to resolve an actionable ancestor.
     try {
-      const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId }) as any
-      const elements = (tree && Array.isArray(tree.elements)) ? (tree.elements as UiElement[]) : []
+      const elements = (lastTree && Array.isArray(lastTree.elements)) ? (lastTree.elements as UiElement[]) : []
+      const screen = lastTree?.resolution && typeof lastTree.resolution === 'object' ? lastTree.resolution as UiResolution : null
       let chosen = best as any
       const childBounds = Array.isArray(chosen?.bounds) ? chosen.bounds : null
 
@@ -465,6 +596,16 @@ export class ToolsInteract {
         // small score bump to reflect actionability
         bestScore = Math.min(1, bestScore + 0.02)
       }
+
+      if (best && !(best.clickable || best.focusable)) {
+        const nearbyActionable = ToolsInteract._resolveNearbyActionableControl(elements, { el: best, idx: best._index ?? elements.indexOf(best) }, screen)
+        if (nearbyActionable) {
+          best = nearbyActionable.el
+          best._index = nearbyActionable.idx
+          best._interactable = true
+          best._sliderLike = nearbyActionable.sliderLike
+        }
+      }
     } catch (e) { console.error('Error resolving ancestor:', e) }
 
     if (!best) return { found: false, error: 'Element not found' }
@@ -483,8 +624,18 @@ export class ToolsInteract {
       tapCoordinates,
       telemetry: {
         matchedIndex: best?._index ?? null,
-        matchedInteractable: !!best?._interactable
+        matchedInteractable: !!best?._interactable,
+        sliderLike: !!best?._sliderLike
+      }
+    }
+    if (best?._sliderLike) {
+      const isVertical = !!boundsObj && (boundsObj.bottom - boundsObj.top) > (boundsObj.right - boundsObj.left)
+      const interactionHint = {
+        kind: 'slider',
+        axis: isVertical ? 'vertical' : 'horizontal',
+        trackBounds: boundsObj
       }
+      ;(outEl as any).interactionHint = interactionHint
     }
     const scoreVal = Math.min(1, Number(bestScore.toFixed(3)))
     return { found: true, element: outEl, score: scoreVal, confidence: scoreVal }
@@ -888,7 +1039,8 @@ 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
         },
         observed: {
           status: result.status,
@@ -902,7 +1054,8 @@ 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
           }
         },
         reason: 'selector is visible'
@@ -928,6 +1081,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/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, UIElementState } 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'
@@ -56,7 +56,64 @@ 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 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 +123,7 @@ 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 clickable = traits.includes("UIAccessibilityTraitButton") || type === "Button" || type === "Cell";
   
@@ -83,7 +141,8 @@ function traverseIDBNode(node: IDBElement, elements: UIElement[], parentIndex: n
       visible: true,
       bounds: bounds,
       center: getCenter(bounds),
-      depth: depth
+      depth: depth,
+      state
     };
 
     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.7'
+  version: '0.25.0'
 }
 
 export function createServer() {