digital-ai-testing-mcp 2.2.1 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. package/README.md +28 -16
  2. package/dist/api/browser-events.d.ts +48 -0
  3. package/dist/api/browser-events.d.ts.map +1 -0
  4. package/dist/api/browser-events.js +155 -0
  5. package/dist/api/browser-events.js.map +1 -0
  6. package/dist/api/browser-inspection.d.ts +21 -0
  7. package/dist/api/browser-inspection.d.ts.map +1 -1
  8. package/dist/api/browser-inspection.js +113 -20
  9. package/dist/api/browser-inspection.js.map +1 -1
  10. package/dist/api/playwright-runs.d.ts +42 -0
  11. package/dist/api/playwright-runs.d.ts.map +1 -0
  12. package/dist/api/playwright-runs.js +207 -0
  13. package/dist/api/playwright-runs.js.map +1 -0
  14. package/dist/api/reporting.d.ts.map +1 -1
  15. package/dist/api/reporting.js +4 -2
  16. package/dist/api/reporting.js.map +1 -1
  17. package/dist/api/repository.d.ts +13 -1
  18. package/dist/api/repository.d.ts.map +1 -1
  19. package/dist/api/repository.js +39 -4
  20. package/dist/api/repository.js.map +1 -1
  21. package/dist/api/test-runs.d.ts +5 -0
  22. package/dist/api/test-runs.d.ts.map +1 -1
  23. package/dist/api/test-runs.js.map +1 -1
  24. package/dist/api/webdriver.d.ts +23 -2
  25. package/dist/api/webdriver.d.ts.map +1 -1
  26. package/dist/api/webdriver.js +142 -13
  27. package/dist/api/webdriver.js.map +1 -1
  28. package/dist/index.js +1 -1
  29. package/dist/tools/boilerplate-tools.d.ts +22 -0
  30. package/dist/tools/boilerplate-tools.d.ts.map +1 -1
  31. package/dist/tools/boilerplate-tools.js +323 -44
  32. package/dist/tools/boilerplate-tools.js.map +1 -1
  33. package/dist/tools/device-group-tools.js +2 -2
  34. package/dist/tools/device-group-tools.js.map +1 -1
  35. package/dist/tools/device-tools.js +3 -3
  36. package/dist/tools/device-tools.js.map +1 -1
  37. package/dist/tools/inspection-tools.d.ts +24 -0
  38. package/dist/tools/inspection-tools.d.ts.map +1 -1
  39. package/dist/tools/inspection-tools.js +129 -13
  40. package/dist/tools/inspection-tools.js.map +1 -1
  41. package/dist/tools/meta-tools.d.ts +1 -1
  42. package/dist/tools/meta-tools.d.ts.map +1 -1
  43. package/dist/tools/meta-tools.js +3 -2
  44. package/dist/tools/meta-tools.js.map +1 -1
  45. package/dist/tools/prompt-tools.d.ts.map +1 -1
  46. package/dist/tools/prompt-tools.js +4 -0
  47. package/dist/tools/prompt-tools.js.map +1 -1
  48. package/dist/tools/reporting-tools.d.ts.map +1 -1
  49. package/dist/tools/reporting-tools.js +27 -8
  50. package/dist/tools/reporting-tools.js.map +1 -1
  51. package/dist/tools/repository-tools.d.ts.map +1 -1
  52. package/dist/tools/repository-tools.js +5 -3
  53. package/dist/tools/repository-tools.js.map +1 -1
  54. package/dist/tools/test-run-tools.d.ts.map +1 -1
  55. package/dist/tools/test-run-tools.js +107 -6
  56. package/dist/tools/test-run-tools.js.map +1 -1
  57. package/dist/tools/usage-report-tools.d.ts.map +1 -1
  58. package/dist/tools/usage-report-tools.js +6 -4
  59. package/dist/tools/usage-report-tools.js.map +1 -1
  60. package/dist/tools/web-inspection-tools.d.ts.map +1 -1
  61. package/dist/tools/web-inspection-tools.js +116 -13
  62. package/dist/tools/web-inspection-tools.js.map +1 -1
  63. package/dist/types/digital-ai.d.ts +6 -1
  64. package/dist/types/digital-ai.d.ts.map +1 -1
  65. package/dist/utils/adb-shell.d.ts +25 -0
  66. package/dist/utils/adb-shell.d.ts.map +1 -0
  67. package/dist/utils/adb-shell.js +87 -0
  68. package/dist/utils/adb-shell.js.map +1 -0
  69. package/dist/utils/credential-env.d.ts +36 -0
  70. package/dist/utils/credential-env.d.ts.map +1 -0
  71. package/dist/utils/credential-env.js +57 -0
  72. package/dist/utils/credential-env.js.map +1 -0
  73. package/dist/utils/failure-triage.d.ts +13 -0
  74. package/dist/utils/failure-triage.d.ts.map +1 -0
  75. package/dist/utils/failure-triage.js +53 -0
  76. package/dist/utils/failure-triage.js.map +1 -0
  77. package/dist/utils/locator-recommend.d.ts +27 -0
  78. package/dist/utils/locator-recommend.d.ts.map +1 -0
  79. package/dist/utils/locator-recommend.js +59 -0
  80. package/dist/utils/locator-recommend.js.map +1 -0
  81. package/dist/utils/response-formatter.d.ts +8 -0
  82. package/dist/utils/response-formatter.d.ts.map +1 -1
  83. package/dist/utils/response-formatter.js +26 -0
  84. package/dist/utils/response-formatter.js.map +1 -1
  85. package/dist/utils/usage-report-summary.d.ts +2 -0
  86. package/dist/utils/usage-report-summary.d.ts.map +1 -1
  87. package/dist/utils/usage-report-summary.js +5 -1
  88. package/dist/utils/usage-report-summary.js.map +1 -1
  89. package/package.json +13 -6
  90. package/resources/boilerplate/Android-Native/NodeJS (WebDriver)/wdio-oss.conf.js +1 -0
  91. package/resources/boilerplate/Android-Native/Python/AndroidNative-oss.py +3 -2
  92. package/resources/boilerplate/Android-Native/Python/pip-oss +1 -1
  93. package/resources/boilerplate/Android-Native/Robot Framework/AndroidNative-oss.robot +1 -1
  94. package/resources/boilerplate/iOS-Native/NodeJS (WebDriver)/wdio-oss.conf.js +1 -0
  95. package/resources/boilerplate/iOS-Native/Python/iOSNative-oss.py +3 -2
  96. package/resources/boilerplate/iOS-Native/Python/pip-oss.txt +1 -1
  97. package/resources/boilerplate/iOS-Native/Robot Framework/iOSNative-oss.robot +1 -1
@@ -1,3 +1,27 @@
1
1
  import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
+ interface ParsedElement {
3
+ className: string;
4
+ resourceId: string | null;
5
+ contentDesc: string | null;
6
+ text: string | null;
7
+ bounds: string | null;
8
+ clickable: boolean;
9
+ enabled: boolean;
10
+ fullResourceId: string | null;
11
+ name: string | null;
12
+ label: string | null;
13
+ value: string | null;
14
+ }
15
+ declare function parseElementTree(xml: string, platform: 'android' | 'ios'): {
16
+ elements: ParsedElement[];
17
+ totalNodes: number;
18
+ };
19
+ declare function formatElementTable(elements: ParsedElement[], totalNodes: number, platform: 'android' | 'ios'): string;
20
+ /** Test seam: the element-table pipeline get_element_tree uses. */
21
+ export declare const __elementTreeForTests: {
22
+ parseElementTree: typeof parseElementTree;
23
+ formatElementTable: typeof formatElementTable;
24
+ };
2
25
  export declare function registerInspectionTools(server: McpServer): void;
26
+ export {};
3
27
  //# sourceMappingURL=inspection-tools.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"inspection-tools.d.ts","sourceRoot":"","sources":["../../src/tools/inspection-tools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAiSzE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA8/C/D"}
1
+ {"version":3,"file":"inspection-tools.d.ts","sourceRoot":"","sources":["../../src/tools/inspection-tools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAkJzE,UAAU,aAAa;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,iBAAS,gBAAgB,CACvB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,SAAS,GAAG,KAAK,GAC1B;IACD,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB,CAqEA;AAqBD,iBAAS,kBAAkB,CACzB,QAAQ,EAAE,aAAa,EAAE,EACzB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,SAAS,GAAG,KAAK,GAC1B,MAAM,CA6DR;AAED,mEAAmE;AACnE,eAAO,MAAM,qBAAqB;;;CAA2C,CAAC;AAI9E,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA6kD/D"}
@@ -1,6 +1,6 @@
1
1
  import { z } from 'zod';
2
2
  import { caseInsensitiveEnum } from '../utils/schema.js';
3
- import { createInspectionSession, quitInspectionSession, captureScreenshot, getPageSource, findElements, tapElement, typeIntoElement, clearElement, swipeScreen, getWindowSize, launchApp, pressBack, longPress, doubleTap, dragAndDrop, pinchZoom, scrollToElement, pressKey, isKeyboardShown, hideKeyboard, appControl, getOrientation, setOrientation, getClipboard, setClipboard, setGeolocation, resetGeolocation, handleAlert, pushFileToDevice, pullFileFromDevice, mockAuthentication, requireSession, findFirstElementId, listActiveSessions, getPendingReportIds, sweepTimedOutStarts, deleteAllTrackedReports, automotiveControl, audioControl, AUTOMOTIVE_RESOLUTIONS, INSTRUMENT_CLUSTER_CONTENT, getForegroundActivity, isSameActivity, listContexts, switchContext, getDeviceLog, getAlertInfo, isWebviewContext, sessionCapture, networkConnection, setNetworkConditions, injectCameraImage, clearWebCache, deviceDiagnostics, setAppearance, accessibilityAudit } from '../api/webdriver.js';
3
+ import { createInspectionSession, quitInspectionSession, captureScreenshot, getPageSource, findElements, tapElement, typeIntoElement, clearElement, swipeScreen, getWindowSize, launchApp, pressBack, longPress, doubleTap, tapAt, appPermissions, dragAndDrop, pinchZoom, scrollToElement, pressKey, isKeyboardShown, hideKeyboard, appControl, getOrientation, setOrientation, getClipboard, setClipboard, setGeolocation, resetGeolocation, handleAlert, pushFileToDevice, pullFileFromDevice, mockAuthentication, requireSession, findFirstElementId, listActiveSessions, getPendingReportIds, sweepTimedOutStarts, deleteAllTrackedReports, automotiveControl, audioControl, AUTOMOTIVE_RESOLUTIONS, INSTRUMENT_CLUSTER_CONTENT, getForegroundActivity, isSameActivity, listContexts, switchContext, getDeviceLog, getAlertInfo, isWebviewContext, sessionCapture, networkConnection, setNetworkConditions, injectCameraImage, clearWebCache, deviceDiagnostics, setAppearance, accessibilityAudit, adbShell } from '../api/webdriver.js';
4
4
  import { checkDestructiveGuard } from '../utils/destructive-guard.js';
5
5
  import { getActiveUrl } from '../api/client.js';
6
6
  import { checkDeleteAllowed } from '../api/access-level.js';
@@ -10,11 +10,15 @@ import { listFiles } from '../api/repository.js';
10
10
  import { validateInputPath, validateOutputPath } from '../utils/path-guard.js';
11
11
  import { readFileSync, writeFileSync } from 'fs';
12
12
  import { getDeploymentMode } from '../utils/deployment-mode.js';
13
+ import { classifyShellCommand, shellGuardMessage, capShellOutput, shellCommandProblem } from '../utils/adb-shell.js';
14
+ import { recommendLocators, formatRecommendation } from '../utils/locator-recommend.js';
13
15
  // '-ios predicate string' is XCUITest's NSPredicate locator (e.g. "type == 'XCUIElementTypeButton' AND label == 'Login'")
14
16
  // — faster and less brittle than xpath on iOS, and the form the Mobile Studio iOS Test Recorder emits. iOS on Appium
15
17
  // Server only: the Appium Grid rejects it ("Locator Strategy '-ios predicate string' is not supported for this
16
18
  // session", verified live 2026-10-09 on an iPhone 13 Pro Max) — use xpath or accessibility id there.
17
- const LOCATOR_STRATEGIES = ['xpath', 'id', 'accessibility id', 'class name', '-ios predicate string', 'css selector'];
19
+ // '-android uiautomator' is UiAutomator2's UiSelector locator (e.g. 'new UiSelector().resourceIdMatches(".*login")') —
20
+ // regex / partial matches xpath can't express cheaply. Verified live 2026-11-12 on Appium Server (OnePlus 6, Android 9).
21
+ const LOCATOR_STRATEGIES = ['xpath', 'id', 'accessibility id', 'class name', '-ios predicate string', '-android uiautomator', 'css selector'];
18
22
  // ─── Helpers ─────────────────────────────────────────────────────────────────
19
23
  // Returns an error result if the session is a browser (web) session — used to
20
24
  // guard mobile-only tools so they produce a clear message instead of a protocol error.
@@ -129,6 +133,25 @@ function parseElementTree(xml, platform) {
129
133
  }
130
134
  return { elements, totalNodes };
131
135
  }
136
+ /** The locator ladder applied to this screen — one recommended selector per listed element (src/utils/locator-recommend.ts). */
137
+ function recommendationLines(all, shown, platform) {
138
+ const recs = recommendLocators(all, platform);
139
+ const byElement = new Map(all.map((e, i) => [e, recs[i]]));
140
+ const MAX = 40;
141
+ const lines = [
142
+ '',
143
+ `Recommended locator per element (${platform === 'ios' ? 'accessibility id → @label xpath' : 'resource-id → accessibility id → @text xpath'}; unique on this screen — copy these into find_elements and the test):`,
144
+ ];
145
+ for (const e of shown.slice(0, MAX)) {
146
+ const what = platform === 'ios'
147
+ ? `${shortClass(e.className).replace(/^XCUIElementType/, '')} "${(e.label ?? e.name ?? e.value ?? '').slice(0, 30)}"`
148
+ : `${shortClass(e.className)} "${(e.text ?? e.contentDesc ?? (e.resourceId ? shortId(e.resourceId) : '')).slice(0, 30)}"`;
149
+ lines.push(` ${what} → ${formatRecommendation(byElement.get(e) ?? null)}`);
150
+ }
151
+ if (shown.length > MAX)
152
+ lines.push(` … ${shown.length - MAX} more — use find_elements to narrow.`);
153
+ return lines;
154
+ }
132
155
  function formatElementTable(elements, totalNodes, platform) {
133
156
  if (platform === 'ios') {
134
157
  const interesting = elements.filter((e) => e.name || e.label || e.value);
@@ -149,6 +172,9 @@ function formatElementTable(elements, totalNodes, platform) {
149
172
  if (interesting.length === 0) {
150
173
  lines.push(' (no elements with name, label, or value found on this screen)');
151
174
  }
175
+ else {
176
+ lines.push(...recommendationLines(elements, interesting, 'ios'));
177
+ }
152
178
  lines.push('', "Locate iOS elements with: strategy 'accessibility id' (matches name), xpath like //*[@label='...'] or //XCUIElementTypeButton, or on Appium Server projects '-ios predicate string' like \"label == '...'\".");
153
179
  return lines.join('\n');
154
180
  }
@@ -171,8 +197,20 @@ function formatElementTable(elements, totalNodes, platform) {
171
197
  if (interesting.length === 0) {
172
198
  lines.push(' (no elements with resource-id, content-desc, or text found on this screen)');
173
199
  }
200
+ else {
201
+ lines.push(...recommendationLines(elements, interesting, 'android'));
202
+ // Jetpack Compose exposes Modifier.testTag as resource-id only when the app opts in — a screen of texts with no ids
203
+ // is the usual sign. The fix is in the app, not the test.
204
+ if (interesting.length >= 3 && !interesting.some((e) => e.resourceId)) {
205
+ lines.push('', 'No element on this screen has a resource-id. If this is a Jetpack Compose app, ask its developers to set ' +
206
+ 'testTagsAsResourceId = true (Modifier.semantics) so Modifier.testTag values become resource-ids; until then ' +
207
+ 'use accessibility id (contentDescription) or text.');
208
+ }
209
+ }
174
210
  return lines.join('\n');
175
211
  }
212
+ /** Test seam: the element-table pipeline get_element_tree uses. */
213
+ export const __elementTreeForTests = { parseElementTree, formatElementTable };
176
214
  // ─── Tool registration ────────────────────────────────────────────────────────
177
215
  export function registerInspectionTools(server) {
178
216
  // ── start_inspection_session ──────────────────────────────────────────────
@@ -408,7 +446,12 @@ export function registerInspectionTools(server) {
408
446
  .describe('Preserve the session report (and its platform-recorded video) instead of deleting it. Default false.'),
409
447
  }, async (args) => {
410
448
  try {
411
- const { reportDeleted, reportKept, canDeleteReport, reportTestId, reportUrl, reportDeleteError } = await quitInspectionSession(args.handle, args.keepReport ?? false);
449
+ const { reportDeleted, reportKept, canDeleteReport, reportTestId, reportUrl, reportDeleteError, geolocationReset } = await quitInspectionSession(args.handle, args.keepReport ?? false);
450
+ const geoNote = geolocationReset === true
451
+ ? '\n🧭 The simulated location was reset before stopping, so the next user of this device gets its real location.'
452
+ : geolocationReset === false
453
+ ? '\n⚠️ The simulated location could not be reset before stopping — the device may still report the simulated location.'
454
+ : '';
412
455
  let text;
413
456
  if (reportKept) {
414
457
  text =
@@ -437,6 +480,7 @@ export function registerInspectionTools(server) {
437
480
  else {
438
481
  text = `✅ Session ${args.handle} stopped. Device released.`;
439
482
  }
483
+ text += geoNote;
440
484
  text +=
441
485
  '\n\n📌 If you have the View URL open in a browser, please close that tab now — ' +
442
486
  'the device has been released but the browser session may still appear connected.';
@@ -605,11 +649,16 @@ export function registerInspectionTools(server) {
605
649
  'Strategies: "id" (Android resource-id, fastest), "accessibility id" (Android content-desc; on iOS it IS the name ' +
606
650
  'attribute — identifier, else label — so it matches exactly what //*[@name=\'x\'] matches, without walking the tree; ' +
607
651
  'works on the Grid too), "-ios predicate string" (iOS on Appium Server projects only — NSPredicate such as ' +
608
- '"type == \'XCUIElementTypeButton\' AND label == \'Login\'"; the Appium Grid rejects it), "class name" (by widget ' +
652
+ '"type == \'XCUIElementTypeButton\' AND label == \'Login\'"; the Appium Grid rejects it), "-android uiautomator" ' +
653
+ '(Android on Appium Server — a UiSelector such as \'new UiSelector().resourceIdMatches(".*login")\' or ' +
654
+ '\'new UiSelector().textContains("Pay")\', for partial / regex matches), "class name" (by widget ' +
609
655
  'type, often returns many), "xpath" (most flexible, slowest — attribute matches only, never positional [1]/[2]), ' +
610
656
  '"css selector" (ONLY inside a WEBVIEW context — see webview_context). ' +
611
657
  'Prefer them in that order and copy the strategy you used into the generated test. Attributes are fetched for the first ' +
612
- 'maxResults matches (default 20); the rest are listed by elementId — narrow the selector rather than raising it.', {
658
+ 'maxResults matches (default 20); the rest are listed by elementId — narrow the selector rather than raising it. ' +
659
+ 'Android TOASTS: find xpath //android.widget.Toast[contains(@text,\'<part of the message>\')] straight after the action ' +
660
+ 'that shows it — the text check must be IN the locator: the toast element goes stale at once (reading its text ' +
661
+ 'afterwards fails) and the toast is gone within a few seconds (verified live, UiAutomator2).', {
613
662
  handle: z
614
663
  .string()
615
664
  .describe("Session handle from start_inspection_session."),
@@ -693,6 +742,10 @@ export function registerInspectionTools(server) {
693
742
  (args.strategy === '-ios predicate string' && /not supported/i.test(e.message)
694
743
  ? '\n\nThis session is on the Appium Grid, which does not support iOS predicates. Use xpath (e.g. ' +
695
744
  '//XCUIElementTypeButton[@label=\'Login\']) or accessibility id instead.'
745
+ : '') +
746
+ (args.strategy === '-android uiautomator' && /not supported|invalid selector|unknown/i.test(e.message)
747
+ ? '\n\n"-android uiautomator" needs an Android session on an Appium Server project. Use id, accessibility id ' +
748
+ 'or an attribute xpath (e.g. //*[contains(@resource-id,\'login\')]) instead.'
696
749
  : ''),
697
750
  }],
698
751
  isError: true,
@@ -731,8 +784,22 @@ export function registerInspectionTools(server) {
731
784
  server.tool('tap_element', 'Tap (click) an element on the device screen. ' +
732
785
  'Target it directly with strategy + selector (one call — the find happens internally), ' +
733
786
  'or pass an elementId from a previous find_elements call. ' +
734
- 'After tapping, call take_inspection_screenshot to verify the result.', { ...targetParams }, async (args) => {
787
+ 'x + y (instead of an element) tap a screen point — only for what has no element (a map, a canvas, a game); ' +
788
+ 'coordinates break across screen sizes, so never put them in a generated test when an element exists. ' +
789
+ 'After tapping, call take_inspection_screenshot to verify the result.', {
790
+ ...targetParams,
791
+ x: z.number().int().min(0).optional().describe('Tap a screen point instead of an element: X in the session\'s own coordinates (see take_inspection_screenshot / the window size).'),
792
+ y: z.number().int().min(0).optional().describe('Y of the screen point (with x).'),
793
+ }, async (args) => {
735
794
  try {
795
+ if (args.x != null || args.y != null) {
796
+ if (args.x == null || args.y == null)
797
+ return { content: [{ type: 'text', text: 'Error: a point tap needs both x and y.' }], isError: true };
798
+ if (args.elementId || args.selector)
799
+ return { content: [{ type: 'text', text: 'Error: pass either an element (elementId / strategy+selector) or x+y, not both.' }], isError: true };
800
+ await tapAt(args.handle, args.x, args.y);
801
+ return { content: [{ type: 'text', text: `✅ Tapped the point (${args.x}, ${args.y}).\n\nCall take_inspection_screenshot to verify the result.` }] };
802
+ }
736
803
  const target = await resolveTargetElement(args);
737
804
  if ('error' in target) {
738
805
  return { content: [{ type: 'text', text: `Error: ${target.error}` }], isError: true };
@@ -899,12 +966,17 @@ export function registerInspectionTools(server) {
899
966
  .string()
900
967
  .optional()
901
968
  .describe("Android launch activity, e.g. '.LoginActivity' — from get_application_info mainActivity; effectively required on Android Grid sessions. Ignored on iOS."),
969
+ launchArguments: z
970
+ .array(z.string())
971
+ .optional()
972
+ .describe('iOS, Appium Server only: process arguments for the app, e.g. ["-AppleLanguages", "(de)"] to open it in German, ' +
973
+ 'or the app’s own feature-flag arguments. The app is terminated first — a running app ignores launch arguments.'),
902
974
  }, async (args) => {
903
975
  const mobileErr = requireMobileSession(args.handle, 'launch_app');
904
976
  if (mobileErr)
905
977
  return mobileErr;
906
978
  try {
907
- const result = await launchApp(args.handle, args.packageName, args.activity);
979
+ const result = await launchApp(args.handle, args.packageName, args.activity, args.launchArguments);
908
980
  return {
909
981
  content: [{
910
982
  type: 'text',
@@ -1082,6 +1154,10 @@ export function registerInspectionTools(server) {
1082
1154
  .optional()
1083
1155
  .describe('Named key. Provide this OR keycode. iOS supports HOME, VOLUME_UP, VOLUME_DOWN, POWER.'),
1084
1156
  keycode: z.number().int().optional().describe('Raw Android keycode (e.g. 66 = ENTER). Android only. Provide this OR key.'),
1157
+ longPress: z
1158
+ .boolean()
1159
+ .optional()
1160
+ .describe('Android, Appium Server only: hold the key instead of tapping it (e.g. a long HOME opens the assistant).'),
1085
1161
  }, async (args) => {
1086
1162
  const mobileErr = requireMobileSession(args.handle, 'press_key');
1087
1163
  if (mobileErr)
@@ -1090,7 +1166,7 @@ export function registerInspectionTools(server) {
1090
1166
  if (!args.key && args.keycode == null) {
1091
1167
  return { content: [{ type: 'text', text: 'Error: provide either key (named) or keycode (number).' }], isError: true };
1092
1168
  }
1093
- const pressed = await pressKey(args.handle, args.key, args.keycode);
1169
+ const pressed = await pressKey(args.handle, args.key, args.keycode, args.longPress === true);
1094
1170
  return {
1095
1171
  content: [{ type: 'text', text: `✅ Pressed ${pressed}.\n\nCall take_inspection_screenshot to verify the result.` }],
1096
1172
  };
@@ -1127,17 +1203,22 @@ export function registerInspectionTools(server) {
1127
1203
  'is_installed (true/false for packageName), current (what is in the foreground: Android package + activity, iOS bundle id), ' +
1128
1204
  'install (install a repository build mid-session from appRef "cloud:<package or bundle>" / "cloud:uniqueName=<name>" — Appium Server only; ' +
1129
1205
  'this lifts the "install before the session" rule for Appium Server projects), ' +
1130
- 'clear_web_cache (seetest:client.hybridClearCache — drops the cache of the app\'s webviews; both modes). ' +
1206
+ 'clear_web_cache (seetest:client.hybridClearCache — drops the cache of the app\'s webviews; both modes), ' +
1207
+ 'permissions (Android, Appium Server: list the app\'s requested / granted / denied runtime permissions; with ' +
1208
+ 'permissionAction grant or revoke and permissions, change them first — only permissions the app declares can change, ' +
1209
+ 'and revoking one makes Android kill the app, so relaunch it with launch_app afterwards). ' +
1131
1210
  'NOTE on Grid sessions: query_state/current report only the foreground activity (Android) or are unavailable (iOS); deep_link is best-effort; ' +
1132
1211
  'background, is_installed and install are Appium Server only. To relaunch after terminate, use launch_app.', {
1133
1212
  handle: z.string().describe('Session handle from start_inspection_session.'),
1134
1213
  action: z
1135
- .enum(['terminate', 'clear_data', 'query_state', 'deep_link', 'background', 'is_installed', 'current', 'install', 'clear_web_cache'])
1214
+ .enum(['terminate', 'clear_data', 'query_state', 'deep_link', 'background', 'is_installed', 'current', 'install', 'clear_web_cache', 'permissions'])
1136
1215
  .describe('Lifecycle action to perform.'),
1216
+ permissionAction: z.enum(['list', 'grant', 'revoke']).optional().describe('For permissions: list (default), grant or revoke.'),
1217
+ permissions: z.array(z.string()).optional().describe('For permissions grant/revoke: full names, e.g. ["android.permission.CAMERA"].'),
1137
1218
  packageName: z
1138
1219
  .string()
1139
1220
  .optional()
1140
- .describe('Android package name or iOS bundle identifier. Required for terminate, clear_data, query_state, is_installed; optional Android handler hint for deep_link.'),
1221
+ .describe('Android package name or iOS bundle identifier. Required for terminate, clear_data, query_state, is_installed; for deep_link: Android handler package, or the iOS bundle id that should open the URL — com.apple.mobilesafari opens a web URL straight in Safari (no address-bar typing).'),
1141
1222
  url: z.string().optional().describe('URL or URI scheme for deep_link, e.g. "myapp://orders/42" or "https://...".'),
1142
1223
  seconds: z.number().int().min(1).max(300).optional().describe('For background: how long to keep the app in the background. Default 3.'),
1143
1224
  appRef: z.string().optional().describe('For install: repository reference — "cloud:com.example.app" (Android may add "/.MainActivity"), "cloud:uniqueName=<name>", or "cloud:<package>:releaseVersion=<v>:buildVersion=<b>".'),
@@ -1146,6 +1227,23 @@ export function registerInspectionTools(server) {
1146
1227
  if (mobileErr)
1147
1228
  return mobileErr;
1148
1229
  try {
1230
+ if (args.action === 'permissions') {
1231
+ if (!args.packageName)
1232
+ return { content: [{ type: 'text', text: 'Error: permissions requires packageName (the app\'s Android package).' }], isError: true };
1233
+ const act = args.permissionAction ?? 'list';
1234
+ if (act !== 'list' && !args.permissions?.length) {
1235
+ return { content: [{ type: 'text', text: `Error: permissions ${act} requires permissions, e.g. ["android.permission.CAMERA"].` }], isError: true };
1236
+ }
1237
+ const p = await appPermissions(args.handle, act, args.packageName, args.permissions ?? []);
1238
+ const changed = act === 'list' ? '' : (args.permissions ?? []).map((x) => `${x}: ${p.granted.includes(x) ? 'granted' : p.requested.includes(x) ? 'not granted' : 'NOT DECLARED by the app — it cannot be changed'}`).join('\n') + '\n';
1239
+ return {
1240
+ content: [{
1241
+ type: 'text',
1242
+ text: `${changed}Granted: ${p.granted.join(', ') || '(none)'}\nDenied: ${p.denied.join(', ') || '(none)'}\nRequested: ${p.requested.join(', ') || '(none)'}` +
1243
+ (act === 'revoke' ? '\nAndroid kills an app when one of its permissions is revoked — relaunch it with launch_app.' : ''),
1244
+ }],
1245
+ };
1246
+ }
1149
1247
  if (args.action === 'clear_web_cache') {
1150
1248
  await clearWebCache(args.handle);
1151
1249
  return { content: [{ type: 'text', text: '✅ Webview cache cleared (hybridClearCache).' }] };
@@ -1165,13 +1263,19 @@ export function registerInspectionTools(server) {
1165
1263
  'device_info (one call: model, OS/API level, locale, time zone, battery, screen size/scale, system bars, lock state, ' +
1166
1264
  'light/dark appearance — Appium Server), set_appearance (style dark|light: iOS appearance / Android night mode — ' +
1167
1265
  'dark-mode screenshot checks), accessibility_audit (iOS: XCTest\'s built-in audit of the current screen, no extra ' +
1168
- 'dependency; Android: use includeAxeScan in get_test_boilerplate). ' +
1266
+ 'dependency; Android: use includeAxeScan in get_test_boilerplate), shell (Android Appium Server: adb shell ' +
1267
+ 'command — getprop, dumpsys <service>, settings get, pm list/path, wm size run directly (device log: get_device_log); anything that can change ' +
1268
+ 'the shared device, or uses shell operators, returns a preview until confirmChange: true). ' +
1169
1269
  'Grid session limits: alerts and reset_geolocation are not supported, and iOS Grid devices reject clipboard ops ' +
1170
1270
  '(clear errors explain alternatives). iOS file paths may require the @bundleId:container syntax.', {
1171
1271
  handle: z.string().describe('Session handle from start_inspection_session.'),
1172
1272
  action: z
1173
- .enum(['get_orientation', 'set_orientation', 'get_clipboard', 'set_clipboard', 'set_geolocation', 'reset_geolocation', 'get_alert', 'accept_alert', 'dismiss_alert', 'push_file', 'pull_file', 'device_info', 'set_appearance', 'accessibility_audit'])
1273
+ .enum(['get_orientation', 'set_orientation', 'get_clipboard', 'set_clipboard', 'set_geolocation', 'reset_geolocation', 'get_alert', 'accept_alert', 'dismiss_alert', 'push_file', 'pull_file', 'device_info', 'set_appearance', 'accessibility_audit', 'shell'])
1174
1274
  .describe('Device action to perform.'),
1275
+ command: z.string().optional().describe('For shell: the adb shell command, e.g. "dumpsys battery", "getprop ro.build.version.release", ' +
1276
+ '"settings get global airplane_mode_on". Put everything in this string (no separate args needed).'),
1277
+ confirmChange: z.boolean().optional().describe('For shell: set true only after the user agreed to a command that changes the device (the first call returns ' +
1278
+ 'a preview saying why). Read-only commands never need it.'),
1175
1279
  orientation: z.enum(['PORTRAIT', 'LANDSCAPE']).optional().describe('For set_orientation.'),
1176
1280
  style: z.enum(['dark', 'light']).optional().describe('For set_appearance.'),
1177
1281
  text: z.string().optional().describe('For set_clipboard: the text to place on the clipboard.'),
@@ -1239,6 +1343,18 @@ export function registerInspectionTools(server) {
1239
1343
  const lines = findings.slice(0, 30).map((f, i) => `${i + 1}. ${String(f.type ?? f.auditType ?? 'issue')}: ${String(f.detailedDescription ?? f.compactDescription ?? f.elementDescription ?? '').split('\n')[0].slice(0, 200)}`);
1240
1344
  return { content: [{ type: 'text', text: findings.length ? `${findings.length} accessibility finding(s) on this screen:\n${lines.join('\n')}${findings.length > 30 ? `\n… ${findings.length - 30} more` : ''}` : 'No accessibility findings on this screen.' }] };
1241
1345
  }
1346
+ case 'shell': {
1347
+ if (!args.command?.trim())
1348
+ return { content: [{ type: 'text', text: 'Error: shell requires command, e.g. "dumpsys battery".' }], isError: true };
1349
+ const problem = shellCommandProblem(args.command);
1350
+ if (problem)
1351
+ return { content: [{ type: 'text', text: `Error: ${problem}` }], isError: true };
1352
+ const c = classifyShellCommand(args.command.trim());
1353
+ if (!c.readOnly && args.confirmChange !== true)
1354
+ return { content: [{ type: 'text', text: shellGuardMessage(c) }] };
1355
+ const out = await adbShell(args.handle, c.commandLine);
1356
+ return { content: [{ type: 'text', text: `$ adb shell ${c.commandLine}\n${capShellOutput(out.trimEnd()) || '(no output)'}` }] };
1357
+ }
1242
1358
  case 'get_alert': {
1243
1359
  const a = await getAlertInfo(args.handle);
1244
1360
  return { content: [{ type: 'text', text: `Alert text: ${JSON.stringify(a.text)}${a.buttons ? `\nButtons: ${a.buttons.map((b) => `"${b}"`).join(', ')} — press one with accept_alert + buttonLabel` : ''}` }] };