mobile-debug-mcp 0.26.3 → 0.26.4

package/docs/ROADMAP.md

@@ -52,10 +52,62 @@ Higher task success with fewer retries.
 
 ## Upcoming Work
 
+- Environment Auto-Configuration and Toolchain Discovery
 - Adjustable Control Support
 - Better Compose / Custom Control Semantics
 - 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.
+
+**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
+
+## 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
+
+## 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
+
+## Dependencies
+Depends on:
+- Stronger State Verification
+- Richer Element Identity
+
+Strengthens:
+- Actionability Resolution
+- Broader user adoption readiness
+
+---
 
 ## Later Horizon
 
@@ -516,6 +568,7 @@ Foundation
 - Richer Element Identity
 
 Synchronization & Actionability
+- Environment Auto-Configuration and Toolchain Discovery
 - Wait and Synchronization Reliability
 - Actionability Resolution
 
@@ -536,9 +589,10 @@ Deep Observability
 - Richer Element Identity
 - Wait and Synchronization Reliability
 - Actionability Resolution
+- Environment Auto-Configuration and Toolchain Discovery
 
 Focus:
-Make core loop more reliable.
+Make core loop reliable and reduce onboarding friction.
 
 ---
 
@@ -575,16 +629,17 @@ Roadmap Ordering:
 1. Stronger State Verification
 2. Richer Element Identity
 3. Wait and Synchronization Reliability
-4. Actionability Resolution
-5. Adjustable Control Support
-6. Better Compose / Custom Control Semantics
-7. Signal-Oriented Diagnostic Filtering
-8. Long Press Gesture
-9. Pinch to Zoom
-10. Action Trace Correlation
+4. Environment Auto-Configuration and Toolchain Discovery
+5. Actionability Resolution
+6. Adjustable Control Support
+7. Better Compose / Custom Control Semantics
+8. Signal-Oriented Diagnostic Filtering
+9. Long Press Gesture
+10. Pinch to Zoom
+11. Action Trace Correlation
 
 Rationale:
-- Early roadmap items harden state, targeting, synchronization, action execution.
+- 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.

package/docs/rfcs/008-adjustable-control-support-and-semantic-value-manipulation.md

@@ -0,0 +1,273 @@
+
+
+
+# RFC 008 — Adjustable Control Support and Semantic Value Manipulation
+
+## 1. Summary
+
+This RFC defines semantic interaction support for adjustable controls whose primary interaction changes a value rather than triggering a discrete action.
+
+Examples include:
+- sliders
+- steppers
+- seek bars
+- drag-based range controls
+- quantized parameter selectors
+
+Goal:
+Enable reliable value-setting interactions with verification, minimizing coordinate guessing and brittle gesture calibration.
+
+Builds on:
+- RFC 005 — correctness model
+- RFC 006 — runtime execution binding
+- RFC 007 — target resolution
+
+---
+
+## 2. Problem Statement
+
+Current control adjustment often degrades into coordinate heuristics.
+
+Observed failure modes:
+- slider handles not semantically surfaced
+- coordinate calibration guesswork
+- snapping or quantized values behaving unexpectedly
+- weak confirmation of resulting value
+- retries caused by partial adjustment success
+
+This is not primarily a gesture problem.
+
+It is:
+- a control semantics problem
+- a value verification problem
+- an adjustment convergence problem
+
+---
+
+## 3. Design Goals
+
+Support MUST:
+- Prefer semantic adjustment over coordinate manipulation
+- Support deterministic value targeting
+- Verify resulting value after adjustment
+- Handle quantized or snapping controls
+- Support bounded tolerance when exact values are impossible
+- Use coordinate fallback only as degraded mode
+
+---
+
+## 4. Adjustable Control Model
+
+Treat adjustable controls as a combination of:
+- target control
+- value model
+- adjustment mechanism
+- verification loop
+
+Control should expose where possible:
+- current value
+- minimum and maximum range
+- step granularity (if known)
+- adjustable role metadata
+
+---
+
+## 5. Primary Primitive
+
+Illustrative adjustment primitive (conceptual, not yet a committed tool surface):
+
+set_slider_value(target, value, tolerance?)
+
+This denotes an adjustment capability, not a required standalone tool API. Implementations may realize it as:
+- an extension of existing gesture tools
+- an internal adjustment helper
+- a future dedicated control-adjustment tool surface
+
+This RFC does not mandate which mechanism is used.
+
+Semantics:
+- resolve control target
+- perform adjustment
+- read back resulting value
+- converge or fail explicitly
+
+This is not:
+blind drag gestures
+
+It is:
+set and verify
+
+## 5.1 Tool Surface Boundary
+
+This RFC specifies adjustment semantics, not a committed tool API.
+
+It does not assume a new public tool is introduced in this RFC.
+Implementation may extend existing gesture/runtime surfaces before introducing any dedicated adjustment command.
+
+---
+
+## 6. Adjustment Modes
+
+### Semantic mode (preferred)
+Use control semantics to set value directly or intelligently drive adjustment.
+
+---
+
+### Gesture-assisted mode
+Use controlled drag informed by:
+- bounds
+- target percentage
+- snapping model
+
+---
+
+### Coordinate fallback (last resort)
+Allowed only when semantic control support is absent.
+
+Must be explicit degraded mode.
+
+---
+
+## 7. Verification Loop
+
+Adjustment is incomplete until verified.
+
+Loop:
+- adjust
+- read back
+- compare to target or tolerance
+- converge or fail after bounded retries
+
+Possible outcomes:
+- Verified
+- Tolerance satisfied
+- Failed to converge
+
+Aligns with RFC 005.
+Verification may initially be realized through explicit expect_state mappings for control value assertions. Dedicated value verifiers are a possible future extension, not a prerequisite of this RFC.
+
+---
+
+## 8. Quantized / Snapping Controls
+
+Support:
+- discrete step controls
+- snapping values
+- non-linear scales (where detectable)
+
+Tolerance model required.
+
+Example:
+Target 30
+Actual 29.8
+Within tolerance acceptable
+Discrete or non-numeric controls may satisfy convergence through semantic state equivalence rather than numeric tolerance alone.
+
+---
+
+## 9. Control Resolution Dependency
+
+Uses RFC 007 target resolution for:
+- locating actual adjustable control
+- avoiding fake slider containers
+- resolving executable adjustable target
+
+RFC 007 resolves what to adjust.
+RFC 008 defines how to adjust it.
+
+---
+
+## 10. Compose / Custom Control Support
+
+Support derived adjustable semantics for:
+- Compose sliders
+- custom parameter widgets
+- composite adjustable controls
+
+Strengthens Better Compose / Custom Control Semantics.
+
+---
+
+## 11. Output / Result Model (Illustrative)
+
+Illustrative result shape:
+
+{
+  "target_state": 30,
+  "actual_state": 30,
+  "converged": true,
+  "adjustment_mode": "semantic"
+}
+
+State may be numeric, discrete, or semantic depending on control type. This model is illustrative and current implementations may expose only a subset through existing verification surfaces.
+
+---
+
+## 12. Success Metrics
+
+Track:
+- reduction in coordinate fallback usage
+- reduced retries adjusting controls
+- improved first-pass value convergence
+- improved custom control adjustment success
+
+---
+
+## 13. Dependencies
+
+Depends on:
+- Stronger State Verification
+- Actionability Resolution (RFC 007)
+
+Strengthens:
+- Better Compose / Custom Control Semantics
+- Pinch to Zoom (future)
+
+---
+
+## 14. Relationship to Prior RFCs
+
+RFC 005
+Defines successful adjustment verification.
+
+RFC 006
+Defines runtime execution interpretation.
+
+RFC 007
+Defines which adjustable target gets selected.
+
+RFC 008
+Defines how value-changing controls are manipulated reliably.
+
+Together:
+- RFC 005 — correctness
+- RFC 006 — runtime binding
+- RFC 007 — target resolution
+- RFC 008 — value manipulation
+
+---
+
+## 15. Summary
+
+This RFC moves adjustable controls from:
+- gesture guesswork
+
+to:
+- semantic value manipulation with verification
+
+It reduces one of the largest remaining sources of interaction brittleness.
+
+---
+
+## 16. Non-Goals / Scope Boundary
+
+This RFC defines adjustment semantics and convergence behavior.
+
+It does not commit in this RFC to:
+- a specific runtime tool API
+- full adjustable control support across all control types
+- generalized gesture framework support
+- arbitrary drag or canvas manipulation
+- pinch-to-zoom or broader gesture semantics
+
+This RFC specifies the behavioral model adjustable-control support should satisfy as implementations mature.

package/docs/specs/mcp-tooling-spec-v1.md

@@ -52,7 +52,7 @@ For backend/API activity, `wait_for_screen_change` is not the right verification
 Action tools mutate application state.
 
 Includes:
-`start_app`, `restart_app`, `tap`, `tap_element`, `swipe`, `scroll_to_element`, `type_text`, `press_back`
+`start_app`, `restart_app`, `tap`, `tap_element`, `swipe`, `scroll_to_element`, `type_text`, `press_back`, `adjust_control`
 
 ### 4.2 Required Semantics
 

package/docs/tools/interact.md

@@ -172,6 +172,27 @@ Guidance:
 
 ---
 
+## adjust_control
+
+Purpose:
+
+- adjust a numeric control value with bounded verification
+
+Notes:
+
+- initial support is for slider-like controls that expose `value_range` or readable numeric value state
+- `expect_state` is the verification surface used to read back the resulting value
+- direct target placement is preferred; drag fallback is treated as degraded mode
+- the tool returns `target_state`, `actual_state`, `within_tolerance`, `converged`, `attempts`, and `adjustment_mode`
+
+Input example:
+
+```json
+{ "selector": { "text": "Duration" }, "property": "value", "targetValue": 30, "tolerance": 0.5, "platform": "android", "deviceId": "emulator-5554" }
+```
+
+---
+
 ## find_element
 
 Locate a UI element on the current screen using semantic matching and return an actionable element descriptor.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.26.3",
+  "version": "0.26.4",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {