mobile-debug-mcp 0.30.1 → 0.31.0

package/dist/system/ios.js

@@ -11,14 +11,22 @@ export async function checkIOS() {
             iosAvailable = true;
             try {
                 const simOut = execSync(`${xcrun} simctl list devices booted --json`, { encoding: 'utf8', timeout: 1500, stdio: ['ignore', 'pipe', 'ignore'] });
-                const data = JSON.parse(simOut);
-                let count = 0;
-                for (const k in data.devices) {
-                    const arr = data.devices[k];
-                    if (Array.isArray(arr))
-                        count += arr.filter((d) => (d.state || '').toLowerCase() === 'booted').length;
+                try {
+                    const data = JSON.parse(simOut);
+                    let count = 0;
+                    for (const k in data.devices) {
+                        const arr = data.devices[k];
+                        if (Array.isArray(arr))
+                            count += arr.filter((d) => (d.state || '').toLowerCase() === 'booted').length;
+                    }
+                    iosDevices = count;
+                }
+                catch {
+                    // Some xcrun builds include extra text around the JSON response.
+                    // Fall back to counting explicit booted state markers so readiness remains deterministic.
+                    const bootedMatches = (simOut.match(/"state"\s*:\s*"Booted"/gi) || []).length;
+                    iosDevices = bootedMatches;
                 }
-                iosDevices = count;
                 if (iosDevices === 0)
                     issues.push('No iOS simulators/devices booted');
             }

package/dist/utils/android/utils.js

@@ -25,9 +25,12 @@ function findInPath(cmd) {
     return null;
 }
 export function resolveAdbCmd() {
-    // Priority: explicit env ADB_PATH -> ANDROID_SDK_ROOT/platform-tools/adb -> ANDROID_HOME/platform-tools/adb -> ~/Library/Android/sdk/platform-tools/adb -> PATH discovery -> 'adb'
+    // Priority: explicit env ADB_PATH -> PATH -> known SDK locations -> fallback to 'adb'
     if (process.env.ADB_PATH && process.env.ADB_PATH.trim())
         return process.env.ADB_PATH;
+    const found = findInPath('adb');
+    if (found)
+        return found;
     const sdkRoot = process.env.ANDROID_SDK_ROOT || process.env.ANDROID_HOME;
     if (sdkRoot) {
         const candidate = path.join(sdkRoot, 'platform-tools', process.platform === 'win32' ? 'adb.exe' : 'adb');
@@ -38,9 +41,6 @@ export function resolveAdbCmd() {
     const homeSdk = path.join(process.env.HOME || '', 'Library', 'Android', 'sdk', 'platform-tools', process.platform === 'win32' ? 'adb.exe' : 'adb');
     if (existsSync(homeSdk))
         return homeSdk;
-    const found = findInPath('adb');
-    if (found)
-        return found;
     return 'adb';
 }
 export function getAdbCmd() { return resolveAdbCmd(); }

package/dist/utils/cli/idb/check-idb.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { execSync, spawnSync } from 'child_process';
 import { main as installMain } from './install-idb.js';
-import { getIdbCmd, isIDBInstalled } from './idb-helper.js';
+import { getIdbCmd, getIdbPackageVersion, isIDBInstalled } from './idb-helper.js';
 function which(cmd) {
     try {
         const r = spawnSync('command', ['-v', cmd], { stdio: ['ignore', 'pipe', 'ignore'] });
@@ -48,11 +48,18 @@ try {
     const idb = process.env.IDB_PATH || getIdbCmd();
     print('idb:', idb);
     if (idb && isIDBInstalled()) {
+        const version = getIdbPackageVersion();
+        if (version)
+            print('fb-idb version:', version);
         try {
-            print('idb --version:', execSync(`${idb} --version`, { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim());
+            const output = execSync(`${idb} list-targets --json`, { stdio: ['ignore', 'pipe', 'pipe'], timeout: 5000 }).toString().trim();
+            print('idb list-targets --json: ok');
+            if (output)
+                print(output);
         }
         catch (e) {
-            print('idb --version: (failed)', e instanceof Error ? e.message : String(e));
+            print('idb list-targets --json: (failed)', e instanceof Error ? e.message : String(e));
+            process.exit(2);
         }
         const companion = which('idb_companion');
         print('which idb_companion:', companion);

package/dist/utils/cli/idb/idb-helper.js

@@ -71,21 +71,55 @@ export function getIdbCmd() {
     }
     return null;
 }
-export function isIDBInstalled() {
-    const cmd = getIdbCmd();
+export function getIdbPackageVersion() {
+    const runners = ['python3', 'python'];
+    for (const runner of runners) {
+        try {
+            const result = spawnSync(runner, ['-m', 'pip', 'show', 'fb-idb'], {
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'pipe']
+            });
+            if (result.status !== 0)
+                continue;
+            const output = `${result.stdout || ''}\n${result.stderr || ''}`;
+            const match = output.match(/^Version:\s*(.+)$/mi);
+            if (match?.[1])
+                return match[1].trim();
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+export function probeIdb(cmd = getIdbCmd()) {
     if (!cmd)
-        return false;
+        return { ok: false, raw: null, parsedVersion: null };
     try {
-        // command -v <cmd>
-        const r = spawnSync('command', ['-v', cmd], { stdio: ['ignore', 'pipe', 'ignore'] });
-        if (r && r.status === 0)
-            return true;
+        const result = spawnSync(cmd, ['list-targets', '--json'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: 5000
+        });
+        if (result.status !== 0) {
+            return {
+                ok: false,
+                raw: `${result.stdout || ''}${result.stderr || ''}`.trim() || null,
+                parsedVersion: null
+            };
+        }
+        const version = getIdbPackageVersion();
+        const raw = version ? `fb-idb ${version}` : `${result.stdout || ''}${result.stderr || ''}`.trim() || null;
+        return {
+            ok: true,
+            raw,
+            parsedVersion: version
+        };
     }
-    catch { }
-    try {
-        execSync(`${cmd} list-targets --json`, { stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 });
-        return true;
+    catch {
+        return { ok: false, raw: null, parsedVersion: null };
     }
-    catch { }
-    return false;
+}
+export function isIDBInstalled() {
+    return probeIdb().ok;
 }

package/dist/utils/ios/utils.js

@@ -71,19 +71,15 @@ export function getIdbCmd() {
 }
 export async function isIDBInstalled() {
     const cmd = getIdbCmd();
+    if (!cmd)
+        return false;
     try {
-        execSync(`command -v ${cmd}`, { stdio: ['ignore', 'pipe', 'ignore'] });
+        execSync(`${cmd} list-targets --json`, { stdio: ['ignore', 'pipe', 'pipe'], timeout: 5000 });
         return true;
     }
     catch (e) {
-        try {
-            execSync(`${cmd} list-targets --json`, { stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 });
-            return true;
-        }
-        catch (e2) {
-            console.debug(`[isIDBInstalled] idb presence check failed for '${cmd}': ${e instanceof Error ? e.message : String(e2)}`);
-            return false;
-        }
+        console.debug(`[isIDBInstalled] idb probe failed for '${cmd}': ${e instanceof Error ? e.message : String(e)}`);
+        return false;
     }
 }
 // Validate bundle ID to prevent any potential injection or invalid characters

package/docs/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.31.0]
+- Added tool discovery/automation
+
+## [0.30.2]
+- improved slider interaction
+
 ## [0.30.1]
 - Synced the server-reported version in `src/server-core.ts` with `package.json` so contract checks pass.
 - Completed the RFC 013 wait/synchronization implementation, including scoped waits and freshness metadata.

package/docs/ROADMAP.md

@@ -1,124 +1,26 @@
 # Mobile Debug MCP Roadmap
 
-## Planning Principles
-
-Ordered by:
-
-
-1. Impact on agent reliability  
-2. Reduction in retries / brittleness  
-3. Breadth of app coverage improved  
-4. Implementation complexity vs payoff
-
-## Capability Status Definitions
-
-- **Completed**  
-  Capability implemented and considered part of the baseline platform.
-
-- **Spec Ready**  
-  Capability design or RFC is mature and implementation-ready, but not yet delivered.
-
-- **Planned**  
-  Capability is prioritized on the roadmap, but detailed specification and/or implementation work remains ahead.
-
-## Program-Level Success Metrics
-Track roadmap impact across releases using:
-
-- Retry reduction rate (% fewer action retries per task)
-- Element match success rate (% successful element targeting)
-- Verification success rate (% expect_* checks passing first attempt)
-- Wait success rate for asynchronous UI flows
-- Custom control interaction success rate
-- Gesture success rate
-- Mean time to root cause during debugging
-- Overall agent task completion rate
-- Reduced sequencing errors in multi-step interaction flows
-
-Primary KPI:
-Higher task success with fewer retries.
-
----
-
-# Roadmap Status Overview
-
-## Completed Capabilities
-
-- Stronger State Verification — Complete (Foundational verification layer shipped)
-- Richer Element Identity — Complete (Identity and selector confidence foundations shipped)
-- Better Compose / Custom Control Semantics — Complete (Semantic role enrichment and custom-adjustable inference shipped)
-- Verification Stabilization and Temporal Convergence — Complete (Temporal verification and convergence logic shipped)
-- Action Trace and Execution Observability — Complete (Structured execution trace model shipped)
-- Wait and Synchronization Reliability — Complete (RFC 013 folded into the main spec and shipped behavior verified on emulator)
-
-## Current Focus
+## Done
 
+- Stronger State Verification
+- Richer Element Identity
+- Better Compose / Custom Control Semantics
+- Verification Stabilization and Temporal Convergence
+- Action Trace and Execution Observability
+- Wait and Synchronization Reliability
 - Actionability Resolution
-- Adjustable Control Precision Hardening
+- Environment Auto-Configuration and Toolchain Discovery
+- Adjustable Control Support
 
-## Upcoming Work
+## Todo
 
 - Adjustable Control Precision Hardening
-- Environment Auto-Configuration and Toolchain Discovery
-- Adjustable Control Support
 - Signal-Oriented Diagnostic Filtering
 - Long Press Gesture
-
-## Rationale
-Reduce onboarding friction and improve developer experience by minimizing manual setup dependencies.
-
-**Status:** Planned
-
-Addresses friction around:
-- manual idb installation
-- manual adb path configuration
-- manual xcrun path configuration
-- environment drift across machines
-- setup failures blocking first use
-
-- Automatic discovery of adb
-- Automatic discovery of xcrun
-- idb detection and guided bootstrap support
-- Startup toolchain validation
-- Environment health diagnostics / doctor-style checks
-- Minimal-manual-configuration defaults
-- Runtime device/emulator health signals (crash detection, process lifecycle awareness)
-- App stability monitoring during active sessions
-
-## Expected Impact
-High.
-
-## Exit Criteria
-- adb and xcrun auto-discovery implemented
-- Missing dependencies surfaced with guided remediation
-- Startup environment validation available
-- Manual path configuration eliminated or minimized for standard setups
-- First-run setup validated on representative developer environments
-
-## Success Metrics
-- Reduced setup friction during onboarding
-- Lower environment configuration failures
-- Faster time-to-first-successful-session
-- Reduced support/debugging caused by local setup issues
-- Reduced unknown-failure sessions caused by app or emulator instability
-
-## Dependencies
-Depends on:
-- Stronger State Verification
-- Richer Element Identity
-
-Strengthens:
-- Actionability Resolution
-- Broader user adoption readiness
-
----
-
-## Later Horizon
-
+- Runtime Debugger Introspection
 - Pinch to Zoom
 - Advanced Trace Correlation and Analysis
 
----
-
 # Stronger State Verification
 
 ## Rationale
@@ -303,7 +205,7 @@ Strengthens:
 ## Rationale
 Reduces failures caused by interacting with discoverable but non-actionable UI nodes.
 
-**Status:** Planned
+**Status:** Completed
 
 Addresses cases where:
 - visible text is not the true click target
@@ -349,7 +251,7 @@ Blocks or strengthens:
 ## Rationale
 High leverage improvement for sliders and parameterized controls.
 
-**Status:** Planned
+**Status:** Completed
 
 Addresses friction around:
 - coordinate-calibrated slider interaction
@@ -577,6 +479,81 @@ Depends on:
 
 ---
 
+# Runtime Debugger Introspection
+
+## Rationale
+Enables agents to move from symptom observation to runtime causal analysis by inspecting paused application state during debugging sessions.
+
+**Status:** Planned
+
+Addresses limitations where agents:
+- observe UI failures but cannot determine runtime cause
+- cannot inspect ViewModel or controller state
+- lack access to local variables and stack context
+- cannot reason about async execution state
+
+## Scope
+Debugger-assisted runtime inspection primitives:
+
+```javascript
+debugger.pause_state()
+debugger.stack_trace()
+debugger.locals()
+debugger.inspect_object(object_id)
+debugger.evaluate(expression)
+debugger.threads()
+```
+
+Includes:
+- stack frame inspection
+- local variable inspection
+- object graph traversal
+- thread inspection
+- expression evaluation
+- platform abstraction over JDWP / LLDB
+- bounded object expansion and summarization
+- coroutine/task inspection support
+
+Future exploration:
+- controlled stepping support
+- debugger-assisted recovery workflows
+
+## Expected Impact
+Very high.
+
+Transforms debugging from:
+- surface-level symptom detection
+
+toward:
+- root-cause-oriented runtime reasoning
+
+## Exit Criteria
+- Paused runtime state accessible through MCP
+- Local variable inspection implemented
+- Stack trace inspection implemented
+- Object inspection primitives implemented
+- Runtime inspection validated on representative Android flows
+- Object expansion safeguards implemented
+- Expression evaluation available with safety limits
+
+## Success Metrics
+- Lower mean time-to-root-cause
+- Higher causal diagnosis accuracy
+- Reduced debugging iteration loops
+- Faster identification of state-management failures
+- Improved async/concurrency failure diagnosis
+
+## Dependencies
+Depends on:
+- Action Trace and Execution Observability
+- Stronger State Verification
+- Wait and Synchronization Reliability
+- Signal-Oriented Diagnostic Filtering
+
+Strengthens:
+- Advanced Trace Correlation and Analysis
+- Future autonomous recovery systems
+
 # Pinch to Zoom
 
 ## Rationale
@@ -658,104 +635,3 @@ Depends on:
 - Stronger State Verification
 - Richer Element Identity
 - Wait and Synchronization Reliability
-
----
-
-# Roadmap Sequence
-
-## Dependency Summary
-
-Foundation
-- Stronger State Verification
-- Richer Element Identity
-
-Synchronization & Actionability
-- Environment Auto-Configuration and Toolchain Discovery
-- Wait and Synchronization Reliability
-- Actionability Resolution
-
-Control Precision & Observability
-- Adjustable Control Support
-- Adjustable Control Precision Hardening
-- Better Compose / Custom Control Semantics
-- Signal-Oriented Diagnostic Filtering
-- Verification Stabilization and Temporal Convergence
-
-Interaction Expansion
-- Long Press Gesture
-- Pinch to Zoom
-
-Deep Observability
-- Advanced Trace Correlation and Analysis
-
-## Wave 1 (Current Focus)
-- Stronger State Verification
-- Richer Element Identity
-- Wait and Synchronization Reliability
-- Actionability Resolution
-- Environment Auto-Configuration and Toolchain Discovery
-
-Focus:
-Make core loop reliable and reduce onboarding friction.
-
----
-
-## Wave 2 (Control Precision + Diagnostics)
-- Adjustable Control Support
-- Adjustable Control Precision Hardening
-- Better Compose / Custom Control Semantics
-- Signal-Oriented Diagnostic Filtering
-
-Focus:
-Improve control precision, verification convergence, custom control reliability, and signal observability.
-
----
-
-## Wave 3 (Interaction Expansion)
-- Long Press Gesture
-
-Focus:
-Expand interaction capability after core control reliability is improved.
-
----
-
-## Wave 4 (Advanced Gestures + Deep Observability)
-- Pinch to Zoom
-- Advanced Trace Correlation and Analysis
-
-Focus:
-Advanced gestures + deep observability.
-
----
-
-# Roadmap Ordering
-
-Roadmap Ordering:
-1. Stronger State Verification
-2. Richer Element Identity
-3. Wait and Synchronization Reliability
-4. Actionability Resolution
-5. Adjustable Control Support
-6. Adjustable Control Precision Hardening
-7. Environment Auto-Configuration and Toolchain Discovery
-8. Better Compose / Custom Control Semantics
-9. Signal-Oriented Diagnostic Filtering
-10. Long Press Gesture
-11. Pinch to Zoom
-12. Advanced Trace Correlation and Analysis
-
-Rationale:
-- Early roadmap items harden state, targeting, synchronization, environment readiness, and action execution.
-- Mid roadmap items improve control precision and signal observability.
-- Later interaction-focused items expand interaction coverage.
-- Final observability work deepens debugging observability.
-
----
-
-## Future Considerations
-Still out of scope:
-
-- Full autonomous recovery planning (deferred until after verification stabilization)
-- Autonomous retry strategy
-- MCP-level agent orchestration
-- Autonomous recovery hinting (future consideration only)

package/docs/specs/baseline-spec-v0.md

@@ -81,7 +81,7 @@ That flow is applied to `start_app`, `restart_app`, `tap`, `swipe`, `scroll_to_e
 | --- | --- | --- | --- | --- |
 | `classify_action_outcome` | Deterministic rule-based classifier over supplied signals. | `{ uiChanged: boolean, expectedElementVisible?: boolean, networkRequests?: { url?: string, status: 'success'\|'failure'\|'retryable' }[], hasLogErrors?: boolean }` | `{ outcome: 'success'\|'no_op'\|'backend_failure'\|'ui_failure'\|'unknown', reasoning: string, nextAction?: 'call_get_network_activity' }` | Pure computation. |
 | `get_network_activity` | Return normalized request events since last action window. | `{}` | `{ requests: NetworkRequestSummary[], count: number }` | Reads logs, advances internal `lastConsumedTimestamp`. |
-| `get_system_status` | Aggregate Android/iOS/Gradle readiness. | `{}` | `{ success, status: 'ready'\|'degraded'\|'blocked', adbAvailable, adbVersion, devices, deviceStates, logsAvailable, envValid, issues, appInstalled, iosAvailable, iosDevices, gradleJavaHome, gradleValid, gradleFilesChecked, gradleSuggestedFixes, summary }` | Reads toolchain/device state. |
+| `get_system_status` | Aggregate Android/iOS/Gradle readiness. | `{}` | Additive response: legacy flat fields remain available, with nested `host`, `android`, and `ios` objects added alongside them. | Reads toolchain/device state. |
 
 ## 3. Action Tools (Mutation Tools)