mobile-debug-mcp 0.34.0 → 0.36.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/skills/mcp-builder/SKILL.md +44 -64
- package/.agents/skills/mcp-builder/references/build-flags.md +44 -43
- package/.agents/skills/mcp-builder/references/diagnostics-schema.md +4 -1
- package/.agents/skills/mcp-builder/references/toolchain-details.md +49 -62
- package/.agents/skills/spec-review/references/spec-review-checklist.md +7 -0
- package/.agents/skills/test-authoring/SKILL.md +7 -6
- package/.agents/skills/test-authoring/references/repo-test-layout.md +3 -1
- package/.agents/skills/test-authoring/references/test-authoring-workflow.md +16 -7
- package/.agents/skills/test-authoring/references/test-quality-checklist.md +2 -1
- package/.cursor-plugin/marketplace.json +1 -1
- package/.github/copilot-instructions.md +14 -36
- package/.github/workflows/ci.yml +4 -4
- package/AGENTS.md +12 -3
- package/CONTRIBUTING.md +79 -0
- package/README.md +218 -129
- package/agent-plugin/.antigravity-plugin/README.md +48 -0
- package/agent-plugin/.antigravity-plugin/plugin.json +18 -0
- package/agent-plugin/.claude-plugin/plugin.json +2 -2
- package/agent-plugin/.codex-plugin/plugin.json +1 -1
- package/agent-plugin/.cursor-plugin/plugin.json +2 -2
- package/agent-plugin/.mcp.json +1 -1
- package/agent-plugin/README.md +50 -11
- package/agent-plugin/cursor/.cursor-plugin/plugin.json +23 -0
- package/agent-plugin/cursor/LICENSE +201 -0
- package/agent-plugin/cursor/README.md +9 -0
- package/agent-plugin/cursor/skills/mobile-debug-mcp/SKILL.md +253 -0
- package/agent-plugin/mcp.json +1 -1
- package/agent-plugin/mcp_config.json +13 -0
- package/agent-plugin/plugin.json +1 -1
- package/agent-plugin/skills/mobile-debug-mcp/SKILL.md +62 -17
- package/dist/contracts/execution-controls.js +24 -0
- package/dist/contracts/selector.js +8 -0
- package/dist/contracts/target.js +15 -0
- package/dist/contracts/ui.js +1 -0
- package/dist/debugger/android.js +2 -1
- package/dist/debugger/diagnostics.js +54 -0
- package/dist/debugger/guard.js +4 -4
- package/dist/debugger/ios-worker.js +62 -0
- package/dist/debugger/ios.js +57 -0
- package/dist/debugger/protocol.js +33 -0
- package/dist/debugger/sessions.js +133 -74
- package/dist/debugger/worker.js +59 -46
- package/dist/interact/adjustment/adjustment-context.js +41 -0
- package/dist/interact/adjustment/adjustment-gestures.js +55 -0
- package/dist/interact/adjustment/adjustment-plan.js +18 -0
- package/dist/interact/adjustment/adjustment-resolution.js +127 -0
- package/dist/interact/adjustment/adjustment-result.js +19 -0
- package/dist/interact/adjustment/adjustment-semantic.js +64 -0
- package/dist/interact/adjustment/adjustment-verification.js +35 -0
- package/dist/interact/adjustment/adjustment.js +52 -0
- package/dist/interact/adjustment/control-geometry.js +87 -0
- package/dist/interact/adjustment/control-values.js +136 -0
- package/dist/interact/adjustment/slider-labels.js +84 -0
- package/dist/interact/assertions/screen-assertion.js +37 -0
- package/dist/interact/assertions/state-assertion-context.js +35 -0
- package/dist/interact/assertions/state-assertion.js +76 -0
- package/dist/interact/assertions/state-comparison.js +141 -0
- package/dist/interact/assertions/visibility-assertion.js +34 -0
- package/dist/interact/conditional-action.js +12 -7
- package/dist/interact/index.js +77 -3092
- package/dist/interact/input-service.js +1 -0
- package/dist/interact/interaction-trace.js +21 -0
- package/dist/interact/model.js +1 -0
- package/dist/interact/observation.js +1 -0
- package/dist/interact/targeting/candidate-ancestor.js +58 -0
- package/dist/interact/targeting/candidate-result.js +23 -0
- package/dist/interact/targeting/candidate-scoring.js +50 -0
- package/dist/interact/targeting/element-helpers.js +216 -0
- package/dist/interact/targeting/find-element.js +65 -0
- package/dist/interact/targeting/nearby-control.js +56 -0
- package/dist/interact/targeting/resolved-elements.js +21 -0
- package/dist/interact/targeting/tap-target.js +17 -0
- package/dist/interact/targeting/target-scope.js +104 -0
- package/dist/interact/waits/legacy-log-wait.js +38 -0
- package/dist/interact/waits/legacy-wait-observations.js +103 -0
- package/dist/interact/waits/legacy-wait-state.js +34 -0
- package/dist/interact/waits/legacy-wait.js +48 -0
- package/dist/interact/waits/screen-wait.js +49 -0
- package/dist/interact/waits/ui-change-helpers.js +157 -0
- package/dist/interact/waits/ui-change-state.js +18 -0
- package/dist/interact/waits/ui-change-wait.js +77 -0
- package/dist/interact/waits/ui-wait-condition.js +56 -0
- package/dist/interact/waits/ui-wait-state.js +38 -0
- package/dist/interact/waits/ui-wait.js +106 -0
- package/dist/manage/android.js +55 -51
- package/dist/manage/index.js +38 -75
- package/dist/manage/ios/build-types.js +1 -0
- package/dist/manage/ios/build.js +210 -0
- package/dist/manage/ios/project-discovery.js +29 -0
- package/dist/manage/ios/scheme.js +18 -0
- package/dist/manage/ios.js +44 -256
- package/dist/observe/android/context.js +1 -0
- package/dist/observe/android/current-screen.js +55 -0
- package/dist/observe/android/fingerprint.js +13 -0
- package/dist/observe/android/log-stream.js +132 -0
- package/dist/observe/android/logs.js +107 -0
- package/dist/observe/android/screenshot.js +70 -0
- package/dist/observe/android/ui-tree.js +107 -0
- package/dist/observe/android.js +16 -520
- package/dist/observe/evidence.js +114 -75
- package/dist/observe/index.js +16 -263
- package/dist/observe/ios/context.js +16 -0
- package/dist/observe/ios/fingerprint.js +12 -0
- package/dist/observe/ios/log-stream.js +105 -0
- package/dist/observe/ios/logs.js +168 -0
- package/dist/observe/ios/screenshot.js +22 -0
- package/dist/observe/ios/ui-elements.js +241 -0
- package/dist/observe/ios/ui-tree.js +137 -0
- package/dist/observe/ios-trace/artifact.js +63 -0
- package/dist/observe/ios-trace/capabilities.js +86 -0
- package/dist/observe/ios-trace/native.js +93 -0
- package/dist/observe/ios-trace/notification.js +35 -0
- package/dist/observe/ios-trace/process.js +98 -0
- package/dist/observe/ios-trace/sessions.js +244 -0
- package/dist/observe/ios.js +17 -715
- package/dist/observe/logs/model.js +1 -0
- package/dist/{network → observe/network}/index.js +2 -2
- package/dist/observe/readiness-service.js +5 -3
- package/dist/observe/readiness.js +33 -14
- package/dist/observe/screenshot-encoding.js +41 -0
- package/dist/observe/snapshot-collection.js +79 -0
- package/dist/observe/snapshot-logs.js +30 -0
- package/dist/observe/snapshot-metadata.js +43 -31
- package/dist/observe/snapshot-semantic.js +115 -0
- package/dist/observe/system-trace-error.js +7 -0
- package/dist/observe/system-trace-router.js +81 -0
- package/dist/observe/system-trace.js +26 -21
- package/dist/runtime/action-results.js +270 -0
- package/dist/runtime/clock.js +4 -0
- package/dist/server/common.js +1 -256
- package/dist/server/definitions/assert.js +162 -0
- package/dist/server/definitions/diagnostic.js +118 -0
- package/dist/server/definitions/input.js +274 -0
- package/dist/server/definitions/manage.js +194 -0
- package/dist/server/definitions/observe.js +149 -0
- package/dist/server/definitions/target.js +138 -0
- package/dist/server/definitions/wait.js +105 -0
- package/dist/server/handlers/action-execution.js +163 -0
- package/dist/server/handlers/correlation.js +23 -0
- package/dist/server/handlers/debugger-handlers.js +67 -0
- package/dist/server/handlers/debugger-response.js +9 -0
- package/dist/server/handlers/diagnostic.js +77 -0
- package/dist/server/handlers/handler-types.js +1 -0
- package/dist/server/handlers/input.js +154 -0
- package/dist/server/handlers/interact.js +113 -0
- package/dist/server/handlers/journey-assertions.js +35 -0
- package/dist/server/handlers/journey.js +147 -0
- package/dist/server/handlers/manage.js +119 -0
- package/dist/server/handlers/observe.js +95 -0
- package/dist/server/handlers/payload.js +4 -0
- package/dist/server/handlers/tool-handlers.js +170 -0
- package/dist/server/schemas/condition-schema.js +2 -0
- package/dist/server/{debugger-schema.js → schemas/debugger-schema.js} +20 -12
- package/dist/server/{journey-schema.js → schemas/journey-schema.js} +7 -22
- package/dist/server/schemas/system-trace-schema.js +22 -0
- package/dist/server/tool-definitions.js +58 -1135
- package/dist/server-core.js +2 -2
- package/dist/server.js +4 -4
- package/dist/system/android-status.js +101 -0
- package/dist/system/android.js +37 -27
- package/dist/system/index.js +13 -439
- package/dist/system/ios-status.js +132 -0
- package/dist/system/ios.js +11 -8
- package/dist/system/model.js +1 -0
- package/dist/system/probes.js +105 -0
- package/dist/system/status-summary.js +43 -0
- package/dist/system/unsupported-status.js +52 -0
- package/dist/utils/android/commands.js +89 -0
- package/dist/utils/android/gradle.js +139 -0
- package/dist/utils/android/logs.js +103 -0
- package/dist/utils/android/ui-tree.js +233 -0
- package/dist/utils/android/utils.js +6 -564
- package/dist/utils/cli/idb/idb-helper.js +4 -6
- package/dist/utils/cli/idb/install-idb.js +13 -9
- package/dist/utils/cli/ios/preflight-ios.js +42 -38
- package/dist/utils/ios/utils.js +48 -46
- package/dist/utils/java.js +65 -49
- package/dist/utils/resolve-device.js +4 -2
- package/dist/utils/ui/index.js +26 -26
- package/docs/CHANGELOG.md +67 -1
- package/docs/README.md +38 -0
- package/docs/agent-plugin-installation-verification.md +39 -0
- package/docs/benchmarks/README.md +18 -0
- package/docs/benchmarks/interaction-latency/README.md +14 -0
- package/docs/benchmarks/interaction-latency/final.md +4 -1
- package/docs/benchmarks/interaction-latency/ios-validation.md +2 -0
- package/docs/benchmarks/ui-tree-performance/README.md +24 -16
- package/docs/benchmarks/ui-tree-performance/comparison.md +11 -10
- package/docs/code-structure.md +120 -0
- package/docs/specs/001-state-verification/spec.md +16 -14
- package/docs/specs/002-richer-element-identity/spec.md +12 -10
- package/docs/specs/003-wait-and-synchronization-reliability/spec.md +12 -10
- package/docs/specs/004-action-verification-routing/spec.md +3 -3
- package/docs/specs/005-unified-action-execution-and-verification-model/spec.md +2 -0
- package/docs/specs/006-runtime-action-instrumentation-and-binding-layer/spec.md +2 -0
- package/docs/specs/007-actionability-resolution-and-executable-target-selection/spec.md +3 -1
- package/docs/specs/008-adjustable-control-support-and-semantic-value-manipulation/spec.md +3 -4
- package/docs/specs/009-semantic-control-modeling-for-custom-and-composite-controls/spec.md +2 -0
- package/docs/specs/010-verification-stabilization-and-temporal-convergence/spec.md +2 -2
- package/docs/specs/011-recovery-and-replanning-for-failed-or-ambiguous-interaction-flows/spec.md +2 -2
- package/docs/specs/011.1-recovery-contract-types-and-runtime-wiring-spec/spec.md +2 -0
- package/docs/specs/012-action-trace-and-xecution-observability/spec.md +2 -3
- package/docs/specs/013-wait-and-synchronization-reliability/spec.md +19 -19
- package/docs/specs/014-actionability-resolution/spec.md +20 -18
- package/docs/specs/015-adjustable-control-support/spec.md +17 -15
- package/docs/specs/016-environment-tools/spec.md +20 -20
- package/docs/specs/018-interaction-latency-and-batched-journeys/spec.md +2 -0
- package/docs/specs/019-ui-tree-observation-performance/spec.md +3 -1
- package/docs/specs/020-conditional-actions/intent.md +5 -3
- package/docs/specs/020-conditional-actions/plan.md +8 -9
- package/docs/specs/020-conditional-actions/spec.md +4 -2
- package/docs/specs/021-app-readiness-signals/intent.md +4 -2
- package/docs/specs/021-app-readiness-signals/plan.md +7 -6
- package/docs/specs/021-app-readiness-signals/spec.md +3 -1
- package/docs/specs/022-correlated-evidence/intent.md +4 -4
- package/docs/specs/022-correlated-evidence/plan.md +10 -11
- package/docs/specs/022-correlated-evidence/spec.md +3 -1
- package/docs/specs/023-android-system-traces/intent.md +3 -2
- package/docs/specs/023-android-system-traces/plan.md +5 -7
- package/docs/specs/023-android-system-traces/spec.md +3 -1
- package/docs/specs/024-android-heap-dump-capture/intent.md +3 -1
- package/docs/specs/025-android-runtime-debugger/intent.md +4 -3
- package/docs/specs/025-android-runtime-debugger/plan.md +3 -1
- package/docs/specs/025-android-runtime-debugger/spec.md +4 -3
- package/docs/specs/026-code-structure-and-quality-gates/health-plan.md +88 -0
- package/docs/specs/026-code-structure-and-quality-gates/intent.md +47 -0
- package/docs/specs/026-code-structure-and-quality-gates/plan.md +191 -0
- package/docs/specs/026-code-structure-and-quality-gates/spec.md +138 -0
- package/docs/specs/026-code-structure-and-quality-gates/verification-final.json +200 -0
- package/docs/specs/026-code-structure-and-quality-gates/verification-thin-facade.json +154 -0
- package/docs/specs/026-code-structure-and-quality-gates/verification.json +136 -0
- package/docs/specs/027-debugger-failure-diagnostics/intent.md +43 -0
- package/docs/specs/027-debugger-failure-diagnostics/plan.md +86 -0
- package/docs/specs/027-debugger-failure-diagnostics/spec.md +133 -0
- package/docs/specs/028-compact-debugger-responses/intent.md +41 -0
- package/docs/specs/028-compact-debugger-responses/plan.md +112 -0
- package/docs/specs/028-compact-debugger-responses/spec.md +108 -0
- package/docs/specs/029-kotlin-locals-validation/report.md +119 -0
- package/docs/specs/030-android-coroutine-validation/evidence.json +475 -0
- package/docs/specs/030-android-coroutine-validation/intent.md +47 -0
- package/docs/specs/030-android-coroutine-validation/plan.md +147 -0
- package/docs/specs/030-android-coroutine-validation/report.md +240 -0
- package/docs/specs/030-android-coroutine-validation/spec.md +107 -0
- package/docs/specs/031-ios-system-traces/intent.md +38 -0
- package/docs/specs/031-ios-system-traces/investigation.md +92 -0
- package/docs/specs/031-ios-system-traces/late-run-failure-evidence.json +32 -0
- package/docs/specs/031-ios-system-traces/plan.md +138 -0
- package/docs/specs/031-ios-system-traces/pr102-monitor-evidence.json +22 -0
- package/docs/specs/031-ios-system-traces/simulator-evidence.json +47 -0
- package/docs/specs/031-ios-system-traces/spec.md +135 -0
- package/docs/specs/032-ios-runtime-debugger/evidence.json +176 -0
- package/docs/specs/032-ios-runtime-debugger/intent.md +38 -0
- package/docs/specs/032-ios-runtime-debugger/plan.md +95 -0
- package/docs/specs/032-ios-runtime-debugger/report.md +205 -0
- package/docs/specs/032-ios-runtime-debugger/spec.md +153 -0
- package/docs/tools/TOOLS.md +31 -18
- package/docs/tools/{evidence.md → correlated-evidence.md} +9 -1
- package/docs/tools/debugger.md +120 -4
- package/docs/tools/interact.md +42 -20
- package/docs/tools/manage.md +25 -44
- package/docs/tools/observe.md +55 -23
- package/docs/tools/system-traces.md +89 -14
- package/docs/tools/system.md +12 -5
- package/package.json +12 -8
- package/scripts/agent-plugin.mjs +55 -5
- package/scripts/architecture-graph.mjs +69 -0
- package/scripts/check-architecture.mjs +47 -0
- package/scripts/code-quality-baseline.json +1 -0
- package/scripts/code-quality.mjs +161 -0
- package/src/contracts/execution-controls.ts +26 -0
- package/src/contracts/selector.ts +17 -0
- package/src/contracts/target.ts +19 -0
- package/src/contracts/ui.ts +94 -0
- package/src/debugger/android.ts +3 -2
- package/src/debugger/diagnostics.ts +43 -0
- package/src/debugger/guard.ts +10 -5
- package/src/debugger/ios-worker.ts +49 -0
- package/src/debugger/ios.ts +45 -0
- package/{worker → src/debugger/java}/DebuggerWorker.java +9 -3
- package/src/debugger/lldb/breakpoints.py +51 -0
- package/src/debugger/lldb/inspection.py +109 -0
- package/src/debugger/lldb/worker.py +203 -0
- package/src/debugger/protocol.ts +37 -0
- package/src/debugger/sessions.ts +326 -155
- package/src/debugger/worker.ts +57 -41
- package/src/interact/adjustment/adjustment-context.ts +83 -0
- package/src/interact/adjustment/adjustment-gestures.ts +48 -0
- package/src/interact/adjustment/adjustment-plan.ts +23 -0
- package/src/interact/adjustment/adjustment-resolution.ts +104 -0
- package/src/interact/adjustment/adjustment-result.ts +34 -0
- package/src/interact/adjustment/adjustment-semantic.ts +53 -0
- package/src/interact/adjustment/adjustment-verification.ts +60 -0
- package/src/interact/adjustment/adjustment.ts +49 -0
- package/src/interact/adjustment/control-geometry.ts +120 -0
- package/src/interact/adjustment/control-values.ts +141 -0
- package/src/interact/adjustment/slider-labels.ts +84 -0
- package/src/interact/assertions/screen-assertion.ts +39 -0
- package/src/interact/assertions/state-assertion-context.ts +48 -0
- package/src/interact/assertions/state-assertion.ts +64 -0
- package/src/interact/assertions/state-comparison.ts +168 -0
- package/src/interact/assertions/visibility-assertion.ts +41 -0
- package/src/interact/conditional-action.ts +18 -12
- package/src/interact/index.ts +89 -3494
- package/src/interact/input-service.ts +11 -0
- package/src/interact/interaction-trace.ts +36 -0
- package/src/interact/model.ts +109 -0
- package/src/interact/observation.ts +7 -0
- package/src/interact/targeting/candidate-ancestor.ts +49 -0
- package/src/interact/targeting/candidate-result.ts +24 -0
- package/src/interact/targeting/candidate-scoring.ts +42 -0
- package/src/interact/targeting/element-helpers.ts +243 -0
- package/src/interact/targeting/find-element.ts +47 -0
- package/src/interact/targeting/nearby-control.ts +46 -0
- package/src/interact/targeting/resolved-elements.ts +20 -0
- package/src/interact/targeting/tap-target.ts +22 -0
- package/src/interact/targeting/target-scope.ts +121 -0
- package/src/interact/waits/legacy-log-wait.ts +30 -0
- package/src/interact/waits/legacy-wait-observations.ts +55 -0
- package/src/interact/waits/legacy-wait-state.ts +48 -0
- package/src/interact/waits/legacy-wait.ts +34 -0
- package/src/interact/waits/screen-wait.ts +37 -0
- package/src/interact/waits/ui-change-helpers.ts +184 -0
- package/src/interact/waits/ui-change-state.ts +26 -0
- package/src/interact/waits/ui-change-wait.ts +59 -0
- package/src/interact/waits/ui-wait-condition.ts +52 -0
- package/src/interact/waits/ui-wait-state.ts +55 -0
- package/src/interact/waits/ui-wait.ts +84 -0
- package/src/manage/android.ts +56 -50
- package/src/manage/index.ts +63 -93
- package/src/manage/ios/build-types.ts +14 -0
- package/src/manage/ios/build.ts +230 -0
- package/src/manage/ios/project-discovery.ts +26 -0
- package/src/manage/ios/scheme.ts +16 -0
- package/src/manage/ios.ts +67 -298
- package/src/observe/android/context.ts +1 -0
- package/src/observe/android/current-screen.ts +63 -0
- package/src/observe/android/fingerprint.ts +13 -0
- package/src/observe/android/log-stream.ts +127 -0
- package/src/observe/android/logs.ts +110 -0
- package/src/observe/android/screenshot.ts +79 -0
- package/src/observe/android/ui-tree.ts +113 -0
- package/src/observe/android.ts +17 -531
- package/src/observe/evidence.ts +122 -70
- package/src/observe/index.ts +24 -286
- package/src/observe/ios/context.ts +22 -0
- package/src/observe/ios/fingerprint.ts +12 -0
- package/src/observe/ios/log-stream.ts +103 -0
- package/src/observe/ios/logs.ts +179 -0
- package/src/observe/ios/screenshot.ts +26 -0
- package/src/observe/ios/ui-elements.ts +266 -0
- package/src/observe/ios/ui-tree.ts +143 -0
- package/src/observe/ios-trace/artifact.ts +55 -0
- package/src/observe/ios-trace/capabilities.ts +74 -0
- package/src/observe/ios-trace/native.ts +72 -0
- package/src/observe/ios-trace/notification.ts +30 -0
- package/src/observe/ios-trace/process.ts +82 -0
- package/src/observe/ios-trace/sessions.ts +204 -0
- package/src/observe/ios.ts +18 -749
- package/src/observe/logs/model.ts +11 -0
- package/src/{network → observe/network}/index.ts +2 -2
- package/src/observe/readiness-service.ts +6 -4
- package/src/observe/readiness.ts +42 -21
- package/src/observe/screenshot-encoding.ts +32 -0
- package/src/observe/snapshot-collection.ts +69 -0
- package/src/observe/snapshot-logs.ts +26 -0
- package/src/observe/snapshot-metadata.ts +51 -31
- package/src/observe/snapshot-semantic.ts +153 -0
- package/src/observe/system-trace-error.ts +3 -0
- package/src/observe/system-trace-router.ts +61 -0
- package/src/observe/system-trace.ts +28 -19
- package/src/runtime/action-results.ts +376 -0
- package/src/runtime/clock.ts +9 -0
- package/src/server/common.ts +9 -359
- package/src/server/definitions/assert.ts +164 -0
- package/src/server/definitions/diagnostic.ts +120 -0
- package/src/server/definitions/input.ts +276 -0
- package/src/server/definitions/manage.ts +196 -0
- package/src/server/definitions/observe.ts +151 -0
- package/src/server/definitions/target.ts +140 -0
- package/src/server/definitions/wait.ts +107 -0
- package/src/server/handlers/action-execution.ts +164 -0
- package/src/server/handlers/correlation.ts +20 -0
- package/src/server/handlers/debugger-handlers.ts +58 -0
- package/src/server/handlers/debugger-response.ts +7 -0
- package/src/server/handlers/diagnostic.ts +86 -0
- package/src/server/handlers/handler-types.ts +7 -0
- package/src/server/handlers/input.ts +173 -0
- package/src/server/handlers/interact.ts +135 -0
- package/src/server/handlers/journey-assertions.ts +39 -0
- package/src/server/handlers/journey.ts +132 -0
- package/src/server/handlers/manage.ts +141 -0
- package/src/server/handlers/observe.ts +116 -0
- package/src/server/handlers/payload.ts +36 -0
- package/src/server/handlers/tool-handlers.ts +170 -0
- package/src/server/schemas/condition-schema.ts +2 -0
- package/src/server/schemas/debugger-schema.ts +46 -0
- package/src/server/{journey-schema.ts → schemas/journey-schema.ts} +7 -22
- package/src/server/schemas/system-trace-schema.ts +23 -0
- package/src/server/tool-definitions.ts +67 -1143
- package/src/server-core.ts +2 -2
- package/src/server.ts +4 -4
- package/src/system/android-status.ts +124 -0
- package/src/system/android.ts +33 -21
- package/src/system/index.ts +21 -525
- package/src/system/ios-status.ts +147 -0
- package/src/system/ios.ts +14 -10
- package/src/system/model.ts +41 -0
- package/src/system/probes.ts +114 -0
- package/src/system/status-summary.ts +47 -0
- package/src/system/unsupported-status.ts +55 -0
- package/src/types.ts +16 -106
- package/src/utils/android/commands.ts +81 -0
- package/src/utils/android/gradle.ts +132 -0
- package/src/utils/android/logs.ts +103 -0
- package/src/utils/android/ui-tree.ts +239 -0
- package/src/utils/android/utils.ts +16 -556
- package/src/utils/cli/idb/check-idb.ts +4 -4
- package/src/utils/cli/idb/idb-helper.ts +6 -8
- package/src/utils/cli/idb/install-idb.ts +15 -9
- package/src/utils/cli/ios/preflight-ios.ts +39 -31
- package/src/utils/cli/ios/run-ios-ui-tree-tap.ts +4 -4
- package/src/utils/ios/utils.ts +60 -61
- package/src/utils/java.ts +62 -43
- package/src/utils/resolve-device.ts +9 -6
- package/src/utils/ui/index.ts +28 -28
- package/test/device/automated/debugger/coroutine-lifecycle.ts +27 -0
- package/test/device/automated/debugger/coroutine-support.ts +140 -0
- package/test/device/automated/debugger/coroutine.android.test.ts +169 -0
- package/test/device/automated/debugger/kotlin.android.test.ts +127 -0
- package/test/device/automated/debugger/runtime.android.test.ts +19 -3
- package/test/device/automated/debugger/runtime.ios.test.ts +221 -0
- package/test/device/automated/interact/interaction.android.test.ts +56 -0
- package/test/device/automated/observe/ios-system-trace.smoke.ts +119 -0
- package/test/device/automated/observe/system-trace.smoke.ts +1 -1
- package/test/device/manual/interact/modul8_selector_tap.manual.ts +1 -1
- package/test/fixtures/contracts/tool-definitions.json +3696 -0
- package/test/fixtures/coroutine-app/MainActivity.kt +100 -0
- package/test/fixtures/coroutine-app/README.md +48 -0
- package/test/fixtures/coroutine-app/build.ts +35 -0
- package/test/fixtures/debugger-app/MainActivity.java +21 -0
- package/test/fixtures/debugger-app/MainActivity.kt +32 -0
- package/test/fixtures/debugger-app/README.md +52 -0
- package/test/fixtures/debugger-app/build.ts +25 -15
- package/test/fixtures/ios-debugger-app/Main.swift +95 -0
- package/test/fixtures/ios-debugger-app/README.md +27 -0
- package/test/fixtures/ios-debugger-app/build.ts +21 -0
- package/test/fixtures/latency-journey-app/README.md +2 -0
- package/test/fixtures/readiness-app/README.md +2 -0
- package/test/helpers/ios-trace-shutdown.ts +29 -0
- package/test/unit/debugger/coroutine-lifecycle.test.ts +43 -0
- package/test/unit/debugger/diagnostic-sessions.test.ts +67 -0
- package/test/unit/debugger/diagnostics.test.ts +80 -0
- package/test/unit/debugger/guards.test.ts +4 -0
- package/test/unit/debugger/handle-guards.test.ts +88 -0
- package/test/unit/debugger/ios-preparation.test.ts +57 -0
- package/test/unit/debugger/ios.test.ts +104 -0
- package/test/unit/debugger/lldb-worker.py +166 -0
- package/test/unit/debugger/lldb-worker.test.ts +10 -0
- package/test/unit/debugger/preparation.test.ts +32 -0
- package/test/unit/debugger/protocol.test.ts +15 -0
- package/test/unit/debugger/sessions.test.ts +1 -1
- package/test/unit/interact/adjustment_service.test.ts +42 -0
- package/test/unit/interact/adjustment_verification.test.ts +35 -0
- package/test/unit/interact/clock_dependencies.test.ts +63 -0
- package/test/unit/interact/element_helpers.test.ts +19 -0
- package/test/unit/interact/legacy_wait_service.test.ts +17 -0
- package/test/unit/interact/state_comparison.test.ts +20 -0
- package/test/unit/interact/target_scope.test.ts +35 -0
- package/test/unit/network/get_network_activity.test.ts +1 -1
- package/test/unit/observe/ios-trace-native.test.ts +90 -0
- package/test/unit/observe/ios-trace-sessions.test.ts +131 -0
- package/test/unit/observe/readiness.test.ts +1 -1
- package/test/unit/observe/screenshot-encoding.test.ts +30 -0
- package/test/unit/observe/snapshot-logs.test.ts +14 -0
- package/test/unit/observe/system-trace-router.test.ts +49 -0
- package/test/unit/quality/agent-plugin-export.test.ts +38 -0
- package/test/unit/quality/architecture.test.ts +60 -0
- package/test/unit/quality/code-quality.test.ts +58 -0
- package/test/unit/quality/interaction_boundaries.test.ts +24 -0
- package/test/unit/server/conditional_actions.test.ts +1 -1
- package/test/unit/server/conditional_schema.test.ts +2 -2
- package/test/unit/server/debugger-response.test.ts +63 -0
- package/test/unit/server/system-trace.test.ts +12 -3
- package/test/unit/server/tool_definitions_parity.test.ts +8 -0
- package/dist/server/debugger-handlers.js +0 -38
- package/dist/server/system-trace-schema.js +0 -17
- package/dist/server/tool-handlers.js +0 -1000
- package/docs/ROADMAP.md +0 -646
- package/docs/benchmarks/ui-tree-performance/bridge-probe.json +0 -29
- package/docs/benchmarks/ui-tree-performance/initial-baseline.json +0 -59560
- package/docs/specs/baseline-spec-v0.md +0 -312
- package/docs/specs/mcp-tooling-spec-v1.md +0 -446
- package/src/server/debugger-handlers.ts +0 -29
- package/src/server/debugger-schema.ts +0 -37
- package/src/server/system-trace-schema.ts +0 -17
- package/src/server/tool-handlers.ts +0 -1008
- /package/dist/{server/condition-schema.js → contracts/condition.js} +0 -0
- /package/dist/server/{readiness-schema.js → schemas/readiness-schema.js} +0 -0
- /package/src/{server/condition-schema.ts → contracts/condition.ts} +0 -0
- /package/src/server/{readiness-schema.ts → schemas/readiness-schema.ts} +0 -0
package/CONTRIBUTING.md
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
Read the [development process](docs/specs/process.md) before planning, editing,
|
|
4
|
+
or reviewing a change. Documentation and maintenance use its lightweight path;
|
|
5
|
+
new capabilities and material contract changes require intent and specification
|
|
6
|
+
approval. Automated contributors also start with [AGENTS.md](AGENTS.md).
|
|
7
|
+
|
|
8
|
+
## Local development
|
|
9
|
+
|
|
10
|
+
Use Node.js 22 or newer and npm. Platform tooling is needed only for the mobile
|
|
11
|
+
operations you exercise; see [requirements and setup](README.md#requirements).
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
npm ci
|
|
15
|
+
npm run build
|
|
16
|
+
npm start
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
The TypeScript entrypoint is [src/server.ts](src/server.ts); registration and
|
|
20
|
+
dispatch live in [src/server-core.ts](src/server-core.ts) and [src/server/](src/server/).
|
|
21
|
+
The optional Java debugger bridge lives in
|
|
22
|
+
[src/debugger/java/](src/debugger/java/). It is shipped as source and compiled
|
|
23
|
+
on demand by the debugger; the TypeScript build does not compile Java.
|
|
24
|
+
|
|
25
|
+
Platform operations are grouped under `src/manage/`, `src/interact/`,
|
|
26
|
+
`src/observe/`, `src/debugger/`, and `src/system/`, with shared helpers in `src/utils/`.
|
|
27
|
+
|
|
28
|
+
## Validation
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
npm run verify
|
|
32
|
+
npm run test:device
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
`verify` runs lint, the TypeScript build, automated unit tests, and plugin
|
|
36
|
+
consistency checks. Run applicable device checks for native or runtime changes;
|
|
37
|
+
record which devices and behaviours actually ran. See the [process verification
|
|
38
|
+
requirements](docs/specs/process.md#5-verify-and-report) for reporting failures,
|
|
39
|
+
blocked checks, and unrun coverage. Documentation-only work needs diff, relative
|
|
40
|
+
link/path, command, and consistency checks; builds and device tests are unnecessary.
|
|
41
|
+
|
|
42
|
+
Load the [test-authoring skill](.agents/skills/test-authoring/SKILL.md) before
|
|
43
|
+
changing tests, and the [MCP builder skill](.agents/skills/mcp-builder/SKILL.md)
|
|
44
|
+
for installation or native toolchain work. Automated unit tests belong in
|
|
45
|
+
`test/unit/`, automated device tests in `test/device/automated/`, and manual
|
|
46
|
+
helpers in `test/device/manual/`.
|
|
47
|
+
|
|
48
|
+
## Code structure
|
|
49
|
+
|
|
50
|
+
Follow the [code structure and quality checks](docs/code-structure.md) for module
|
|
51
|
+
ownership, enforced limits, and review of legacy exceptions. `npm run lint`
|
|
52
|
+
includes ESLint, structural/type limits and ArchUnitTS dependency checks; CI runs
|
|
53
|
+
the same checks. To diagnose a failure, run `npm run check:quality` or
|
|
54
|
+
`npm run check:architecture` separately. Change a rule or reviewed exception only
|
|
55
|
+
with the corresponding design rationale, rather than suppressing the failure.
|
|
56
|
+
|
|
57
|
+
## Documentation conventions
|
|
58
|
+
|
|
59
|
+
Use the [documentation index](docs/README.md) to place new material. Keep one
|
|
60
|
+
page responsible for each contract and link to it from related guides. Keep
|
|
61
|
+
setup in the root README, current tool contracts in `docs/tools/`, design records
|
|
62
|
+
in `docs/specs/`, and measurements in `docs/benchmarks/`.
|
|
63
|
+
|
|
64
|
+
Write guides around a reader's task: explain when to use the page, show a complete
|
|
65
|
+
example where useful, and link to the likely next step. Keep agent usage
|
|
66
|
+
workflows in the existing plugin skill and detailed contracts in the tool
|
|
67
|
+
reference. Avoid duplicating the full navigation on every page; long references
|
|
68
|
+
should offer task-based links to their own sections.
|
|
69
|
+
|
|
70
|
+
Use one descriptive level-one heading per document and a logical heading
|
|
71
|
+
hierarchy. Use relative links for repository files. Explain prerequisites before
|
|
72
|
+
commands and distinguish examples, proposals, and verified behaviour. Keep
|
|
73
|
+
historical approval and verification evidence dated; avoid chat-relative wording,
|
|
74
|
+
agent handoff instructions, transient checkout status, and temporary log paths.
|
|
75
|
+
Do not turn an earlier design decision into a current support or release claim.
|
|
76
|
+
|
|
77
|
+
When usage changes, update the relevant tool reference, README, and changelog.
|
|
78
|
+
When plugin metadata or its server pin changes, run `npm run sync:agent-plugin`
|
|
79
|
+
and `npm run check:agent-plugin`; see the [plugin guide](agent-plugin/README.md).
|
package/README.md
CHANGED
|
@@ -1,56 +1,200 @@
|
|
|
1
1
|
# Mobile Debug Tools
|
|
2
2
|
[](https://www.npmjs.com/package/mobile-debug-mcp)
|
|
3
3
|
|
|
4
|
-
|
|
4
|
+
Build, install, control, and inspect Android and iOS apps from an MCP-compatible
|
|
5
|
+
client. Mobile Debug Tools connects your client to local device toolchains and
|
|
6
|
+
provides UI actions, screenshots, logs, state assertions, and optional Android
|
|
7
|
+
performance capture and runtime debugging.
|
|
8
|
+
|
|
9
|
+
Android, iOS, and Kotlin Multiplatform projects are supported. Flutter and React
|
|
10
|
+
Native have not been tested. Platform and device limitations are described in the
|
|
11
|
+
[tool reference](docs/tools/TOOLS.md).
|
|
12
|
+
|
|
13
|
+
## What you can use it for
|
|
14
|
+
|
|
15
|
+
Mobile Debug Tools gives a coding agent access to a running app, so development
|
|
16
|
+
can include feedback from the device as well as the source code. For example:
|
|
17
|
+
|
|
18
|
+
- **Build and test a feature.** After adding a settings screen, build and install
|
|
19
|
+
the app, navigate to it, and check that its controls display and behave as
|
|
20
|
+
expected. See [app management](docs/tools/manage.md) and
|
|
21
|
+
[UI interactions and assertions](docs/tools/interact.md).
|
|
22
|
+
- **Check a bug fix or regression.** Reproduce a sequence such as opening a form,
|
|
23
|
+
entering text and submitting it, then verify the resulting screen or control
|
|
24
|
+
state. Repeat the journey after a code change to check the outcome.
|
|
25
|
+
- **Review the UI on a device.** Capture screenshots to inspect layout and visual
|
|
26
|
+
changes, or inspect the UI hierarchy for exposed labels and control state.
|
|
27
|
+
See [observations](docs/tools/observe.md).
|
|
28
|
+
- **Investigate an app failure.** Collect logs, screenshots and a debug snapshot
|
|
29
|
+
around a failing action to understand what happened. [Evidence
|
|
30
|
+
correlation](docs/tools/correlated-evidence.md) links observations to the action.
|
|
31
|
+
- **Investigate mobile performance or runtime behaviour.** Capture a
|
|
32
|
+
[Perfetto or iOS simulator Instruments trace](docs/tools/system-traces.md) during a slow flow, or attach the
|
|
33
|
+
[runtime debugger](docs/tools/debugger.md) to a debuggable app to inspect
|
|
34
|
+
breakpoints, call stacks and locals on Android or an iOS simulator.
|
|
35
|
+
|
|
36
|
+
## How it works
|
|
37
|
+
|
|
38
|
+
Your agent client launches a local MCP server and communicates with it over
|
|
39
|
+
stdio. The server translates tool calls into operations through Android's ADB
|
|
40
|
+
or Apple's Xcode tools and idb, then returns device observations and action
|
|
41
|
+
results to the client. It connects to emulators, simulators and supported
|
|
42
|
+
physical devices through those toolchains.
|
|
43
|
+
|
|
44
|
+
The agent plugin bundles the server configuration and usage skill. The same
|
|
45
|
+
server can also be configured directly in an MCP client or run from a source
|
|
46
|
+
checkout. See [code structure](docs/code-structure.md#module-ownership) for the
|
|
47
|
+
implementation's module boundaries.
|
|
48
|
+
|
|
49
|
+
## Start here
|
|
50
|
+
|
|
51
|
+
Choose how to connect:
|
|
52
|
+
|
|
53
|
+
1. **[Agent plugin](#agent-plugin) — Recommended.** Installs the server configuration
|
|
54
|
+
and usage skill together for supported agent clients.
|
|
55
|
+
2. **[Direct MCP configuration](#mcp-configuration).** Connect the published server
|
|
56
|
+
to another MCP-compatible client.
|
|
57
|
+
3. **[Manual setup](#manual-setup).** Build and run a local source checkout.
|
|
58
|
+
|
|
59
|
+
Check the [requirements](#requirements) for your platform before installing.
|
|
5
60
|
|
|
6
|
-
|
|
7
|
-
> * KMP
|
|
8
|
-
> * Android
|
|
9
|
-
> * iOS
|
|
10
|
-
> * Flutter - not tested
|
|
11
|
-
> * React native - not tested
|
|
61
|
+
## Requirements
|
|
12
62
|
|
|
13
|
-
|
|
14
|
-
|
|
63
|
+
- Node.js >= 22
|
|
64
|
+
- [Android SDK](https://developer.android.com/studio) (adb) for Android support
|
|
65
|
+
- Xcode and its command-line tools on macOS for iOS support
|
|
66
|
+
- [idb](https://github.com/facebook/idb) for iOS UI inspection and interaction
|
|
67
|
+
- JDK 17+ for optional [Android runtime debugging](docs/tools/debugger.md); Xcode’s Swift-enabled LLDB/Python for optional iOS simulator debugging
|
|
15
68
|
|
|
16
|
-
|
|
17
|
-
and return local Perfetto artifacts with explicit correlation metadata.
|
|
69
|
+
## Agent plugin
|
|
18
70
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
71
|
+
The plugin installs the MCP server configuration and the `mobile-debug-mcp` usage
|
|
72
|
+
skill together. These are GitHub/local installation routes; they do not require
|
|
73
|
+
approval from a client's public curated marketplace.
|
|
22
74
|
|
|
23
|
-
|
|
75
|
+
<details>
|
|
24
76
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
77
|
+
<summary>Codex</summary>
|
|
78
|
+
|
|
79
|
+
In a terminal with a current Codex CLI:
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
codex plugin marketplace add clivejefferies/mobile-debug-tools --ref main
|
|
83
|
+
codex plugin add mobile-debug-tools@mobile-debug-tools
|
|
84
|
+
codex plugin list
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Start a new chat/session and confirm the plugin is enabled and its skill and MCP
|
|
88
|
+
tools are available. These commands use the repository's marketplace, named
|
|
89
|
+
`mobile-debug-tools`, not a public directory listing. See the
|
|
90
|
+
[official packaging instructions](https://developers.openai.com/plugins/build/plugins).
|
|
29
91
|
|
|
30
|
-
|
|
92
|
+
</details>
|
|
93
|
+
|
|
94
|
+
<details>
|
|
95
|
+
|
|
96
|
+
<summary>Claude Code</summary>
|
|
97
|
+
|
|
98
|
+
Run these shell commands (not slash commands inside a chat):
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
claude plugin marketplace add clivejefferies/mobile-debug-tools --scope user
|
|
102
|
+
claude plugin install mobile-debug-tools@mobile-debug-tools --scope user
|
|
103
|
+
claude plugin list
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Restart the session after installation. In an interactive Claude Code chat, the
|
|
107
|
+
corresponding commands start with `/plugin` instead of `claude plugin`. See
|
|
108
|
+
[Claude Code's installation guide](https://code.claude.com/docs/en/discover-plugins).
|
|
31
109
|
|
|
32
|
-
|
|
110
|
+
</details>
|
|
33
111
|
|
|
34
|
-
|
|
35
|
-
- you have multiple SDKs installed
|
|
36
|
-
- the tools live outside standard locations
|
|
37
|
-
- you want deterministic setup across machines
|
|
38
|
-
- automatic discovery does not find the expected binary
|
|
112
|
+
<details>
|
|
39
113
|
|
|
40
|
-
|
|
41
|
-
- the tools are already on `PATH`
|
|
42
|
-
- the standard Android and Xcode locations are enough
|
|
114
|
+
<summary>Cursor</summary>
|
|
43
115
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
- `ANDROID_SDK_ROOT` or `ANDROID_HOME`: Android SDK root
|
|
47
|
-
- `XCRUN_PATH`: explicit path to `xcrun`
|
|
48
|
-
- `MCP_IDB_PATH` or `IDB_PATH`: explicit path to `idb`
|
|
49
|
-
- `GRADLE_JAVA_HOME` or `JAVA_HOME`: Java home for Gradle-backed operations
|
|
116
|
+
For local installation, clone this repository and run these commands from its
|
|
117
|
+
root in a macOS/Linux shell:
|
|
50
118
|
|
|
51
|
-
|
|
119
|
+
```bash
|
|
120
|
+
git clone https://github.com/clivejefferies/mobile-debug-tools.git
|
|
121
|
+
cd mobile-debug-tools
|
|
122
|
+
cursor_plugin_dir="$HOME/.cursor/plugins/local/mobile-debug-tools"
|
|
123
|
+
if [ -e "$cursor_plugin_dir" ]; then
|
|
124
|
+
echo "Move the existing plugin directory aside before copying the new package."
|
|
125
|
+
else
|
|
126
|
+
mkdir -p "$(dirname "$cursor_plugin_dir")"
|
|
127
|
+
cp -R agent-plugin/cursor "$cursor_plugin_dir"
|
|
128
|
+
fi
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
On Windows, copy the contents of `agent-plugin/cursor` into a new
|
|
132
|
+
`~/.cursor/plugins/local/mobile-debug-tools` folder, including `.cursor-plugin`.
|
|
133
|
+
Use this generated Cursor-native package, not the portable parent: Cursor does
|
|
134
|
+
not expand `${PLUGIN_DATA}` in portable `mcp.json`. Do not symlink to the checkout.
|
|
135
|
+
|
|
136
|
+
Run **Developer: Reload Window**, open **Customize**, and confirm the skill and
|
|
137
|
+
MCP server are loaded. For Teams/Enterprise distribution, import this repository
|
|
138
|
+
under **Dashboard → Plugins & MCPs → Team Marketplaces**; its
|
|
139
|
+
[Cursor catalog](.cursor-plugin/marketplace.json) selects the native package.
|
|
140
|
+
Members install from Customize. See [Cursor's plugin guide](https://cursor.com/docs/plugins).
|
|
141
|
+
|
|
142
|
+
</details>
|
|
143
|
+
|
|
144
|
+
<details>
|
|
145
|
+
|
|
146
|
+
<summary>Antigravity</summary>
|
|
147
|
+
|
|
148
|
+
Install the [Antigravity CLI](https://antigravity.google/docs/getting-started?tab=cli),
|
|
149
|
+
then clone this GitHub repository and export its plugin:
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
git clone https://github.com/clivejefferies/mobile-debug-tools.git
|
|
153
|
+
cd mobile-debug-tools
|
|
154
|
+
npm run package:antigravity -- "$PWD/antigravity-dist"
|
|
155
|
+
agy plugin validate --strict "$PWD/antigravity-dist"
|
|
156
|
+
agy plugin install "$PWD/antigravity-dist"
|
|
157
|
+
agy plugin list --json
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
No `npm install` is needed for the export script. Choose a new output directory;
|
|
161
|
+
the exporter refuses to overwrite an existing one. Check the installed entry has
|
|
162
|
+
one skill (`mobile-debug-mcp`) and one MCP server (`mobile-debug-mcp`), then start
|
|
163
|
+
a new session and approve the specific MCP calls you intend to use.
|
|
164
|
+
|
|
165
|
+
The Antigravity-only export avoids strict-validation warnings from the other
|
|
166
|
+
clients' compatibility files. It uses `mcp_config.json` and the same pinned npm
|
|
167
|
+
server and shared skill. GitHub/local installation does not require the
|
|
168
|
+
Antigravity Marketplace interest form. See [Google's plugin guide](https://antigravity.google/docs/build-plugins).
|
|
169
|
+
|
|
170
|
+
</details>
|
|
171
|
+
|
|
172
|
+
Each client needs Node.js 22 or newer, `npx` on its PATH, npm registry access on
|
|
173
|
+
first launch, and the platform toolchains for your device. After installation,
|
|
174
|
+
ask the agent to list devices, select an explicit emulator/device, and inspect
|
|
175
|
+
its screen. An installed component list alone does not prove a working device
|
|
176
|
+
connection. Disable any separate manual registration of this MCP server in the
|
|
177
|
+
same client to avoid duplicate tools. If a plugin command is unavailable, update
|
|
178
|
+
the client; the [direct MCP configuration](#mcp-configuration) works independently.
|
|
179
|
+
|
|
180
|
+
## MCP configuration
|
|
181
|
+
|
|
182
|
+
For a standard installation, add this stdio server to your client's MCP settings:
|
|
183
|
+
|
|
184
|
+
```json
|
|
185
|
+
{
|
|
186
|
+
"mcpServers": {
|
|
187
|
+
"mobile-debug": {
|
|
188
|
+
"command": "npx",
|
|
189
|
+
"args": ["--yes", "mobile-debug-mcp"]
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
```
|
|
52
194
|
|
|
53
|
-
|
|
195
|
+
If your client uses separate fields, choose stdio, set the command to `npx`, and
|
|
196
|
+
supply `--yes` and `mobile-debug-mcp` as arguments. The examples below add optional
|
|
197
|
+
path overrides; replace the placeholder paths before using them.
|
|
54
198
|
|
|
55
199
|
<details>
|
|
56
200
|
|
|
@@ -63,7 +207,7 @@ Recommended when you want Android only, or when you want to make the Android too
|
|
|
63
207
|
"mcpServers": {
|
|
64
208
|
"mobile-debug": {
|
|
65
209
|
"command": "npx",
|
|
66
|
-
"args": ["--yes","mobile-debug-mcp"
|
|
210
|
+
"args": ["--yes", "mobile-debug-mcp"],
|
|
67
211
|
"env": {
|
|
68
212
|
"ADB_PATH": "/path/to/adb",
|
|
69
213
|
"ANDROID_SDK_ROOT": "/path/to/android/sdk",
|
|
@@ -89,7 +233,7 @@ Recommended when you want iOS simulator or device support, or when `idb` lives i
|
|
|
89
233
|
"mcpServers": {
|
|
90
234
|
"mobile-debug": {
|
|
91
235
|
"command": "npx",
|
|
92
|
-
"args": ["--yes","mobile-debug-mcp"
|
|
236
|
+
"args": ["--yes", "mobile-debug-mcp"],
|
|
93
237
|
"env": {
|
|
94
238
|
"XCRUN_PATH": "/usr/bin/xcrun",
|
|
95
239
|
"MCP_IDB_PATH": "/path/to/idb",
|
|
@@ -104,107 +248,52 @@ For iOS-only setups, `ADB_PATH` and `ANDROID_SDK_ROOT` are not required unless y
|
|
|
104
248
|
|
|
105
249
|
</details>
|
|
106
250
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
<summary>Codex</summary>
|
|
110
|
-
|
|
111
|
-
Use STDIO
|
|
112
|
-
|
|
113
|
-
command: npx
|
|
114
|
-
|
|
115
|
-
args:
|
|
116
|
-
* --yes
|
|
117
|
-
* mobile-debug-mcp
|
|
118
|
-
|
|
119
|
-
environment variables:
|
|
120
|
-
* ADB_PATH: /path/to/adb
|
|
121
|
-
* XCRUN_PATH: /usr/bin/xcrun
|
|
122
|
-
* IDB_PATH: /path/to/idb
|
|
123
|
-
* MCP_IDB_PATH: /path/to/idb
|
|
124
|
-
* ANDROID_SDK_ROOT: /path/to/android/sdk
|
|
125
|
-
* GRADLE_JAVA_HOME: /path/to/jdk
|
|
126
|
-
* JAVA_HOME: /path/to/jdk
|
|
127
|
-
|
|
128
|
-
If you are unsure whether the environment is configured correctly, run `get_system_status` first. It reports the detected host, Android, and iOS toolchain state in a structured form.
|
|
129
|
-
|
|
130
|
-
</details>
|
|
131
|
-
|
|
132
|
-
## Agent Plugin
|
|
133
|
-
|
|
134
|
-
For clients that support Agent Plugins, the [agent-plugin](agent-plugin/README.md)
|
|
135
|
-
package installs the MCP server configuration together with the existing usage
|
|
136
|
-
skill. Direct npm/MCP configuration above remains supported.
|
|
251
|
+
## Manual setup
|
|
137
252
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
Install the plugin from this repository's marketplace:
|
|
253
|
+
For a local source checkout, follow the [development setup](CONTRIBUTING.md#local-development)
|
|
254
|
+
to install dependencies and build the server. Then configure your MCP client to
|
|
255
|
+
launch that build over stdio:
|
|
143
256
|
|
|
144
|
-
```
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
<summary>Claude Code plugin</summary>
|
|
154
|
-
|
|
155
|
-
Install the plugin from this repository's marketplace:
|
|
156
|
-
|
|
157
|
-
```bash
|
|
158
|
-
claude plugin marketplace add clivejefferies/mobile-debug-tools
|
|
159
|
-
claude plugin install mobile-debug-tools@mobile-debug-tools
|
|
257
|
+
```json
|
|
258
|
+
{
|
|
259
|
+
"mcpServers": {
|
|
260
|
+
"mobile-debug": {
|
|
261
|
+
"command": "node",
|
|
262
|
+
"args": ["/absolute/path/to/mobile-debug-mcp/dist/server.js"]
|
|
263
|
+
}
|
|
264
|
+
}
|
|
265
|
+
}
|
|
160
266
|
```
|
|
161
267
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
<details>
|
|
165
|
-
|
|
166
|
-
<summary>Cursor plugin</summary>
|
|
167
|
-
|
|
168
|
-
The repository includes a [Cursor marketplace](.cursor-plugin/marketplace.json).
|
|
169
|
-
Teams and Enterprise admins can import the repository in Dashboard → Plugins & MCPs → Team
|
|
170
|
-
Marketplaces. To test it locally, copy [agent-plugin](agent-plugin/) into
|
|
171
|
-
`~/.cursor/plugins/local/mobile-debug-tools`, then reload Cursor.
|
|
172
|
-
|
|
173
|
-
</details>
|
|
174
|
-
|
|
175
|
-
Start a new chat or session after installation so the client loads the skill
|
|
176
|
-
and MCP tools. Each plugin launches the published npm package locally and needs
|
|
177
|
-
Node.js 18 or newer and the platform toolchains for your device. If you also
|
|
178
|
-
registered the MCP server directly, disable that registration to avoid
|
|
179
|
-
duplicate tools.
|
|
268
|
+
Replace the path with your checkout location. Rebuild after source changes.
|
|
180
269
|
|
|
181
|
-
##
|
|
270
|
+
## Environment setup
|
|
182
271
|
|
|
183
|
-
|
|
184
|
-
|
|
272
|
+
The server discovers platform tools from standard locations and `PATH`. Leave
|
|
273
|
+
path overrides unset for a standard installation. Use them for non-standard
|
|
274
|
+
locations, multiple toolchains, or a pinned development environment.
|
|
185
275
|
|
|
186
|
-
|
|
187
|
-
|
|
276
|
+
| Variable | Purpose |
|
|
277
|
+
| --- | --- |
|
|
278
|
+
| `ADB_PATH` | Path to `adb`. |
|
|
279
|
+
| `ANDROID_SDK_ROOT` or `ANDROID_HOME` | Android SDK root. |
|
|
280
|
+
| `XCRUN_PATH` | Path to `xcrun`. |
|
|
281
|
+
| `MCP_IDB_PATH` or `IDB_PATH` | Path to `idb`. |
|
|
282
|
+
| `GRADLE_JAVA_HOME` or `JAVA_HOME` | Java home for Gradle-backed operations. |
|
|
188
283
|
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
with current UI evidence if the state changed. See
|
|
193
|
-
[conditional actions](docs/tools/interact.md#conditional-actions) for supported
|
|
194
|
-
tools, examples, and the limits of the check.
|
|
284
|
+
After connecting the client, call `get_system_status` to check discovery and
|
|
285
|
+
prerequisites. See [environment diagnostics](docs/tools/system.md) if a toolchain
|
|
286
|
+
or device is unavailable.
|
|
195
287
|
|
|
196
|
-
|
|
288
|
+
Android debugger errors include bounded, sanitized failure classifications and recovery guidance; see the [debugger guide](docs/tools/debugger.md#failure-diagnostics).
|
|
197
289
|
|
|
198
|
-
|
|
199
|
-
state, and `wait_for_app_ready` for a bounded wait. Existing UI waits can opt into
|
|
200
|
-
`requireReady: true`. Results include evidence and uncertainty; see
|
|
201
|
-
[app readiness](docs/tools/observe.md#app-readiness) for limits and examples.
|
|
290
|
+
## Documentation
|
|
202
291
|
|
|
203
|
-
-
|
|
204
|
-
-
|
|
205
|
-
-
|
|
206
|
-
-
|
|
292
|
+
- [Documentation guide](docs/README.md) — find the guide for your task.
|
|
293
|
+
- [Tool reference](docs/tools/TOOLS.md) — inputs, responses, examples, and shared principles.
|
|
294
|
+
- [Contributing](CONTRIBUTING.md) — develop the server and run its checks.
|
|
295
|
+
- [Changelog](docs/CHANGELOG.md) — release history.
|
|
207
296
|
|
|
208
297
|
## License
|
|
209
298
|
|
|
210
|
-
Apache-2.0
|
|
299
|
+
[Apache-2.0](LICENSE)
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Mobile Debug Tools for Antigravity
|
|
2
|
+
|
|
3
|
+
Inspect and interact with Android and iOS apps using a local MCP server and the
|
|
4
|
+
bundled `mobile-debug-mcp` usage skill. Capture screenshots, logs and UI trees;
|
|
5
|
+
verify interactions with explicit evidence. Android additionally supports optional
|
|
6
|
+
runtime debugging and bounded Perfetto system traces. iOS runtime debugging and
|
|
7
|
+
system traces are not supported.
|
|
8
|
+
|
|
9
|
+
## Prerequisites
|
|
10
|
+
|
|
11
|
+
- Node.js 22 or newer, with `npx` on PATH and npm registry access on first launch.
|
|
12
|
+
- Android SDK/platform-tools and an authorized device or running emulator for Android.
|
|
13
|
+
- macOS and the applicable Xcode/idb tooling for iOS.
|
|
14
|
+
- Host JDK 17+ and a debuggable Android app for optional runtime debugging.
|
|
15
|
+
|
|
16
|
+
The server runs locally through `npx`; its exact version is pinned in
|
|
17
|
+
`mcp_config.json`. The plugin uses the client-managed `${PLUGIN_DATA}` directory as its working directory.
|
|
18
|
+
No plugin-specific account, API key, OAuth sign-in or hosted backend is required.
|
|
19
|
+
|
|
20
|
+
## Install and use
|
|
21
|
+
|
|
22
|
+
Install the extracted plugin directory with `agy plugin install /path/to/mobile-debug-tools`.
|
|
23
|
+
Run `agy plugin list --json` and confirm one skill (`mobile-debug-mcp`) and one
|
|
24
|
+
MCP server (`mobile-debug-mcp`) are discovered. Start a new session. Disable a
|
|
25
|
+
separate manual registration of the same MCP server to avoid duplicate tools.
|
|
26
|
+
|
|
27
|
+
Example prompts:
|
|
28
|
+
|
|
29
|
+
- Check my mobile debugging environment and connected devices.
|
|
30
|
+
- Inspect the current screen of my mobile app.
|
|
31
|
+
- Help me reproduce and diagnose a bug in my mobile app.
|
|
32
|
+
|
|
33
|
+
For a first check, select an explicit emulator/device, inspect its current screen,
|
|
34
|
+
and verify a harmless interaction using fresh UI evidence. Readiness is a probe;
|
|
35
|
+
a dispatched action alone does not establish an app outcome.
|
|
36
|
+
|
|
37
|
+
## Access and support
|
|
38
|
+
|
|
39
|
+
Tools can read device screens, logs and shallow debugger locals; they can also
|
|
40
|
+
interact with apps and manage their lifecycle. These may contain private data.
|
|
41
|
+
Use only devices and apps you intend to inspect. Build/install/reset operations
|
|
42
|
+
have their own effects and should be requested explicitly. Trace contents and
|
|
43
|
+
artifacts stay local; this plugin adds no automatic upload service.
|
|
44
|
+
|
|
45
|
+
Source and setup: https://github.com/clivejefferies/mobile-debug-tools
|
|
46
|
+
Tool reference: https://github.com/clivejefferies/mobile-debug-tools/blob/main/docs/tools/TOOLS.md
|
|
47
|
+
Support: https://github.com/clivejefferies/mobile-debug-tools/issues
|
|
48
|
+
License: Apache-2.0. Publisher attribution: mobile-debug-tools contributors.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://antigravity.google/schemas/v1/plugin.json",
|
|
3
|
+
"name": "mobile-debug-tools",
|
|
4
|
+
"version": "0.0.6",
|
|
5
|
+
"description": "Mobile app debugging tools and usage guidance for Android and iOS agents.",
|
|
6
|
+
"author": {
|
|
7
|
+
"name": "mobile-debug-tools contributors"
|
|
8
|
+
},
|
|
9
|
+
"repository": "https://github.com/clivejefferies/mobile-debug-tools",
|
|
10
|
+
"license": "Apache-2.0",
|
|
11
|
+
"displayName": "Mobile Debug Tools",
|
|
12
|
+
"logo": "assets/mobile-debug-tools.svg",
|
|
13
|
+
"suggestedPrompts": [
|
|
14
|
+
"Check my mobile debugging environment and connected devices.",
|
|
15
|
+
"Inspect the current screen of my mobile app.",
|
|
16
|
+
"Help me reproduce and diagnose a bug in my mobile app."
|
|
17
|
+
]
|
|
18
|
+
}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "mobile-debug-tools",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.6",
|
|
4
4
|
"description": "Mobile app debugging tools and usage guidance for Android and iOS agents.",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "mobile-debug-tools contributors"
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
"command": "npx",
|
|
13
13
|
"args": [
|
|
14
14
|
"--yes",
|
|
15
|
-
"mobile-debug-mcp@0.
|
|
15
|
+
"mobile-debug-mcp@0.36.0",
|
|
16
16
|
"server"
|
|
17
17
|
]
|
|
18
18
|
}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "mobile-debug-tools",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.6",
|
|
4
4
|
"description": "Mobile app debugging tools and usage guidance for Android and iOS agents.",
|
|
5
5
|
"repository": "https://github.com/clivejefferies/mobile-debug-tools",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "mobile-debug-tools",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.6",
|
|
4
4
|
"description": "Mobile app debugging tools and usage guidance for Android and iOS agents.",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "mobile-debug-tools contributors"
|
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
"command": "npx",
|
|
15
15
|
"args": [
|
|
16
16
|
"--yes",
|
|
17
|
-
"mobile-debug-mcp@0.
|
|
17
|
+
"mobile-debug-mcp@0.36.0",
|
|
18
18
|
"server"
|
|
19
19
|
],
|
|
20
20
|
"cwd": "${CURSOR_PLUGIN_ROOT}"
|