mobile-debug-mcp 0.31.0 → 0.32.1

package/dist/server/journey-schema.js

@@ -0,0 +1,60 @@
+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) => 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, required, 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/dist/server/tool-definitions.js

@@ -1,3 +1,4 @@
+import { journeyStepsJson } from './journey-schema.js';
 export const toolDefinitions = [
     {
         name: 'start_app',
@@ -47,7 +48,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 +255,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 +313,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 +737,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 +795,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 +1079,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 +1126,25 @@ 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' }
+                } }
+        });
+}