mobile-debug-mcp 0.24.8 → 0.25.0

package/README.md

@@ -1,6 +1,6 @@
 # Mobile Debug Tools
 
-A minimal, secure MCP server for AI-assisted mobile development. Build, install, and inspect Android/iOS apps from an MCP-compatible client.
+A minimal, secure MCP server for AI-assisted mobile development. Build, install, interact and inspect Android/iOS apps from an MCP-compatible client.
 
 > **Support:**
 > * KMP

package/dist/interact/index.js

@@ -34,6 +34,43 @@ export class ToolsInteract {
             return null;
         return normalized;
     }
+    static _matchesSelector(el, selector) {
+        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;
+    }
+    static _findFirstMatchingElement(elements, selector) {
+        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;
+    }
     static _isVisibleElement(el) {
         const bounds = ToolsInteract._normalizeBounds(el.bounds);
         return !!el.visible && !!bounds && bounds[2] > bounds[0] && bounds[3] > bounds[1];
@@ -100,7 +137,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
         };
     }
     static _actionFailure(actionId, timestamp, actionType, selector, resolved, failureCode, retryable, uiFingerprintBefore, uiFingerprintAfter) {
@@ -901,7 +939,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.state ?? null
                 },
                 observed: {
                     status: result.status,
@@ -915,7 +954,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.state ?? null
                     }
                 },
                 reason: 'selector is visible'
@@ -939,6 +979,176 @@ export class ToolsInteract {
             retryable: errorCode === 'TIMEOUT'
         };
     }
+    static async expectStateHandler({ selector, element_id, property, expected, platform, deviceId }) {
+        const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
+        const elements = Array.isArray(tree?.elements) ? tree.elements : [];
+        const treePlatform = tree?.device?.platform === 'ios' ? 'ios' : (platform || 'android');
+        const treeDeviceId = tree?.device?.id || deviceId;
+        let matched = 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] ?? null;
+        const compareBoolean = (value) => typeof value === 'boolean' ? value : null;
+        const compareString = (value) => typeof value === 'string' ? value : null;
+        const compareNumber = (value) => typeof value === 'number' && Number.isFinite(value) ? value : null;
+        let success = false;
+        let reason = '';
+        let rawValue = null;
+        let observedValue = actual;
+        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.id ?? expected.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.id ?? observedState.selected.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;
+                    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 }) {
         const start = Date.now();
         const deadline = start + (timeoutMs || 0);

package/dist/observe/ios.js

@@ -37,7 +37,59 @@ function getCenter(bounds) {
     const [x1, y1, x2, y2] = bounds;
     return [Math.floor((x1 + x2) / 2), Math.floor((y1 + y2) / 2)];
 }
-function traverseIDBNode(node, elements, parentIndex = -1, depth = 0) {
+function parseIOSNumber(value) {
+    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, type, traits) {
+    return /slider|adjustable|stepper|progress/i.test(type) || traits.some((trait) => /adjustable|slider|progress/i.test(trait));
+}
+function extractIOSState(node, type, label, value, traits) {
+    const state = {};
+    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, elements, parentIndex = -1, depth = 0) {
     if (!node)
         return -1;
     let currentIndex = -1;
@@ -46,6 +98,7 @@ function traverseIDBNode(node, elements, parentIndex = -1, depth = 0) {
     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";
     const isUseful = clickable || (label && label.length > 0) || (value && value.length > 0) || type === "Application" || type === "Window";
     if (isUseful) {
@@ -60,7 +113,8 @@ function traverseIDBNode(node, elements, parentIndex = -1, depth = 0) {
             visible: true,
             bounds: bounds,
             center: getCenter(bounds),
-            depth: depth
+            depth: depth,
+            state
         };
         if (parentIndex !== -1) {
             element.parentId = parentIndex;

package/dist/server/common.js

@@ -79,7 +79,8 @@ export function normalizeResolvedTarget(value = null) {
         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
     };
 }
 export function inferGenericFailure(message) {

package/dist/server/tool-definitions.js

@@ -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/dist/server/tool-handlers.js

@@ -208,6 +208,22 @@ async function handleExpectElementVisible(args) {
     const res = await ToolsInteract.expectElementVisibleHandler({ selector, element_id, timeout_ms, poll_interval_ms, platform, deviceId });
     return wrapResponse(res);
 }
+async function handleExpectState(args) {
+    const selector = getObjectArg(args, 'selector');
+    const element_id = getStringArg(args, 'element_id');
+    const property = requireStringArg(args, 'property');
+    const platform = getStringArg(args, 'platform');
+    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;
+    const res = await ToolsInteract.expectStateHandler({ selector: selector ?? undefined, element_id: element_id ?? undefined, property, expected, platform, deviceId });
+    return wrapResponse(res);
+}
 async function handleWaitForUI(args) {
     const selector = getObjectArg(args, 'selector');
     const condition = getStringArg(args, 'condition') ?? 'exists';
@@ -395,6 +411,7 @@ export const toolHandlers = {
     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/dist/server-core.js

@@ -6,7 +6,7 @@ import { handleToolCall } from './server/tool-handlers.js';
 export { wrapResponse, toolDefinitions, handleToolCall };
 export const serverInfo = {
     name: 'mobile-debug-mcp',
-    version: '0.24.8'
+    version: '0.25.0'
 };
 export function createServer() {
     const server = new Server(serverInfo, {

package/dist/utils/android/utils.js

@@ -341,6 +341,70 @@ export function getCenter(bounds) {
     const [x1, y1, x2, y2] = bounds;
     return [Math.floor((x1 + x2) / 2), Math.floor((y1 + y2) / 2)];
 }
+function parseBooleanAttr(value) {
+    if (value === true || value === 'true')
+        return true;
+    if (value === false || value === 'false')
+        return false;
+    return null;
+}
+function parseNumberAttr(value) {
+    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 isSliderLikeAndroid(node) {
+    const className = String(node['@_class'] || '').toLowerCase();
+    return /seekbar|slider|range|progress/i.test(className);
+}
+function extractAndroidState(node) {
+    const checked = parseBooleanAttr(node['@_checked']);
+    const selectedFlag = parseBooleanAttr(node['@_selected']);
+    const focused = parseBooleanAttr(node['@_focused']);
+    const expanded = parseBooleanAttr(node['@_expanded']);
+    const enabled = parseBooleanAttr(node['@_enabled']);
+    const textValue = typeof node['@_text'] === 'string' && node['@_text'].trim().length > 0 ? node['@_text'] : null;
+    const state = {};
+    if (checked !== null)
+        state.checked = checked;
+    if (selectedFlag !== null) {
+        state.selected = textValue || node['@_content-desc'] || true;
+    }
+    if (focused !== null)
+        state.focused = focused;
+    if (expanded !== null)
+        state.expanded = expanded;
+    if (enabled !== null)
+        state.enabled = enabled;
+    if (textValue && /edittext|textfield|search/i.test(String(node['@_class'] || ''))) {
+        state.text_value = textValue;
+    }
+    if (isSliderLikeAndroid(node)) {
+        const rawProgress = parseNumberAttr(node['@_progress']);
+        const max = parseNumberAttr(node['@_max']);
+        const fallbackValue = rawProgress ?? parseNumberAttr(node['@_value']) ?? parseNumberAttr(node['@_content-desc']);
+        const numericValue = rawProgress ?? fallbackValue;
+        if (numericValue !== null) {
+            state.raw_value = numericValue;
+            state.value_range = max !== null && max > 0 ? { min: 0, max } : null;
+            state.value = max !== null && max > 0 ? Math.round((numericValue / max) * 100) : numericValue;
+        }
+    }
+    else {
+        const numericValue = parseNumberAttr(node['@_value']);
+        if (numericValue !== null) {
+            state.value = numericValue;
+            state.raw_value = numericValue;
+        }
+        else if (textValue) {
+            state.value = textValue;
+        }
+    }
+    return Object.keys(state).length > 0 ? state : null;
+}
 export async function getScreenResolution(deviceId) {
     try {
         const output = await execAdb(['shell', 'wm', 'size'], deviceId);
@@ -363,6 +427,7 @@ export function traverseNode(node, elements, parentIndex = -1, depth = 0) {
         const contentDescription = node['@_content-desc'] || null;
         const clickable = node['@_clickable'] === 'true';
         const bounds = parseBounds(node['@_bounds'] || '[0,0][0,0]');
+        const state = extractAndroidState(node);
         const isUseful = clickable || (text && text.length > 0) || (contentDescription && contentDescription.length > 0);
         if (isUseful) {
             const element = {
@@ -375,7 +440,8 @@ export function traverseNode(node, elements, parentIndex = -1, depth = 0) {
                 visible: true,
                 bounds,
                 center: getCenter(bounds),
-                depth
+                depth,
+                state
             };
             if (parentIndex !== -1) {
                 element.parentId = parentIndex;

package/docs/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.25.0]
+- Introduces the `expect_state` tool and a standardized state object for UI elements across Android and iOS.
+
 ## [0.24.8]
 - Improved slider interaction