digital-ai-testing-mcp 1.2.2

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 (333) hide show
  1. package/LICENSE +197 -0
  2. package/README.md +984 -0
  3. package/dist/api/agents.d.ts +5 -0
  4. package/dist/api/agents.d.ts.map +1 -0
  5. package/dist/api/agents.js +33 -0
  6. package/dist/api/agents.js.map +1 -0
  7. package/dist/api/applications.d.ts +35 -0
  8. package/dist/api/applications.d.ts.map +1 -0
  9. package/dist/api/applications.js +162 -0
  10. package/dist/api/applications.js.map +1 -0
  11. package/dist/api/backup.d.ts +4 -0
  12. package/dist/api/backup.d.ts.map +1 -0
  13. package/dist/api/backup.js +13 -0
  14. package/dist/api/backup.js.map +1 -0
  15. package/dist/api/browser-inspection.d.ts +33 -0
  16. package/dist/api/browser-inspection.d.ts.map +1 -0
  17. package/dist/api/browser-inspection.js +273 -0
  18. package/dist/api/browser-inspection.js.map +1 -0
  19. package/dist/api/browsers.d.ts +20 -0
  20. package/dist/api/browsers.d.ts.map +1 -0
  21. package/dist/api/browsers.js +31 -0
  22. package/dist/api/browsers.js.map +1 -0
  23. package/dist/api/client.d.ts +33 -0
  24. package/dist/api/client.d.ts.map +1 -0
  25. package/dist/api/client.js +200 -0
  26. package/dist/api/client.js.map +1 -0
  27. package/dist/api/device-groups.d.ts +15 -0
  28. package/dist/api/device-groups.d.ts.map +1 -0
  29. package/dist/api/device-groups.js +106 -0
  30. package/dist/api/device-groups.js.map +1 -0
  31. package/dist/api/devices.d.ts +32 -0
  32. package/dist/api/devices.d.ts.map +1 -0
  33. package/dist/api/devices.js +192 -0
  34. package/dist/api/devices.js.map +1 -0
  35. package/dist/api/license.d.ts +3 -0
  36. package/dist/api/license.d.ts.map +1 -0
  37. package/dist/api/license.js +11 -0
  38. package/dist/api/license.js.map +1 -0
  39. package/dist/api/nv-servers.d.ts +4 -0
  40. package/dist/api/nv-servers.d.ts.map +1 -0
  41. package/dist/api/nv-servers.js +20 -0
  42. package/dist/api/nv-servers.js.map +1 -0
  43. package/dist/api/projects.d.ts +36 -0
  44. package/dist/api/projects.d.ts.map +1 -0
  45. package/dist/api/projects.js +246 -0
  46. package/dist/api/projects.js.map +1 -0
  47. package/dist/api/provisioning-profiles.d.ts +7 -0
  48. package/dist/api/provisioning-profiles.d.ts.map +1 -0
  49. package/dist/api/provisioning-profiles.js +54 -0
  50. package/dist/api/provisioning-profiles.js.map +1 -0
  51. package/dist/api/regions.d.ts +4 -0
  52. package/dist/api/regions.d.ts.map +1 -0
  53. package/dist/api/regions.js +20 -0
  54. package/dist/api/regions.js.map +1 -0
  55. package/dist/api/reporter-projects.d.ts +3 -0
  56. package/dist/api/reporter-projects.d.ts.map +1 -0
  57. package/dist/api/reporter-projects.js +13 -0
  58. package/dist/api/reporter-projects.js.map +1 -0
  59. package/dist/api/reporting.d.ts +28 -0
  60. package/dist/api/reporting.d.ts.map +1 -0
  61. package/dist/api/reporting.js +340 -0
  62. package/dist/api/reporting.js.map +1 -0
  63. package/dist/api/repository.d.ts +17 -0
  64. package/dist/api/repository.d.ts.map +1 -0
  65. package/dist/api/repository.js +81 -0
  66. package/dist/api/repository.js.map +1 -0
  67. package/dist/api/reservations.d.ts +9 -0
  68. package/dist/api/reservations.d.ts.map +1 -0
  69. package/dist/api/reservations.js +72 -0
  70. package/dist/api/reservations.js.map +1 -0
  71. package/dist/api/sessions.d.ts +3 -0
  72. package/dist/api/sessions.d.ts.map +1 -0
  73. package/dist/api/sessions.js +12 -0
  74. package/dist/api/sessions.js.map +1 -0
  75. package/dist/api/test-views.d.ts +9 -0
  76. package/dist/api/test-views.d.ts.map +1 -0
  77. package/dist/api/test-views.js +77 -0
  78. package/dist/api/test-views.js.map +1 -0
  79. package/dist/api/transactions.d.ts +4 -0
  80. package/dist/api/transactions.d.ts.map +1 -0
  81. package/dist/api/transactions.js +28 -0
  82. package/dist/api/transactions.js.map +1 -0
  83. package/dist/api/usage-reports.d.ts +24 -0
  84. package/dist/api/usage-reports.d.ts.map +1 -0
  85. package/dist/api/usage-reports.js +47 -0
  86. package/dist/api/usage-reports.js.map +1 -0
  87. package/dist/api/users.d.ts +14 -0
  88. package/dist/api/users.d.ts.map +1 -0
  89. package/dist/api/users.js +77 -0
  90. package/dist/api/users.js.map +1 -0
  91. package/dist/api/webdriver.d.ts +97 -0
  92. package/dist/api/webdriver.d.ts.map +1 -0
  93. package/dist/api/webdriver.js +1183 -0
  94. package/dist/api/webdriver.js.map +1 -0
  95. package/dist/index.d.ts +3 -0
  96. package/dist/index.d.ts.map +1 -0
  97. package/dist/index.js +130 -0
  98. package/dist/index.js.map +1 -0
  99. package/dist/tools/agent-tools.d.ts +3 -0
  100. package/dist/tools/agent-tools.d.ts.map +1 -0
  101. package/dist/tools/agent-tools.js +74 -0
  102. package/dist/tools/agent-tools.js.map +1 -0
  103. package/dist/tools/application-tools.d.ts +3 -0
  104. package/dist/tools/application-tools.d.ts.map +1 -0
  105. package/dist/tools/application-tools.js +816 -0
  106. package/dist/tools/application-tools.js.map +1 -0
  107. package/dist/tools/backup-tools.d.ts +3 -0
  108. package/dist/tools/backup-tools.d.ts.map +1 -0
  109. package/dist/tools/backup-tools.js +33 -0
  110. package/dist/tools/backup-tools.js.map +1 -0
  111. package/dist/tools/boilerplate-tools.d.ts +9 -0
  112. package/dist/tools/boilerplate-tools.d.ts.map +1 -0
  113. package/dist/tools/boilerplate-tools.js +1365 -0
  114. package/dist/tools/boilerplate-tools.js.map +1 -0
  115. package/dist/tools/browser-tools.d.ts +3 -0
  116. package/dist/tools/browser-tools.d.ts.map +1 -0
  117. package/dist/tools/browser-tools.js +108 -0
  118. package/dist/tools/browser-tools.js.map +1 -0
  119. package/dist/tools/coverage-tools.d.ts +3 -0
  120. package/dist/tools/coverage-tools.d.ts.map +1 -0
  121. package/dist/tools/coverage-tools.js +148 -0
  122. package/dist/tools/coverage-tools.js.map +1 -0
  123. package/dist/tools/debug-tools.d.ts +3 -0
  124. package/dist/tools/debug-tools.d.ts.map +1 -0
  125. package/dist/tools/debug-tools.js +315 -0
  126. package/dist/tools/debug-tools.js.map +1 -0
  127. package/dist/tools/device-group-tools.d.ts +3 -0
  128. package/dist/tools/device-group-tools.d.ts.map +1 -0
  129. package/dist/tools/device-group-tools.js +284 -0
  130. package/dist/tools/device-group-tools.js.map +1 -0
  131. package/dist/tools/device-tools.d.ts +3 -0
  132. package/dist/tools/device-tools.d.ts.map +1 -0
  133. package/dist/tools/device-tools.js +757 -0
  134. package/dist/tools/device-tools.js.map +1 -0
  135. package/dist/tools/health-tools.d.ts +3 -0
  136. package/dist/tools/health-tools.d.ts.map +1 -0
  137. package/dist/tools/health-tools.js +368 -0
  138. package/dist/tools/health-tools.js.map +1 -0
  139. package/dist/tools/inspection-tools.d.ts +3 -0
  140. package/dist/tools/inspection-tools.d.ts.map +1 -0
  141. package/dist/tools/inspection-tools.js +1170 -0
  142. package/dist/tools/inspection-tools.js.map +1 -0
  143. package/dist/tools/meta-tools.d.ts +4 -0
  144. package/dist/tools/meta-tools.d.ts.map +1 -0
  145. package/dist/tools/meta-tools.js +412 -0
  146. package/dist/tools/meta-tools.js.map +1 -0
  147. package/dist/tools/nv-server-tools.d.ts +3 -0
  148. package/dist/tools/nv-server-tools.d.ts.map +1 -0
  149. package/dist/tools/nv-server-tools.js +67 -0
  150. package/dist/tools/nv-server-tools.js.map +1 -0
  151. package/dist/tools/performance-tools.d.ts +3 -0
  152. package/dist/tools/performance-tools.d.ts.map +1 -0
  153. package/dist/tools/performance-tools.js +295 -0
  154. package/dist/tools/performance-tools.js.map +1 -0
  155. package/dist/tools/project-tools.d.ts +3 -0
  156. package/dist/tools/project-tools.d.ts.map +1 -0
  157. package/dist/tools/project-tools.js +577 -0
  158. package/dist/tools/project-tools.js.map +1 -0
  159. package/dist/tools/prompt-tools.d.ts +3 -0
  160. package/dist/tools/prompt-tools.d.ts.map +1 -0
  161. package/dist/tools/prompt-tools.js +570 -0
  162. package/dist/tools/prompt-tools.js.map +1 -0
  163. package/dist/tools/provisioning-profile-tools.d.ts +3 -0
  164. package/dist/tools/provisioning-profile-tools.d.ts.map +1 -0
  165. package/dist/tools/provisioning-profile-tools.js +169 -0
  166. package/dist/tools/provisioning-profile-tools.js.map +1 -0
  167. package/dist/tools/region-tools.d.ts +3 -0
  168. package/dist/tools/region-tools.d.ts.map +1 -0
  169. package/dist/tools/region-tools.js +46 -0
  170. package/dist/tools/region-tools.js.map +1 -0
  171. package/dist/tools/reporting-tools.d.ts +3 -0
  172. package/dist/tools/reporting-tools.d.ts.map +1 -0
  173. package/dist/tools/reporting-tools.js +1105 -0
  174. package/dist/tools/reporting-tools.js.map +1 -0
  175. package/dist/tools/repository-tools.d.ts +3 -0
  176. package/dist/tools/repository-tools.d.ts.map +1 -0
  177. package/dist/tools/repository-tools.js +208 -0
  178. package/dist/tools/repository-tools.js.map +1 -0
  179. package/dist/tools/reservation-tools.d.ts +3 -0
  180. package/dist/tools/reservation-tools.d.ts.map +1 -0
  181. package/dist/tools/reservation-tools.js +199 -0
  182. package/dist/tools/reservation-tools.js.map +1 -0
  183. package/dist/tools/resources.d.ts +3 -0
  184. package/dist/tools/resources.d.ts.map +1 -0
  185. package/dist/tools/resources.js +91 -0
  186. package/dist/tools/resources.js.map +1 -0
  187. package/dist/tools/test-view-tools.d.ts +3 -0
  188. package/dist/tools/test-view-tools.d.ts.map +1 -0
  189. package/dist/tools/test-view-tools.js +242 -0
  190. package/dist/tools/test-view-tools.js.map +1 -0
  191. package/dist/tools/transaction-tools.d.ts +3 -0
  192. package/dist/tools/transaction-tools.d.ts.map +1 -0
  193. package/dist/tools/transaction-tools.js +391 -0
  194. package/dist/tools/transaction-tools.js.map +1 -0
  195. package/dist/tools/usage-report-tools.d.ts +3 -0
  196. package/dist/tools/usage-report-tools.d.ts.map +1 -0
  197. package/dist/tools/usage-report-tools.js +160 -0
  198. package/dist/tools/usage-report-tools.js.map +1 -0
  199. package/dist/tools/user-tools.d.ts +3 -0
  200. package/dist/tools/user-tools.d.ts.map +1 -0
  201. package/dist/tools/user-tools.js +279 -0
  202. package/dist/tools/user-tools.js.map +1 -0
  203. package/dist/tools/web-inspection-tools.d.ts +3 -0
  204. package/dist/tools/web-inspection-tools.d.ts.map +1 -0
  205. package/dist/tools/web-inspection-tools.js +416 -0
  206. package/dist/tools/web-inspection-tools.js.map +1 -0
  207. package/dist/tools/workflow-tools.d.ts +3 -0
  208. package/dist/tools/workflow-tools.d.ts.map +1 -0
  209. package/dist/tools/workflow-tools.js +1136 -0
  210. package/dist/tools/workflow-tools.js.map +1 -0
  211. package/dist/types/digital-ai.d.ts +691 -0
  212. package/dist/types/digital-ai.d.ts.map +1 -0
  213. package/dist/types/digital-ai.js +3 -0
  214. package/dist/types/digital-ai.js.map +1 -0
  215. package/dist/utils/csv.d.ts +6 -0
  216. package/dist/utils/csv.d.ts.map +1 -0
  217. package/dist/utils/csv.js +77 -0
  218. package/dist/utils/csv.js.map +1 -0
  219. package/dist/utils/destructive-guard.d.ts +2 -0
  220. package/dist/utils/destructive-guard.d.ts.map +1 -0
  221. package/dist/utils/destructive-guard.js +13 -0
  222. package/dist/utils/destructive-guard.js.map +1 -0
  223. package/dist/utils/device-resolver.d.ts +22 -0
  224. package/dist/utils/device-resolver.d.ts.map +1 -0
  225. package/dist/utils/device-resolver.js +69 -0
  226. package/dist/utils/device-resolver.js.map +1 -0
  227. package/dist/utils/download-command.d.ts +18 -0
  228. package/dist/utils/download-command.d.ts.map +1 -0
  229. package/dist/utils/download-command.js +54 -0
  230. package/dist/utils/download-command.js.map +1 -0
  231. package/dist/utils/locality.d.ts +9 -0
  232. package/dist/utils/locality.d.ts.map +1 -0
  233. package/dist/utils/locality.js +22 -0
  234. package/dist/utils/locality.js.map +1 -0
  235. package/dist/utils/output-format.d.ts +13 -0
  236. package/dist/utils/output-format.d.ts.map +1 -0
  237. package/dist/utils/output-format.js +13 -0
  238. package/dist/utils/output-format.js.map +1 -0
  239. package/dist/utils/pagination.d.ts +12 -0
  240. package/dist/utils/pagination.d.ts.map +1 -0
  241. package/dist/utils/pagination.js +24 -0
  242. package/dist/utils/pagination.js.map +1 -0
  243. package/dist/utils/path-guard.d.ts +17 -0
  244. package/dist/utils/path-guard.d.ts.map +1 -0
  245. package/dist/utils/path-guard.js +41 -0
  246. package/dist/utils/path-guard.js.map +1 -0
  247. package/dist/utils/performance-comparison.d.ts +53 -0
  248. package/dist/utils/performance-comparison.d.ts.map +1 -0
  249. package/dist/utils/performance-comparison.js +286 -0
  250. package/dist/utils/performance-comparison.js.map +1 -0
  251. package/dist/utils/performance-stats.d.ts +72 -0
  252. package/dist/utils/performance-stats.d.ts.map +1 -0
  253. package/dist/utils/performance-stats.js +124 -0
  254. package/dist/utils/performance-stats.js.map +1 -0
  255. package/dist/utils/profile-loader.d.ts +37 -0
  256. package/dist/utils/profile-loader.d.ts.map +1 -0
  257. package/dist/utils/profile-loader.js +80 -0
  258. package/dist/utils/profile-loader.js.map +1 -0
  259. package/dist/utils/response-formatter.d.ts +27 -0
  260. package/dist/utils/response-formatter.d.ts.map +1 -0
  261. package/dist/utils/response-formatter.js +493 -0
  262. package/dist/utils/response-formatter.js.map +1 -0
  263. package/dist/utils/timestamp.d.ts +12 -0
  264. package/dist/utils/timestamp.d.ts.map +1 -0
  265. package/dist/utils/timestamp.js +22 -0
  266. package/dist/utils/timestamp.js.map +1 -0
  267. package/dist/utils/tool-registry.d.ts +21 -0
  268. package/dist/utils/tool-registry.d.ts.map +1 -0
  269. package/dist/utils/tool-registry.js +137 -0
  270. package/dist/utils/tool-registry.js.map +1 -0
  271. package/dist/utils/upload-command.d.ts +20 -0
  272. package/dist/utils/upload-command.d.ts.map +1 -0
  273. package/dist/utils/upload-command.js +64 -0
  274. package/dist/utils/upload-command.js.map +1 -0
  275. package/dist/utils/usage-report-guard.d.ts +48 -0
  276. package/dist/utils/usage-report-guard.d.ts.map +1 -0
  277. package/dist/utils/usage-report-guard.js +88 -0
  278. package/dist/utils/usage-report-guard.js.map +1 -0
  279. package/dist/utils/usage-report-summary.d.ts +20 -0
  280. package/dist/utils/usage-report-summary.d.ts.map +1 -0
  281. package/dist/utils/usage-report-summary.js +48 -0
  282. package/dist/utils/usage-report-summary.js.map +1 -0
  283. package/dist/utils/version.d.ts +2 -0
  284. package/dist/utils/version.d.ts.map +1 -0
  285. package/dist/utils/version.js +24 -0
  286. package/dist/utils/version.js.map +1 -0
  287. package/package.json +73 -0
  288. package/resources/boilerplate/Android-Native/Java JUnit5/AndroidNative-oss.java +58 -0
  289. package/resources/boilerplate/Android-Native/Java JUnit5/AndroidNative.java +67 -0
  290. package/resources/boilerplate/Android-Native/Java JUnit5/gradle +10 -0
  291. package/resources/boilerplate/Android-Native/Java JUnit5/gradle-oss +10 -0
  292. package/resources/boilerplate/Android-Native/Java JUnit5/maven +42 -0
  293. package/resources/boilerplate/Android-Native/Java JUnit5/maven-oss +42 -0
  294. package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/AndroidNative.js +30 -0
  295. package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/Shell +19 -0
  296. package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/Shell-oss +19 -0
  297. package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/package-oss.json +12 -0
  298. package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/package.json +12 -0
  299. package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/wdio-oss.conf.js +40 -0
  300. package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/wdio.conf.js +44 -0
  301. package/resources/boilerplate/Android-Native/Python/AndroidNative-oss.py +49 -0
  302. package/resources/boilerplate/Android-Native/Python/AndroidNative.py +69 -0
  303. package/resources/boilerplate/Android-Native/Python/pip +2 -0
  304. package/resources/boilerplate/Android-Native/Python/pip-oss +1 -0
  305. package/resources/boilerplate/Android-Native/java TestNG/AndroidNative-oss.java +58 -0
  306. package/resources/boilerplate/Android-Native/java TestNG/AndroidNative.java +67 -0
  307. package/resources/boilerplate/Android-Native/java TestNG/gradle +13 -0
  308. package/resources/boilerplate/Android-Native/java TestNG/gradle-oss +13 -0
  309. package/resources/boilerplate/Android-Native/java TestNG/maven +42 -0
  310. package/resources/boilerplate/Android-Native/java TestNG/maven-oss +42 -0
  311. package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/Shell-oss.txt +19 -0
  312. package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/Shell.txt +19 -0
  313. package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/iOSNative.js +30 -0
  314. package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/package-oss.json +12 -0
  315. package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/package.json +12 -0
  316. package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/wdio-oss.conf.js +35 -0
  317. package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/wdio.conf.js +39 -0
  318. package/resources/boilerplate/iOS-Native/Python/iOSNative-oss.py +44 -0
  319. package/resources/boilerplate/iOS-Native/Python/iOSNative.py +62 -0
  320. package/resources/boilerplate/iOS-Native/Python/pip-oss.txt +1 -0
  321. package/resources/boilerplate/iOS-Native/Python/pip.txt +2 -0
  322. package/resources/boilerplate/iOS-Native/java-JUnit5/gradle +10 -0
  323. package/resources/boilerplate/iOS-Native/java-JUnit5/gradle-oss +10 -0
  324. package/resources/boilerplate/iOS-Native/java-JUnit5/iOSNative-oss.java +52 -0
  325. package/resources/boilerplate/iOS-Native/java-JUnit5/iOSNative.java +59 -0
  326. package/resources/boilerplate/iOS-Native/java-JUnit5/maven +42 -0
  327. package/resources/boilerplate/iOS-Native/java-JUnit5/maven-oss +42 -0
  328. package/resources/boilerplate/iOS-Native/java-TestNG/gradle +13 -0
  329. package/resources/boilerplate/iOS-Native/java-TestNG/gradle-oss +13 -0
  330. package/resources/boilerplate/iOS-Native/java-TestNG/iOSNative-oss.java +52 -0
  331. package/resources/boilerplate/iOS-Native/java-TestNG/iOSNative.java +59 -0
  332. package/resources/boilerplate/iOS-Native/java-TestNG/maven +42 -0
  333. package/resources/boilerplate/iOS-Native/java-TestNG/maven-oss +42 -0
package/README.md ADDED
@@ -0,0 +1,984 @@
1
+ <picture>
2
+ <source media="(prefers-color-scheme: dark)" srcset=".github/images/dai-logo-dark.svg">
3
+ <source media="(prefers-color-scheme: light)" srcset=".github/images/dai-logo-light.svg">
4
+ <img alt="Digital.ai Testing MCP Server" src=".github/images/dai-logo-light.svg" width="600">
5
+ </picture>
6
+
7
+ # Digital.ai Testing — MCP Server
8
+
9
+ An MCP (Model Context Protocol) server that connects AI assistants to a Digital.ai Testing device farm. The server exposes **191 tools**, **2 resources**, and **6 prompts** covering 26 capability areas: device management, test execution, app lifecycle, reporting, analytics, performance, project administration, interactive mobile inspection, interactive browser inspection, and more.
10
+
11
+ ---
12
+
13
+ ## Quick Start
14
+
15
+ ```bash
16
+ # 1. Pull the image
17
+ docker pull ghcr.io/digitalai-opensource/digital-ai-testing-mcp:latest
18
+
19
+ # 2. Create your .env
20
+ curl -O https://raw.githubusercontent.com/digitalai-opensource/digital-ai-testing-mcp/main/.env.example
21
+ cp .env.example .env # set DIGITAL_AI_BASE_URL and DIGITAL_AI_ACCESS_KEY
22
+ ```
23
+
24
+ Add to your AI client (Claude Desktop shown — see [Connecting AI Clients](#connecting-ai-clients) for VS Code, JetBrains, Copilot, and Cursor):
25
+
26
+ ```json
27
+ {
28
+ "mcpServers": {
29
+ "digital-ai-testing": {
30
+ "command": "docker",
31
+ "args": ["run", "--rm", "-i", "--env-file", "/ABSOLUTE/PATH/TO/.env",
32
+ "ghcr.io/digitalai-opensource/digital-ai-testing-mcp:latest"]
33
+ }
34
+ }
35
+ }
36
+ ```
37
+
38
+ Then ask: *"Show me the overall health of the device farm."*
39
+
40
+ ---
41
+
42
+ ## Table of Contents
43
+
44
+ - [Quick Start](#quick-start)
45
+ - [Prerequisites](#prerequisites)
46
+ - [Access Keys](#access-keys)
47
+ - [Installation](#installation)
48
+ - [Configuration](#configuration)
49
+ - [Connecting AI Clients](#connecting-ai-clients)
50
+ - [Claude Desktop](#claude-desktop)
51
+ - [Claude Code (VS Code)](#claude-code-vs-code)
52
+ - [Claude Code (JetBrains / Android Studio)](#claude-code-jetbrains--android-studio)
53
+ - [GitHub Copilot (VS Code)](#github-copilot-vs-code)
54
+ - [Cursor](#cursor)
55
+ - [Example Prompts](#example-prompts)
56
+ - [Capabilities](#capabilities) — full per-tool reference in [docs/tools.md](docs/tools.md)
57
+ - [Workflow Reference](#workflow-reference)
58
+ - [POC Lifecycle](#poc-lifecycle)
59
+ - [Project Lifecycle](#project-lifecycle)
60
+ - [Boilerplate Generation](#boilerplate-generation)
61
+ - [Recommended agent guardrails](docs/recommended-agent-guardrails.md)
62
+ - [Reference](#reference)
63
+ - [Response Format](#response-format)
64
+ - [Understanding maxResults](#understanding-maxresults)
65
+ - [List Filters & Sorting](#list-filters--sorting)
66
+ - [Test Reporting Schema](#test-reporting-schema)
67
+ - [Safety Guards](#safety-guards)
68
+ - [Development](#development)
69
+ - [Troubleshooting](#troubleshooting)
70
+ - [Known Limitations](#known-limitations)
71
+ - [License](#license)
72
+
73
+ ---
74
+
75
+ ## Prerequisites
76
+
77
+ - **Docker** — required for [Option A/B](#installation) (container-based install)
78
+ - **Node.js 22+** — required for [Option C](#option-c--install-via-npm) (no Docker needed), or if building from source (Option B)
79
+ - **Digital.ai Testing account** with a valid access key
80
+
81
+ ---
82
+
83
+ ## Access Keys
84
+
85
+ Your Digital.ai access key determines what the MCP server can do on your behalf. There are three access levels.
86
+
87
+ | Access level | Key format | Access |
88
+ |---|---|---|
89
+ | **Cloud Admin** | `eyJ…` (long base-64 string) | All tools: device management, user provisioning, project administration, infrastructure, performance data |
90
+ | **Project Admin** | `aut_1_…` | Scoped to one project. Can manage device tags, view project admin settings, list users. v2 API tools (agents, regions, license data) return 403. |
91
+ | **Project User** | `aut_1_…` | Scoped to one project. Read/test operations only. Cannot manage tags, access admin settings, or delete reports. |
92
+
93
+ When a Cloud Admin tool is called with a project-level key, the MCP returns a plain-language error explaining what happened — and, if a Cloud Admin profile is configured, a ready-to-use `switch_environment(...)` command.
94
+
95
+ ### Finding your key
96
+
97
+ 1. Log in to the Digital.ai Testing portal
98
+ 2. Click your **name or avatar** in the top-right corner
99
+ 3. Select **Access Key**
100
+
101
+ The key shown is tied to the **project currently selected in the portal**. If you belong to multiple projects, each has a separate key.
102
+
103
+ ### Using multiple keys
104
+
105
+ Configure named profiles in `.env` to switch contexts at runtime without editing files:
106
+
107
+ ```
108
+ # Default connection (typically Cloud Admin credentials)
109
+ DIGITAL_AI_BASE_URL=https://your-tenant.experitest.com
110
+ DIGITAL_AI_ACCESS_KEY=eyJ...your-cloud-admin-key...
111
+
112
+ # Project-scoped profiles
113
+ DAI_PROFILE_QA_URL=https://your-tenant.experitest.com
114
+ DAI_PROFILE_QA_KEY=aut_1_...your-qa-key...
115
+
116
+ DAI_PROFILE_STAGING_URL=https://your-tenant.experitest.com
117
+ DAI_PROFILE_STAGING_KEY=aut_1_...your-staging-key...
118
+ ```
119
+
120
+ Then ask your AI:
121
+ - *"What environments are configured?"* → `list_environments`
122
+ - *"Switch to QA"* → `switch_environment("qa")`
123
+ - *"Switch back to Cloud Admin"* → `switch_environment("default")`
124
+
125
+ The switch takes effect immediately — no restart needed.
126
+
127
+ > **Security:** Never commit `.env` to source control. Each team member should use their own key obtained from the portal under their own account.
128
+
129
+ ---
130
+
131
+ ## Installation
132
+
133
+ ### Option A — Pull from GitHub Container Registry (Recommended)
134
+
135
+ No cloning or building required. Use this for standard deployment.
136
+
137
+ **Step 1 — Pull the image**
138
+
139
+ ```bash
140
+ docker pull ghcr.io/digitalai-opensource/digital-ai-testing-mcp:latest
141
+ ```
142
+
143
+ **Step 2 — Set up your `.env`**
144
+
145
+ ```bash
146
+ curl -O https://raw.githubusercontent.com/digitalai-opensource/digital-ai-testing-mcp/main/.env.example
147
+ cp .env.example .env
148
+ # Edit .env — set DIGITAL_AI_BASE_URL and DIGITAL_AI_ACCESS_KEY
149
+ ```
150
+
151
+ Use `ghcr.io/digitalai-opensource/digital-ai-testing-mcp:latest` as the image name in your AI client configuration below.
152
+
153
+ > Images are published when a GitHub Release is created — not on every commit. If `latest` is not available yet, use [Option B](#option-b--build-from-source) to build from source.
154
+
155
+ > To update: `docker pull ghcr.io/digitalai-opensource/digital-ai-testing-mcp:latest`
156
+
157
+ ---
158
+
159
+ ### Option B — Build from source
160
+
161
+ Required only for local development or modifying the server.
162
+
163
+ ```bash
164
+ git clone https://github.com/digitalai-opensource/digital-ai-testing-mcp
165
+ cd digital-ai-testing-mcp
166
+ cp .env.example .env
167
+ # Edit .env — set DIGITAL_AI_BASE_URL and DIGITAL_AI_ACCESS_KEY
168
+ docker build -t digital-ai-testing-mcp:latest .
169
+ ```
170
+
171
+ Use `digital-ai-testing-mcp:latest` as the image name in your AI client configuration below.
172
+
173
+ > Rebuild after making changes: `docker build -t digital-ai-testing-mcp:latest .`
174
+
175
+ ---
176
+
177
+ ### Option C — Install via npm
178
+
179
+ No Docker required — runs directly under Node.js. Use this if Docker Desktop isn't available (e.g. locked-down or Docker-unable machines).
180
+
181
+ ```bash
182
+ npm install -g digital-ai-testing-mcp
183
+ ```
184
+
185
+ This installs a `digital-ai-testing-mcp` command onto your `PATH`. Use it directly as the `"command"` in your AI client configuration below (see the "**No Docker? Using the npm package**" callout under each client) — no image name or `.env` file path needed; environment variables go directly in the client's `env` block instead (see [Configuration](#configuration)).
186
+
187
+ > To update: `npm install -g digital-ai-testing-mcp` again (npm updates in place).
188
+
189
+ > This package is currently published and maintained under an individual maintainer's npm account rather than an organization account. Functionally identical to Options A/B; flagging for transparency.
190
+
191
+ ---
192
+
193
+ ## Configuration
194
+
195
+ | Variable | Required | Default | Description |
196
+ |---|---|---|---|
197
+ | `DIGITAL_AI_BASE_URL` | ✅ | — | Your Digital.ai tenant URL |
198
+ | `DIGITAL_AI_ACCESS_KEY` | ✅ | — | Access key — see [Access Keys](#access-keys) for the three access levels and key formats |
199
+ | `MCP_SERVER_NAME` | Optional | `digital-ai-testing-mcp` | Server identity shown in the AI client |
200
+ | `MCP_SERVER_VERSION` | Optional | version from `package.json` | Override the reported server version (rarely needed) |
201
+ | `REQUEST_TIMEOUT_MS` | Optional | `30000` | API request timeout in milliseconds |
202
+ | `UPLOAD_TIMEOUT_MS` | Optional | `120000` | File upload timeout in milliseconds |
203
+
204
+ Additional `DAI_PROFILE_{NAME}_URL` / `DAI_PROFILE_{NAME}_KEY` pairs configure named profiles for multi-project or multi-environment use. See [Access Keys](#access-keys) and `.env.example` for examples.
205
+
206
+ ---
207
+
208
+ ## Connecting AI Clients
209
+
210
+ The examples below default to launching the server as a Docker container (using the GHCR image name from Option A — if you built from source with Option B, replace the image name with `digital-ai-testing-mcp:latest`; replace `/ABSOLUTE/PATH/TO/.env` with the full path to your `.env` file in all cases). Each client section also includes a **no-Docker config** for the [npm package](#option-c--install-via-npm) (Option C) — use whichever matches how you installed the server.
211
+
212
+ ### Claude Desktop
213
+
214
+ Find your config file:
215
+ - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
216
+ - **Windows:** Open Claude Desktop → Settings → Developer → **Edit Config** (the path varies by install method — Windows Store vs. direct installer)
217
+
218
+ ```json
219
+ {
220
+ "mcpServers": {
221
+ "digital-ai-testing": {
222
+ "command": "docker",
223
+ "args": [
224
+ "run", "--rm", "-i",
225
+ "--env-file", "/ABSOLUTE/PATH/TO/.env",
226
+ "ghcr.io/digitalai-opensource/digital-ai-testing-mcp:latest"
227
+ ]
228
+ }
229
+ }
230
+ }
231
+ ```
232
+
233
+ > **Built from source?** Replace `ghcr.io/digitalai-opensource/digital-ai-testing-mcp:latest` with `digital-ai-testing-mcp:latest`.
234
+
235
+ > **No Docker? Using the npm package (Option C):**
236
+ > ```json
237
+ > {
238
+ > "mcpServers": {
239
+ > "digital-ai-testing": {
240
+ > "command": "digital-ai-testing-mcp",
241
+ > "args": [],
242
+ > "env": {
243
+ > "DIGITAL_AI_BASE_URL": "https://your-tenant.experitest.com",
244
+ > "DIGITAL_AI_ACCESS_KEY": "your-access-key"
245
+ > }
246
+ > }
247
+ > }
248
+ > }
249
+ > ```
250
+
251
+ Restart Claude Desktop after editing — the tools appear automatically.
252
+
253
+ ### Claude Code (VS Code)
254
+
255
+ 1. Open the Claude Code extension panel
256
+ 2. Go to **Settings → MCP Servers**
257
+ 3. Add a new server with the Docker command above, or — if using the npm package (Option C) — command `digital-ai-testing-mcp` with no args, and `DIGITAL_AI_BASE_URL`/`DIGITAL_AI_ACCESS_KEY` set in the server's environment variables
258
+
259
+ ### Claude Code (JetBrains / Android Studio)
260
+
261
+ Install the [Claude Code](https://plugins.jetbrains.com/plugin/22828-claude-code) plugin from the JetBrains Marketplace, then open your project and run this command from the project root:
262
+
263
+ ```bash
264
+ # macOS / Linux
265
+ claude mcp add digital-ai-testing -- docker run --rm -i --env-file /absolute/path/to/.env ghcr.io/digitalai-opensource/digital-ai-testing-mcp:latest
266
+
267
+ # Windows (use forward slashes — backslashes are stripped by Claude Code)
268
+ claude mcp add digital-ai-testing -- docker run --rm -i --env-file C:/projects/digital-ai-testing-mcp/.env ghcr.io/digitalai-opensource/digital-ai-testing-mcp:latest
269
+ ```
270
+
271
+ > **Windows users:** Always use forward slashes (`C:/path/to/.env`), never backslashes — regardless of whether you register via the CLI command above or through the Claude Code panel (**Settings → MCP Servers**). Backslashes are silently stripped when Claude Code writes the configuration to `~/.claude.json`, resulting in a broken path and a cryptic `-32000` reconnection error.
272
+
273
+ This stores the server configuration in `~/.claude.json` scoped to the current project. Alternatively, use the Claude Code panel: **Settings → MCP Servers** and add the same Docker command used for Claude Desktop (using forward slashes for the path on Windows).
274
+
275
+ > **Built from source?** Replace the GHCR image name with `digital-ai-testing-mcp:latest`.
276
+
277
+ > **No Docker? Using the npm package (Option C):**
278
+ > ```bash
279
+ > claude mcp add digital-ai-testing --env DIGITAL_AI_BASE_URL=https://your-tenant.experitest.com --env DIGITAL_AI_ACCESS_KEY=your-access-key -- digital-ai-testing-mcp
280
+ > ```
281
+
282
+ Restart the Claude Code panel after adding the server — the tools appear automatically.
283
+
284
+ ### GitHub Copilot (VS Code)
285
+
286
+ GitHub Copilot supports MCP tools in **Agent mode** only. Register the server in one of two scopes:
287
+
288
+ **User settings** — available in all workspaces. Open `settings.json` (`Ctrl+Shift+P` → "Preferences: Open User Settings (JSON)"):
289
+
290
+ ```json
291
+ {
292
+ "mcp": {
293
+ "servers": {
294
+ "digital-ai-testing": {
295
+ "command": "docker",
296
+ "args": [
297
+ "run", "--rm", "-i",
298
+ "--env-file", "/ABSOLUTE/PATH/TO/.env",
299
+ "ghcr.io/digitalai-opensource/digital-ai-testing-mcp:latest"
300
+ ]
301
+ }
302
+ }
303
+ }
304
+ }
305
+ ```
306
+
307
+ **Workspace settings** — scoped to one project. Create `.vscode/mcp.json`:
308
+
309
+ ```json
310
+ {
311
+ "servers": {
312
+ "digital-ai-testing": {
313
+ "command": "docker",
314
+ "args": [
315
+ "run", "--rm", "-i",
316
+ "--env-file", "/ABSOLUTE/PATH/TO/.env",
317
+ "ghcr.io/digitalai-opensource/digital-ai-testing-mcp:latest"
318
+ ]
319
+ }
320
+ }
321
+ }
322
+ ```
323
+
324
+ Committing `.vscode/mcp.json` to source control shares the server configuration with the entire team automatically.
325
+
326
+ > **No Docker? Using the npm package (Option C):** in either settings file above, replace the `"digital-ai-testing"` entry's `command`/`args` with:
327
+ > ```json
328
+ > {
329
+ > "command": "digital-ai-testing-mcp",
330
+ > "args": [],
331
+ > "env": {
332
+ > "DIGITAL_AI_BASE_URL": "https://your-tenant.experitest.com",
333
+ > "DIGITAL_AI_ACCESS_KEY": "your-access-key"
334
+ > }
335
+ > }
336
+ > ```
337
+
338
+ To use the tools: open Copilot Chat (`Ctrl+Alt+I`), switch the mode dropdown to **Agent**, and type your request.
339
+
340
+ > GitHub Copilot on the web (`github.com/copilot`) does not support external MCP servers. VS Code is required.
341
+
342
+ ### Cursor
343
+
344
+ Cursor supports MCP in **Agent mode**. Add the server in **Cursor Settings → MCP** (or `Cursor Settings → Features → MCP`) using the same Docker command:
345
+
346
+ ```json
347
+ {
348
+ "mcpServers": {
349
+ "digital-ai-testing": {
350
+ "command": "docker",
351
+ "args": [
352
+ "run", "--rm", "-i",
353
+ "--env-file", "/ABSOLUTE/PATH/TO/.env",
354
+ "ghcr.io/digitalai-opensource/digital-ai-testing-mcp:latest"
355
+ ]
356
+ }
357
+ }
358
+ }
359
+ ```
360
+
361
+ Alternatively, create a `.cursor/mcp.json` file in your project root with the same `mcpServers` object — this scopes the server to that workspace and can be committed to share it with your team.
362
+
363
+ > **Built from source?** Replace the GHCR image name with `digital-ai-testing-mcp:latest`.
364
+
365
+ > **No Docker? Using the npm package (Option C):**
366
+ > ```json
367
+ > {
368
+ > "mcpServers": {
369
+ > "digital-ai-testing": {
370
+ > "command": "digital-ai-testing-mcp",
371
+ > "args": [],
372
+ > "env": {
373
+ > "DIGITAL_AI_BASE_URL": "https://your-tenant.experitest.com",
374
+ > "DIGITAL_AI_ACCESS_KEY": "your-access-key"
375
+ > }
376
+ > }
377
+ > }
378
+ > }
379
+ > ```
380
+
381
+ > Cursor is available on macOS, Windows, and Linux. It is the recommended option for iOS developers on macOS where Xcode is the primary IDE but does not natively support MCP.
382
+
383
+ ---
384
+
385
+ ## Example Prompts
386
+
387
+ Once connected, talk to the server in plain language — no tool names needed:
388
+
389
+ - *"Show me the overall health of the device farm — how many devices are available, reserved, and offline?"*
390
+ - *"Find an available Android phone running at least version 13 in the US2 region"*
391
+ - *"Did all tests in the QA project pass today? I need a go/no-go for the release."*
392
+ - *"Install the latest build of com.mycompany.app on all available Android devices"*
393
+ - *"Find an available Android phone, then generate a Java JUnit5 test boilerplate"*
394
+ - *"Show the pass/fail breakdown by OS — are Android and iOS failing at different rates?"*
395
+ - *"Did the latest release introduce a CPU regression? Compare version 10553 vs 10554 on Android."*
396
+ - *"Set up a new POC for Acme Corp — 6 devices in US2, 3 iOS and 3 Android, through August 31st"*
397
+
398
+ **[→ docs/examples.md](docs/examples.md)** has 200+ prompts organized by scenario: farm health, device groups, regression sign-off, test analytics, performance, usage reports, interactive inspection, POC lifecycle, and more.
399
+
400
+ ---
401
+
402
+ ## Capabilities
403
+
404
+ 191 tools across 26 capability domains. The complete per-tool reference — descriptions, filters, auth requirements, and usage notes — lives in **[docs/tools.md](docs/tools.md)**.
405
+
406
+ | Domain | Tools | Highlights |
407
+ |---|---|---|
408
+ | [Devices](docs/tools.md#devices) | 19 | List/query devices, find available, release, reboot, tags, Mobile Studio |
409
+ | [Device Groups](docs/tools.md#device-groups) | 9 | Create groups, move devices, control project access |
410
+ | [Reservations](docs/tools.md#reservations) | 5 | Reserve devices, check availability windows |
411
+ | [Applications](docs/tools.md#applications) | 15 | Upload, generate local upload/download commands, install/uninstall, find the latest build |
412
+ | [Repository](docs/tools.md#repository) | 8 | Test-data file storage |
413
+ | [Browsers](docs/tools.md#browsers) | 3 | Selenium browser session management |
414
+ | [Users](docs/tools.md#users) | 8 | Account provisioning, project assignment, tags |
415
+ | [Projects](docs/tools.md#projects) | 17 | Create/configure projects, settings, app assignment |
416
+ | [Provisioning Profiles](docs/tools.md#provisioning-profiles) | 7 | iOS signing profile lifecycle |
417
+ | [Backup](docs/tools.md#backup) | 1 | Trigger a system backup |
418
+ | [Health & Diagnostics](docs/tools.md#health--diagnostics) | 11 | Farm health, readiness checks, license utilization |
419
+ | [Coverage Analytics](docs/tools.md#coverage-analytics) | 2 | Tested-vs-available device gap analysis |
420
+ | [Reporting](docs/tools.md#reporting) | 20 | Search/filter test reports, failure summarization, stability, trends, logs, attachment download command, cleanup |
421
+ | [Test Views](docs/tools.md#test-views) | 7 | Dashboard view groups |
422
+ | [Transactions & Performance](docs/tools.md#transactions--performance) | 4 | CPU/memory/battery/Speed Index analytics *(Cloud Admin)* |
423
+ | [Agents](docs/tools.md#agents) | 2 | Host machine status *(Cloud Admin)* |
424
+ | [Regions](docs/tools.md#regions) | 2 | Region status and infrastructure topology *(Cloud Admin)* |
425
+ | [NV Servers](docs/tools.md#nv-servers) | 2 | Network Virtualization servers *(Cloud Admin)* |
426
+ | [Environment Management](docs/tools.md#environment-management) | 2 | Named connection profiles, runtime switching |
427
+ | [Workflows](docs/tools.md#workflows) | 6 | POC and project lifecycle orchestration |
428
+ | [Boilerplate Generation](docs/tools.md#boilerplate-generation) | 3 | Ready-to-run Appium and Selenium test scripts in 4 languages; validate scripts before delivery |
429
+ | [Remote Debug](docs/tools.md#remote-debug) | 1 | Connect a cloud device as a local ADB device |
430
+ | [Mobile Inspection Sessions](docs/tools.md#mobile-inspection-sessions) | 22 | AI-driven live device interaction — screenshots, element discovery, full gesture set, keys, app/device control |
431
+ | [Web Inspection Sessions](docs/tools.md#web-inspection-sessions) | 8 | AI-driven live browser interaction — navigate, Shadow DOM element discovery, CSS selector verification, browser-neutral Selenium script generation |
432
+ | [Performance Comparison](docs/tools.md#performance-comparison) | 4 | Two-set Speed Index comparison with confound detection, MAD outlier exclusion, and fresh-sample generation *(Cloud Admin)* |
433
+ | [Usage Reports](docs/tools.md#usage-reports) | 3 | Platform usage-report CSV export and in-memory aggregation — device reservations, users/devices/browser usage, license usage *(Cloud Admin)* |
434
+ | [Resources & Prompts](docs/tools.md#resources--prompts) | — | 2 ambient resources, 6 guided prompts |
435
+
436
+ ---
437
+
438
+ ## Workflow Reference
439
+
440
+ ### POC Lifecycle
441
+
442
+ Three tools cover the full POC lifecycle. All derive the project name (`"<Customer> POC"`) and device tag (`"<customername>poc"`) from `customerName` — pass the same value consistently across all three tools.
443
+
444
+ #### `create_poc` — Onboard a new POC environment
445
+
446
+ Collects all parameters upfront, presents a confirmation summary to the operator, then executes 10 sequential steps:
447
+
448
+ 1. Create (or reuse) a device group named `<Customer> POC`
449
+ 2. Locate the Default device group
450
+ 3. Select available phones from the Default group — region-matched, conflict-tag-free, phones only (tablets excluded). Presents the selection to the operator for confirmation before proceeding.
451
+ 4. Add selected devices to the POC group
452
+ 5. Tag each device with the derived POC tag (e.g. `acmecorppoc`)
453
+ 6. Create (or reuse) a project; record the Salesforce URL and end date in project notes
454
+ 7. Remove devices from the Default group — done only after the project exists, so a project-creation failure never strands devices
455
+ 8. Locate the Default project
456
+ 9. Create users, assign to the POC project, remove from Default, and tag each account with the POC tag. Cloud Admin access is never granted through this workflow.
457
+ 10. Assign ExperiBank (or a specified app) to the POC project — falls back to the latest available version if the exact version is not found
458
+
459
+ If any step fails, the workflow stops, reports which steps completed with all created resource IDs, and offers resume (re-invoke — existing resources are detected and reused) or unwind (`delete_poc`) paths.
460
+
461
+ **Required parameters:**
462
+
463
+ | Parameter | Description |
464
+ |---|---|
465
+ | `customerName` | e.g. `"Acme Corp"` → derives project `"Acme Corp POC"` and tag `"acmecorppoc"` |
466
+ | `region` | Testing region, e.g. `"US2"`, `"EU"`, `"SG"` |
467
+ | `salesforceUrl` | Salesforce Opportunity URL — recorded in project notes |
468
+ | `endDate` | Accepts ISO (`"2026-08-31"`), relative offsets (`"+14d"`, `"+2w"`), or natural language (`"in 2 weeks"`) |
469
+ | `users` | Array of `{email, firstName, lastName, role}` — role must be `"User"` or `"ProjectAdmin"` |
470
+
471
+ **Optional parameters:**
472
+
473
+ | Parameter | Default |
474
+ |---|---|
475
+ | `deviceCount` | `6` |
476
+ | `iosCount` | `ceil(deviceCount / 2)` |
477
+ | `androidCount` | `floor(deviceCount / 2)` |
478
+ | `automationType` | `"appium-server"` (alternative: `"appium-grid"`) |
479
+ | `appName` | `"ExperiBank"` |
480
+ | `appVersion` | `"1.0"` |
481
+
482
+ Steps 1 and 6 check for an existing group/project by name before creating — safe to re-run after a partial failure.
483
+
484
+ ---
485
+
486
+ #### `close_poc` — Wind down without deleting
487
+
488
+ Reverses the device and user changes from `create_poc` while leaving the project and device group intact:
489
+
490
+ 1. Locate the POC project and device group by derived name
491
+ 2. List devices in the POC group
492
+ 3. Remove the POC tag from each device (all other tags are preserved)
493
+ 4. Move devices out of the POC group and back into the Default group
494
+ 5. Process users by POC tag: **delete accounts that have no other project memberships; revoke POC access only for users who also belong to other projects**
495
+
496
+ Only `customerName` is required.
497
+
498
+ > The Digital.ai REST API does not expose a user lock or disable endpoint. Deleting the account via `delete_user` is the only API-available way to remove access for users provisioned solely for the POC.
499
+
500
+ ---
501
+
502
+ #### `delete_poc` — Full teardown
503
+
504
+ Performs the same wind-down as `close_poc`, then permanently deletes the device group and the project. Requires `confirmDeletion: true`.
505
+
506
+ Before any destructive action, the workflow gathers a full inventory (project ID, group ID, device list, user breakdown) and presents it for explicit confirmation. Unlike `close_poc`, user processing is batch-confirmed via this upfront inventory rather than per-user prompts.
507
+
508
+ **Best practice:** Run `close_poc` first — it winds down the POC while preserving the project and device group. Note that `close_poc` is not fully reversible: device moves and tag removal can be undone, but it permanently deletes POC-only user accounts (each deletion requires per-user operator confirmation). Use `delete_poc` only once the project data is confirmed no longer needed. Calling `delete_poc` without `confirmDeletion: true` returns a safe explanation and suggests `close_poc` as the alternative.
509
+
510
+ ---
511
+
512
+ ### Project Lifecycle
513
+
514
+ Three tools mirror the POC lifecycle for general project management. They apply the same multi-project user protection rules: users who belong to other projects are revoked from this project only, never deleted from the platform.
515
+
516
+ #### `setup_project` — Provision a new project environment
517
+
518
+ At the start, the workflow asks whether to create a **simple** project record only, or a **full** environment (device group, device allocation, user provisioning, app assignment).
519
+
520
+ Full setup steps:
521
+
522
+ 1. Create (or reuse) the project with the specified name and automation type; record the memo in project notes
523
+ 2. Create (or reuse) a device group and link it to the project
524
+ 3. Pre-flight check that the target app exists in the repository
525
+ 4. Select available devices matching the target OS and region — presented to the operator for confirmation
526
+ 5. Add the selected devices to the project group
527
+ 6. Tag each device with a project-derived tag
528
+ 7. Remove devices from other groups — only when `isolateDevices: true`; by default existing group links (including Default) are kept intact
529
+ 8. Create users, assign them to the project with the specified roles, remove them from Default, and tag each account
530
+ 9. Assign the specified application to the project
531
+
532
+ **Required parameters:**
533
+
534
+ | Parameter | Description |
535
+ |---|---|
536
+ | `projectName` | The name for the new project |
537
+ | `region` | Target region for device selection |
538
+
539
+ **Optional parameters:**
540
+
541
+ | Parameter | Default | Description |
542
+ |---|---|---|
543
+ | `deviceCount` | `6` | Total devices to allocate |
544
+ | `iosCount` | `ceil(deviceCount / 2)` | iOS device count |
545
+ | `androidCount` | `floor(deviceCount / 2)` | Android device count |
546
+ | `automationType` | `"appium-server"` | `"appium-server"` or `"appium-grid"` |
547
+ | `isolateDevices` | `false` | Remove devices from all other groups before assignment |
548
+ | `users` | `[]` | Array of `{email, firstName, lastName, role}` |
549
+ | `appName` | _(none)_ | App to assign to the project |
550
+ | `memo` | _(none)_ | Notes to record on the project |
551
+
552
+ ---
553
+
554
+ #### `close_project_resources` — Release resources without deleting
555
+
556
+ Wind down the project environment while leaving the project record intact:
557
+
558
+ 1. Locate the project and its associated device group
559
+ 2. List the devices in the project group
560
+ 3. Remove the project-derived tag from each device
561
+ 4. Return devices to the Default group
562
+ 5. Process users: **delete accounts with no other project memberships; revoke project access only for multi-project users** (each action individually confirmed by the operator)
563
+
564
+ Only `projectName` is required. Active sessions and installed apps on the devices are not touched — release sessions with `release_orphaned_sessions` and remove apps with `uninstall_application` separately if needed.
565
+
566
+ ---
567
+
568
+ #### `teardown_project` — Full project deletion
569
+
570
+ Performs all `close_project_resources` steps, then permanently deletes the device group and the project. Requires `confirmDeletion: true`.
571
+
572
+ The workflow presents a full inventory summary before any irreversible action. The same multi-project user protection applies.
573
+
574
+ **Best practice:** Run `close_project_resources` first, then confirm the project is no longer needed before calling `teardown_project`.
575
+
576
+ ---
577
+
578
+ ## Boilerplate Generation
579
+
580
+ ### Two ways to create a test
581
+
582
+ The server supports two test-creation modes for both mobile and web, and the agent is instructed to route between them based on context:
583
+
584
+ | | **Autonomous** (`get_test_boilerplate` / `get_web_test_boilerplate`) | **Interactive** (`start_inspection_session` / `start_browser_inspection_session` / `collaborative_test_creation` / `collaborative_web_test_creation` prompt) |
585
+ |---|---|---|
586
+ | **When** | Intent is specific — a standardized flow ("create a login test") or step-level detail — AND selectors are derivable (app source in the workspace, or a prior inspection session) | Request is vague ("I want a test for app X"), no source access (chat-only, or IDE without this app's code), or the user wants to watch/drive on a live device or browser |
587
+ | **User involvement** | None required — the agent writes the test from boilerplate + source knowledge + best practices | Collaborative — the agent builds the test step by step with the user (browser sessions relay screenshots; mobile sessions share a live device view URL) |
588
+ | **Output** | In an IDE: a local test automation project. Chat-only: portable project files presented inline | Same, plus selectors verified against the real app or page along the way |
589
+
590
+ **Hybrid is often best:** even in autonomous mode, the agent can open a short inspection session — no user involvement — to capture or verify element IDs or CSS selectors against the real build. The agent is explicitly instructed to **never fabricate selectors** — when in doubt it verifies live, and when the mode itself is ambiguous it asks.
591
+
592
+ > **Stronger guarantees:** the server ships this routing policy automatically in its MCP `instructions`, and both boilerplate tools structurally refuse to emit code for a real app or URL without verified selectors. Because not every client surfaces server `instructions` — and no MCP server can intercept a file an agent writes by hand — you can install a client-side reinforcement for a stronger, client-independent guarantee. See **[Recommended agent guardrails](docs/recommended-agent-guardrails.md)**.
593
+
594
+ ### `get_test_boilerplate`
595
+
596
+ Generates a complete, pre-configured Appium test script. The Digital.ai server URL and access key are pre-filled from the active connection profile — switch profiles with `switch_environment` first to generate scripts carrying a project-scoped key instead of your admin key.
597
+
598
+ | Parameter | Values | Default |
599
+ |---|---|---|
600
+ | `platform` | `android` \| `ios` | _(required)_ |
601
+ | `language` | `java-junit5` \| `java-testng` \| `nodejs` \| `python` | _(required)_ |
602
+ | `appId` | Numeric app ID from `list_applications` | Recommended |
603
+ | `deviceCategory` | `PHONE` \| `TABLET` | `PHONE` |
604
+ | `testName` | Any string | `"My First Mobile Test"` |
605
+ | `packageName` | Android package name (e.g. `com.mycompany.app`) | _(optional)_ |
606
+ | `mainActivity` | Android main activity (e.g. `.MainActivity`) | _(optional)_ |
607
+ | `bundleIdentifier` | iOS bundle ID (e.g. `com.mycompany.app`) | _(optional)_ |
608
+ | `region` | Region code from `find_available_device` response (e.g. `US2`, `SG1`) | _(optional, strongly recommended)_ |
609
+ | `projectType` | `standalone-gradle` \| `standalone-maven` \| `android-gradle-submodule` | `standalone-gradle` |
610
+ | `includePerformanceTransactions` | `true` \| `false` | `false` |
611
+ | `includeAxeScan` | `true` \| `false` | `false` |
612
+ | `confirmSelectorsVerified` | `true` \| `false` | _(optional)_ |
613
+ | `outputFormat` | `json` \| `human` | `json` |
614
+
615
+ > **Inspection gate (v42):** when you target a real app (`appId`/`packageName`/`bundleIdentifier`), this tool returns **no code** and a structured `{ status: "blocked", reason: "no_verified_selectors" }` error UNLESS a live inspection session exists in the MCP process, or you set `confirmSelectorsVerified: true` (escape hatch for selectors already captured via rdb/UIAutomator, `open_mobile_studio`, or authoritative source). The built-in ExperiBank demo (no app identifiers) is never gated. This makes it structurally impossible to receive a placeholder scaffold and pass it off as a finished test.
616
+
617
+ **Recommended workflow** for building a new test:
618
+
619
+ 1. `get_application_info` — confirm package name, launch activity, and app ID
620
+ 2. `get_test_boilerplate` — generate starter test with capabilities pre-filled (this step)
621
+ 3. `open_mobile_studio` or `get_automation_properties` — inspect live element IDs (no ADB required)
622
+ 4. `release_orphaned_sessions(maxAgeHours=4, dryRun=true)` — pre-flight device check
623
+ 5. `find_available_device` — select a healthy device and read its `region`
624
+ 6. Write/run the test
625
+ 7. `release_device` — explicit cleanup
626
+
627
+ **Performance transactions:** Pass `includePerformanceTransactions: true` to bracket the test body with `startPerformanceTransaction` / `endPerformanceTransaction` calls. The start arg is the NV network profile (defaults to `"Monitor"` — observe without throttling); the end arg is the transaction name. The platform records CPU, memory, battery, and Speed Index metrics; results appear in the reporter Transactions tab (~1 min after `endPerformanceTransaction`) and are queryable via `list_transactions`. Pre-requisite: an NV server must be ONLINE and tunnel-connected in the device region (`list_nv_servers`). Note: a throttling profile activates NV shaping immediately; `"Monitor"` is pass-through and carries no ANR risk.
628
+
629
+ **Accessibility scanning:** Pass `includeAxeScan: true` to inject a Deque Axe DevTools Mobile accessibility scan (`mobile: axeScan` executeScript call). Sets the required `appium:automationName` capability automatically (`AxeUiAutomator2` for Android, `AxeXCUITest` for iOS). Requires `AXE_DEVTOOLS_API_KEY` in the MCP environment.
630
+
631
+ Both flags can be combined — the Axe scan runs inside the performance transaction boundary.
632
+
633
+ **Element locators:** Use `open_mobile_studio` first — it is the platform's native UI Inspector and requires no local tooling. For scenarios requiring direct ADB access (file push, shell commands), use `get_remote_debug_command` to connect the device locally.
634
+
635
+ > ⚠️ The generated script is an **end-product artifact** — do not execute it as a discovery step. Running it without known element selectors creates Incomplete sessions visible to the whole team. Discover selectors with `open_mobile_studio` first.
636
+
637
+ ### `validate_test_script`
638
+
639
+ Delivery backstop (v43) for the case the `get_test_boilerplate` gate cannot catch — a test written by hand with guessed selectors. Pass the full `scriptContent` before presenting or saving any test; it scans for unreplaced `<…>` placeholder selectors, the deliberate scaffold fail-guard, placeholder/fabricated credentials, and resource IDs from a known prior fabrication incident. Returns `isError` with a `fail` verdict when any high-severity pattern is found, so a non-functional test cannot be delivered as finished. A `pass` is necessary but not sufficient — it confirms obvious placeholders are gone, not that selectors are real; a live inspection remains the authoritative source.
640
+
641
+ | Parameter | Values | Default |
642
+ |---|---|---|
643
+ | `scriptContent` | The full test script text | _(required)_ |
644
+ | `fileName` | Label for the result | _(optional)_ |
645
+ | `outputFormat` | `json` \| `human` | `json` |
646
+
647
+ `projectType` controls the Java output layout only (ignored for Node.js and Python): `standalone-gradle` produces `src/test/java/` with both `build.gradle` and `pom.xml`; `standalone-maven` produces `pom.xml` only; `android-gradle-submodule` scopes files under `e2e-tests/` for embedding in an existing Android Studio project.
648
+
649
+ **Files generated per language:**
650
+
651
+ | Language | Files |
652
+ |---|---|
653
+ | `java-junit5` / `java-testng` | `AndroidNative.java` or `iOSNative.java` + `build.gradle` + `pom.xml` |
654
+ | `nodejs` | `wdio.conf.js` + test file + setup shell steps |
655
+ | `python` | Test file + `requirements.txt` |
656
+
657
+ All boilerplate defaults to the ExperiBank demo app as the starting point. ExperiBank is available on most farm devices and can verify connectivity before switching to your own app.
658
+
659
+ ### `get_web_test_boilerplate`
660
+
661
+ Generates a complete, pre-configured Selenium test script for browser testing. The Digital.ai server URL and access key are pre-filled from the active connection profile.
662
+
663
+ | Parameter | Values | Default |
664
+ |---|---|---|
665
+ | `language` | `java-junit5` \| `java-testng` \| `nodejs` \| `python` | _(required)_ |
666
+ | `url` | URL of the page being tested | _(optional)_ |
667
+ | `testName` | Any string | `"My First Web Test"` |
668
+ | `targetBrowser` | `chrome` \| `firefox` \| `edge` \| `safari` | _(optional)_ |
669
+ | `shadowDomSupport` | `auto` \| `always` \| `never` | `auto` |
670
+ | `confirmSelectorsVerified` | `true` \| `false` | _(optional)_ |
671
+ | `outputFormat` | `json` \| `human` | `json` |
672
+
673
+ > **Inspection gate:** when you target a real URL (`url` provided), this tool returns **no code** and a structured `{ status: "blocked", reason: "no_verified_selectors" }` error UNLESS a live browser inspection session exists in the MCP process, or you set `confirmSelectorsVerified: true` (escape hatch for selectors captured via a prior `start_browser_inspection_session` session). This mirrors the mobile boilerplate gate.
674
+
675
+ **Browser-neutral by default:** when `targetBrowser` is omitted, the generated script reads the browser name at runtime from an environment variable (`BROWSER`). This means the same script runs on Chrome, Firefox, Edge, and Safari without modification — just change the env var or CI matrix. Specify `targetBrowser` only when you need browser-specific options (e.g. Safari-only session setup).
676
+
677
+ **Shadow DOM support:** when `shadowDomSupport` is `auto` (the default) or `always`, the generated script includes a `shadowQuery(host, cssSelector)` helper that traverses into shadow roots using `executeScript`. Use this for apps built with Web Components, Lit, Polymer, or other shadow-DOM frameworks. `get_page_dom` detects shadow DOM automatically during inspection and reports `hasShadowDom: true` when present.
678
+
679
+ **Recommended workflow for building a new web test:**
680
+
681
+ 1. `list_available_browsers` — confirm which browsers and OS combinations are available in your region
682
+ 2. `start_browser_inspection_session` — open a live browser session on the target URL
683
+ 3. `get_page_dom` — extract the rendered DOM, including shadow trees; note element IDs and `data-testid` values
684
+ 4. `find_web_elements` / `tap_element` / `type_into_element` — interact with elements to verify selectors work
685
+ 5. `take_inspection_screenshot` — relay screenshots at each key step for verification
686
+ 6. `stop_browser_inspection_session`
687
+ 7. `get_web_test_boilerplate(confirmSelectorsVerified: true)` — generate the verified script
688
+
689
+ ---
690
+
691
+ ## Performance Comparison Reports
692
+
693
+ Compare performance (Speed Index, CPU, memory, battery, duration) between two sets of conditions — app v1 vs v2, device A vs device B, OS version X vs Y, region to region, two network profiles, or two automation scripts. Works with all access levels — Cloud Admin sees all projects; project-level keys (Project Admin and Project User) see only their own project's transactions.
694
+
695
+ The headline metric is reported three ways every time — **trimmed mean, median, and raw mean** — so a small or noisy sample can't hide behind a single number.
696
+
697
+ | Tool | Purpose |
698
+ |---|---|
699
+ | `compare_performance_transactions` | Two-set comparison; trimmed-mean/median/mean per side + delta and % change. MAD outliers excluded by default (≥4 samples/side). Pass `comparisonAxis` to embed a confound check. |
700
+ | `assess_comparison_confounds` | Verdict — **clean / caveated / confounded** — by flagging any dimension other than the declared axis (device model, OS, OS version, network profile, project, transaction name) that varies across or within the sides, plus missing telemetry and sample imbalance. |
701
+ | `detect_performance_outliers` | Robust median/MAD outlier flagging on a single set; returns the kept set and recommended exclusions/re-runs. |
702
+ | `performance_transaction_control` | Phase 2: generate fresh samples inside an inspection session — `start` (with an NV profile) → run the verified flow → `end` (names the record). Records appear in the reporter ~1 min later. |
703
+
704
+ > **Why the confound check matters:** comparing transactions 1894 (Speed Index 1015) and 1895 (1000) looks like a 1.5% version delta — but they ran on *different device models, different OS versions, and different projects*, and 1894 has no CPU/memory telemetry. `assess_comparison_confounds` returns **confounded** and names all three, so the delta is never misread as a version regression.
705
+
706
+ The **`performance_comparison_report` prompt** orchestrates the full workflow end to end: define the axis → scrub confounds → negotiate sample size → **require explicit plan confirmation with a time estimate** → run the series with outlier-driven re-runs → report the delta with root-cause reasoning. True host/background interference is not directly observable; the report approximates device quietness (idle, healthy status, no concurrent reservation) and states that limit explicitly.
707
+
708
+ ---
709
+
710
+ ## Reference
711
+
712
+ ### Response Format
713
+
714
+ All data-returning tools accept an `outputFormat` parameter:
715
+
716
+ | Value | Default? | Use when |
717
+ |---|---|---|
718
+ | `"json"` | ✅ Yes | Chaining tool calls — IDs and values pass directly to the next tool without parsing |
719
+ | `"human"` | No | Displaying results to an operator — formatted prose with status indicators |
720
+
721
+ The default is `"json"` because the primary consumers are AI agents that need to extract IDs for follow-up calls. Agents can render JSON for human display; they cannot reliably parse prose for IDs.
722
+
723
+ ```
724
+ # Example: pass device group IDs without string manipulation
725
+ list_device_groups { outputFormat: "json" }
726
+ → {"deviceGroups":[{"id":"7","name":"Default"},{"id":"12","name":"Acme Corp POC"}]}
727
+
728
+ get_devices_in_group { groupId: "7" }
729
+ → {"devices":[{"id":"abc123","name":"iPhone 14 Pro",...}]}
730
+
731
+ add_devices_to_group { groupId: "12", deviceIds: ["abc123"] }
732
+ ```
733
+
734
+ Tools that only perform mutations (create, delete, install, etc.) return simple success strings and do not have an `outputFormat` parameter.
735
+
736
+ ### Understanding maxResults
737
+
738
+ The Digital.ai API returns complete datasets — there is no server-side pagination for most endpoints. The MCP caps responses at `maxResults` (default: 50, max: 500) to keep response sizes manageable for AI assistants.
739
+
740
+ Use filters to narrow results rather than raising `maxResults`. When results are truncated, you will see:
741
+
742
+ > ⚠️ Showing 50 of 312 results. Use filters to narrow results, or increase maxResults (max 500) to see more.
743
+
744
+ ### List Filters & Sorting
745
+
746
+ | Tool | Available Filters | Available `sortBy` values |
747
+ |---|---|---|
748
+ | `list_users` | firstName, lastName, email, authenticationType, isCloudAdmin, tag | firstName, lastName, email, userName, authenticationType |
749
+ | `list_devices` | query (@-syntax), region, model | deviceName, deviceOs, osVersion, manufacturer, displayStatus, agentName, region |
750
+ | `get_devices_in_group` | osType, status, category, excludeTags, requireTags | _(none)_ |
751
+ | `list_reservations` | username, project, deviceUid | reservationStart, reservationEnd, username, project, deviceUid |
752
+ | `list_projects` | name (partial match) | name, id |
753
+ | `list_project_users` | username (partial), role (exact) | firstName, lastName, email, userName, role |
754
+ | `list_applications` | nameContains, osType, packageName, bundleIdentifier, fileType, isForSimulator | applicationName, version, createdAt (default), osType |
755
+ | `list_test_reports` | status, name, has_attachment, success; startDate/endDate (date range) | start_time |
756
+
757
+ All list tools accept `sortOrder: "asc" | "desc"` (default: `"asc"`).
758
+
759
+ ### Test Reporting Schema
760
+
761
+ Report fields use **snake_case** to match the API response:
762
+
763
+ | Field | Type | Description |
764
+ |---|---|---|
765
+ | `uuid` | string | Unique test execution identifier |
766
+ | `test_id` | number | Numeric reporter ID |
767
+ | `name` | string | Test name |
768
+ | `status` | string | `Passed`, `Failed`, `Incomplete`, `Skipped`, `Error`, `Healed` |
769
+ | `success` | boolean | True when status is Passed |
770
+ | `start_time` | string | ISO 8601 execution start timestamp |
771
+ | `duration` | number \| null | Milliseconds (`null` for in-progress sessions) |
772
+ | `project_id` | number | Owning project |
773
+ | `has_attachment` | string | `"Y"` or `"N"` |
774
+
775
+ **Diagnostic fields — `get_test_report` (single record) only, NOT present on `list_test_reports`:**
776
+
777
+ | Field | Type | Description |
778
+ |---|---|---|
779
+ | `cause` | string | Human-readable failure cause (e.g. `"no such element - …"`) |
780
+ | `errorCategory` | string | Broad bucket (e.g. `assertion`) |
781
+ | `errorClassification` | string | Specific class (e.g. `element_not_found`) |
782
+ | `errorDetail` | string | Full error object including stack trace |
783
+ | `subTestCount` / `failedSubTestCount` | number | Sub-test totals for merged reports |
784
+
785
+ To diagnose a failure, list with `list_test_reports`, then call `get_test_report(testId)` per test — the list view does not carry the diagnostic fields (the backend omits them there).
786
+
787
+ **Confirmed working filter properties:** `status`, `name` (with `contains` for substring match), `has_attachment`, `success`, `test_id`, `project_id`, `device.os` (case-sensitive: `"Android"` / `"iOS"`), `duration`, `attachment_count`, `attachments_size`, `status_code`. Operators: `=`, `>`, `<`, `>=`, `<=`, `contains`.
788
+
789
+ **CSRF-blocked filters** — return 401 regardless of key type: `start_time`, `create_time`, `uuid`. Use the `startDate`/`endDate` parameters on `list_test_reports` for date-range filtering instead — these are applied client-side after fetching.
790
+
791
+ **Reporter ID types:**
792
+
793
+ | Identifier | Source | How to retrieve |
794
+ |---|---|---|
795
+ | `test_id` | List results | `get_test_report(testId: N)` |
796
+ | `uuid` | List results | No direct endpoint — look up via `test_id` |
797
+ | `report_api_id` | Returned by session-start tools | `get_test_by_report_id(reportApiId: "...")` — wait ~60 s after session close |
798
+
799
+ **Examples:**
800
+
801
+ ```
802
+ # Recent failures
803
+ list_test_reports
804
+ filter: [{"property":"status","operator":"=","value":"Failed"}]
805
+ sort: [{"property":"start_time","descending":true}]
806
+ limit: 20
807
+
808
+ # Date range
809
+ list_test_reports
810
+ startDate: "2026-05-01T00:00:00Z"
811
+ endDate: "2026-05-15T23:59:59Z"
812
+
813
+ # Pass/fail by OS
814
+ get_grouped_test_reports
815
+ groupBy: ["device.os"]
816
+ pivotBy: ["status"]
817
+
818
+ # Project summary
819
+ get_project_test_summary
820
+ startDate: "2026-05-01T00:00:00Z"
821
+ projectName: "My Project"
822
+ ```
823
+
824
+ #### Root cause analysis of a failure
825
+
826
+ ```
827
+ # 1. Find the failures
828
+ list_test_reports
829
+ filter: [{"property":"status","operator":"=","value":"Failed"}]
830
+
831
+ # 2. Diagnose — structured cause without any download
832
+ get_test_report(testId: 69)
833
+ → cause, errorCategory, errorClassification, errorDetail (stack trace)
834
+
835
+ # 3. Full Appium log as text, when the structured fields aren't enough
836
+ get_test_log(uuid: "…", logType: "appium")
837
+
838
+ # 4. Pull the binary artifacts (session video .mp4, full ZIP) to YOUR machine
839
+ # when the server runs in Docker/remote
840
+ get_test_attachments_download_command(uuid: "…", localPlatform: "macos")
841
+ → a curl command you run locally; the file never transits the container
842
+ ```
843
+
844
+ ### Local File Transfer (Docker / remote deployments)
845
+
846
+ Any tool that reads or writes a local file path operates on the **MCP server's own filesystem** — which, in the published Docker image or a remote deployment, is **not** your machine. A `download_*` tool writes into the container; an `upload_*` tool reads from it. Neither is reachable from your local shell unless you volume-mount a shared directory.
847
+
848
+ For those deployments, every file-transfer tool has a **command-generator sibling** that emits a `curl` / PowerShell command you run locally, so the bytes move directly between your machine and the platform — never through the container:
849
+
850
+ | Direction | Server-side tool (shared FS only) | Local-command sibling (Docker/remote) |
851
+ |---|---|---|
852
+ | Upload app | `upload_application_file` | `get_application_upload_command` |
853
+ | Upload repo file | `upload_repository_file` | `get_repository_upload_command` |
854
+ | Upload profile | `upload_provisioning_profile` | `get_provisioning_profile_upload_command` |
855
+ | Download test attachments (.mp4, logs) | `download_test_attachments` | `get_test_attachments_download_command` |
856
+ | Download repo file | `download_repository_file` | `get_repository_file_download_command` |
857
+ | Download profile | `download_provisioning_profile` | `get_provisioning_profile_download_command` |
858
+ | Download app language files | `extract_app_language_files` | `get_app_language_files_download_command` |
859
+ | Download iOS app container | `download_ios_app_container` | `get_ios_app_container_download_command` |
860
+
861
+ For test **logs** specifically, `get_test_log` is simpler still — it returns the Appium/device log text inline in the response, no command or download needed. The generated commands embed the active access key in plaintext, so run them immediately and don't save the output.
862
+
863
+ ---
864
+
865
+ ## Safety Guards
866
+
867
+ All destructive operations require `confirmDeletion: true`. Without it:
868
+
869
+ > ⚠️ Safety guard triggered. "Delete user 42" is a destructive operation that cannot be undone. Include `confirmDeletion: true` to proceed. No changes were made.
870
+
871
+ The first call describes exactly what will be deleted. The second call — with `confirmDeletion: true` — executes. This prevents accidental data loss when an AI assistant misinterprets intent.
872
+
873
+ Two further guards run before any request leaves the server:
874
+
875
+ - **Auth pre-flight:** report-deletion tools (`delete_test_reports*`, `cleanup_inspection_sessions`) check the active key type first and return a clear "switch to a Cloud Admin profile" message instead of an opaque CSRF 401 when called with a project-level key.
876
+ - **Upload path validation:** tools that read local files for upload refuse relative paths, path traversal, and credential-file names (`.env*`, SSH private keys) — a misdirected request cannot publish secrets to the cloud repository.
877
+
878
+ ---
879
+
880
+ ## Development
881
+
882
+ ```bash
883
+ npm install
884
+ npm run build # compile TypeScript to dist/
885
+ npm run dev # nodemon + ts-node for live reload
886
+ ```
887
+
888
+ **Running tests** — most suites require a live `.env` with valid credentials and call the real Digital.ai API. The exception is `test:tools`, which exercises registered tool handlers (guards, auth gates, path validation) through an in-memory MCP transport with no live API access:
889
+
890
+ ```bash
891
+ npm run test # all tests
892
+ npm run test:tools # tool-layer guard/gate regression tests (offline)
893
+ npm run test:devices # device management
894
+ npm run test:users # user management
895
+ npm run test:applications # app lifecycle
896
+ npm run test:reservations # reservations
897
+ npm run test:projects # project management
898
+ npm run test:reporting # test reporting
899
+ npm run test:test-views # test view groups
900
+ npm run test:browsers # browser/Selenium
901
+ npm run test:device-groups # device groups
902
+ npm run test:repository # file repository
903
+ npm run test:provisioning # iOS provisioning profiles
904
+ npm run test:health # environment health
905
+ npm run test:utils # utility functions
906
+ npm run test:transactions # performance transactions
907
+ npm run test:analytics # analytics tools
908
+ npm run test:infrastructure # agents / regions / NV servers / sessions
909
+ ```
910
+
911
+ Tests can also be run from VS Code: `Ctrl+Shift+P` → "Tasks: Run Task".
912
+
913
+ ---
914
+
915
+ ## Troubleshooting
916
+
917
+ ### Common symptoms
918
+
919
+ | Symptom | Cause | Fix |
920
+ |---|---|---|
921
+ | `403 Forbidden` on admin tools (agents, regions, license) | Active profile is a project-level key — v2 endpoints require Cloud Admin access | Ask Agent: *"switch to my Cloud Admin profile"* — it will call `list_environments` and pick the right one |
922
+ | Report delete tools return "Cloud Admin access required" | Reporter mutation endpoints are CSRF-blocked for project-level keys (Project Admin and Project User) | Switch to a Cloud Admin profile, re-run, switch back |
923
+ | `install_application` returns 400 on a device you can see | Device is reserved via an rdb (remote debug) session | Install **first**, then run `get_remote_debug_command` — not the other way around |
924
+ | `install_application` returns 400 (no rdb involved) | App not assigned to a project containing the target device | Call `assign_app_to_project` first |
925
+ | Repeatable `NoSuchElementException` while sibling tests pass | Device health, not test code — device stuck in a wrong state or offline-but-pooled | Run `get_device_health_summary`; scope the deviceQuery with `@region='<healthy-region>'` |
926
+ | Tests missing from `list_test_reports` results | Project has its own reporter instance — unscoped queries search the default scope | Pass `projectName` (exact name from `list_projects`) |
927
+ | rdb fails: `validation error / Failed to reserve device` | Project-level key resolved an internal device ID instead of the real serial | Ask Agent: *"switch to Cloud Admin"* → regenerate the rdb script → switch back |
928
+ | Device query returns nothing for `@manufacturer` / `@tag` | These fields are silently ignored server-side | Use the `manufacturer`/`tags` parameters on `find_available_device` — they filter client-side |
929
+
930
+ ### `Failed to reconnect to digital-ai-testing: -32000`
931
+
932
+ On Windows this usually means the `--env-file` path was stored with backslashes stripped. Open `~/.claude.json`, find the `mcpServers` entry for this project, and check that the env file path looks correct (e.g. `C:/projects/digital-ai-testing-mcp/.env`). If it shows something like `C:projectsdigital-ai-testing-mcp.env`, the backslashes were eaten. Fix the path in the file directly (use forward slashes), then run `/mcp` in Claude Code to reconnect.
933
+
934
+ ### Workflow tools failing?
935
+
936
+ Run this sequence:
937
+
938
+ ```
939
+ 1. get_server_info — confirm tool count (expect 180) and active profile
940
+ 2. check_workflow_readiness — which dependency tools are present or missing
941
+ 3. check_connectivity — confirm the backend API is reachable
942
+ ```
943
+
944
+ `check_workflow_readiness` returns a structured report:
945
+
946
+ ```json
947
+ {
948
+ "allWorkflowsReady": true,
949
+ "registeredToolCount": 180,
950
+ "workflows": {
951
+ "create_poc": { "ready": true, "missingRead": [], "missingWrite": [] },
952
+ "setup_project": { "ready": true, "missingRead": [], "missingWrite": [] }
953
+ }
954
+ }
955
+ ```
956
+
957
+ If `ready` is `false`, `missingRead` and `missingWrite` list exactly which tools are absent. The most common cause is a stale Docker image — rebuild:
958
+
959
+ ```bash
960
+ docker build -t digital-ai-testing-mcp:latest .
961
+ ```
962
+
963
+ The server also logs a readiness check at startup (visible in Docker logs): `Workflow readiness: all workflows ready ✓`, or `⚠️ DEGRADED: create_poc — missing: ...` when tools are absent.
964
+
965
+ ---
966
+
967
+ ## Known Limitations
968
+
969
+ The four most commonly encountered:
970
+
971
+ 1. **No API to trigger Appium test execution.** Tests launch from Appium clients (IDE, CI scripts). The server manages devices, apps, reservations, and results — it cannot start an Appium session itself. (Interactive [mobile inspection sessions](docs/tools.md#mobile-inspection-sessions) and [browser inspection sessions](docs/tools.md#web-inspection-sessions) are the exception: live WebDriver sessions for element discovery on Android, iOS, and desktop browsers.)
972
+ 2. **Inspection sessions support Android and iOS** on both the legacy Appium Grid (JWP) and Appium Server (W3C/OSS) projects. iOS caveats: no clear-app-data, no clipboard on Grid devices, and back navigation uses the nav-bar button (iOS has no Back button).
973
+ 3. **No user disable/lock endpoint.** Removing access for a user provisioned solely for a POC means deleting the account — which is why `close_poc` requires per-user confirmation.
974
+ 4. **Reporter API restrictions for project-level keys** — server-side sort and report deletion require Cloud Admin access. Tools compensate automatically (client-side sorting, clear pre-flight errors), at the cost of slower full-scan queries under project-level keys.
975
+
976
+ See [docs/limitations.md](docs/limitations.md) for the full list of 15.
977
+
978
+ ---
979
+
980
+ ## License
981
+
982
+ This project is licensed under the Apache License, Version 2.0. See [LICENSE](./LICENSE) for the full license text.
983
+
984
+ Use of this software is also subject to the [Supplemental Terms of Use](./SUPPLEMENTAL_TERMS.md), which address AI client responsibilities, agentic action risks, liability limitations, and other obligations specific to the Digital.ai MCP Server for Testing. By using this software, you agree to both the Apache 2.0 License and the Supplemental Terms.