mobile-debug-mcp 0.34.0 → 0.35.0

package/src/server/definitions/input.ts

@@ -0,0 +1,276 @@
+import { verificationModeJson, responseModeJson } from '../../contracts/execution-controls.js'
+import type { Tool } from '@modelcontextprotocol/sdk/types.js'
+
+export const inputTools: Tool[] = [
+{
+    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.'
+        }
+      }
+    }
+  }
+]

package/src/server/definitions/manage.ts

@@ -0,0 +1,196 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js'
+
+export const manageTools: Tool[] = [
+{
+    name: 'start_app',
+    description: `Purpose:
+Launch a mobile app on Android or iOS.
+
+Inputs:
+- platform
+- appId
+- 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 = { appId }
+- success = true when launch was dispatched successfully
+- failure_code/retryable when launch dispatch fails
+- ui_fingerprint_before/ui_fingerprint_after when available
+
+Recommended Usage:
+1. Define the expected landing screen when it is known
+2. Call start_app
+3. If needed, wait for transition using wait_for_*
+4. Verify with expect_screen
+5. If verification fails, retry once or capture a snapshot
+
+Verification Guidance:
+- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT
+- expect_screen is the authoritative verification step when the landing screen is known
+- Do not treat timing or screen change alone as final verification
+
+Failure Handling:
+- TIMEOUT → retry once
+- UNKNOWN → inspect snapshot/logs before retrying`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        platform: {
+          type: 'string',
+          enum: ['android', 'ios']
+        },
+        appId: {
+          type: 'string',
+          description: 'Android package name or iOS bundle id'
+        },
+        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']
+    }
+  },
+{
+    name: 'terminate_app',
+    description: 'Terminate a mobile app on Android or iOS simulator',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        platform: {
+          type: 'string',
+          enum: ['android', 'ios']
+        },
+        appId: {
+          type: 'string',
+          description: 'Android package name or iOS bundle id'
+        },
+        deviceId: {
+          type: 'string',
+          description: 'Device UDID (iOS) or Serial (Android). Defaults to booted/connected.'
+        }
+      },
+      required: ['platform', 'appId']
+    }
+  },
+{
+    name: 'restart_app',
+    description: `Purpose:
+Restart a mobile app on Android or iOS.
+
+Inputs:
+- platform
+- appId
+- 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 = { appId }
+- success = true when the restart command completed
+- failure_code/retryable when restart dispatch fails
+- ui_fingerprint_before/ui_fingerprint_after when available
+
+Recommended Usage:
+1. Define the expected landing screen when it is known
+2. Call restart_app
+3. If needed, wait for transition using wait_for_*
+4. Verify with expect_screen
+5. If verification fails, retry once or capture a snapshot
+
+Verification Guidance:
+- Follow RESOLVE → ACT → WAIT (if needed) → EXPECT
+- expect_screen is the authoritative verification step when the reopened screen is known
+- Do not treat timing or screen change alone as final verification
+
+Failure Handling:
+- TIMEOUT → retry once
+- UNKNOWN → inspect snapshot/logs before retrying`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        platform: {
+          type: 'string',
+          enum: ['android', 'ios']
+        },
+        appId: {
+          type: 'string',
+          description: 'Android package name or iOS bundle id'
+        },
+        deviceId: {
+          type: 'string',
+          description: 'Device UDID (iOS) or Serial (Android). Defaults to booted/connected.'
+        }
+      },
+      required: ['platform', 'appId']
+    }
+  },
+{
+    name: 'reset_app_data',
+    description: 'Reset app data (clear storage) for a mobile app on Android or iOS simulator',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        platform: {
+          type: 'string',
+          enum: ['android', 'ios']
+        },
+        appId: {
+          type: 'string',
+          description: 'Android package name or iOS bundle id'
+        },
+        deviceId: {
+          type: 'string',
+          description: 'Device UDID (iOS) or Serial (Android). Defaults to booted/connected.'
+        }
+      },
+      required: ['platform', 'appId']
+    }
+  },
+{
+    name: 'install_app',
+    description: 'Install an app on Android or iOS. Accepts a built binary (apk/.ipa/.app) or a project directory to build then install. platform and projectType are required.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        platform: { type: 'string', enum: ['android', 'ios'], description: 'Platform to install to (required).' },
+        projectType: { type: 'string', enum: ['native', 'kmp', 'react-native', 'flutter'], description: 'Project type to guide build/install tool selection (required).' },
+        appPath: { type: 'string', description: 'Path to APK, .app, .ipa, or project directory' },
+        deviceId: { type: 'string', description: 'Device UDID (iOS) or Serial (Android). Defaults to booted/connected.' }
+      },
+      required: ['platform', 'projectType', 'appPath']
+    }
+  },
+{
+    name: 'build_app',
+    description: 'Build a project for Android or iOS and return the built artifact path. Does not install. platform and projectType are required.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        platform: { type: 'string', enum: ['android', 'ios'], description: 'Platform to build for (required).' },
+        projectType: { type: 'string', enum: ['native', 'kmp', 'react-native', 'flutter'], description: 'Project type to guide build tool selection (required).' },
+        projectPath: { type: 'string', description: 'Path to project directory (contains gradlew or xcodeproj/xcworkspace)' },
+        variant: { type: 'string', description: 'Optional build variant (e.g., Debug/Release)' }
+      },
+      required: ['platform', 'projectType', 'projectPath']
+    }
+  },
+{
+    name: 'list_devices',
+    description: 'List connected devices and their metadata (android + ios).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        platform: { type: 'string', enum: ['android', 'ios'] }
+      }
+    }
+  }
+]

package/src/server/definitions/observe.ts

@@ -0,0 +1,151 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js'
+
+export const observeTools: Tool[] = [
+{
+    name: 'get_logs',
+    description: 'Get recent logs from Android or iOS simulator. Returns device metadata and structured logs suitable for AI consumption.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        platform: {
+          type: 'string',
+          enum: ['android', 'ios']
+        },
+        appId: {
+          type: 'string',
+          description: 'Filter by Android package name or iOS bundle id'
+        },
+        deviceId: {
+          type: 'string',
+          description: 'Device UDID (iOS) or Serial (Android). Defaults to booted/connected.'
+        },
+        pid: { type: 'number', description: 'Filter by process id' },
+        tag: { type: 'string', description: 'Filter by tag (Android) or subsystem/category (iOS)' },
+        level: { type: 'string', description: 'Log level filter (VERBOSE, DEBUG, INFO, WARN, ERROR)' },
+        contains: { type: 'string', description: 'Substring to match in log message' },
+        since_seconds: { type: 'number', description: 'Only return logs from the last N seconds' },
+        limit: { type: 'number', description: 'Override default number of returned lines' },
+        lines: {
+          type: 'number',
+          description: 'Legacy - number of log lines (android only)'
+        }
+      },
+      required: ['platform']
+    }
+  },
+{
+    name: 'capture_screenshot',
+    description: 'Capture a screenshot from an Android device or iOS simulator. Returns device metadata and the screenshot image.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        platform: {
+          type: 'string',
+          enum: ['android', 'ios']
+        },
+        deviceId: {
+          type: 'string',
+          description: 'Device UDID (iOS) or Serial (Android). Defaults to booted/connected.'
+        }
+      },
+      required: ['platform']
+    }
+  },
+{
+    name: 'capture_debug_snapshot',
+    description: 'Capture a complete debug snapshot (raw observation layer plus optional derived semantic layer). Returns structured JSON with snapshot_revision, captured_at_ms, snapshot_delta, and loading_state when detectable.',
+    inputSchema: {
+      type: 'object',
+      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)' },
+        deviceId: { type: 'string', description: 'Optional device serial/udid' },
+        sessionId: { type: 'string', description: 'Optional log stream session id to prefer' }
+      }
+    }
+  },
+{
+    name: 'start_log_stream',
+    description: 'Start streaming logs for a target application on Android or iOS. For Android this uses adb logcat --pid=<pid>; for iOS it streams `xcrun simctl spawn <device> log stream` with a predicate.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        platform: { type: 'string', enum: ['android', 'ios'], default: 'android' },
+        packageName: { type: 'string', description: 'Android package name or iOS bundle id' },
+        level: { type: 'string', enum: ['error', 'warn', 'info', 'debug'], default: 'error' },
+        deviceId: { type: 'string', description: 'Device Serial (Android) or UDID (iOS). Defaults to connected/booted device.' },
+        sessionId: { type: 'string', description: 'Session identifier for the log stream' }
+      },
+      required: ['packageName']
+    }
+  },
+{
+    name: 'read_log_stream',
+    description: 'Read accumulated log stream entries for the active session.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: { type: 'string' }
+      }
+    }
+  },
+{
+    name: 'stop_log_stream',
+    description: 'Stop an active log stream for the session.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: { type: 'string' }
+      }
+    }
+  },
+{
+    name: 'get_ui_tree',
+    description: 'Get the current UI hierarchy from an Android device or iOS simulator. Returns a structured JSON representation of the screen content with snapshot metadata and incremental delta signals when available.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        platform: {
+          type: 'string',
+          enum: ['android', 'ios'],
+          description: 'Platform to get UI tree for'
+        },
+        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']
+    }
+  },
+{
+    name: 'get_current_screen',
+    description: 'Get the currently visible activity on an Android device. Returns package and activity name.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        deviceId: {
+          type: 'string',
+          description: 'Device Serial (Android). Defaults to connected/booted device.'
+        }
+      }
+    }
+  },
+{
+    name: 'get_screen_fingerprint',
+    description: 'Generate a stable fingerprint representing the current visible screen (activity + visible UI elements).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        platform: { type: 'string', enum: ['android', 'ios'], description: 'Optional platform override (android|ios)' },
+        deviceId: { type: 'string', description: 'Optional device id/udid to target' }
+      }
+    }
+  }
+]