mobile-debug-mcp 0.30.2 → 0.32.0

package/src/server/common.ts

@@ -1,3 +1,4 @@
+import { recordTiming } from '../utils/timing.js'
 import type {
   ActionTrace,
   ActionExecutionResult,
@@ -14,13 +15,17 @@ import { ToolsObserve } from '../observe/index.js'
 export const DEFAULT_MAX_RECOVERY_ATTEMPTS = 3
 export const DEFAULT_MAX_RETRY_DEPTH = 3
 
-export function wrapResponse<T>(data: T) {
-  return {
-    content: [{
-      type: 'text' as const,
-      text: JSON.stringify(data, null, 2)
-    }]
+export function wrapResponse<T>(data: T, includeSerializationTiming = true) {
+  const start = performance.now()
+  let text = JSON.stringify(data, null, 2)
+  const elapsed = performance.now() - start
+  const value = data as any
+  if (includeSerializationTiming && value && typeof value === 'object' && value.timing && typeof value.timing === 'object') {
+    value.timing.serialization_ms = (value.timing.serialization_ms ?? 0) + elapsed
+    recordTiming('serialization_ms', elapsed)
+    text = JSON.stringify(value, null, 2)
   }
+  return { content: [{ type: 'text' as const, text }] }
 }
 
 export type ToolCallArgs = Record<string, unknown>
@@ -312,6 +317,7 @@ function mapFailureCodeToFailureClass(code: ActionFailureCode): FailureClass {
     case 'STALE_REFERENCE':
       return 'TargetResolutionFailure'
     case 'ELEMENT_NOT_INTERACTABLE':
+    case 'ACTION_TIMEOUT':
       return 'ExecutionFailure'
     case 'TIMEOUT':
     case 'ACTION_REJECTED':
@@ -320,6 +326,7 @@ function mapFailureCodeToFailureClass(code: ActionFailureCode): FailureClass {
       return 'ExecutionFailure'
     case 'VERIFICATION_FAILED':
     case 'EXPECT_STATE_MISMATCH':
+    case 'ASSERTION_TIMEOUT':
       return 'VerificationFailure'
     case 'CONTROL_CONVERGENCE_FAILED':
       return 'ControlConvergenceFailure'

package/src/server/journey-schema.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod'
+
+const selector = z.object({
+  text: z.string().min(1).optional(), resource_id: z.string().min(1).optional(),
+  accessibility_id: z.string().min(1).optional(), contains: z.boolean().optional()
+}).strict().refine(value => !!(value.text || value.resource_id || value.accessibility_id), 'Selector requires a target')
+const verificationMode = z.enum(['none', 'light', 'full'])
+const timeoutMs = z.number().int().min(100).max(60000).optional()
+const pollIntervalMs = z.number().int().min(50).max(1000).optional()
+const waitFor = z.object({
+  condition: z.enum(['exists', 'visible', 'clickable']).optional(),
+  timeoutMs: z.number().int().min(100).max(10000).optional(), pollIntervalMs,
+  match: z.object({ index: z.number().int().nonnegative().optional() }).strict().optional()
+}).strict()
+const target = { selector: selector.optional(), elementId: z.string().min(1).optional() }
+const exactlyOneTarget = (value: { selector?: unknown, elementId?: string }) => Number(!!value.selector) + Number(!!value.elementId) === 1
+const assertion = z.union([
+  z.object({ kind: z.literal('element_visible'), selector }).strict(),
+  z.object({ kind: z.literal('element_absent'), selector }).strict(),
+  z.object({ kind: z.literal('screen_fingerprint'), fingerprint: z.string().min(1) }).strict(),
+  z.object({ kind: z.literal('state_equals'), property: z.string().min(1), expected: z.union([z.boolean(), z.number().finite(), z.string()]), ...target }).strict().refine(exactlyOneTarget)
+])
+const id = z.string().min(1)
+const step = z.union([
+  z.object({ id, type: z.literal('start_app'), appId: z.string().min(1), verificationMode: verificationMode.optional() }).strict(),
+  z.object({ id, type: z.literal('tap'), ...target, waitFor: waitFor.optional(), verificationMode: verificationMode.optional() }).strict().refine(exactlyOneTarget),
+  z.object({ id, type: z.literal('wait'), selector, condition: z.enum(['exists', 'not_exists', 'visible', 'clickable']).optional(), timeoutMs, pollIntervalMs }).strict(),
+  z.object({ id, type: z.literal('assert'), assertion, timeoutMs, pollIntervalMs }).strict()
+])
+export const tapElementControlsSchema = z.object({
+  elementId: z.string().min(1).optional(), selector: selector.optional(), waitFor: waitFor.optional()
+}).strict().refine(value => Number(!!value.elementId) + Number(!!value.selector) === 1 && (!value.elementId || !value.waitFor))
+
+export const journeySchema = z.object({
+  platform: z.enum(['android', 'ios']), deviceId: z.string().min(1).optional(),
+  responseMode: z.enum(['compact', 'debug']).default('compact'), captureOnFailure: z.boolean().default(false),
+  defaults: z.object({ verificationMode: verificationMode.optional(), actionTimeoutMs: z.number().int().finite().optional(), verificationTimeoutMs: z.number().int().finite().optional() }).strict().optional(),
+  steps: z.array(step).min(1).max(50)
+}).strict().refine(value => new Set(value.steps.map(step => step.id)).size === value.steps.length, 'Step IDs must be unique')
+
+const selectorJson = { type: 'object', additionalProperties: false, properties: {
+  text: { type: 'string', minLength: 1 }, resource_id: { type: 'string', minLength: 1 }, accessibility_id: { type: 'string', minLength: 1 }, contains: { type: 'boolean' }
+}, anyOf: ['text', 'resource_id', 'accessibility_id'].map(key => ({ required: [key] })) }
+const targetJson = { selector: selectorJson, elementId: { type: 'string', minLength: 1 } }
+const oneTargetJson = [{ required: ['selector'], not: { required: ['elementId'] } }, { required: ['elementId'], not: { required: ['selector'] } }]
+const intervalJson = { timeoutMs: { type: 'integer', minimum: 100, maximum: 60000 }, pollIntervalMs: { type: 'integer', minimum: 50, maximum: 1000 } }
+const modeJson = { type: 'string', enum: ['none', 'light', 'full'] }
+const objectJson = (properties: Record<string, unknown>, required: string[], extra = {}) => ({ type: 'object', additionalProperties: false, properties, required, ...extra })
+export const journeyStepsJson = {
+  type: 'array', minItems: 1, maxItems: 50, items: { oneOf: [
+    objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'start_app' }, appId: { type: 'string', minLength: 1 }, verificationMode: modeJson }, ['id', 'type', 'appId']),
+    objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'tap' }, ...targetJson, verificationMode: modeJson,
+      waitFor: objectJson({ ...intervalJson, timeoutMs: { type: 'integer', minimum: 100, maximum: 10000 }, condition: { enum: ['exists', 'visible', 'clickable'] }, match: objectJson({ index: { type: 'integer', minimum: 0 } }, []) }, [])
+    }, ['id', 'type'], { oneOf: oneTargetJson }),
+    objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'wait' }, selector: selectorJson, condition: { enum: ['exists', 'not_exists', 'visible', 'clickable'] }, ...intervalJson }, ['id', 'type', 'selector']),
+    objectJson({ id: { type: 'string', minLength: 1 }, type: { const: 'assert' }, ...intervalJson, assertion: { oneOf: [
+      objectJson({ kind: { const: 'element_visible' }, selector: selectorJson }, ['kind', 'selector']),
+      objectJson({ kind: { const: 'element_absent' }, selector: selectorJson }, ['kind', 'selector']),
+      objectJson({ kind: { const: 'screen_fingerprint' }, fingerprint: { type: 'string', minLength: 1 } }, ['kind', 'fingerprint']),
+      objectJson({ kind: { const: 'state_equals' }, ...targetJson, property: { type: 'string', minLength: 1 }, expected: { type: ['boolean', 'number', 'string'] } }, ['kind', 'property', 'expected'], { oneOf: oneTargetJson })
+    ] } }, ['id', 'type', 'assertion'])
+  ] }
+}

package/src/server/tool-definitions.ts

@@ -1,4 +1,6 @@
-export const toolDefinitions = [
+import { journeyStepsJson } from './journey-schema.js'
+
+export const toolDefinitions: any[] = [
   {
     name: 'start_app',
     description: `Purpose:
@@ -47,7 +49,11 @@ Failure Handling:
         deviceId: {
           type: 'string',
           description: 'Device UDID (iOS) or Serial (Android). Defaults to booted/connected.'
-        }
+        },
+        verificationMode: { type: 'string', enum: ['none', 'light', 'full'], default: 'full' },
+        responseMode: { type: 'string', enum: ['compact', 'debug'], default: 'debug' },
+        actionTimeoutMs: { type: 'number', minimum: 100, maximum: 30000 },
+        verificationTimeoutMs: { type: 'number', minimum: 100, maximum: 60000 }
       },
       required: ['platform', 'appId']
     }
@@ -250,6 +256,7 @@ Failure Handling:
       properties: {
         reason: { type: 'string', description: 'Optional reason for snapshot' },
         includeLogs: { type: 'boolean', description: 'Whether to include logs', default: true },
+        includeScreenshot: { type: 'boolean', description: 'Whether to collect screenshot bytes', default: true },
         logLines: { type: 'number', description: 'Maximum number of log lines to include', default: 200 },
         platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override' },
         appId: { type: 'string', description: 'Optional appId to scope logs (package/bundle id)' },
@@ -307,7 +314,9 @@ Failure Handling:
         deviceId: {
           type: 'string',
           description: 'Device Serial (Android) or UDID (iOS). Defaults to connected/booted device.'
-        }
+        },
+        responseMode: { type: 'string', enum: ['compact', 'debug'], default: 'debug' },
+        sinceSnapshotRevision: { type: 'number', minimum: 1 }
       },
       required: ['platform']
     }
@@ -729,7 +738,11 @@ Failure Handling:
         deviceId: {
           type: 'string',
           description: 'Device Serial/UDID. Defaults to connected/booted device.'
-        }
+        },
+        verificationMode: { type: 'string', enum: ['none', 'light', 'full'], default: 'full' },
+        responseMode: { type: 'string', enum: ['compact', 'debug'], default: 'debug' },
+        actionTimeoutMs: { type: 'number', minimum: 100, maximum: 30000 },
+        verificationTimeoutMs: { type: 'number', minimum: 100, maximum: 60000 }
       },
       required: ['x', 'y']
     }
@@ -783,9 +796,14 @@ This tool reports execution success only. Verification must be done with a separ
         elementId: {
           type: 'string',
           description: 'A unique element identifier returned by wait_for_ui'
-        }
-      },
-      required: ['elementId']
+        },
+        selector: { type: 'object', properties: { text: { type: 'string' }, resource_id: { type: 'string' }, accessibility_id: { type: 'string' }, contains: { type: 'boolean' } } },
+        waitFor: { type: 'object', properties: { condition: { type: 'string', enum: ['exists', 'visible', 'clickable'] }, timeoutMs: { type: 'number', minimum: 100, maximum: 10000 }, pollIntervalMs: { type: 'number', minimum: 50, maximum: 1000 }, match: { type: 'object', properties: { index: { type: 'number' } } } } },
+        platform: { type: 'string', enum: ['android', 'ios'] },
+        deviceId: { type: 'string' },
+        verificationMode: { type: 'string', enum: ['none', 'light', 'full'], default: 'full' },
+        responseMode: { type: 'string', enum: ['compact', 'debug'], default: 'debug' }
+      }
     }
   },
   {
@@ -1062,6 +1080,20 @@ BEHAVIOUR after outcome:
       required: ['uiChanged']
     }
   },
+  {
+    name: 'run_journey',
+    description: 'Run an ordered, bounded sequence of start_app, tap, wait, and deterministic assertion steps against one device. Stops after the first failed step.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        platform: { type: 'string', enum: ['android', 'ios'] },
+        deviceId: { type: 'string' },
+        responseMode: { type: 'string', enum: ['compact', 'debug'], default: 'compact' },
+        steps: { type: 'array', minItems: 1, maxItems: 50, items: { type: 'object', properties: { id: { type: 'string' }, type: { type: 'string', enum: ['start_app', 'tap', 'wait', 'assert'] } }, required: ['id', 'type'] } }
+      },
+      required: ['platform', 'steps']
+    }
+  },
   {
     name: 'get_network_activity',
     description: `Returns structured network events captured from platform logs since the last action.
@@ -1095,3 +1127,24 @@ Returns { requests: [], count: 0 } when no credible network signals are found.`,
     }
   }
 ]
+
+// Keep the additive execution controls consistent across all action tools.
+for (const tool of toolDefinitions) {
+  if (['start_app', 'restart_app', 'tap', 'tap_element', 'swipe', 'scroll_to_element', 'type_text', 'press_back'].includes(tool.name)) {
+    Object.assign(tool.inputSchema.properties, {
+      verificationMode: { type: 'string', enum: ['none', 'light', 'full'], default: 'full' },
+      responseMode: { type: 'string', enum: ['compact', 'debug'], default: 'debug' },
+      actionTimeoutMs: { type: 'integer', description: 'Dispatch budget in milliseconds, clamped to 100–30000.' },
+      verificationTimeoutMs: { type: 'integer', description: 'Light observation budget in milliseconds, clamped to 100–60000.' }
+    })
+  }
+  if (tool.name === 'tap_element') Object.assign(tool.inputSchema, { oneOf: [{ required: ['elementId'], not: { required: ['selector'] } }, { required: ['selector'], not: { required: ['elementId'] } }] })
+  if (tool.name === 'run_journey') Object.assign(tool.inputSchema.properties, {
+    steps: journeyStepsJson,
+    captureOnFailure: { type: 'boolean', default: false },
+    defaults: { type: 'object', additionalProperties: false, properties: {
+      verificationMode: { type: 'string', enum: ['none', 'light', 'full'] },
+      actionTimeoutMs: { type: 'integer' }, verificationTimeoutMs: { type: 'integer' }
+    } }
+  })
+}