mobile-debug-mcp 0.26.1 → 0.26.3

package/src/server/tool-handlers.ts

@@ -47,6 +47,7 @@ async function handleStartApp(args: ToolCallArgs) {
   const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId)
   return wrapResponse(buildActionExecutionResult({
     actionType: 'start_app',
+    sourceModule: 'server',
     device: res.device,
     selector: { appId },
     success: !!res.appStarted,
@@ -82,6 +83,7 @@ async function handleRestartApp(args: ToolCallArgs) {
   const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId)
   return wrapResponse(buildActionExecutionResult({
     actionType: 'restart_app',
+    sourceModule: 'server',
     device: res.device,
     selector: { appId },
     success: !!res.appRestarted,
@@ -319,6 +321,7 @@ async function handleTap(args: ToolCallArgs) {
   const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId)
   return wrapResponse(buildActionExecutionResult({
     actionType: 'tap',
+    sourceModule: 'server',
     selector: { x, y },
     success: !!res.success,
     uiFingerprintBefore,
@@ -348,6 +351,7 @@ async function handleSwipe(args: ToolCallArgs) {
   const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId)
   return wrapResponse(buildActionExecutionResult({
     actionType: 'swipe',
+    sourceModule: 'server',
     selector: { x1, y1, x2, y2, duration },
     success: !!res.success,
     uiFingerprintBefore,
@@ -369,6 +373,7 @@ async function handleScrollToElement(args: ToolCallArgs) {
   const uiFingerprintAfter = await captureActionFingerprint(platform, deviceId)
   return wrapResponse(buildActionExecutionResult({
     actionType: 'scroll_to_element',
+    sourceModule: 'server',
     selector: selector ?? null,
     resolved: res?.success && res?.element ? {
       elementId: null,
@@ -395,6 +400,7 @@ async function handleTypeText(args: ToolCallArgs) {
   const uiFingerprintAfter = await captureActionFingerprint('android', deviceId)
   return wrapResponse(buildActionExecutionResult({
     actionType: 'type_text',
+    sourceModule: 'server',
     selector: { text },
     success: !!res.success,
     uiFingerprintBefore,
@@ -411,6 +417,7 @@ async function handlePressBack(args: ToolCallArgs) {
   const uiFingerprintAfter = await captureActionFingerprint('android', deviceId)
   return wrapResponse(buildActionExecutionResult({
     actionType: 'press_back',
+    sourceModule: 'server',
     selector: { key: 'back' },
     success: !!res.success,
     uiFingerprintBefore,

package/src/server-core.ts

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

package/src/types.ts

@@ -254,10 +254,85 @@ export interface ActionTargetResolved {
   semantic?: UIElementSemanticMetadata | null;
 }
 
+export interface ResolutionAlternate {
+  text: string | null;
+  resource_id: string | null;
+  accessibility_id: string | null;
+  class: string | null;
+  bounds: {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+  } | null;
+  clickable: boolean;
+  enabled: boolean;
+  score: number;
+  reason: string;
+}
+
+export interface ResolutionSummary {
+  confidence: number;
+  reason: string;
+  fallback_available: boolean;
+  matched_count: number;
+  alternates: ResolutionAlternate[];
+}
+
+export interface FindElementElement {
+  text: string | null;
+  resourceId: string | null;
+  contentDesc: string | null;
+  class: string | null;
+  bounds: {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+  } | null;
+  clickable: boolean;
+  enabled: boolean;
+  stable_id?: string | null;
+  role?: string | null;
+  test_tag?: string | null;
+  selector?: UIResolutionSelector | null;
+  semantic?: UIElementSemanticMetadata | null;
+  tapCoordinates: {
+    x: number;
+    y: number;
+  } | null;
+  telemetry: {
+    matchedIndex: number | null;
+    matchedInteractable: boolean;
+    sliderLike: boolean;
+  };
+  interactionHint?: {
+    kind: 'slider';
+    axis: 'horizontal' | 'vertical';
+    trackBounds: {
+      left: number;
+      top: number;
+      right: number;
+      bottom: number;
+    } | null;
+  };
+}
+
+export interface FindElementResponse {
+  found: boolean;
+  element?: FindElementElement | null;
+  score?: number;
+  confidence?: number;
+  resolution?: ResolutionSummary | null;
+  error?: string;
+}
+
 export interface ActionExecutionResult {
   action_id: string;
   timestamp: string;
   action_type: string;
+  lifecycle_state?: 'pending_verification' | 'failed';
+  source_module?: 'server' | 'interact';
   device?: DeviceInfo;
   target: {
     selector: Record<string, unknown> | null;

package/test/unit/observe/find_element.test.ts

@@ -73,6 +73,9 @@ async function run() {
     process.stdout.write('res4 ' + JSON.stringify(res4, null, 2) + '\n');
     const pass4 = res4.found === true && res4.element && res4.element.clickable === true && res4.element.resourceId === 'btn_generate' && res4.element.tapCoordinates && typeof res4.element.tapCoordinates.x === 'number' && typeof res4.element.tapCoordinates.y === 'number' && typeof res4.confidence === 'number'
     assert.ok(pass4, 'Child text should resolve to a clickable parent ancestor')
+    assert.strictEqual(res4.resolution?.reason, 'clickable_parent_preferred')
+    assert.strictEqual(res4.resolution?.fallback_available, true)
+    assert.ok((res4.resolution?.alternates || []).length >= 1, 'Parent promotion should preserve alternates')
     process.stdout.write('Test 4: ' + (pass4 ? 'PASS' : 'FAIL') + '\n');
 
     // Test 5: duration label should resolve to the nearby slider control
@@ -111,6 +114,8 @@ async function run() {
     process.stdout.write('Test 6: ' + (pass6 ? 'PASS' : 'FAIL') + '\n');
     const pass6b = res6.element && res6.element.telemetry && res6.element.telemetry.sliderLike === true && res6.element.interactionHint && res6.element.interactionHint.kind === 'slider'
     assert.ok(pass6b, 'Duration lookup should include slider-specific telemetry')
+    assert.strictEqual(res6.resolution?.reason, 'slider_track_preferred')
+    assert.strictEqual(res6.resolution?.fallback_available, true)
     process.stdout.write('Test 6b: ' + (pass6b ? 'PASS' : 'FAIL') + '\n');
 
     // Test 7: prefer vertical track-like control over a closer text button

package/test/unit/server/response_shapes.test.ts

@@ -61,6 +61,8 @@ async function run() {
       action_id: 'tap_element_1',
       timestamp: '2026-04-23T08:00:00.000Z',
       action_type: 'tap_element',
+      lifecycle_state: 'pending_verification',
+      source_module: 'interact',
       target: {
         selector: { elementId: 'el_ready' },
         resolved: { elementId: 'el_ready', text: 'Ready', resource_id: null, accessibility_id: null, class: 'Button', bounds: [0, 0, 10, 10], index: 0 }
@@ -74,6 +76,8 @@ async function run() {
     const tapElementPayload = JSON.parse((tapElementResponse as any).content[0].text)
     assert.strictEqual(tapElementPayload.success, true)
     assert.strictEqual(tapElementPayload.action_type, 'tap_element')
+    assert.strictEqual(tapElementPayload.lifecycle_state, 'pending_verification')
+    assert.strictEqual(tapElementPayload.source_module, 'interact')
     assert.match(tapElementPayload.timestamp, /^\d{4}-\d{2}-\d{2}T/)
     assert.strictEqual(tapElementPayload.target.resolved.elementId, 'el_ready')
     assert.strictEqual(tapElementPayload.ui_fingerprint_before, 'fp_before')
@@ -84,6 +88,8 @@ async function run() {
     const tapPayload = JSON.parse((tapResponse as any).content[0].text)
     assert.strictEqual(tapPayload.success, true)
     assert.strictEqual(tapPayload.action_type, 'tap')
+    assert.strictEqual(tapPayload.lifecycle_state, 'pending_verification')
+    assert.strictEqual(tapPayload.source_module, 'server')
     assert.match(tapPayload.timestamp, /^\d{4}-\d{2}-\d{2}T/)
     assert.deepStrictEqual(tapPayload.target.selector, { x: 1, y: 2 })
     assert.strictEqual(tapPayload.ui_fingerprint_before, 'fp_mock')
@@ -107,6 +113,8 @@ async function run() {
     const startAppPayload = JSON.parse((startAppResponse as any).content[0].text)
     assert.strictEqual(startAppPayload.success, true)
     assert.strictEqual(startAppPayload.action_type, 'start_app')
+    assert.strictEqual(startAppPayload.lifecycle_state, 'pending_verification')
+    assert.strictEqual(startAppPayload.source_module, 'server')
     assert.match(startAppPayload.timestamp, /^\d{4}-\d{2}-\d{2}T/)
     assert.strictEqual(startAppPayload.device.id, 'emulator-5554')
     assert.deepStrictEqual(startAppPayload.target.selector, { appId: 'com.example.app' })