mobile-debug-mcp 0.25.0 → 0.25.1

package/dist/interact/index.js

@@ -105,7 +105,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
         };
     }
     static _rememberResolvedElement(elementId, context) {
@@ -138,7 +144,12 @@ export class ToolsInteract {
             class: element.type ?? element.class ?? null,
             bounds: ToolsInteract._normalizeBounds(element.bounds),
             index,
-            state: element.state ?? null
+            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
         };
     }
     static _actionFailure(actionId, timestamp, actionType, selector, resolved, failureCode, retryable, uiFingerprintBefore, uiFingerprintAfter) {
@@ -542,6 +553,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,
@@ -940,7 +956,12 @@ export class ToolsInteract {
                     class: result.element.class ?? null,
                     bounds: result.element.bounds ?? null,
                     index: typeof result.element.index === 'number' ? result.element.index : null,
-                    state: result.element.state ?? null
+                    state: result.element.state ?? null,
+                    stable_id: result.element.stable_id ?? null,
+                    role: result.element.role ?? null,
+                    test_tag: result.element.test_tag ?? null,
+                    selector: result.element.selector ?? null,
+                    semantic: result.element.semantic ?? null
                 },
                 observed: {
                     status: result.status,
@@ -955,7 +976,12 @@ export class ToolsInteract {
                         class: result.element.class ?? null,
                         bounds: result.element.bounds ?? null,
                         index: typeof result.element.index === 'number' ? result.element.index : null,
-                        state: result.element.state ?? null
+                        state: result.element.state ?? null,
+                        stable_id: result.element.stable_id ?? null,
+                        role: result.element.role ?? null,
+                        test_tag: result.element.test_tag ?? null,
+                        selector: result.element.selector ?? null,
+                        semantic: result.element.semantic ?? null
                     }
                 },
                 reason: 'selector is visible'

package/dist/observe/ios.js

@@ -45,6 +45,65 @@ function parseIOSNumber(value) {
     const parsed = Number(value);
     return Number.isFinite(parsed) ? parsed : null;
 }
+function normalizeIOSType(value) {
+    return typeof value === 'string' ? value.trim().toLowerCase() : '';
+}
+function inferIOSRole(type, traits) {
+    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) {
+    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) {
+    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, label, value, stableId) {
+    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, traits) {
+    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, type, traits) {
     return /slider|adjustable|stepper|progress/i.test(type) || traits.some((trait) => /adjustable|slider|progress/i.test(trait));
 }
@@ -99,6 +158,11 @@ export function traverseIDBNode(node, elements, parentIndex = -1, depth = 0) {
     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";
     const isUseful = clickable || (label && label.length > 0) || (value && value.length > 0) || type === "Application" || type === "Window";
     if (isUseful) {
@@ -107,14 +171,19 @@ export function traverseIDBNode(node, elements, parentIndex = -1, depth = 0) {
             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,
-            state
+            state,
+            stable_id: stableId,
+            role,
+            test_tag: stableId,
+            selector,
+            semantic
         };
         if (parentIndex !== -1) {
             element.parentId = parentIndex;

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.25.0'
+    version: '0.25.1'
 };
 export function createServer() {
     const server = new Server(serverInfo, {

package/dist/utils/android/utils.js

@@ -356,6 +356,59 @@ function parseNumberAttr(value) {
     const parsed = Number(value);
     return Number.isFinite(parsed) ? parsed : null;
 }
+function normalizeClassName(value) {
+    return typeof value === 'string' ? value.trim().toLowerCase() : '';
+}
+function inferAndroidRole(className) {
+    if (/seekbar|slider|progress/.test(className))
+        return 'slider';
+    if (/switch|toggle/.test(className))
+        return 'switch';
+    if (/checkbox/.test(className))
+        return 'checkbox';
+    if (/radiobutton|radio/.test(className))
+        return 'radio';
+    if (/edittext|textfield|search/.test(className))
+        return 'text_field';
+    if (/button|fab/.test(className))
+        return 'button';
+    if (/imageview|icon/.test(className))
+        return 'image';
+    if (/recyclerview|scroll|layout|viewgroup|frame/.test(className))
+        return 'container';
+    return null;
+}
+function buildAndroidSelectorConfidence(source) {
+    switch (source) {
+        case 'resource_id':
+            return { score: 1, reason: 'resource_id' };
+        case 'content_desc':
+            return { score: 0.9, reason: 'content_description' };
+        case 'text':
+            return { score: 0.6, reason: 'text_match' };
+        case 'class':
+            return { score: 0.35, reason: 'class_match' };
+        default:
+            return null;
+    }
+}
+function buildAndroidSelector(text, contentDescription, resourceId, className) {
+    if (resourceId)
+        return { value: resourceId, confidence: buildAndroidSelectorConfidence('resource_id') };
+    if (contentDescription)
+        return { value: contentDescription, confidence: buildAndroidSelectorConfidence('content_desc') };
+    if (text)
+        return { value: text, confidence: buildAndroidSelectorConfidence('text') };
+    if (className)
+        return { value: className, confidence: buildAndroidSelectorConfidence('class') };
+    return null;
+}
+function buildAndroidSemantic(clickable, className) {
+    return {
+        is_clickable: clickable,
+        is_container: /recyclerview|scroll|layout|viewgroup|frame/.test(className)
+    };
+}
 function isSliderLikeAndroid(node) {
     const className = String(node['@_class'] || '').toLowerCase();
     return /seekbar|slider|range|progress/i.test(className);
@@ -426,22 +479,34 @@ export function traverseNode(node, elements, parentIndex = -1, depth = 0) {
         const text = node['@_text'] || null;
         const contentDescription = node['@_content-desc'] || null;
         const clickable = node['@_clickable'] === 'true';
+        const className = String(node['@_class'] || 'unknown');
         const bounds = parseBounds(node['@_bounds'] || '[0,0][0,0]');
         const state = extractAndroidState(node);
+        const role = inferAndroidRole(normalizeClassName(className));
+        const resourceId = typeof node['@_resource-id'] === 'string' && node['@_resource-id'].trim().length > 0 ? node['@_resource-id'] : null;
+        const stableId = resourceId ?? (typeof contentDescription === 'string' && contentDescription.trim().length > 0 ? contentDescription : null);
+        const testTag = stableId;
+        const selector = buildAndroidSelector(text, contentDescription, resourceId, normalizeClassName(className));
+        const semantic = buildAndroidSemantic(clickable, normalizeClassName(className));
         const isUseful = clickable || (text && text.length > 0) || (contentDescription && contentDescription.length > 0);
         if (isUseful) {
             const element = {
                 text,
                 contentDescription,
-                type: node['@_class'] || 'unknown',
-                resourceId: node['@_resource-id'] || null,
+                type: className,
+                resourceId,
                 clickable,
                 enabled: node['@_enabled'] === 'true',
                 visible: true,
                 bounds,
                 center: getCenter(bounds),
                 depth,
-                state
+                state,
+                stable_id: stableId,
+                role,
+                test_tag: testTag,
+                selector,
+                semantic
             };
             if (parentIndex !== -1) {
                 element.parentId = parentIndex;

package/docs/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.25.1]
+- Platform-native element identity metadata for UI targeting
+- Hierarchy-independent element references
+- Selector confidence metadata for reliability
+- Structured fallback resolution strategy
+
 ## [0.25.0]
 - Introduces the `expect_state` tool and a standardized state object for UI elements across Android and iOS.
 

package/docs/ROADMAP.md

@@ -26,11 +26,27 @@ Higher task success with fewer retries.
 
 ---
 
+# Completed
+
+These priorities are done and kept here for history:
+
+- Priority 1 — Stronger State Verification
+- Priority 2 — Richer Element Identity
+
+Completion notes:
+
+- State-aware verification is now implemented and wired through the tool surface.
+- Platform-native element metadata and selector-confidence hints are now part of the runtime contract.
+
+---
+
 # Priority 1 — Stronger State Verification
 
 ## Why first
 Highest leverage improvement.
 
+**Status:** Completed
+
 Most failures are not “can’t act,” they’re:
 - uncertain state
 - weak verification
@@ -68,6 +84,8 @@ Blocks or strengthens:
 ## Why second
 Directly reduces selector brittleness.
 
+**Status:** Completed
+
 Improves:
 - targeting stability
 - repeatability
@@ -385,4 +403,4 @@ Still out of scope:
 - Recovery planning logic
 - Autonomous retry strategy
 - MCP-level agent orchestration
-- Autonomous recovery hinting (future consideration only)
+- Autonomous recovery hinting (future consideration only)