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
@@ -0,0 +1,757 @@
1
+ import { z } from 'zod';
2
+ import { getAllDevices, getDevicesByQuery, getDevice, editDevice, releaseDevice, rebootDevice, resetDeviceUsb, downloadIosAppContainer, startDeviceWebControl, openMobileStudio, createMobileManualTest, getDeviceTags, addDeviceTag, removeDeviceTag, removeAllDeviceTags, getDeviceCaCertificates, } from '../api/devices.js';
3
+ import { checkDestructiveGuard } from '../utils/destructive-guard.js';
4
+ import { validateOutputPath } from '../utils/path-guard.js';
5
+ import { SERVER_FS_DOWNLOAD_NOTICE, SERVER_FS_OUTPUT_PARAM } from '../utils/locality.js';
6
+ import { buildDownloadCommand } from '../utils/download-command.js';
7
+ import { applyMaxResults, appendTruncationNotice } from '../utils/pagination.js';
8
+ import { formatDeviceList, formatDeviceHealthSummary } from '../utils/response-formatter.js';
9
+ import { resolveDevice, formatResolvedDevice } from '../utils/device-resolver.js';
10
+ import { outputFormatParam, respond } from '../utils/output-format.js';
11
+ import { getActiveUrl } from '../api/client.js';
12
+ // Region affinity by cloud hostname — used as the preferRegions default so callers
13
+ // get server-proximate devices without passing the param explicitly.
14
+ const CLOUD_REGION_AFFINITY = [
15
+ { hostMatch: 'uscloud', regions: ['US1', 'US2'] },
16
+ { hostMatch: 'eucloud', regions: ['DE1', 'UK1'] },
17
+ { hostMatch: 'apcloud', regions: ['SG1', 'AU1'] },
18
+ ];
19
+ function defaultPreferRegions() {
20
+ try {
21
+ const host = new URL(getActiveUrl()).hostname.toLowerCase();
22
+ return CLOUD_REGION_AFFINITY.find((a) => host.includes(a.hostMatch))?.regions;
23
+ }
24
+ catch {
25
+ return undefined;
26
+ }
27
+ }
28
+ const MODE_MAP = {
29
+ manual: 0,
30
+ view: 1,
31
+ automation: 2,
32
+ debug: 3,
33
+ };
34
+ export function registerDeviceTools(server) {
35
+ server.tool('list_devices', "Lists all devices you have access to with their current status, OS, model, and agent. Optionally filter by region or model (client-side), or use the query syntax for server-side filtering.", {
36
+ query: z
37
+ .string()
38
+ .optional()
39
+ .describe("Server-side device query filter using @ syntax. " +
40
+ "SYNTAX: values MUST be in single quotes and clauses joined with ' and ' — e.g. \"@os='android' and @category='PHONE' and @version>'14.0'\". " +
41
+ "Missing quotes or using a space instead of ' and ' silently returns 0 results. " +
42
+ "CONFIRMED WORKING fields: " +
43
+ "@os ('android'/'iOS', case-insensitive), " +
44
+ "@version (decimal required — '14.0' works, '14' matches nothing; supports =, >, <, !=), " +
45
+ "@category ('PHONE'/'TABLET' — UPPERCASE required, lowercase returns nothing), " +
46
+ "@region (e.g. 'US2', 'SG1'), " +
47
+ "@serialNumber (exact device serial/UDID), " +
48
+ "@name (exact device display name), " +
49
+ "@model (exact model code or display name), " +
50
+ "@modelName (exact human-readable model name), " +
51
+ "@emulator ('true'/'false'). " +
52
+ "BROKEN fields (silently return 0 results — do not use in query): " +
53
+ "@manufacturer, @tag, @deviceName, @id, @udid, @status, @agentName, @region+manufacturer combined. " +
54
+ "For manufacturer, tag, model substring, or region filtering prefer the dedicated params below — those apply client-side and always work."),
55
+ os: z
56
+ .enum(['iOS', 'Android'])
57
+ .optional()
58
+ .describe("Filter by OS (client-side convenience param — equivalent to @os in query but without needing query syntax)."),
59
+ region: z
60
+ .string()
61
+ .optional()
62
+ .describe("Filter by region code (partial match, case-insensitive, client-side). E.g. 'US2', 'SG', 'EU'."),
63
+ model: z
64
+ .string()
65
+ .optional()
66
+ .describe("Filter by device model or name (partial match, case-insensitive, client-side). E.g. 'iPhone 13', 'Pixel 6'."),
67
+ sortBy: z
68
+ .enum(['deviceName', 'deviceOs', 'osVersion', 'manufacturer', 'displayStatus', 'agentName', 'region'])
69
+ .optional()
70
+ .describe('Sort results by this field (client-side). Default: no sort (platform order).'),
71
+ sortOrder: z
72
+ .enum(['asc', 'desc'])
73
+ .optional()
74
+ .default('asc')
75
+ .describe("Sort direction: 'asc' or 'desc'. Default: 'asc'."),
76
+ maxResults: z
77
+ .number()
78
+ .optional()
79
+ .default(50)
80
+ .describe('Maximum number of results to return (default: 50, max: 500).'),
81
+ outputFormat: outputFormatParam,
82
+ }, async ({ query, os, region, model, sortBy, sortOrder, maxResults, outputFormat }) => {
83
+ try {
84
+ let devices = query ? await getDevicesByQuery(query) : await getAllDevices();
85
+ if (os) {
86
+ devices = devices.filter(d => d.deviceOs === os);
87
+ }
88
+ if (region) {
89
+ const q = region.toLowerCase();
90
+ devices = devices.filter(d => d.region.toLowerCase().includes(q));
91
+ }
92
+ if (model) {
93
+ const q = model.toLowerCase();
94
+ devices = devices.filter(d => d.model.toLowerCase().includes(q) ||
95
+ (d.modelName ?? '').toLowerCase().includes(q) ||
96
+ d.deviceName.toLowerCase().includes(q));
97
+ }
98
+ if (sortBy) {
99
+ devices = [...devices].sort((a, b) => {
100
+ const av = String(a[sortBy] ?? '').toLowerCase();
101
+ const bv = String(b[sortBy] ?? '').toLowerCase();
102
+ return sortOrder === 'desc' ? bv.localeCompare(av) : av.localeCompare(bv);
103
+ });
104
+ }
105
+ const filterDesc = [
106
+ query ? `query="${query}"` : '',
107
+ os ? `os="${os}"` : '',
108
+ region ? `region~"${region}"` : '',
109
+ model ? `model~"${model}"` : '',
110
+ ].filter(Boolean).join(', ');
111
+ const paged = applyMaxResults(devices, maxResults);
112
+ const structured = {
113
+ devices: paged.items.map(d => ({
114
+ id: d.id,
115
+ name: d.deviceName,
116
+ osType: d.deviceOs,
117
+ osVersion: d.osVersion,
118
+ model: d.model,
119
+ manufacturer: d.manufacturer,
120
+ deviceCategory: d.deviceCategory,
121
+ displayStatus: d.displayStatus,
122
+ region: d.region,
123
+ tags: d.tags,
124
+ })),
125
+ };
126
+ const header = filterDesc
127
+ ? `Found ${paged.total} device(s) matching [${filterDesc}]:\n\n`
128
+ : `Found ${paged.total} device(s):\n\n`;
129
+ const humanText = appendTruncationNotice(header + formatDeviceList(paged.items), paged);
130
+ return respond(outputFormat, structured, humanText);
131
+ }
132
+ catch (e) {
133
+ return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
134
+ }
135
+ });
136
+ server.tool('get_device_detail', "Gets the full profile of a specific device including device groups, agent connection details, and complete status history. Cloud Admin only. Accepts numeric device ID, serial number, UDID, or device name — MCP resolves the identifier automatically.", {
137
+ deviceId: z.string().describe('Numeric device ID, serial number, UDID, or device name (e.g. "39031FDJH00B3U", "iPhone 15 Pro", or "12345").'),
138
+ outputFormat: outputFormatParam,
139
+ }, async ({ deviceId, outputFormat }) => {
140
+ try {
141
+ const resolved = await resolveDevice(deviceId);
142
+ const d = await getDevice(resolved.id);
143
+ const tags = d.tags && d.tags.length > 0 ? d.tags.join(', ') : 'none';
144
+ const groups = d.deviceGroups
145
+ ? Object.entries(d.deviceGroups)
146
+ .map(([id, name]) => `${name} (ID: ${id})`)
147
+ .join(', ')
148
+ : 'none';
149
+ const humanText = [
150
+ `📱 Device: ${d.deviceName} (ID: ${d.id})`,
151
+ `OS: ${d.deviceOs} ${d.osVersion}`,
152
+ `Model: ${d.model}${d.modelName ? ` (${d.modelName})` : ''}`,
153
+ `Manufacturer: ${d.manufacturer}`,
154
+ `Status: ${d.displayStatus}`,
155
+ `Category: ${d.deviceCategory}`,
156
+ d.project ? `Projects: ${d.project}` : '',
157
+ `Agent: ${d.agentName} (${d.agentIp})`,
158
+ `Region: ${d.region}`,
159
+ `Current User: ${d.currentUser || 'none'}`,
160
+ `Tags: ${tags}`,
161
+ `Device Groups: ${groups}`,
162
+ `Is Emulator: ${d.isEmulator}`,
163
+ `UDID: ${d.udid}`,
164
+ `Status Age: ${d.statusAgeInMinutes} minutes`,
165
+ `Last Used: ${d.lastUsedDateTime}`,
166
+ d.phoneNumber1 ? `Phone: ${d.phoneNumber1}` : '',
167
+ d.screenWidth && d.screenHeight ? `Screen: ${d.screenWidth}x${d.screenHeight}` : '',
168
+ ]
169
+ .filter(Boolean)
170
+ .join('\n');
171
+ return respond(outputFormat, d, humanText);
172
+ }
173
+ catch (e) {
174
+ return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
175
+ }
176
+ });
177
+ server.tool('edit_device', "Updates a device's display name, internal notes, or category (Phone, Tablet, Watch). Cloud Admin only. Accepts numeric device ID, serial number, UDID, or device name.", {
178
+ deviceId: z.string().describe('Numeric device ID, serial number, UDID, or device name.'),
179
+ name: z.string().optional().describe('New display name for the device.'),
180
+ notes: z.string().optional().describe('Internal notes about the device.'),
181
+ category: z
182
+ .enum(['PHONE', 'TABLET', 'WATCH', 'UNKNOWN'])
183
+ .optional()
184
+ .describe("Device category: 'PHONE', 'TABLET', 'WATCH', or 'UNKNOWN'."),
185
+ }, async ({ deviceId, name, notes, category }) => {
186
+ try {
187
+ const resolved = await resolveDevice(deviceId);
188
+ await editDevice(resolved.id, { name, notes, category });
189
+ return {
190
+ content: [{ type: 'text', text: `✅ ${formatResolvedDevice(resolved, deviceId)} updated successfully.` }],
191
+ };
192
+ }
193
+ catch (e) {
194
+ return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
195
+ }
196
+ });
197
+ server.tool('release_device', 'Releases a device from its current user, making it available to others. Useful when a device is stuck in a reserved state. Available to all users for their own sessions. Releasing a device someone else is using ends their session. Requires confirmDeletion: true. Accepts numeric device ID, serial number, UDID, or device name.', {
198
+ deviceId: z.string().describe('Numeric device ID, serial number, UDID, or device name.'),
199
+ confirmDeletion: z
200
+ .boolean()
201
+ .optional()
202
+ .describe('Must be true to confirm. Releasing a device in use ends the current user\'s session. No changes are made without this.'),
203
+ }, async ({ deviceId, confirmDeletion }) => {
204
+ try {
205
+ const guard = checkDestructiveGuard(confirmDeletion, `Release device "${deviceId}" from its current user`);
206
+ if (guard)
207
+ return { content: [{ type: 'text', text: guard }] };
208
+ const resolved = await resolveDevice(deviceId);
209
+ await releaseDevice(resolved.id);
210
+ return {
211
+ content: [
212
+ { type: 'text', text: `✅ ${formatResolvedDevice(resolved, deviceId)} released and is now available.` },
213
+ ],
214
+ };
215
+ }
216
+ catch (e) {
217
+ return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
218
+ }
219
+ });
220
+ server.tool('reboot_device', 'Reboots a device remotely. Use when a device is unresponsive or misbehaving. Cloud Admin only. The device will be briefly unavailable while it restarts. Accepts numeric device ID, serial number, UDID, or device name.', {
221
+ deviceId: z.string().describe('Numeric device ID, serial number, UDID, or device name.'),
222
+ }, async ({ deviceId }) => {
223
+ try {
224
+ const resolved = await resolveDevice(deviceId);
225
+ await rebootDevice(resolved.id);
226
+ return {
227
+ content: [
228
+ {
229
+ type: 'text',
230
+ text: `✅ Reboot command sent to ${formatResolvedDevice(resolved, deviceId)}. The device will be briefly unavailable during restart.`,
231
+ },
232
+ ],
233
+ };
234
+ }
235
+ catch (e) {
236
+ return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
237
+ }
238
+ });
239
+ server.tool('reset_device_usb', 'Resets the USB connection for a device. Try this before rebooting — it often resolves connectivity issues without a full restart. Cloud Admin only. Accepts numeric device ID, serial number, UDID, or device name.', {
240
+ deviceId: z.string().describe('Numeric device ID, serial number, UDID, or device name.'),
241
+ }, async ({ deviceId }) => {
242
+ try {
243
+ const resolved = await resolveDevice(deviceId);
244
+ await resetDeviceUsb(resolved.id);
245
+ return {
246
+ content: [
247
+ { type: 'text', text: `✅ USB reset command sent to ${formatResolvedDevice(resolved, deviceId)}.` },
248
+ ],
249
+ };
250
+ }
251
+ catch (e) {
252
+ return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
253
+ }
254
+ });
255
+ server.tool('start_device_web_control', "Opens a browser-based control session for a specific device. Mode options: 'manual' (interactive testing), 'view' (watch only), 'automation' (automated test mode), 'debug' (debug mode — requires the Digital.ai Grid to be running as the same user who calls this API). Returns a session URL. Cloud Admin only. Accepts numeric device ID, serial number, UDID, or device name.", {
256
+ deviceId: z.string().describe('Numeric device ID, serial number, UDID, or device name.'),
257
+ mode: z
258
+ .enum(['manual', 'view', 'automation', 'debug'])
259
+ .describe("Session mode: 'manual' (interactive), 'view' (watch only), 'automation' (automated), 'debug' (requires Grid running as same user)."),
260
+ emulatorInstanceName: z
261
+ .string()
262
+ .optional()
263
+ .describe('Optional emulator instance name (for emulator devices only).'),
264
+ }, async ({ deviceId, mode, emulatorInstanceName }) => {
265
+ try {
266
+ const resolved = await resolveDevice(deviceId);
267
+ const type = MODE_MAP[mode];
268
+ const result = await startDeviceWebControl(resolved.id, type, emulatorInstanceName);
269
+ const text = [
270
+ `✅ Web control session started.`,
271
+ `Session URL: ${result.regularLink}`,
272
+ result.externalLink ? `External URL: ${result.externalLink}` : '',
273
+ `Mode: ${mode}`,
274
+ ]
275
+ .filter(Boolean)
276
+ .join('\n');
277
+ return { content: [{ type: 'text', text }] };
278
+ }
279
+ catch (e) {
280
+ return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
281
+ }
282
+ });
283
+ server.tool('open_mobile_studio', "Opens Mobile Studio — the platform's browser-based UI Inspector — on a cloud device for ad-hoc visual inspection. " +
284
+ 'Shows a live interactive element tree with resource IDs, XPaths, and accessibility IDs. No local tooling or ADB required. ' +
285
+ 'Available to all users. Returns a regional Mobile Studio session link (e.g. us2region.experitest.com/mobile-studio/…). ' +
286
+ 'NOTE: This is for VISUAL inspection only — it does NOT provide get_element_tree / find_elements / gesture access and does NOT return ' +
287
+ 'the published /#/open/device/{id}/1 view URL. ' +
288
+ 'For programmatic test generation (element-tree access, screenshot relay, boilerplate, and a shareable device view URL) use start_inspection_session instead.', {
289
+ deviceQuery: z
290
+ .string()
291
+ .describe("Device query expression. Example: \"@os='iOS'\", \"@id='123'\"."),
292
+ }, async ({ deviceQuery }) => {
293
+ try {
294
+ const result = await openMobileStudio(deviceQuery);
295
+ return {
296
+ content: [
297
+ {
298
+ type: 'text',
299
+ text: `✅ Mobile Studio session opened.\nSession URL: ${result.link}`,
300
+ },
301
+ ],
302
+ };
303
+ }
304
+ catch (e) {
305
+ return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
306
+ }
307
+ });
308
+ server.tool('create_mobile_manual_test', "Creates a structured manual test session for a mobile device. Returns a session link for the tester and a report_api_id. IMPORTANT: the report_api_id is only resolvable via get_test_by_report_id AFTER the session ends — querying it while the session is active returns 404. A session that is created but never opened and executed by a tester produces NO persisted report at all: the report_api_id will 404 forever and nothing appears in list_test_reports. The session URL hostname is regional (e.g. sgregion, ukregion) and reflects which agent controls the device; this is expected.", {
309
+ deviceQuery: z
310
+ .string()
311
+ .describe("Device query expression to select the target device. Example: \"@os='Android'\"."),
312
+ testName: z.string().describe('Name of the test session (appears in the report).'),
313
+ testSteps: z
314
+ .array(z.object({
315
+ name: z.string().max(255).describe('Step name (max 255 characters).'),
316
+ description: z.string().optional().describe('What to do in this step.'),
317
+ expectedResult: z.string().optional().describe('What the expected outcome is.'),
318
+ attachment: z.string().optional().describe('URL to an attachment or screenshot.'),
319
+ }))
320
+ .describe('Ordered list of test steps.'),
321
+ }, async ({ deviceQuery, testName, testSteps }) => {
322
+ try {
323
+ const result = await createMobileManualTest(deviceQuery, testName, testSteps);
324
+ return {
325
+ content: [
326
+ {
327
+ type: 'text',
328
+ text: [
329
+ `✅ Manual test session created: "${testName}"`,
330
+ `Session URL: ${result.link}`,
331
+ `Report ID (report_api_id): ${result.report_api_id}`,
332
+ `Steps: ${testSteps.length}`,
333
+ ``,
334
+ `Note: the session URL hostname is regional and reflects the device's agent location.`,
335
+ `Use get_test_by_report_id with the report_api_id AFTER closing the session to retrieve results.`,
336
+ ].join('\n'),
337
+ },
338
+ ],
339
+ };
340
+ }
341
+ catch (e) {
342
+ return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
343
+ }
344
+ });
345
+ server.tool('download_ios_app_container', "Downloads the app data container from an iOS device as a ZIP file (useful for inspecting app state after a test). The device must be reserved and the app must be a debug build. Cloud Admin only. iOS only. Accepts numeric device ID, serial number, UDID, or device name." + SERVER_FS_DOWNLOAD_NOTICE, {
346
+ deviceId: z.string().describe('Numeric device ID, serial number, UDID, or iOS device name.'),
347
+ bundleId: z
348
+ .string()
349
+ .describe('iOS bundle identifier, e.g. com.mycompany.myapp.'),
350
+ localPath: z.string().describe(SERVER_FS_OUTPUT_PARAM),
351
+ }, async ({ deviceId, bundleId, localPath }) => {
352
+ const pathErr = validateOutputPath(localPath);
353
+ if (pathErr)
354
+ return { content: [{ type: 'text', text: `Error: ${pathErr}` }], isError: true };
355
+ try {
356
+ const resolved = await resolveDevice(deviceId);
357
+ await downloadIosAppContainer(resolved.id, bundleId, localPath);
358
+ return {
359
+ content: [
360
+ {
361
+ type: 'text',
362
+ text: `✅ App container for ${bundleId} downloaded to: ${localPath}`,
363
+ },
364
+ ],
365
+ };
366
+ }
367
+ catch (e) {
368
+ return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
369
+ }
370
+ });
371
+ server.tool('get_ios_app_container_download_command', 'Generates a ready-to-run curl or PowerShell command for downloading an iOS app data container ZIP directly to the user\'s local machine. ' +
372
+ 'Use this instead of download_ios_app_container when the MCP server runs in Docker/remote and the written file would be inaccessible to the user. ' +
373
+ 'The device must be reserved and the app must be a debug build. Cloud Admin only. iOS only.\n\n' +
374
+ 'WARNING: The generated command embeds the active access key in plaintext. Instruct the user to run it immediately and not save or share the output.', {
375
+ deviceId: z.string().describe('Numeric device ID, serial number, UDID, or iOS device name.'),
376
+ bundleId: z.string().describe('iOS bundle identifier, e.g. com.mycompany.myapp.'),
377
+ localPath: z.string().optional().default('app-container.zip').describe('Path on the user\'s local machine to save the ZIP. Default: "app-container.zip".'),
378
+ localPlatform: z.enum(['windows', 'macos', 'linux']).describe('Platform of the machine that will run the command. "windows" emits both Git Bash curl and PowerShell. Cannot be inferred — the MCP runs in Docker.'),
379
+ outputFormat: outputFormatParam,
380
+ }, async ({ deviceId, bundleId, localPath, localPlatform, outputFormat }) => {
381
+ try {
382
+ const resolved = await resolveDevice(deviceId);
383
+ const result = buildDownloadCommand({
384
+ path: `/api/v1/devices/${resolved.id}/app-container/${bundleId}`,
385
+ localPath: localPath ?? 'app-container.zip',
386
+ localPlatform,
387
+ });
388
+ return respond(outputFormat, { endpoint: result.endpoint, curlCommand: result.curlCommand, psCommand: result.psCommand }, result.humanText);
389
+ }
390
+ catch (e) {
391
+ return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
392
+ }
393
+ });
394
+ server.tool('get_device_tags', 'Gets all tags currently assigned to a device. Available to all users. Accepts numeric device ID, serial number, UDID, or device name.', {
395
+ deviceId: z.string().describe('Numeric device ID, serial number, UDID, or device name.'),
396
+ outputFormat: outputFormatParam,
397
+ }, async ({ deviceId, outputFormat }) => {
398
+ try {
399
+ const resolved = await resolveDevice(deviceId);
400
+ const tags = await getDeviceTags(resolved.id);
401
+ const label = formatResolvedDevice(resolved, deviceId);
402
+ const structured = { deviceId: resolved.id, tags };
403
+ const humanText = tags.length > 0
404
+ ? `Tags on ${label}: ${tags.join(', ')}`
405
+ : `${label} has no tags.`;
406
+ return respond(outputFormat, structured, humanText);
407
+ }
408
+ catch (e) {
409
+ return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
410
+ }
411
+ });
412
+ server.tool('add_device_tag', 'Assigns a tag to a device (max 10 total). ' +
413
+ 'Use this to label, mark, or categorize a device — for example, tagging devices with a POC identifier during create_poc (Step 5). ' +
414
+ 'Tags may only contain letters, digits, and underscores — no spaces or special characters. Not case-sensitive. ' +
415
+ 'Accepts numeric device ID, serial number, UDID, or device name. Available to Cloud Admin and Project Admin.', {
416
+ deviceId: z.string().describe('Numeric device ID, serial number, UDID, or device name.'),
417
+ tag: z
418
+ .string()
419
+ .regex(/^[a-zA-Z0-9_]+$/)
420
+ .describe('Tag value — letters, digits, and underscores only. No spaces.'),
421
+ }, async ({ deviceId, tag }) => {
422
+ try {
423
+ const resolved = await resolveDevice(deviceId);
424
+ await addDeviceTag(resolved.id, tag);
425
+ return {
426
+ content: [{ type: 'text', text: `✅ Tag "${tag}" added to ${formatResolvedDevice(resolved, deviceId)}.` }],
427
+ };
428
+ }
429
+ catch (e) {
430
+ return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
431
+ }
432
+ });
433
+ server.tool('remove_device_tag', 'Removes a specific tag from a device. Available to Cloud Admin and Project Admin. Requires confirmDeletion: true. Accepts numeric device ID, serial number, UDID, or device name.', {
434
+ deviceId: z.string().describe('Numeric device ID, serial number, UDID, or device name.'),
435
+ tag: z.string().describe('The tag value to remove.'),
436
+ confirmDeletion: z
437
+ .boolean()
438
+ .describe('Must be true to confirm this destructive, irreversible operation. No changes are made without this.'),
439
+ }, async ({ deviceId, tag, confirmDeletion }) => {
440
+ try {
441
+ const guard = checkDestructiveGuard(confirmDeletion, `Remove tag "${tag}" from device "${deviceId}"`);
442
+ if (guard)
443
+ return { content: [{ type: 'text', text: guard }] };
444
+ const resolved = await resolveDevice(deviceId);
445
+ await removeDeviceTag(resolved.id, tag);
446
+ return {
447
+ content: [{ type: 'text', text: `✅ Tag "${tag}" removed from ${formatResolvedDevice(resolved, deviceId)}.` }],
448
+ };
449
+ }
450
+ catch (e) {
451
+ return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
452
+ }
453
+ });
454
+ server.tool('remove_all_device_tags', 'Removes all tags from a device at once. Available to Cloud Admin and Project Admin. Requires confirmDeletion: true. Accepts numeric device ID, serial number, UDID, or device name.', {
455
+ deviceId: z.string().describe('Numeric device ID, serial number, UDID, or device name.'),
456
+ confirmDeletion: z
457
+ .boolean()
458
+ .describe('Must be true to confirm this destructive, irreversible operation. No changes are made without this.'),
459
+ }, async ({ deviceId, confirmDeletion }) => {
460
+ try {
461
+ const guard = checkDestructiveGuard(confirmDeletion, `Remove all tags from device "${deviceId}"`);
462
+ if (guard)
463
+ return { content: [{ type: 'text', text: guard }] };
464
+ const resolved = await resolveDevice(deviceId);
465
+ await removeAllDeviceTags(resolved.id);
466
+ return {
467
+ content: [{ type: 'text', text: `✅ All tags removed from ${formatResolvedDevice(resolved, deviceId)}.` }],
468
+ };
469
+ }
470
+ catch (e) {
471
+ return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
472
+ }
473
+ });
474
+ server.tool('get_device_ca_certificates', 'Lists the CA (Certificate Authority) certificates installed on an Android device. Useful for verifying that network capture or proxy certificates are correctly installed. Android only. Cloud Admin only. Note: pre-existing manufacturer accounts (Google, Samsung, Xiaomi) must be removed from the device before first use. Accepts numeric device ID, serial number, UDID, or device name.', {
475
+ deviceId: z.string().describe('Numeric device ID, serial number, UDID, or device name (Android only).'),
476
+ outputFormat: outputFormatParam,
477
+ }, async ({ deviceId, outputFormat }) => {
478
+ try {
479
+ const resolved = await resolveDevice(deviceId);
480
+ const certs = await getDeviceCaCertificates(resolved.id);
481
+ const label = formatResolvedDevice(resolved, deviceId);
482
+ const structured = { deviceId: resolved.id, certificates: certs };
483
+ const humanText = certs.length > 0
484
+ ? `CA Certificates on ${label} (${certs.length}):\n${certs.map((c) => ` • ${c}`).join('\n')}`
485
+ : `No CA certificates found on ${label}.`;
486
+ return respond(outputFormat, structured, humanText);
487
+ }
488
+ catch (e) {
489
+ return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
490
+ }
491
+ });
492
+ server.tool('get_device_health_summary', 'Shows a health overview of all devices: counts by status, breakdown by OS, per-agent device counts, and any devices that have been offline unusually long.', {
493
+ offlineThresholdMinutes: z
494
+ .number()
495
+ .optional()
496
+ .default(60)
497
+ .describe('Flag devices offline longer than this many minutes (default: 60).'),
498
+ maxResults: z
499
+ .number()
500
+ .optional()
501
+ .default(200)
502
+ .describe('Maximum number of devices to include in the analysis (default: 200, max: 500).'),
503
+ outputFormat: outputFormatParam,
504
+ }, async ({ offlineThresholdMinutes, maxResults, outputFormat }) => {
505
+ try {
506
+ const devices = await getAllDevices();
507
+ const paged = applyMaxResults(devices, maxResults);
508
+ // Build structured summary
509
+ const available = paged.items.filter(d => d.displayStatus.toLowerCase() === 'available').length;
510
+ const reserved = paged.items.filter(d => d.displayStatus.toLowerCase() === 'reserved').length;
511
+ const offline = paged.items.filter(d => d.displayStatus.toLowerCase() === 'offline').length;
512
+ const ios = paged.items.filter(d => d.deviceOs === 'iOS').length;
513
+ const android = paged.items.filter(d => d.deviceOs === 'Android').length;
514
+ const agentMapStruct = {};
515
+ for (const d of paged.items) {
516
+ if (!agentMapStruct[d.agentName])
517
+ agentMapStruct[d.agentName] = { total: 0, online: 0, ip: d.agentIp };
518
+ agentMapStruct[d.agentName].total++;
519
+ if (d.displayStatus.toLowerCase() !== 'offline')
520
+ agentMapStruct[d.agentName].online++;
521
+ }
522
+ const agentArray = Object.entries(agentMapStruct).map(([name, counts]) => ({ name, ...counts }));
523
+ const longOfflineArray = paged.items
524
+ .filter(d => d.displayStatus.toLowerCase() === 'offline' && parseFloat(d.statusAgeInMinutes) > offlineThresholdMinutes)
525
+ .map(d => ({ id: d.id, name: d.deviceName, offlineMinutes: parseFloat(d.statusAgeInMinutes) }));
526
+ const structured = {
527
+ total: paged.total,
528
+ analyzed: paged.returned,
529
+ truncated: paged.truncated,
530
+ available, reserved, offline, ios, android,
531
+ agents: agentArray,
532
+ longOffline: longOfflineArray,
533
+ };
534
+ const humanSummary = formatDeviceHealthSummary(paged.items, offlineThresholdMinutes);
535
+ const humanText = appendTruncationNotice(humanSummary, paged);
536
+ return respond(outputFormat, structured, humanText);
537
+ }
538
+ catch (e) {
539
+ return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
540
+ }
541
+ });
542
+ // ─── find_available_device ────────────────────────────────────────────────
543
+ server.tool('find_available_device', 'Find the first available device matching capability criteria (OS, version, manufacturer, tags, model). ' +
544
+ 'Filtering by os and category is applied server-side for speed; manufacturer, tags, model, and osVersion are ' +
545
+ 'applied client-side (the API @manufacturer and @tag query fields do not work). ' +
546
+ 'Returns the device immediately if one is free, or reports how many matching devices exist and their current statuses if none are available. ' +
547
+ 'IMPORTANT: Call this tool before generating any digitalai:deviceQuery capability strings — use the osVersion AND region values ' +
548
+ 'from the RESPONSE (not the parameters you passed) when calling get_test_boilerplate. ' +
549
+ 'The osVersion parameter is a minimum filter (≥), so the returned device may be running a higher version than requested. ' +
550
+ 'Region preference defaults automatically from the active cloud URL (uscloud → US1/US2, eucloud → DE1/UK1, ' +
551
+ 'apcloud → SG1/AU1) to avoid cross-region session latency; pass preferRegions explicitly to override, ' +
552
+ 'or preferRegions: [] to disable the default and search all regions equally.', {
553
+ os: z
554
+ .enum(['iOS', 'Android'])
555
+ .optional()
556
+ .describe('Target operating system. Applied server-side.'),
557
+ osVersion: z
558
+ .string()
559
+ .optional()
560
+ .describe('Minimum OS version filter (≥), e.g. "14.0". Applied client-side. ' +
561
+ 'The returned device may be running a HIGHER version than requested — always read osVersion from the ' +
562
+ 'response and use that exact value (e.g. "14.0") in your digitalai:deviceQuery @version field. ' +
563
+ 'Do not use the value you passed as the parameter.'),
564
+ manufacturer: z
565
+ .string()
566
+ .optional()
567
+ .describe('Device manufacturer, e.g. "Apple" or "samsung" (case-insensitive, client-side filter).'),
568
+ model: z
569
+ .string()
570
+ .optional()
571
+ .describe('Device model substring matched against deviceName and modelName (case-insensitive, client-side). E.g. "iPhone 14", "Pixel 6".'),
572
+ tags: z
573
+ .array(z.string())
574
+ .optional()
575
+ .describe('All listed tags must be present on the device (case-insensitive, client-side filter).'),
576
+ category: z
577
+ .enum(['PHONE', 'TABLET', 'WATCH'])
578
+ .optional()
579
+ .describe('Device form factor. Applied server-side.'),
580
+ preferRegions: z
581
+ .array(z.string())
582
+ .optional()
583
+ .describe('Region codes in preference order (e.g. ["US1","US2"]). The tool returns the first ' +
584
+ 'available device in the highest-priority region that has one, falling back to any available device if ' +
585
+ 'none of the preferred regions have a healthy device. DEFAULT: derived from the active cloud URL ' +
586
+ '(uscloud → ["US1","US2"]; eucloud → ["DE1","UK1"]; apcloud → ["SG1","AU1"]). ' +
587
+ 'Pass [] to disable the default and treat all regions equally. ' +
588
+ 'The response includes regionPreferenceApplied to confirm which case applied.'),
589
+ outputFormat: outputFormatParam,
590
+ }, async ({ os, osVersion, manufacturer, model, tags, category, preferRegions, outputFormat }) => {
591
+ try {
592
+ // No explicit preference → derive from the active cloud URL. An explicit [] opts out.
593
+ const effectiveRegions = preferRegions ?? defaultPreferRegions();
594
+ const regionsDefaulted = !preferRegions && !!effectiveRegions;
595
+ // @os and @category are confirmed to work server-side (live-verified).
596
+ // @manufacturer and @tag silently return 0 results — filter those client-side.
597
+ const clauses = [];
598
+ if (os)
599
+ clauses.push(`@os='${os}'`);
600
+ if (category)
601
+ clauses.push(`@category='${category}'`);
602
+ const query = clauses.join(' and ');
603
+ const devices = query ? await getDevicesByQuery(query) : await getAllDevices();
604
+ // Apply all remaining filters client-side (manufacturer, tags, model, osVersion).
605
+ const filtered = devices.filter((d) => {
606
+ if (os && d.deviceOs !== os)
607
+ return false;
608
+ if (osVersion && parseFloat(d.osVersion) < parseFloat(osVersion))
609
+ return false;
610
+ if (manufacturer && d.manufacturer.toLowerCase() !== manufacturer.toLowerCase())
611
+ return false;
612
+ if (tags && !tags.every(t => d.tags.map(dt => dt.toLowerCase()).includes(t.toLowerCase())))
613
+ return false;
614
+ if (model && !d.deviceName.toLowerCase().includes(model.toLowerCase()) &&
615
+ !(d.modelName ?? '').toLowerCase().includes(model.toLowerCase()))
616
+ return false;
617
+ return true;
618
+ });
619
+ if (filtered.length === 0) {
620
+ return respond(outputFormat, { found: false, matchingCount: 0 }, 'No devices match the specified criteria.');
621
+ }
622
+ const available = filtered.filter((d) => d.displayStatus.toLowerCase() === 'available');
623
+ if (available.length > 0) {
624
+ // Apply region preference: pick first available device in the highest-priority region.
625
+ let d = available[0];
626
+ let regionPreferenceApplied = false;
627
+ let preferredRegionUsed = null;
628
+ if (effectiveRegions && effectiveRegions.length > 0) {
629
+ for (const preferredRegion of effectiveRegions) {
630
+ const inRegion = available.filter(dev => dev.region === preferredRegion);
631
+ if (inRegion.length > 0) {
632
+ d = inRegion[0];
633
+ regionPreferenceApplied = true;
634
+ preferredRegionUsed = preferredRegion;
635
+ break;
636
+ }
637
+ }
638
+ }
639
+ const structured = {
640
+ found: true,
641
+ device: {
642
+ id: d.id,
643
+ name: d.deviceName,
644
+ osType: d.deviceOs,
645
+ osVersion: d.osVersion,
646
+ model: d.model,
647
+ manufacturer: d.manufacturer,
648
+ region: d.region,
649
+ agentName: d.agentName,
650
+ tags: d.tags,
651
+ },
652
+ alternativesAvailable: available.length - 1,
653
+ regionPreferenceApplied,
654
+ preferredRegionUsed,
655
+ preferRegionsDefaulted: regionsDefaulted,
656
+ };
657
+ const regionNote = effectiveRegions && effectiveRegions.length > 0 && !regionPreferenceApplied
658
+ ? `\n⚠️ None of the preferred regions (${effectiveRegions.join(', ')}${regionsDefaulted ? ', cloud default' : ''}) had available devices — returned device is from region: ${d.region}`
659
+ : '';
660
+ const humanText = [
661
+ `✅ Available device found:`,
662
+ ` Name: ${d.deviceName} (ID: ${d.id})`,
663
+ ` OS: ${d.deviceOs} ${d.osVersion}`,
664
+ ` Model: ${d.model}${d.modelName ? ` (${d.modelName})` : ''}`,
665
+ ` Manufacturer: ${d.manufacturer}`,
666
+ ` Region: ${d.region}`,
667
+ ` Agent: ${d.agentName}`,
668
+ ` Tags: ${d.tags.length > 0 ? d.tags.join(', ') : 'none'}`,
669
+ available.length > 1 ? `\n${available.length - 1} other matching device(s) also available.` : '',
670
+ regionNote,
671
+ ].filter(Boolean).join('\n');
672
+ return respond(outputFormat, structured, humanText);
673
+ }
674
+ // None available — report status breakdown
675
+ const statusCounts = {};
676
+ for (const d of filtered) {
677
+ const s = d.displayStatus || 'Unknown';
678
+ statusCounts[s] = (statusCounts[s] ?? 0) + 1;
679
+ }
680
+ const breakdown = Object.entries(statusCounts)
681
+ .map(([s, n]) => ` ${s}: ${n}`)
682
+ .join('\n');
683
+ return respond(outputFormat, { found: false, matchingCount: filtered.length, statusBreakdown: statusCounts }, `No available devices match the criteria. ${filtered.length} matching device(s) found:\n${breakdown}`);
684
+ }
685
+ catch (e) {
686
+ return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
687
+ }
688
+ });
689
+ // ─── release_orphaned_sessions ────────────────────────────────────────────
690
+ server.tool('release_orphaned_sessions', 'Find and release devices that have been in an "In Use" state longer than the specified threshold. Useful for clearing sessions orphaned by crashed test runners or forgotten manual sessions. Requires confirmDeletion: true to actually release; omit it to preview what would be released.', {
691
+ maxAgeHours: z
692
+ .number()
693
+ .min(0.5)
694
+ .default(4)
695
+ .describe('Release devices that have been in use longer than this many hours. Default: 4 hours.'),
696
+ confirmDeletion: z
697
+ .boolean()
698
+ .optional()
699
+ .describe('Must be true to actually release the devices. Omit to preview without making changes.'),
700
+ dryRun: z
701
+ .boolean()
702
+ .optional()
703
+ .describe('Alias for omitting confirmDeletion — explicitly show what would be released without releasing.'),
704
+ outputFormat: outputFormatParam,
705
+ }, async ({ maxAgeHours, confirmDeletion, dryRun, outputFormat }) => {
706
+ try {
707
+ const devices = await getAllDevices();
708
+ const thresholdMinutes = maxAgeHours * 60;
709
+ const orphaned = devices.filter((d) => {
710
+ const status = d.displayStatus.toLowerCase();
711
+ const isInUse = status === 'in use' || status === 'inuse' || status === 'busy';
712
+ const age = parseFloat(d.statusAgeInMinutes);
713
+ return isInUse && !isNaN(age) && age >= thresholdMinutes;
714
+ });
715
+ if (orphaned.length === 0) {
716
+ return {
717
+ content: [{
718
+ type: 'text',
719
+ text: `No orphaned sessions found (threshold: ${maxAgeHours}h). All in-use devices are within the time limit.`,
720
+ }],
721
+ };
722
+ }
723
+ const preview = orphaned
724
+ .map((d) => {
725
+ const hours = (parseFloat(d.statusAgeInMinutes) / 60).toFixed(1);
726
+ return ` • ${d.deviceName} (ID: ${d.id}) — in use for ${hours}h by ${d.currentUser || 'unknown'}`;
727
+ })
728
+ .join('\n');
729
+ const guard = checkDestructiveGuard(dryRun ? false : confirmDeletion, `Release ${orphaned.length} orphaned device session(s) held for >${maxAgeHours}h`);
730
+ if (guard) {
731
+ return {
732
+ content: [{ type: 'text', text: `${guard}\n\nDevices that would be released:\n${preview}` }],
733
+ };
734
+ }
735
+ const results = [];
736
+ const releaseResults = [];
737
+ for (const d of orphaned) {
738
+ try {
739
+ await releaseDevice(d.id);
740
+ results.push(` ✅ Released: ${d.deviceName} (ID: ${d.id})`);
741
+ releaseResults.push({ id: d.id, name: d.deviceName, status: 'released' });
742
+ }
743
+ catch (err) {
744
+ results.push(` ❌ Failed: ${d.deviceName} (ID: ${d.id}) — ${err.message}`);
745
+ releaseResults.push({ id: d.id, name: d.deviceName, status: 'failed', error: err.message });
746
+ }
747
+ }
748
+ const structured = { released: releaseResults.filter(r => r.status === 'released').length, results: releaseResults };
749
+ const humanText = `Released ${orphaned.length} orphaned session(s):\n${results.join('\n')}`;
750
+ return respond(outputFormat, structured, humanText);
751
+ }
752
+ catch (e) {
753
+ return { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true };
754
+ }
755
+ });
756
+ }
757
+ //# sourceMappingURL=device-tools.js.map