mobile-debug-mcp 0.29.0 → 0.30.0

package/AGENTS.md

@@ -75,3 +75,16 @@ For test authoring details, rely on the `test-authoring` skill package rather th
 ## Notes for maintainers
 
 This file is intentionally short. Keep task-specific guidance in `skills/...` so multiple agent systems can reuse the same instructions.
+
+## Testing
+
+- `npm run test:unit` runs every automated unit test under `test/unit/...`
+- `npm run test:device` runs the automated device smoke checks under `test/device/automated/...`
+- `npm run verify` runs the default maintainer verification sequence: lint, build, and unit tests
+- Manual and debug-oriented device scripts live under `test/device/manual/...` and are not part of the default test commands
+
+## Utility Scripts
+
+- `npm run healthcheck` runs the `idb`/tooling healthcheck helper from `src/utils/cli/idb/check-idb.ts`
+- `npm run install-idb` runs the guided `idb` installer helper from `src/utils/cli/idb/install-idb.ts`
+- `npm run preflight-ios` runs the iOS preflight helper from `src/utils/cli/ios/preflight-ios.ts`

package/README.md

@@ -16,7 +16,11 @@ A minimal, secure MCP server for AI-assisted mobile development. Build, install,
 - Xcode command-line tools for iOS support
 - [idb](https://github.com/facebook/idb) for iOS device support
 
-## Configuration example
+## Configuration
+
+<details>
+
+<summary>Android Studio</summary>
 
 ```json
 {
@@ -29,7 +33,45 @@ A minimal, secure MCP server for AI-assisted mobile development. Build, install,
   }
 }
 ```
-You will need to add ADB_PATH for Android and XCRUN_PATH and IDB_PATH for iOS.
+
+</details>
+
+<details>
+
+<summary>Copilot</summary>
+
+```json
+{
+  "mcpServers": {
+    "mobile-debug": {
+      "command": "npx",
+      "args": ["--yes","mobile-debug-mcp","server"],
+      "env": { "ADB_PATH": "/path/to/adb", "XCRUN_PATH": "/usr/bin/xcrun", "IDB_PATH": "/path/to/idb" }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+
+<summary>Codex</summary>
+
+Use STDIO
+
+command: npx
+
+args: 
+* --yes
+* mobile-debug-mcp
+
+environment variables:
+* ADB_PATH: /path/to/adb
+* XCRUN_PATH: /usr/bin/xcrun
+* IDC_PATH: /path/to/idb"
+
+</details>
 
 ## Usage
 
@@ -48,25 +90,6 @@ Feature building:
 - Agents: [AGENTS.md](AGENTS.md) — cold-start guidance for autonomous agents entering the public repo
 - Skills: [skills/README.md](skills/README.md) — portable Markdown skill packages for agents such as Copilot, Codex, Claude, or custom systems
 
-## Testing
-
-- `npm run test:unit` runs every automated unit test under `test/unit/...`
-- `npm run test:device` runs the automated device smoke checks under `test/device/automated/...`
-- `npm run verify` runs the default maintainer verification sequence: lint, build, and unit tests
-- Manual and debug-oriented device scripts live under `test/device/manual/...` and are not part of the default test commands
-
-## Utility Scripts
-
-- `npm run healthcheck` runs the `idb`/tooling healthcheck helper from `src/utils/cli/idb/check-idb.ts`
-- `npm run install-idb` runs the guided `idb` installer helper from `src/utils/cli/idb/install-idb.ts`
-- `npm run preflight-ios` runs the iOS preflight helper from `src/utils/cli/ios/preflight-ios.ts`
-
-## Agent skills
-
-- `skills/mcp-builder/` contains reusable build/install guidance for agents
-- `skills/test-authoring/` contains reusable test-creation guidance aligned to this repo's current test structure
-- Skills are written as plain Markdown packages so they can be consumed by different agent systems rather than one vendor-specific runtime
-
 ## License
 
 MIT

package/dist/interact/index.js

@@ -205,6 +205,9 @@ export class ToolsInteract {
         }
         return null;
     }
+    static _uiChangeSignaturesEqual(left, right) {
+        return left.hierarchy === right.hierarchy && left.text === right.text && left.state === right.state;
+    }
     static _resolvedTargetFromElement(elementId, element, index) {
         return {
             elementId,
@@ -1708,13 +1711,16 @@ export class ToolsInteract {
             }
         };
     }
-    static async waitForUIChangeHandler({ platform, deviceId, timeout_ms = 60000, stability_window_ms = 250, expected_change }) {
+    static async waitForUIChangeHandler({ platform, deviceId, timeout_ms = 60000, stability_window_ms = 300, expected_change }) {
         const start = Date.now();
         const pollIntervalMs = 300;
-        const stabilityWindow = Math.max(0, typeof stability_window_ms === 'number' ? stability_window_ms : 250);
+        const stabilityWindow = Math.max(0, typeof stability_window_ms === 'number' ? stability_window_ms : 300);
         let baseline = null;
         let lastObservedRevision = null;
         let lastLoadingState = null;
+        let candidateSignatures = null;
+        let candidateObservedChange = null;
+        let candidateSinceMs = null;
         while (Date.now() - start < timeout_ms) {
             try {
                 const tree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
@@ -1727,30 +1733,29 @@ export class ToolsInteract {
                 else {
                     const observedChange = ToolsInteract._matchesUiChange(expected_change, baseline, signatures);
                     if (observedChange) {
-                        if (stabilityWindow > 0) {
-                            await new Promise(resolve => setTimeout(resolve, stabilityWindow));
-                            const confirmTree = await ToolsObserve.getUITreeHandler({ platform, deviceId });
-                            const confirmSignatures = ToolsInteract._buildUiChangeSignatures(confirmTree);
-                            const confirmChange = ToolsInteract._matchesUiChange(expected_change, baseline, confirmSignatures);
-                            if (!confirmChange || confirmSignatures.hierarchy !== signatures.hierarchy || confirmSignatures.text !== signatures.text || confirmSignatures.state !== signatures.state) {
-                                lastObservedRevision = typeof confirmTree?.snapshot_revision === 'number' ? confirmTree.snapshot_revision : lastObservedRevision;
-                                lastLoadingState = confirmTree?.loading_state ?? lastLoadingState;
-                                await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
-                                continue;
-                            }
-                            lastObservedRevision = typeof confirmTree?.snapshot_revision === 'number' ? confirmTree.snapshot_revision : lastObservedRevision;
-                            lastLoadingState = confirmTree?.loading_state ?? lastLoadingState;
+                        if (!candidateSignatures || !ToolsInteract._uiChangeSignaturesEqual(candidateSignatures, signatures) || candidateObservedChange !== observedChange) {
+                            candidateSignatures = signatures;
+                            candidateObservedChange = observedChange;
+                            candidateSinceMs = Date.now();
                         }
-                        return {
-                            success: true,
-                            observed_change: observedChange,
-                            snapshot_revision: lastObservedRevision ?? undefined,
-                            timeout: false,
-                            elapsed_ms: Date.now() - start,
-                            expected_change,
-                            loading_state: lastLoadingState ?? null,
-                            reason: 'UI change observed'
-                        };
+                        const stableForMs = candidateSinceMs === null ? 0 : Date.now() - candidateSinceMs;
+                        if (stabilityWindow === 0 || stableForMs >= stabilityWindow) {
+                            return {
+                                success: true,
+                                observed_change: candidateObservedChange ?? observedChange,
+                                snapshot_revision: lastObservedRevision ?? undefined,
+                                timeout: false,
+                                elapsed_ms: Date.now() - start,
+                                expected_change,
+                                loading_state: lastLoadingState ?? null,
+                                reason: 'UI change observed'
+                            };
+                        }
+                    }
+                    else {
+                        candidateSignatures = null;
+                        candidateObservedChange = null;
+                        candidateSinceMs = null;
                     }
                 }
             }

package/dist/server/tool-definitions.js

@@ -391,7 +391,7 @@ Failure Handling:
                 deviceId: { type: 'string', description: 'Optional device id/udid to target' },
                 expected_change: { type: 'string', enum: ['hierarchy_diff', 'text_change', 'state_change'], description: 'Optional type of UI change to wait for' },
                 timeout_ms: { type: 'number', description: 'Timeout in ms to wait for change (default 60000)', default: 60000 },
-                stability_window_ms: { type: 'number', description: 'How long the change must remain stable before success (default 250)', default: 250 }
+                stability_window_ms: { type: 'number', description: 'How long the change must remain stable before success (default 300)', default: 300 }
             }
         }
     },

package/dist/server/tool-handlers.js

@@ -266,7 +266,7 @@ async function handleWaitForUIChange(args) {
     const platform = getStringArg(args, 'platform');
     const deviceId = getStringArg(args, 'deviceId');
     const timeout_ms = getNumberArg(args, 'timeout_ms') ?? 60000;
-    const stability_window_ms = getNumberArg(args, 'stability_window_ms') ?? 250;
+    const stability_window_ms = getNumberArg(args, 'stability_window_ms') ?? 300;
     const expected_change = getStringArg(args, 'expected_change');
     const res = await ToolsInteract.waitForUIChangeHandler({ platform, deviceId, timeout_ms, stability_window_ms, expected_change });
     return wrapResponse(res);

package/dist/server-core.js

@@ -6,7 +6,7 @@ import { handleToolCall } from './server/tool-handlers.js';
 export { wrapResponse, toolDefinitions, handleToolCall };
 export const serverInfo = {
     name: 'mobile-debug-mcp',
-    version: '0.29.0'
+    version: '0.30.0'
 };
 export function createServer() {
     const server = new Server(serverInfo, {

package/docs/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to the **Mobile Debug MCP** project will be documented in this file.
 
+## [0.30.0]
+- Folded RFC 013 synchronization semantics into the main spec and aligned the interact docs with the shipped `wait_for_ui_change` behavior.
+- Updated `wait_for_ui_change` to use a 300ms stabilization default and to reset stabilization on new in-place mutations.
+- Validated the in-place UI mutation flow on the Modul8 emulator app, including a delayed state-change case.
+
 ## [0.29.0]
 - Added empty resource handlers and declared the `resources` capability so Codex MCP discovery can complete the handshake against the published npm package.
 - Moved the startup healthcheck behind an opt-in flag to keep the stdio protocol channel quiet by default.

package/docs/ROADMAP.md

@@ -32,6 +32,7 @@ Track roadmap impact across releases using:
 - 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.
@@ -47,10 +48,10 @@ Higher task success with fewer retries.
 - 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
 
-- Wait and Synchronization Reliability (implementation + tuning)
 - Actionability Resolution
 - Adjustable Control Precision Hardening
 
@@ -74,13 +75,14 @@ Addresses friction around:
 - environment drift across machines
 - setup failures blocking first use
 
-## Scope
 - 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.
@@ -97,6 +99,7 @@ High.
 - 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:
@@ -151,7 +154,7 @@ Very high.
 Blocks or strengthens:
 - Better Compose / Custom Control Semantics
 - Pinch to Zoom
-- Action Trace Correlation
+- Advanced Trace Correlation and Analysis
 
 ---
 
@@ -212,8 +215,11 @@ Addresses failures where agents:
 - wait_for_ui_change (hierarchy diff based waiting)
 - Structured loading state detection
 - Snapshot revision / staleness metadata
-- Focused snapshot views / incremental snapshot diffs
+- Incremental / diff-based snapshot delivery (token-efficient)
+- Focused snapshot scoping (subtree / target-based)
 - Compose-aware wait robustness improvements
+- Explicit interaction sequencing guidance (tap → wait → verify pattern)
+- Exploration of optional action-level synchronization ergonomics (e.g. implicit stabilization or wait flags)
 
 ## Expected Impact
 Very high.
@@ -231,6 +237,8 @@ Very high.
 - Fewer retries caused by premature actions
 - Higher wait success rate for dynamic UI flows
 - Lower fallback usage to network/log checks
+- Reduced need for manual sequencing by agents in stateful flows
+- Reduced average snapshot size (tokens)
 
 ## Dependencies
 Depends on:
@@ -239,7 +247,7 @@ Depends on:
 
 Blocks or strengthens:
 - Better Compose / Custom Control Semantics
-- Action Trace Correlation
+- Advanced Trace Correlation and Analysis
 
 ---
 
@@ -307,6 +315,7 @@ Addresses cases where:
 - Executable-target preference rules
 - Actionability confidence metadata
 - Post-action state verification integration
+- Geometry-aware fallback targeting for weak semantic surfaces (e.g. sliders without accessible nodes)
 
 ## Expected Impact
 High.
@@ -321,6 +330,7 @@ High.
 - Reduced mis-targeted action failures
 - Lower retarget retries
 - Higher first-attempt action success
+- Reduced need for empirical coordinate probing on custom controls
 
 ## Dependencies
 Depends on:
@@ -403,6 +413,7 @@ Addresses friction around:
 - Drag vs tap adjustment strategy heuristics
 - Improved value snapping convergence
 - Control-specific adjustment fallback policies
+- Controlled search strategies for value convergence (e.g. binary / progressive adjustment)
 
 ## Expected Impact
 High.
@@ -465,7 +476,7 @@ Depends on:
 - Wait and Synchronization Reliability
 
 Strengthens:
-- Action Trace Correlation
+- Advanced Trace Correlation and Analysis
 
 ---
 
@@ -675,7 +686,7 @@ Interaction Expansion
 - Pinch to Zoom
 
 Deep Observability
-- Action Trace Correlation
+- Advanced Trace Correlation and Analysis
 
 ## Wave 1 (Current Focus)
 - Stronger State Verification