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.
Files changed (500) hide show
  1. package/.agents/skills/mcp-builder/SKILL.md +44 -64
  2. package/.agents/skills/mcp-builder/references/build-flags.md +44 -43
  3. package/.agents/skills/mcp-builder/references/diagnostics-schema.md +4 -1
  4. package/.agents/skills/mcp-builder/references/toolchain-details.md +49 -62
  5. package/.agents/skills/spec-review/references/spec-review-checklist.md +7 -0
  6. package/.agents/skills/test-authoring/SKILL.md +7 -6
  7. package/.agents/skills/test-authoring/references/repo-test-layout.md +3 -1
  8. package/.agents/skills/test-authoring/references/test-authoring-workflow.md +16 -7
  9. package/.agents/skills/test-authoring/references/test-quality-checklist.md +2 -1
  10. package/.cursor-plugin/marketplace.json +1 -1
  11. package/.github/copilot-instructions.md +14 -36
  12. package/.github/workflows/ci.yml +4 -4
  13. package/AGENTS.md +12 -3
  14. package/CONTRIBUTING.md +79 -0
  15. package/README.md +218 -129
  16. package/agent-plugin/.antigravity-plugin/README.md +48 -0
  17. package/agent-plugin/.antigravity-plugin/plugin.json +18 -0
  18. package/agent-plugin/.claude-plugin/plugin.json +2 -2
  19. package/agent-plugin/.codex-plugin/plugin.json +1 -1
  20. package/agent-plugin/.cursor-plugin/plugin.json +2 -2
  21. package/agent-plugin/.mcp.json +1 -1
  22. package/agent-plugin/README.md +50 -11
  23. package/agent-plugin/cursor/.cursor-plugin/plugin.json +23 -0
  24. package/agent-plugin/cursor/LICENSE +201 -0
  25. package/agent-plugin/cursor/README.md +9 -0
  26. package/agent-plugin/cursor/skills/mobile-debug-mcp/SKILL.md +253 -0
  27. package/agent-plugin/mcp.json +1 -1
  28. package/agent-plugin/mcp_config.json +13 -0
  29. package/agent-plugin/plugin.json +1 -1
  30. package/agent-plugin/skills/mobile-debug-mcp/SKILL.md +62 -17
  31. package/dist/contracts/execution-controls.js +24 -0
  32. package/dist/contracts/selector.js +8 -0
  33. package/dist/contracts/target.js +15 -0
  34. package/dist/contracts/ui.js +1 -0
  35. package/dist/debugger/android.js +2 -1
  36. package/dist/debugger/diagnostics.js +54 -0
  37. package/dist/debugger/guard.js +4 -4
  38. package/dist/debugger/ios-worker.js +62 -0
  39. package/dist/debugger/ios.js +57 -0
  40. package/dist/debugger/protocol.js +33 -0
  41. package/dist/debugger/sessions.js +133 -74
  42. package/dist/debugger/worker.js +59 -46
  43. package/dist/interact/adjustment/adjustment-context.js +41 -0
  44. package/dist/interact/adjustment/adjustment-gestures.js +55 -0
  45. package/dist/interact/adjustment/adjustment-plan.js +18 -0
  46. package/dist/interact/adjustment/adjustment-resolution.js +127 -0
  47. package/dist/interact/adjustment/adjustment-result.js +19 -0
  48. package/dist/interact/adjustment/adjustment-semantic.js +64 -0
  49. package/dist/interact/adjustment/adjustment-verification.js +35 -0
  50. package/dist/interact/adjustment/adjustment.js +52 -0
  51. package/dist/interact/adjustment/control-geometry.js +87 -0
  52. package/dist/interact/adjustment/control-values.js +136 -0
  53. package/dist/interact/adjustment/slider-labels.js +84 -0
  54. package/dist/interact/assertions/screen-assertion.js +37 -0
  55. package/dist/interact/assertions/state-assertion-context.js +35 -0
  56. package/dist/interact/assertions/state-assertion.js +76 -0
  57. package/dist/interact/assertions/state-comparison.js +141 -0
  58. package/dist/interact/assertions/visibility-assertion.js +34 -0
  59. package/dist/interact/conditional-action.js +12 -7
  60. package/dist/interact/index.js +77 -3092
  61. package/dist/interact/input-service.js +1 -0
  62. package/dist/interact/interaction-trace.js +21 -0
  63. package/dist/interact/model.js +1 -0
  64. package/dist/interact/observation.js +1 -0
  65. package/dist/interact/targeting/candidate-ancestor.js +58 -0
  66. package/dist/interact/targeting/candidate-result.js +23 -0
  67. package/dist/interact/targeting/candidate-scoring.js +50 -0
  68. package/dist/interact/targeting/element-helpers.js +216 -0
  69. package/dist/interact/targeting/find-element.js +65 -0
  70. package/dist/interact/targeting/nearby-control.js +56 -0
  71. package/dist/interact/targeting/resolved-elements.js +21 -0
  72. package/dist/interact/targeting/tap-target.js +17 -0
  73. package/dist/interact/targeting/target-scope.js +104 -0
  74. package/dist/interact/waits/legacy-log-wait.js +38 -0
  75. package/dist/interact/waits/legacy-wait-observations.js +103 -0
  76. package/dist/interact/waits/legacy-wait-state.js +34 -0
  77. package/dist/interact/waits/legacy-wait.js +48 -0
  78. package/dist/interact/waits/screen-wait.js +49 -0
  79. package/dist/interact/waits/ui-change-helpers.js +157 -0
  80. package/dist/interact/waits/ui-change-state.js +18 -0
  81. package/dist/interact/waits/ui-change-wait.js +77 -0
  82. package/dist/interact/waits/ui-wait-condition.js +56 -0
  83. package/dist/interact/waits/ui-wait-state.js +38 -0
  84. package/dist/interact/waits/ui-wait.js +106 -0
  85. package/dist/manage/android.js +55 -51
  86. package/dist/manage/index.js +38 -75
  87. package/dist/manage/ios/build-types.js +1 -0
  88. package/dist/manage/ios/build.js +210 -0
  89. package/dist/manage/ios/project-discovery.js +29 -0
  90. package/dist/manage/ios/scheme.js +18 -0
  91. package/dist/manage/ios.js +44 -256
  92. package/dist/observe/android/context.js +1 -0
  93. package/dist/observe/android/current-screen.js +55 -0
  94. package/dist/observe/android/fingerprint.js +13 -0
  95. package/dist/observe/android/log-stream.js +132 -0
  96. package/dist/observe/android/logs.js +107 -0
  97. package/dist/observe/android/screenshot.js +70 -0
  98. package/dist/observe/android/ui-tree.js +107 -0
  99. package/dist/observe/android.js +16 -520
  100. package/dist/observe/evidence.js +114 -75
  101. package/dist/observe/index.js +16 -263
  102. package/dist/observe/ios/context.js +16 -0
  103. package/dist/observe/ios/fingerprint.js +12 -0
  104. package/dist/observe/ios/log-stream.js +105 -0
  105. package/dist/observe/ios/logs.js +168 -0
  106. package/dist/observe/ios/screenshot.js +22 -0
  107. package/dist/observe/ios/ui-elements.js +241 -0
  108. package/dist/observe/ios/ui-tree.js +137 -0
  109. package/dist/observe/ios-trace/artifact.js +63 -0
  110. package/dist/observe/ios-trace/capabilities.js +86 -0
  111. package/dist/observe/ios-trace/native.js +93 -0
  112. package/dist/observe/ios-trace/notification.js +35 -0
  113. package/dist/observe/ios-trace/process.js +98 -0
  114. package/dist/observe/ios-trace/sessions.js +244 -0
  115. package/dist/observe/ios.js +17 -715
  116. package/dist/observe/logs/model.js +1 -0
  117. package/dist/{network → observe/network}/index.js +2 -2
  118. package/dist/observe/readiness-service.js +5 -3
  119. package/dist/observe/readiness.js +33 -14
  120. package/dist/observe/screenshot-encoding.js +41 -0
  121. package/dist/observe/snapshot-collection.js +79 -0
  122. package/dist/observe/snapshot-logs.js +30 -0
  123. package/dist/observe/snapshot-metadata.js +43 -31
  124. package/dist/observe/snapshot-semantic.js +115 -0
  125. package/dist/observe/system-trace-error.js +7 -0
  126. package/dist/observe/system-trace-router.js +81 -0
  127. package/dist/observe/system-trace.js +26 -21
  128. package/dist/runtime/action-results.js +270 -0
  129. package/dist/runtime/clock.js +4 -0
  130. package/dist/server/common.js +1 -256
  131. package/dist/server/definitions/assert.js +162 -0
  132. package/dist/server/definitions/diagnostic.js +118 -0
  133. package/dist/server/definitions/input.js +274 -0
  134. package/dist/server/definitions/manage.js +194 -0
  135. package/dist/server/definitions/observe.js +149 -0
  136. package/dist/server/definitions/target.js +138 -0
  137. package/dist/server/definitions/wait.js +105 -0
  138. package/dist/server/handlers/action-execution.js +163 -0
  139. package/dist/server/handlers/correlation.js +23 -0
  140. package/dist/server/handlers/debugger-handlers.js +67 -0
  141. package/dist/server/handlers/debugger-response.js +9 -0
  142. package/dist/server/handlers/diagnostic.js +77 -0
  143. package/dist/server/handlers/handler-types.js +1 -0
  144. package/dist/server/handlers/input.js +154 -0
  145. package/dist/server/handlers/interact.js +113 -0
  146. package/dist/server/handlers/journey-assertions.js +35 -0
  147. package/dist/server/handlers/journey.js +147 -0
  148. package/dist/server/handlers/manage.js +119 -0
  149. package/dist/server/handlers/observe.js +95 -0
  150. package/dist/server/handlers/payload.js +4 -0
  151. package/dist/server/handlers/tool-handlers.js +170 -0
  152. package/dist/server/schemas/condition-schema.js +2 -0
  153. package/dist/server/{debugger-schema.js → schemas/debugger-schema.js} +20 -12
  154. package/dist/server/{journey-schema.js → schemas/journey-schema.js} +7 -22
  155. package/dist/server/schemas/system-trace-schema.js +22 -0
  156. package/dist/server/tool-definitions.js +58 -1135
  157. package/dist/server-core.js +2 -2
  158. package/dist/server.js +4 -4
  159. package/dist/system/android-status.js +101 -0
  160. package/dist/system/android.js +37 -27
  161. package/dist/system/index.js +13 -439
  162. package/dist/system/ios-status.js +132 -0
  163. package/dist/system/ios.js +11 -8
  164. package/dist/system/model.js +1 -0
  165. package/dist/system/probes.js +105 -0
  166. package/dist/system/status-summary.js +43 -0
  167. package/dist/system/unsupported-status.js +52 -0
  168. package/dist/utils/android/commands.js +89 -0
  169. package/dist/utils/android/gradle.js +139 -0
  170. package/dist/utils/android/logs.js +103 -0
  171. package/dist/utils/android/ui-tree.js +233 -0
  172. package/dist/utils/android/utils.js +6 -564
  173. package/dist/utils/cli/idb/idb-helper.js +4 -6
  174. package/dist/utils/cli/idb/install-idb.js +13 -9
  175. package/dist/utils/cli/ios/preflight-ios.js +42 -38
  176. package/dist/utils/ios/utils.js +48 -46
  177. package/dist/utils/java.js +65 -49
  178. package/dist/utils/resolve-device.js +4 -2
  179. package/dist/utils/ui/index.js +26 -26
  180. package/docs/CHANGELOG.md +67 -1
  181. package/docs/README.md +38 -0
  182. package/docs/agent-plugin-installation-verification.md +39 -0
  183. package/docs/benchmarks/README.md +18 -0
  184. package/docs/benchmarks/interaction-latency/README.md +14 -0
  185. package/docs/benchmarks/interaction-latency/final.md +4 -1
  186. package/docs/benchmarks/interaction-latency/ios-validation.md +2 -0
  187. package/docs/benchmarks/ui-tree-performance/README.md +24 -16
  188. package/docs/benchmarks/ui-tree-performance/comparison.md +11 -10
  189. package/docs/code-structure.md +120 -0
  190. package/docs/specs/001-state-verification/spec.md +16 -14
  191. package/docs/specs/002-richer-element-identity/spec.md +12 -10
  192. package/docs/specs/003-wait-and-synchronization-reliability/spec.md +12 -10
  193. package/docs/specs/004-action-verification-routing/spec.md +3 -3
  194. package/docs/specs/005-unified-action-execution-and-verification-model/spec.md +2 -0
  195. package/docs/specs/006-runtime-action-instrumentation-and-binding-layer/spec.md +2 -0
  196. package/docs/specs/007-actionability-resolution-and-executable-target-selection/spec.md +3 -1
  197. package/docs/specs/008-adjustable-control-support-and-semantic-value-manipulation/spec.md +3 -4
  198. package/docs/specs/009-semantic-control-modeling-for-custom-and-composite-controls/spec.md +2 -0
  199. package/docs/specs/010-verification-stabilization-and-temporal-convergence/spec.md +2 -2
  200. package/docs/specs/011-recovery-and-replanning-for-failed-or-ambiguous-interaction-flows/spec.md +2 -2
  201. package/docs/specs/011.1-recovery-contract-types-and-runtime-wiring-spec/spec.md +2 -0
  202. package/docs/specs/012-action-trace-and-xecution-observability/spec.md +2 -3
  203. package/docs/specs/013-wait-and-synchronization-reliability/spec.md +19 -19
  204. package/docs/specs/014-actionability-resolution/spec.md +20 -18
  205. package/docs/specs/015-adjustable-control-support/spec.md +17 -15
  206. package/docs/specs/016-environment-tools/spec.md +20 -20
  207. package/docs/specs/018-interaction-latency-and-batched-journeys/spec.md +2 -0
  208. package/docs/specs/019-ui-tree-observation-performance/spec.md +3 -1
  209. package/docs/specs/020-conditional-actions/intent.md +5 -3
  210. package/docs/specs/020-conditional-actions/plan.md +8 -9
  211. package/docs/specs/020-conditional-actions/spec.md +4 -2
  212. package/docs/specs/021-app-readiness-signals/intent.md +4 -2
  213. package/docs/specs/021-app-readiness-signals/plan.md +7 -6
  214. package/docs/specs/021-app-readiness-signals/spec.md +3 -1
  215. package/docs/specs/022-correlated-evidence/intent.md +4 -4
  216. package/docs/specs/022-correlated-evidence/plan.md +10 -11
  217. package/docs/specs/022-correlated-evidence/spec.md +3 -1
  218. package/docs/specs/023-android-system-traces/intent.md +3 -2
  219. package/docs/specs/023-android-system-traces/plan.md +5 -7
  220. package/docs/specs/023-android-system-traces/spec.md +3 -1
  221. package/docs/specs/024-android-heap-dump-capture/intent.md +3 -1
  222. package/docs/specs/025-android-runtime-debugger/intent.md +4 -3
  223. package/docs/specs/025-android-runtime-debugger/plan.md +3 -1
  224. package/docs/specs/025-android-runtime-debugger/spec.md +4 -3
  225. package/docs/specs/026-code-structure-and-quality-gates/health-plan.md +88 -0
  226. package/docs/specs/026-code-structure-and-quality-gates/intent.md +47 -0
  227. package/docs/specs/026-code-structure-and-quality-gates/plan.md +191 -0
  228. package/docs/specs/026-code-structure-and-quality-gates/spec.md +138 -0
  229. package/docs/specs/026-code-structure-and-quality-gates/verification-final.json +200 -0
  230. package/docs/specs/026-code-structure-and-quality-gates/verification-thin-facade.json +154 -0
  231. package/docs/specs/026-code-structure-and-quality-gates/verification.json +136 -0
  232. package/docs/specs/027-debugger-failure-diagnostics/intent.md +43 -0
  233. package/docs/specs/027-debugger-failure-diagnostics/plan.md +86 -0
  234. package/docs/specs/027-debugger-failure-diagnostics/spec.md +133 -0
  235. package/docs/specs/028-compact-debugger-responses/intent.md +41 -0
  236. package/docs/specs/028-compact-debugger-responses/plan.md +112 -0
  237. package/docs/specs/028-compact-debugger-responses/spec.md +108 -0
  238. package/docs/specs/029-kotlin-locals-validation/report.md +119 -0
  239. package/docs/specs/030-android-coroutine-validation/evidence.json +475 -0
  240. package/docs/specs/030-android-coroutine-validation/intent.md +47 -0
  241. package/docs/specs/030-android-coroutine-validation/plan.md +147 -0
  242. package/docs/specs/030-android-coroutine-validation/report.md +240 -0
  243. package/docs/specs/030-android-coroutine-validation/spec.md +107 -0
  244. package/docs/specs/031-ios-system-traces/intent.md +38 -0
  245. package/docs/specs/031-ios-system-traces/investigation.md +92 -0
  246. package/docs/specs/031-ios-system-traces/late-run-failure-evidence.json +32 -0
  247. package/docs/specs/031-ios-system-traces/plan.md +138 -0
  248. package/docs/specs/031-ios-system-traces/pr102-monitor-evidence.json +22 -0
  249. package/docs/specs/031-ios-system-traces/simulator-evidence.json +47 -0
  250. package/docs/specs/031-ios-system-traces/spec.md +135 -0
  251. package/docs/specs/032-ios-runtime-debugger/evidence.json +176 -0
  252. package/docs/specs/032-ios-runtime-debugger/intent.md +38 -0
  253. package/docs/specs/032-ios-runtime-debugger/plan.md +95 -0
  254. package/docs/specs/032-ios-runtime-debugger/report.md +205 -0
  255. package/docs/specs/032-ios-runtime-debugger/spec.md +153 -0
  256. package/docs/tools/TOOLS.md +31 -18
  257. package/docs/tools/{evidence.md → correlated-evidence.md} +9 -1
  258. package/docs/tools/debugger.md +120 -4
  259. package/docs/tools/interact.md +42 -20
  260. package/docs/tools/manage.md +25 -44
  261. package/docs/tools/observe.md +55 -23
  262. package/docs/tools/system-traces.md +89 -14
  263. package/docs/tools/system.md +12 -5
  264. package/package.json +12 -8
  265. package/scripts/agent-plugin.mjs +55 -5
  266. package/scripts/architecture-graph.mjs +69 -0
  267. package/scripts/check-architecture.mjs +47 -0
  268. package/scripts/code-quality-baseline.json +1 -0
  269. package/scripts/code-quality.mjs +161 -0
  270. package/src/contracts/execution-controls.ts +26 -0
  271. package/src/contracts/selector.ts +17 -0
  272. package/src/contracts/target.ts +19 -0
  273. package/src/contracts/ui.ts +94 -0
  274. package/src/debugger/android.ts +3 -2
  275. package/src/debugger/diagnostics.ts +43 -0
  276. package/src/debugger/guard.ts +10 -5
  277. package/src/debugger/ios-worker.ts +49 -0
  278. package/src/debugger/ios.ts +45 -0
  279. package/{worker → src/debugger/java}/DebuggerWorker.java +9 -3
  280. package/src/debugger/lldb/breakpoints.py +51 -0
  281. package/src/debugger/lldb/inspection.py +109 -0
  282. package/src/debugger/lldb/worker.py +203 -0
  283. package/src/debugger/protocol.ts +37 -0
  284. package/src/debugger/sessions.ts +326 -155
  285. package/src/debugger/worker.ts +57 -41
  286. package/src/interact/adjustment/adjustment-context.ts +83 -0
  287. package/src/interact/adjustment/adjustment-gestures.ts +48 -0
  288. package/src/interact/adjustment/adjustment-plan.ts +23 -0
  289. package/src/interact/adjustment/adjustment-resolution.ts +104 -0
  290. package/src/interact/adjustment/adjustment-result.ts +34 -0
  291. package/src/interact/adjustment/adjustment-semantic.ts +53 -0
  292. package/src/interact/adjustment/adjustment-verification.ts +60 -0
  293. package/src/interact/adjustment/adjustment.ts +49 -0
  294. package/src/interact/adjustment/control-geometry.ts +120 -0
  295. package/src/interact/adjustment/control-values.ts +141 -0
  296. package/src/interact/adjustment/slider-labels.ts +84 -0
  297. package/src/interact/assertions/screen-assertion.ts +39 -0
  298. package/src/interact/assertions/state-assertion-context.ts +48 -0
  299. package/src/interact/assertions/state-assertion.ts +64 -0
  300. package/src/interact/assertions/state-comparison.ts +168 -0
  301. package/src/interact/assertions/visibility-assertion.ts +41 -0
  302. package/src/interact/conditional-action.ts +18 -12
  303. package/src/interact/index.ts +89 -3494
  304. package/src/interact/input-service.ts +11 -0
  305. package/src/interact/interaction-trace.ts +36 -0
  306. package/src/interact/model.ts +109 -0
  307. package/src/interact/observation.ts +7 -0
  308. package/src/interact/targeting/candidate-ancestor.ts +49 -0
  309. package/src/interact/targeting/candidate-result.ts +24 -0
  310. package/src/interact/targeting/candidate-scoring.ts +42 -0
  311. package/src/interact/targeting/element-helpers.ts +243 -0
  312. package/src/interact/targeting/find-element.ts +47 -0
  313. package/src/interact/targeting/nearby-control.ts +46 -0
  314. package/src/interact/targeting/resolved-elements.ts +20 -0
  315. package/src/interact/targeting/tap-target.ts +22 -0
  316. package/src/interact/targeting/target-scope.ts +121 -0
  317. package/src/interact/waits/legacy-log-wait.ts +30 -0
  318. package/src/interact/waits/legacy-wait-observations.ts +55 -0
  319. package/src/interact/waits/legacy-wait-state.ts +48 -0
  320. package/src/interact/waits/legacy-wait.ts +34 -0
  321. package/src/interact/waits/screen-wait.ts +37 -0
  322. package/src/interact/waits/ui-change-helpers.ts +184 -0
  323. package/src/interact/waits/ui-change-state.ts +26 -0
  324. package/src/interact/waits/ui-change-wait.ts +59 -0
  325. package/src/interact/waits/ui-wait-condition.ts +52 -0
  326. package/src/interact/waits/ui-wait-state.ts +55 -0
  327. package/src/interact/waits/ui-wait.ts +84 -0
  328. package/src/manage/android.ts +56 -50
  329. package/src/manage/index.ts +63 -93
  330. package/src/manage/ios/build-types.ts +14 -0
  331. package/src/manage/ios/build.ts +230 -0
  332. package/src/manage/ios/project-discovery.ts +26 -0
  333. package/src/manage/ios/scheme.ts +16 -0
  334. package/src/manage/ios.ts +67 -298
  335. package/src/observe/android/context.ts +1 -0
  336. package/src/observe/android/current-screen.ts +63 -0
  337. package/src/observe/android/fingerprint.ts +13 -0
  338. package/src/observe/android/log-stream.ts +127 -0
  339. package/src/observe/android/logs.ts +110 -0
  340. package/src/observe/android/screenshot.ts +79 -0
  341. package/src/observe/android/ui-tree.ts +113 -0
  342. package/src/observe/android.ts +17 -531
  343. package/src/observe/evidence.ts +122 -70
  344. package/src/observe/index.ts +24 -286
  345. package/src/observe/ios/context.ts +22 -0
  346. package/src/observe/ios/fingerprint.ts +12 -0
  347. package/src/observe/ios/log-stream.ts +103 -0
  348. package/src/observe/ios/logs.ts +179 -0
  349. package/src/observe/ios/screenshot.ts +26 -0
  350. package/src/observe/ios/ui-elements.ts +266 -0
  351. package/src/observe/ios/ui-tree.ts +143 -0
  352. package/src/observe/ios-trace/artifact.ts +55 -0
  353. package/src/observe/ios-trace/capabilities.ts +74 -0
  354. package/src/observe/ios-trace/native.ts +72 -0
  355. package/src/observe/ios-trace/notification.ts +30 -0
  356. package/src/observe/ios-trace/process.ts +82 -0
  357. package/src/observe/ios-trace/sessions.ts +204 -0
  358. package/src/observe/ios.ts +18 -749
  359. package/src/observe/logs/model.ts +11 -0
  360. package/src/{network → observe/network}/index.ts +2 -2
  361. package/src/observe/readiness-service.ts +6 -4
  362. package/src/observe/readiness.ts +42 -21
  363. package/src/observe/screenshot-encoding.ts +32 -0
  364. package/src/observe/snapshot-collection.ts +69 -0
  365. package/src/observe/snapshot-logs.ts +26 -0
  366. package/src/observe/snapshot-metadata.ts +51 -31
  367. package/src/observe/snapshot-semantic.ts +153 -0
  368. package/src/observe/system-trace-error.ts +3 -0
  369. package/src/observe/system-trace-router.ts +61 -0
  370. package/src/observe/system-trace.ts +28 -19
  371. package/src/runtime/action-results.ts +376 -0
  372. package/src/runtime/clock.ts +9 -0
  373. package/src/server/common.ts +9 -359
  374. package/src/server/definitions/assert.ts +164 -0
  375. package/src/server/definitions/diagnostic.ts +120 -0
  376. package/src/server/definitions/input.ts +276 -0
  377. package/src/server/definitions/manage.ts +196 -0
  378. package/src/server/definitions/observe.ts +151 -0
  379. package/src/server/definitions/target.ts +140 -0
  380. package/src/server/definitions/wait.ts +107 -0
  381. package/src/server/handlers/action-execution.ts +164 -0
  382. package/src/server/handlers/correlation.ts +20 -0
  383. package/src/server/handlers/debugger-handlers.ts +58 -0
  384. package/src/server/handlers/debugger-response.ts +7 -0
  385. package/src/server/handlers/diagnostic.ts +86 -0
  386. package/src/server/handlers/handler-types.ts +7 -0
  387. package/src/server/handlers/input.ts +173 -0
  388. package/src/server/handlers/interact.ts +135 -0
  389. package/src/server/handlers/journey-assertions.ts +39 -0
  390. package/src/server/handlers/journey.ts +132 -0
  391. package/src/server/handlers/manage.ts +141 -0
  392. package/src/server/handlers/observe.ts +116 -0
  393. package/src/server/handlers/payload.ts +36 -0
  394. package/src/server/handlers/tool-handlers.ts +170 -0
  395. package/src/server/schemas/condition-schema.ts +2 -0
  396. package/src/server/schemas/debugger-schema.ts +46 -0
  397. package/src/server/{journey-schema.ts → schemas/journey-schema.ts} +7 -22
  398. package/src/server/schemas/system-trace-schema.ts +23 -0
  399. package/src/server/tool-definitions.ts +67 -1143
  400. package/src/server-core.ts +2 -2
  401. package/src/server.ts +4 -4
  402. package/src/system/android-status.ts +124 -0
  403. package/src/system/android.ts +33 -21
  404. package/src/system/index.ts +21 -525
  405. package/src/system/ios-status.ts +147 -0
  406. package/src/system/ios.ts +14 -10
  407. package/src/system/model.ts +41 -0
  408. package/src/system/probes.ts +114 -0
  409. package/src/system/status-summary.ts +47 -0
  410. package/src/system/unsupported-status.ts +55 -0
  411. package/src/types.ts +16 -106
  412. package/src/utils/android/commands.ts +81 -0
  413. package/src/utils/android/gradle.ts +132 -0
  414. package/src/utils/android/logs.ts +103 -0
  415. package/src/utils/android/ui-tree.ts +239 -0
  416. package/src/utils/android/utils.ts +16 -556
  417. package/src/utils/cli/idb/check-idb.ts +4 -4
  418. package/src/utils/cli/idb/idb-helper.ts +6 -8
  419. package/src/utils/cli/idb/install-idb.ts +15 -9
  420. package/src/utils/cli/ios/preflight-ios.ts +39 -31
  421. package/src/utils/cli/ios/run-ios-ui-tree-tap.ts +4 -4
  422. package/src/utils/ios/utils.ts +60 -61
  423. package/src/utils/java.ts +62 -43
  424. package/src/utils/resolve-device.ts +9 -6
  425. package/src/utils/ui/index.ts +28 -28
  426. package/test/device/automated/debugger/coroutine-lifecycle.ts +27 -0
  427. package/test/device/automated/debugger/coroutine-support.ts +140 -0
  428. package/test/device/automated/debugger/coroutine.android.test.ts +169 -0
  429. package/test/device/automated/debugger/kotlin.android.test.ts +127 -0
  430. package/test/device/automated/debugger/runtime.android.test.ts +19 -3
  431. package/test/device/automated/debugger/runtime.ios.test.ts +221 -0
  432. package/test/device/automated/interact/interaction.android.test.ts +56 -0
  433. package/test/device/automated/observe/ios-system-trace.smoke.ts +119 -0
  434. package/test/device/automated/observe/system-trace.smoke.ts +1 -1
  435. package/test/device/manual/interact/modul8_selector_tap.manual.ts +1 -1
  436. package/test/fixtures/contracts/tool-definitions.json +3696 -0
  437. package/test/fixtures/coroutine-app/MainActivity.kt +100 -0
  438. package/test/fixtures/coroutine-app/README.md +48 -0
  439. package/test/fixtures/coroutine-app/build.ts +35 -0
  440. package/test/fixtures/debugger-app/MainActivity.java +21 -0
  441. package/test/fixtures/debugger-app/MainActivity.kt +32 -0
  442. package/test/fixtures/debugger-app/README.md +52 -0
  443. package/test/fixtures/debugger-app/build.ts +25 -15
  444. package/test/fixtures/ios-debugger-app/Main.swift +95 -0
  445. package/test/fixtures/ios-debugger-app/README.md +27 -0
  446. package/test/fixtures/ios-debugger-app/build.ts +21 -0
  447. package/test/fixtures/latency-journey-app/README.md +2 -0
  448. package/test/fixtures/readiness-app/README.md +2 -0
  449. package/test/helpers/ios-trace-shutdown.ts +29 -0
  450. package/test/unit/debugger/coroutine-lifecycle.test.ts +43 -0
  451. package/test/unit/debugger/diagnostic-sessions.test.ts +67 -0
  452. package/test/unit/debugger/diagnostics.test.ts +80 -0
  453. package/test/unit/debugger/guards.test.ts +4 -0
  454. package/test/unit/debugger/handle-guards.test.ts +88 -0
  455. package/test/unit/debugger/ios-preparation.test.ts +57 -0
  456. package/test/unit/debugger/ios.test.ts +104 -0
  457. package/test/unit/debugger/lldb-worker.py +166 -0
  458. package/test/unit/debugger/lldb-worker.test.ts +10 -0
  459. package/test/unit/debugger/preparation.test.ts +32 -0
  460. package/test/unit/debugger/protocol.test.ts +15 -0
  461. package/test/unit/debugger/sessions.test.ts +1 -1
  462. package/test/unit/interact/adjustment_service.test.ts +42 -0
  463. package/test/unit/interact/adjustment_verification.test.ts +35 -0
  464. package/test/unit/interact/clock_dependencies.test.ts +63 -0
  465. package/test/unit/interact/element_helpers.test.ts +19 -0
  466. package/test/unit/interact/legacy_wait_service.test.ts +17 -0
  467. package/test/unit/interact/state_comparison.test.ts +20 -0
  468. package/test/unit/interact/target_scope.test.ts +35 -0
  469. package/test/unit/network/get_network_activity.test.ts +1 -1
  470. package/test/unit/observe/ios-trace-native.test.ts +90 -0
  471. package/test/unit/observe/ios-trace-sessions.test.ts +131 -0
  472. package/test/unit/observe/readiness.test.ts +1 -1
  473. package/test/unit/observe/screenshot-encoding.test.ts +30 -0
  474. package/test/unit/observe/snapshot-logs.test.ts +14 -0
  475. package/test/unit/observe/system-trace-router.test.ts +49 -0
  476. package/test/unit/quality/agent-plugin-export.test.ts +38 -0
  477. package/test/unit/quality/architecture.test.ts +60 -0
  478. package/test/unit/quality/code-quality.test.ts +58 -0
  479. package/test/unit/quality/interaction_boundaries.test.ts +24 -0
  480. package/test/unit/server/conditional_actions.test.ts +1 -1
  481. package/test/unit/server/conditional_schema.test.ts +2 -2
  482. package/test/unit/server/debugger-response.test.ts +63 -0
  483. package/test/unit/server/system-trace.test.ts +12 -3
  484. package/test/unit/server/tool_definitions_parity.test.ts +8 -0
  485. package/dist/server/debugger-handlers.js +0 -38
  486. package/dist/server/system-trace-schema.js +0 -17
  487. package/dist/server/tool-handlers.js +0 -1000
  488. package/docs/ROADMAP.md +0 -646
  489. package/docs/benchmarks/ui-tree-performance/bridge-probe.json +0 -29
  490. package/docs/benchmarks/ui-tree-performance/initial-baseline.json +0 -59560
  491. package/docs/specs/baseline-spec-v0.md +0 -312
  492. package/docs/specs/mcp-tooling-spec-v1.md +0 -446
  493. package/src/server/debugger-handlers.ts +0 -29
  494. package/src/server/debugger-schema.ts +0 -37
  495. package/src/server/system-trace-schema.ts +0 -17
  496. package/src/server/tool-handlers.ts +0 -1008
  497. /package/dist/{server/condition-schema.js → contracts/condition.js} +0 -0
  498. /package/dist/server/{readiness-schema.js → schemas/readiness-schema.js} +0 -0
  499. /package/src/{server/condition-schema.ts → contracts/condition.ts} +0 -0
  500. /package/src/server/{readiness-schema.ts → schemas/readiness-schema.ts} +0 -0
@@ -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
  [![npm version](https://img.shields.io/npm/v/mobile-debug-mcp.svg)](https://www.npmjs.com/package/mobile-debug-mcp)
3
3
 
4
- A minimal, secure MCP server for AI-assisted mobile development. Build, install, interact and inspect Android/iOS apps from an MCP-compatible client.
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
- > **Support:**
7
- > * KMP
8
- > * Android
9
- > * iOS
10
- > * Flutter - not tested
11
- > * React native - not tested
61
+ ## Requirements
12
62
 
13
- Actions, screenshots, trees, and logs expose [correlated evidence](docs/tools/evidence.md)
14
- with explicit action references, phase timestamps, and conservative freshness.
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
- Android [system traces](docs/tools/system-traces.md) can bracket existing journeys
17
- and return local Perfetto artifacts with explicit correlation metadata.
69
+ ## Agent plugin
18
70
 
19
- Android [runtime debugging](docs/tools/debugger.md) supports explicit process attach,
20
- source breakpoints, bounded stacks/locals, stepping, resume and owned detach.
21
- JDK 17+ is optional and required only for debugger tools.
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
- ## Requirements
75
+ <details>
24
76
 
25
- - Node.js >= 18
26
- - [Android SDK](https://developer.android.com/studio) (adb) for Android support
27
- - Xcode command-line tools for iOS support
28
- - [idb](https://github.com/facebook/idb) for iOS device support
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
- ## Environment Setup
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
- The server discovers Android and iOS tools automatically from standard locations by default. Manual environment setup is still supported, but it should be treated as the fallback for non-standard installs, overrides, or reproducible pinned toolchains.
110
+ </details>
33
111
 
34
- Use explicit paths when:
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
- Leave the variables unset when:
41
- - the tools are already on `PATH`
42
- - the standard Android and Xcode locations are enough
114
+ <summary>Cursor</summary>
43
115
 
44
- Common environment variables:
45
- - `ADB_PATH`: explicit path to `adb`
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
- For normal use, call `get_system_status` first. It reports the detected host, Android, and iOS toolchain state so the client can decide whether automatic discovery is sufficient or whether explicit overrides are needed.
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
- ## MCP Configuration
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","server"],
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","server"],
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
- <details>
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
- <details>
139
-
140
- <summary>Codex plugin</summary>
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
- ```bash
145
- codex plugin marketplace add clivejefferies/mobile-debug-tools
146
- codex plugin add mobile-debug-tools@mobile-debug-tools
147
- ```
148
-
149
- </details>
150
-
151
- <details>
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
- </details>
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
- ## Usage
270
+ ## Environment setup
182
271
 
183
- Crash fixing:
184
- > I have a crash on the app, can you diagnose it, fix and validate using the mcp tools available
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
- Feature building:
187
- > Add a button, hook into the repository and confirm API request successful
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
- For actions that depend on a previously observed UI, use an optional
190
- `expectedState` from `get_ui_tree` on the same explicit device. The server checks
191
- a fresh snapshot immediately before input and returns `PRECONDITION_FAILED`
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
- ## Docs
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
- Use `get_app_readiness` to observe loading, transitioning, settled, or unknown UI
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
- - Tools: [Tools](docs/tools/TOOLS.md) — full input/response examples
204
- - Changelog: [Changelog](docs/CHANGELOG.md)
205
- - Agents: [AGENTS.md](AGENTS.md) — cold-start guidance for autonomous agents entering the public repo
206
- - Skills: [.agents/skills/README.md](.agents/skills/README.md) — portable Markdown skill packages for agents such as Copilot, Codex, Claude, or custom systems
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",
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.34.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",
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",
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.34.0",
17
+ "mobile-debug-mcp@0.36.0",
18
18
  "server"
19
19
  ],
20
20
  "cwd": "${CURSOR_PLUGIN_ROOT}"
@@ -5,7 +5,7 @@
5
5
  "command": "npx",
6
6
  "args": [
7
7
  "--yes",
8
- "mobile-debug-mcp@0.34.0",
8
+ "mobile-debug-mcp@0.36.0",
9
9
  "server"
10
10
  ],
11
11
  "cwd": "${PLUGIN_DATA}"