mobile-debug-mcp 0.28.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

@@ -1,19 +1,29 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
-import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ReadResourceRequestSchema, ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { wrapResponse } from './server/common.js';
 import { toolDefinitions } from './server/tool-definitions.js';
 import { handleToolCall } from './server/tool-handlers.js';
 export { wrapResponse, toolDefinitions, handleToolCall };
 export const serverInfo = {
     name: 'mobile-debug-mcp',
-    version: '0.28.0'
+    version: '0.30.0'
 };
 export function createServer() {
     const server = new Server(serverInfo, {
         capabilities: {
+            resources: {},
             tools: {}
         }
     });
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources: []
+    }));
+    server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
+        resourceTemplates: []
+    }));
+    server.setRequestHandler(ReadResourceRequestSchema, async () => ({
+        contents: []
+    }));
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: toolDefinitions
     }));

package/dist/server.js

@@ -3,9 +3,11 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { createServer } from './server-core.js';
 import { getSystemStatus } from './system/index.js';
 const server = createServer();
-getSystemStatus().then((res) => {
-    console.debug('[startup] system status summary:', { adb: res.adbAvailable, ios: res.iosAvailable, devices: res.devices, iosDevices: res.iosDevices });
-}).catch((e) => console.warn('[startup] healthcheck failed:', e instanceof Error ? e.message : String(e)));
+if (process.env.MOBILE_DEBUG_MCP_STARTUP_HEALTHCHECK === '1') {
+    getSystemStatus().then((res) => {
+        console.info('[startup] system status summary:', { adb: res.adbAvailable, ios: res.iosAvailable, devices: res.devices, iosDevices: res.iosDevices });
+    }).catch((e) => console.warn('[startup] healthcheck failed:', e instanceof Error ? e.message : String(e)));
+}
 const transport = new StdioServerTransport();
 async function main() {
     await server.connect(transport);

package/docs/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 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.
+
 ## [0.28.0]
 - Added structured execution trace model for all actions within the MCP runtime. It provides visibility into resolution, execution, verification, stabilization, and recovery stages.
 

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.
@@ -45,25 +46,22 @@ Higher task success with fewer retries.
 - 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
 
-- Wait and Synchronization Reliability
 - Actionability Resolution
-- Verification Stabilization and Temporal Convergence
+- Adjustable Control Precision Hardening
 
 ## Upcoming Work
 
 - Adjustable Control Precision Hardening
 - Environment Auto-Configuration and Toolchain Discovery
 - Adjustable Control Support
-- Verification Stabilization and Temporal Convergence
 - Signal-Oriented Diagnostic Filtering
 - Long Press Gesture
-# Stronger State Verification
-# Richer Element Identity
-# Wait and Synchronization Reliability
-# Environment Auto-Configuration and Toolchain Discovery
 
 ## Rationale
 Reduce onboarding friction and improve developer experience by minimizing manual setup dependencies.
@@ -77,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.
@@ -100,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:
@@ -115,7 +115,7 @@ Strengthens:
 ## Later Horizon
 
 - Pinch to Zoom
-- Action Trace Correlation
+- Advanced Trace Correlation and Analysis
 
 ---
 
@@ -154,7 +154,7 @@ Very high.
 Blocks or strengthens:
 - Better Compose / Custom Control Semantics
 - Pinch to Zoom
-- Action Trace Correlation
+- Advanced Trace Correlation and Analysis
 
 ---
 
@@ -215,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.
@@ -234,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:
@@ -242,7 +247,7 @@ Depends on:
 
 Blocks or strengthens:
 - Better Compose / Custom Control Semantics
-- Action Trace Correlation
+- Advanced Trace Correlation and Analysis
 
 ---
 
@@ -251,7 +256,7 @@ Blocks or strengthens:
 ## Rationale
 Real-world feedback exposed false-negative readiness failures caused by transient UI timing, even when target state had actually converged.
 
-**Status:** Planned
+**Status:** Completed
 
 Addresses friction where agents:
 - fail readiness checks on transient timing races
@@ -310,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.
@@ -324,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:
@@ -406,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.
@@ -468,7 +476,7 @@ Depends on:
 - Wait and Synchronization Reliability
 
 Strengthens:
-- Action Trace Correlation
+- Advanced Trace Correlation and Analysis
 
 ---
 
@@ -615,12 +623,14 @@ Depends on:
 
 ---
 
-# Action Trace Correlation
+# Advanced Trace Correlation
 
 ## Rationale
 Very valuable for debugging,
 but less critical than improving control success first.
 
+Builds on the foundational Action Trace and Execution Observability capability by linking traces across UI, network, and logs.
+
 **Status:** Planned
 
 Improves diagnosis more than task completion.
@@ -676,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
@@ -695,7 +705,6 @@ Make core loop reliable and reduce onboarding friction.
 - Adjustable Control Precision Hardening
 - Better Compose / Custom Control Semantics
 - Signal-Oriented Diagnostic Filtering
-- Verification Stabilization and Temporal Convergence
 
 Focus:
 Improve control precision, verification convergence, custom control reliability, and signal observability.
@@ -712,7 +721,7 @@ Expand interaction capability after core control reliability is improved.
 
 ## Wave 4 (Advanced Gestures + Deep Observability)
 - Pinch to Zoom
-- Action Trace Correlation
+- Advanced Trace Correlation and Analysis
 
 Focus:
 Advanced gestures + deep observability.
@@ -725,16 +734,15 @@ Roadmap Ordering:
 1. Stronger State Verification
 2. Richer Element Identity
 3. Wait and Synchronization Reliability
-4. Verification Stabilization and Temporal Convergence
-5. Environment Auto-Configuration and Toolchain Discovery
-6. Actionability Resolution
-7. Adjustable Control Support
-8. Adjustable Control Precision Hardening
-9. Better Compose / Custom Control Semantics
-10. Signal-Oriented Diagnostic Filtering
-11. Long Press Gesture
-12. Pinch to Zoom
-13. Action Trace Correlation
+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.