mobile-debug-mcp 0.34.0 → 0.35.0

package/dist/server/definitions/assert.js

@@ -0,0 +1,162 @@
+export const assertTools = [
+    {
+        name: 'expect_screen',
+        description: `Purpose:
+Deterministically verify that the intended navigation outcome of an action has occurred.
+
+Inputs:
+- fingerprint: preferred exact-match screen fingerprint
+- screen: exact semantic screen identifier when a fingerprint is not available
+
+Output Structure:
+- success: true when the expected screen matches the observed screen
+- observed_screen: current fingerprint and screen identifier
+- expected_screen: the expected fingerprint and/or screen identifier
+- confidence: 1 for an exact match, otherwise 0
+
+Recommended Usage:
+1. Define the expected screen before executing the action
+2. Resolve the target element or screen state
+3. Call an action tool such as tap_element
+4. If needed, wait for transition using wait_for_*
+5. Call expect_screen as the final verification step
+6. If success=false, treat the outcome as unverified and follow the action tool retry guidance
+
+Verification Guidance:
+- Primary and authoritative verification tool for navigation outcomes
+- Prefer fingerprint whenever you have one
+- Use screen only as a fallback exact match against known identifiers
+- Works best when the expected screen identifier is known ahead of time
+- If the expected screen is not already known, capture or define it before executing the action
+
+Constraints:
+- Returns structured binary success/failure only
+- Must not rely on natural-language interpretation or reasoning
+
+Failure Handling:
+- success=false means the expected screen was not reached; retry or recover using the action tool's failure strategy`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override (android|ios)' },
+                fingerprint: { type: 'string', description: 'Expected screen fingerprint. Preferred verification mechanism.' },
+                screen: { type: 'string', description: 'Expected exact screen identifier when no fingerprint is available.' },
+                deviceId: { type: 'string', description: 'Optional device id/udid to target' }
+            }
+        }
+    },
+    {
+        name: 'expect_element_visible',
+        description: `Purpose:
+Deterministically verify that the intended UI outcome of an action has occurred by confirming a target element is visible.
+
+Inputs:
+- selector: required selector used to resolve the target element
+- element_id: optional previously resolved element identifier used only as context
+
+Output Structure:
+- success: true when the element is visible
+- selector: selector used for verification
+- element_id: resolved element identifier when available
+- element: minimal resolved element info when visible
+- failure_code: TIMEOUT or UNKNOWN when verification fails
+- retryable: true when failure_code=TIMEOUT
+
+Recommended Usage:
+1. Define the expected element state before executing the action
+2. Resolve the target element or triggering control
+3. Call an action tool such as tap_element
+4. If needed, wait for UI availability using wait_for_*
+5. Call expect_element_visible as the final verification step
+6. If success=false, follow the action tool retry guidance
+
+Verification Guidance:
+- Primary and authoritative verification tool for expected element appearance or visibility
+- Use this when the screen should stay the same but the UI should reveal or update a specific element
+- selector is the primary input; element_id is an optional optimization only
+- The tool resolves the selector internally when needed
+
+Constraints:
+- Returns structured binary success/failure only
+- Must not rely on natural-language interpretation or reasoning
+
+Failure Handling:
+- TIMEOUT → retry verification once or retry the action after re-resolving
+- 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.' },
+                timeout_ms: { type: 'number', default: 5000 },
+                poll_interval_ms: { type: 'number', default: 300 },
+                platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override' },
+                deviceId: { type: 'string', description: 'Optional device serial/udid' }
+            },
+            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']
+        }
+    }
+];

package/dist/server/definitions/diagnostic.js

@@ -0,0 +1,118 @@
+export const diagnosticTools = [
+    {
+        name: 'get_system_status',
+        description: 'Quick healthcheck of local mobile debugging environment (adb, devices, logs, env, iOS).',
+        inputSchema: { type: 'object', properties: {} }
+    },
+    {
+        name: 'classify_action_outcome',
+        description: `Classify the outcome of the most recent action into exactly one of: success, no_op, backend_failure, ui_failure, unknown.
+
+Use the runtime action result's \`action_type\` as \`actionType\` so the classifier can distinguish local-state actions from side-effect actions.
+Use this when the intended outcome is not already fully verified by the UI signal alone.
+For backend/API activity, compare get_screen_fingerprint before and after the action and call get_network_activity immediately after the action if the outcome is still ambiguous.
+
+HOW TO GATHER INPUTS before calling:
+1. Call wait_for_screen_change or compare get_screen_fingerprint before/after — set uiChanged accordingly.
+2. If you checked for a specific element with wait_for_ui, set expectedElementVisible.
+3. Pass actionType from the action response when available.
+4. Only provide networkRequests if you already collected them or want to classify a side-effect action with backend evidence.
+
+RULES (applied in order — stop at first match):
+1. If uiChanged=true OR expectedElementVisible=true → outcome=success
+2. If actionType is missing → outcome=unknown
+3. If any request has status=failure or retryable → outcome=backend_failure
+4. If actionType maps to a local-state action → outcome=no_op; prefer state-based verification and avoid default network fallback
+5. If actionType maps to a side-effect action and no networkRequests were supplied → outcome=unknown
+6. If no requests returned → outcome=no_op
+7. If all requests succeeded → outcome=ui_failure
+8. Otherwise → outcome=unknown
+
+BEHAVIOUR after outcome:
+- success → continue
+- no_op → retry with richer state verification or re-resolve the element
+- backend_failure → stop and report the failing endpoint
+- ui_failure → stop and report failure
+- unknown → take one recovery step (e.g. capture_debug_snapshot), then stop`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                uiChanged: {
+                    type: 'boolean',
+                    description: 'true if the screen fingerprint or activity changed after the action. Use wait_for_screen_change or compare get_screen_fingerprint before and after.'
+                },
+                expectedElementVisible: {
+                    type: 'boolean',
+                    description: 'true if the element you expected to appear is now visible (from wait_for_ui). Omit if you did not check for a specific element.'
+                },
+                actionType: {
+                    type: 'string',
+                    description: 'The runtime action_type from the action response (for example tap, tap_element, swipe, type_text, press_back, start_app).'
+                },
+                networkRequests: {
+                    type: 'array',
+                    description: 'Optional network evidence collected after the action. Use it when the expected outcome is backend/API activity or when the UI signal is ambiguous.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            endpoint: { type: 'string', description: 'Request endpoint or full URL' },
+                            status: { type: 'string', enum: ['success', 'failure', 'retryable'], description: 'Outcome of the request' }
+                        },
+                        required: ['endpoint', 'status']
+                    }
+                },
+                hasLogErrors: {
+                    type: 'boolean',
+                    description: 'true if structured log errors were observed (e.g. from read_log_stream). Optional — include if you have already read logs.'
+                }
+            },
+            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.
+
+Call this immediately after an action when you want backend evidence for a side-effect flow, only if the result is still ambiguous.
+Do not call more than once per action.
+
+Events are filtered to significant (non-background) requests only.
+Each event includes endpoint, method, statusCode, networkError, status, and durationMs.
+
+status values:
+- success: HTTP 2xx or request detected with no error signal
+- failure: HTTP 4xx
+- retryable: HTTP 5xx, network error (timeout, dns_error, tls_error, etc.)
+
+Returns { requests: [], count: 0 } when no credible network signals are found.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                platform: {
+                    type: 'string',
+                    enum: ['android', 'ios'],
+                    description: 'Platform to read network logs from'
+                },
+                deviceId: {
+                    type: 'string',
+                    description: 'Device Serial (Android) or UDID (iOS). Defaults to connected/booted device.'
+                }
+            },
+            required: ['platform']
+        }
+    }
+];

package/dist/server/definitions/input.js

@@ -0,0 +1,274 @@
+import { verificationModeJson, responseModeJson } from '../../contracts/execution-controls.js';
+export const inputTools = [
+    {
+        name: 'tap',
+        description: `Purpose:
+Dispatch a tap at specific screen coordinates.
+
+Inputs:
+- x, y coordinates
+- platform (optional)
+- deviceId (optional)
+
+Output Structure:
+ - action_id, timestamp (ISO 8601), action_type
+ - lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+ - source_module: runtime source of the action envelope
+ - target.selector = { x, y }
+- success = true when the tap was dispatched
+- failure_code/retryable when dispatch fails
+- ui_fingerprint_before/ui_fingerprint_after when available
+
+Recommended Usage:
+1. Resolve coordinates deterministically
+2. Call tap
+3. If needed, wait for transition using wait_for_*
+4. Verify with expect_screen or expect_element_visible depending on the intended outcome
+
+Verification Guidance:
+- Prefer tap_element over tap when an element can be resolved
+- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT
+- Use expect_screen for navigation and expect_element_visible for local UI changes
+- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists
+
+Failure Handling:
+- TIMEOUT → retry once
+- UNKNOWN → capture a snapshot and stop`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                platform: {
+                    type: 'string',
+                    enum: ['android', 'ios'],
+                    description: 'Platform to tap on'
+                },
+                x: {
+                    type: 'number',
+                    description: 'X coordinate'
+                },
+                y: {
+                    type: 'number',
+                    description: 'Y coordinate'
+                },
+                deviceId: {
+                    type: 'string',
+                    description: 'Device Serial/UDID. Defaults to connected/booted device.'
+                },
+                verificationMode: { ...verificationModeJson, default: 'full' },
+                responseMode: { ...responseModeJson, default: 'debug' },
+                actionTimeoutMs: { type: 'number', minimum: 100, maximum: 30000 },
+                verificationTimeoutMs: { type: 'number', minimum: 100, maximum: 60000 }
+            },
+            required: ['x', 'y']
+        }
+    },
+    {
+        name: 'swipe',
+        description: `Purpose:
+Dispatch a swipe gesture on Android or iOS.
+
+Inputs:
+- start and end coordinates
+- duration
+- platform/deviceId (optional)
+
+Output Structure:
+- action_id, timestamp (ISO 8601), action_type
+- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+- source_module: runtime source of the action envelope
+- target.selector = { x1, y1, x2, y2, duration }
+- success = true when the swipe was dispatched
+- failure_code/retryable when dispatch fails
+- ui_fingerprint_before/ui_fingerprint_after when available
+
+Recommended Usage:
+1. Determine swipe coordinates
+2. Call swipe
+3. If needed, wait for transition using wait_for_*
+4. Verify with expect_screen or expect_element_visible when a deterministic outcome is expected
+
+Verification Guidance:
+- Swipe outcomes are less predictable; choose the most specific verifier available for the intended effect
+- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT
+- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists
+
+Failure Handling:
+- TIMEOUT → retry once
+- UNKNOWN → capture a snapshot and stop`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                platform: {
+                    type: 'string',
+                    enum: ['android', 'ios'],
+                    description: 'Platform to swipe on (android or ios)'
+                },
+                x1: { type: 'number', description: 'Start X coordinate' },
+                y1: { type: 'number', description: 'Start Y coordinate' },
+                x2: { type: 'number', description: 'End X coordinate' },
+                y2: { type: 'number', description: 'End Y coordinate' },
+                duration: { type: 'number', description: 'Duration in ms' },
+                deviceId: {
+                    type: 'string',
+                    description: 'Device Serial/UDID. Defaults to connected/booted device.'
+                }
+            },
+            required: ['x1', 'y1', 'x2', 'y2', 'duration']
+        }
+    },
+    {
+        name: 'scroll_to_element',
+        description: `Purpose:
+Scroll until a target element becomes visible.
+
+Inputs:
+- platform
+- selector
+- direction, maxScrolls, scrollAmount, deviceId (optional)
+
+Output Structure:
+- action_id, timestamp (ISO 8601), action_type
+- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+- source_module: runtime source of the action envelope
+- target.selector = original selector
+- target.resolved = minimal resolved element info when found
+- success = true when scrolling produced a visible target element
+- failure_code/retryable when the target was not reached
+- ui_fingerprint_before/ui_fingerprint_after when available
+
+Recommended Usage:
+1. Resolve the target selector
+2. Call scroll_to_element
+3. If needed, wait for UI stabilization using wait_for_*
+4. Verify with expect_element_visible when the expected element visibility is known
+5. If success=false, follow failure handling before retrying
+
+Verification Guidance:
+- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT
+- Use expect_element_visible when you need an explicit post-scroll confirmation
+- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists
+
+Failure Handling:
+- NAVIGATION_NO_CHANGE → adjust scroll direction or stop
+- TIMEOUT → retry with refined selector or larger scroll budget
+- UNKNOWN → capture a snapshot and stop`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                platform: { type: 'string', enum: ['android', 'ios'], description: 'Platform to operate on (required)' },
+                selector: {
+                    type: 'object',
+                    properties: {
+                        text: { type: 'string' },
+                        resourceId: { type: 'string' },
+                        contentDesc: { type: 'string' },
+                        className: { type: 'string' }
+                    }
+                },
+                direction: { type: 'string', enum: ['down', 'up'], default: 'down' },
+                maxScrolls: { type: 'number', default: 10 },
+                scrollAmount: { type: 'number', default: 0.7 },
+                deviceId: { type: 'string', description: 'Device UDID (iOS) or Serial (Android). Defaults to booted/connected.' }
+            },
+            required: ['platform', 'selector']
+        }
+    },
+    {
+        name: 'type_text',
+        description: `Purpose:
+Type text into the currently focused Android input field.
+
+Inputs:
+- text
+- platform/deviceId (optional)
+
+Output Structure:
+- action_id, timestamp (ISO 8601), action_type
+- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+- source_module: runtime source of the action envelope
+- target.selector = { text }
+- success = true when text input was dispatched
+- failure_code/retryable when dispatch fails
+- ui_fingerprint_before/ui_fingerprint_after when available
+
+Recommended Usage:
+1. Resolve or focus the target input first
+2. Call type_text
+3. If needed, wait for UI stabilization using wait_for_*
+4. Verify with expect_element_visible or expect_screen, depending on the intended outcome
+
+Verification Guidance:
+- Prefer verifying the next expected element or screen state instead of inferring success from the text action alone
+- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT
+- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists
+
+Failure Handling:
+- TIMEOUT → retry once
+- UNKNOWN → re-focus the input or capture a snapshot`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                platform: {
+                    type: 'string',
+                    enum: ['android'],
+                    description: 'Platform to type on (currently only android supported)'
+                },
+                text: {
+                    type: 'string',
+                    description: 'The text to type'
+                },
+                deviceId: {
+                    type: 'string',
+                    description: 'Device Serial/UDID. Defaults to connected/booted device.'
+                }
+            },
+            required: ['text']
+        }
+    },
+    {
+        name: 'press_back',
+        description: `Purpose:
+Dispatch the Android Back action.
+
+Inputs:
+- platform/deviceId (optional)
+
+Output Structure:
+- action_id, timestamp (ISO 8601), action_type
+- lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
+- source_module: runtime source of the action envelope
+- target.selector = { key: "back" }
+- success = true when the back action was dispatched
+- failure_code/retryable when dispatch fails
+- ui_fingerprint_before/ui_fingerprint_after when available
+
+Recommended Usage:
+1. Call press_back
+2. If needed, wait for transition using wait_for_*
+3. Verify with expect_screen when a known destination is expected
+4. If verification fails, retry once or recover explicitly
+
+Verification Guidance:
+- Back outcomes can vary by screen, so verify against the intended destination when possible
+- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT
+- Do not use wait_for_* alone as final verification when an applicable expect_* tool exists
+
+Failure Handling:
+- TIMEOUT → retry once
+- UNKNOWN → capture a snapshot and stop`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                platform: {
+                    type: 'string',
+                    enum: ['android'],
+                    description: 'Platform (currently only android supported)'
+                },
+                deviceId: {
+                    type: 'string',
+                    description: 'Device Serial/UDID. Defaults to connected/booted device.'
+                }
+            }
+        }
+    }
+];