appium-mcp 1.98.0 → 1.99.1

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 (54) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +30 -0
  3. package/dist/locators/element-filter.d.ts +3 -1
  4. package/dist/locators/element-filter.d.ts.map +1 -1
  5. package/dist/locators/element-filter.js +44 -14
  6. package/dist/locators/element-filter.js.map +1 -1
  7. package/dist/locators/generate-all-locators.d.ts +6 -1
  8. package/dist/locators/generate-all-locators.d.ts.map +1 -1
  9. package/dist/locators/generate-all-locators.js +1 -1
  10. package/dist/locators/generate-all-locators.js.map +1 -1
  11. package/dist/locators/locator-generation.d.ts +4 -3
  12. package/dist/locators/locator-generation.d.ts.map +1 -1
  13. package/dist/locators/locator-generation.js +31 -10
  14. package/dist/locators/locator-generation.js.map +1 -1
  15. package/dist/locators/types.d.ts +3 -0
  16. package/dist/locators/types.d.ts.map +1 -0
  17. package/dist/locators/types.js +2 -0
  18. package/dist/locators/types.js.map +1 -0
  19. package/dist/tools/gestures/schema.d.ts.map +1 -1
  20. package/dist/tools/gestures/schema.js +7 -15
  21. package/dist/tools/gestures/schema.js.map +1 -1
  22. package/dist/tools/interactions/screen-recording.d.ts.map +1 -1
  23. package/dist/tools/interactions/screen-recording.js +4 -1
  24. package/dist/tools/interactions/screen-recording.js.map +1 -1
  25. package/dist/tools/test-generation/locators.d.ts.map +1 -1
  26. package/dist/tools/test-generation/locators.js +19 -5
  27. package/dist/tools/test-generation/locators.js.map +1 -1
  28. package/dist/ui/inspector-screenshot-script.d.ts +3 -0
  29. package/dist/ui/inspector-screenshot-script.d.ts.map +1 -0
  30. package/dist/ui/inspector-screenshot-script.js +164 -0
  31. package/dist/ui/inspector-screenshot-script.js.map +1 -0
  32. package/dist/ui/mcp-ui-utils.d.ts.map +1 -1
  33. package/dist/ui/mcp-ui-utils.js +14 -73
  34. package/dist/ui/mcp-ui-utils.js.map +1 -1
  35. package/dist/ui/page-source-inspector-app.d.ts.map +1 -1
  36. package/dist/ui/page-source-inspector-app.js +79 -75
  37. package/dist/ui/page-source-inspector-app.js.map +1 -1
  38. package/dist/ui/xml-inspector-scripts.d.ts +4 -0
  39. package/dist/ui/xml-inspector-scripts.d.ts.map +1 -0
  40. package/dist/ui/xml-inspector-scripts.js +91 -0
  41. package/dist/ui/xml-inspector-scripts.js.map +1 -0
  42. package/package.json +1 -1
  43. package/server.json +2 -2
  44. package/src/locators/element-filter.ts +50 -16
  45. package/src/locators/generate-all-locators.ts +13 -7
  46. package/src/locators/locator-generation.ts +43 -10
  47. package/src/locators/types.ts +2 -0
  48. package/src/tools/gestures/schema.ts +7 -17
  49. package/src/tools/interactions/screen-recording.ts +4 -1
  50. package/src/tools/test-generation/locators.ts +31 -7
  51. package/src/ui/inspector-screenshot-script.ts +163 -0
  52. package/src/ui/mcp-ui-utils.ts +15 -73
  53. package/src/ui/page-source-inspector-app.ts +80 -75
  54. package/src/ui/xml-inspector-scripts.ts +91 -0
@@ -7,6 +7,7 @@ import log from '../logger.js';
7
7
  import {isEmpty, omitNilValues} from '../utils/collection.js';
8
8
  import {childNodesOf, domToXML, findDOMNodeByPath, xmlToDOM} from './source-parsing.js';
9
9
  import type {JSONElement, ElementAttributes} from './source-parsing.js';
10
+ import type {DriverName} from './types.js';
10
11
 
11
12
  // Attributes on nodes that are likely to be unique to the node so we should consider first when
12
13
  // suggesting xpath locators. These are considered IN ORDER.
@@ -84,7 +85,8 @@ export function getComplexSuggestedLocators(
84
85
  path: string,
85
86
  sourceDoc: XMLDocument,
86
87
  isNative: boolean,
87
- automationName: string,
88
+ automationName: DriverName,
89
+ xpathAttributes: string[] = [],
88
90
  ): Record<string, string> {
89
91
  const complexLocators: Record<string, string | null> = {};
90
92
  const domNode = findDOMNodeByPath(path, sourceDoc);
@@ -103,7 +105,7 @@ export function getComplexSuggestedLocators(
103
105
  }
104
106
  }
105
107
  }
106
- complexLocators.xpath = getOptimalXPath(sourceDoc, domNode);
108
+ complexLocators.xpath = getOptimalXPath(sourceDoc, domNode, xpathAttributes);
107
109
 
108
110
  // Remove entries for locators where the optimal selector could not be found
109
111
  return omitNilValues(complexLocators);
@@ -116,11 +118,18 @@ export function getSuggestedLocators(
116
118
  selectedElement: JSONElement,
117
119
  sourceXML: string,
118
120
  isNative: boolean,
119
- automationName: string,
121
+ automationName: DriverName,
122
+ xpathAttributes: string[] = [],
120
123
  ): [string, string][] {
121
124
  const sourceDoc = xmlToDOM(sourceXML);
122
125
  const simpleLocators = getSimpleSuggestedLocators(selectedElement.attributes, sourceDoc, isNative);
123
- const complexLocators = getComplexSuggestedLocators(selectedElement.path, sourceDoc, isNative, automationName);
126
+ const complexLocators = getComplexSuggestedLocators(
127
+ selectedElement.path,
128
+ sourceDoc,
129
+ isNative,
130
+ automationName,
131
+ xpathAttributes,
132
+ );
124
133
 
125
134
  // Combine all locators
126
135
  const allLocators = {...simpleLocators, ...complexLocators};
@@ -171,14 +180,20 @@ export function getSuggestedLocators(
171
180
  /**
172
181
  * Get an optimal XPath for a Node
173
182
  */
174
- export function getOptimalXPath(doc: XMLDocument, domNode: XMLNode): string | null {
183
+ export function getOptimalXPath(doc: XMLDocument, domNode: XMLNode, xpathAttributes: string[] = []): string | null {
175
184
  try {
176
185
  // BASE CASE #1: If this isn't an element, we're above the root, return empty string
177
186
  if (!domNode.nodeName || domNode.nodeType !== 1) {
178
187
  return '';
179
188
  }
180
189
 
181
- const attrsForPairs = [...UNIQUE_XPATH_ATTRIBUTES, ...MAYBE_UNIQUE_XPATH_ATTRIBUTES];
190
+ // Attribute names are data, not XPath expressions. Namespaced attributes need
191
+ // namespace resolution and are intentionally not accepted here.
192
+ if (xpathAttributes.some((name) => !/^[A-Za-z_][A-Za-z0-9_.-]*$/.test(name))) {
193
+ throw new Error('Invalid XPath attribute name');
194
+ }
195
+ const preferredAttributes = [...new Set([...xpathAttributes, ...UNIQUE_XPATH_ATTRIBUTES])];
196
+ const attrsForPairs = [...new Set([...preferredAttributes, ...MAYBE_UNIQUE_XPATH_ATTRIBUTES])];
182
197
  const attrPairsPermutations: [string, string][] = attrsForPairs.flatMap((v1, i) =>
183
198
  attrsForPairs.slice(i + 1).map((v2) => [v1, v2] as [string, string]),
184
199
  );
@@ -186,7 +201,7 @@ export function getOptimalXPath(doc: XMLDocument, domNode: XMLNode): string | nu
186
201
  const cases = [
187
202
  // BASE CASE #2: If this node has a unique attribute or content attribute, return an absolute
188
203
  // XPath with that attribute
189
- UNIQUE_XPATH_ATTRIBUTES,
204
+ preferredAttributes,
190
205
 
191
206
  // BASE CASE #3: If this node has a unique pair of attributes including 'maybe' attributes,
192
207
  // return an xpath based on that pair
@@ -246,7 +261,7 @@ export function getOptimalXPath(doc: XMLDocument, domNode: XMLNode): string | nu
246
261
  }
247
262
 
248
263
  // Make a recursive call to this nodes parents and prepend it to this xpath
249
- return (domNode.parentNode ? getOptimalXPath(doc, domNode.parentNode) : '') + xpath;
264
+ return (domNode.parentNode ? getOptimalXPath(doc, domNode.parentNode, xpathAttributes) : '') + xpath;
250
265
  } catch (error) {
251
266
  // If there's an unexpected exception, abort
252
267
  logLocatorError('XPath', error);
@@ -514,13 +529,13 @@ function getUniqueXPath(
514
529
  if (!attr1Value || !attr2Value) {
515
530
  continue;
516
531
  }
517
- xpath = `//${tagForXpath}[@${attr1Name}="${attr1Value}" and @${attr2Name}="${attr2Value}"]`;
532
+ xpath = `//${tagForXpath}[@${attr1Name}=${xpathLiteral(attr1Value)} and @${attr2Name}=${xpathLiteral(attr2Value)}]`;
518
533
  } else {
519
534
  const attrValue = (domNode as XMLElement).getAttribute?.(attrName as string);
520
535
  if (!attrValue) {
521
536
  continue;
522
537
  }
523
- xpath = `//${tagForXpath}[@${attrName}="${attrValue}"]`;
538
+ xpath = `//${tagForXpath}[@${attrName}=${xpathLiteral(attrValue)}]`;
524
539
  }
525
540
  const [isUnique, indexIfNotUnique] = determineXpathUniqueness(xpath, doc, domNode);
526
541
  if (isUnique) {
@@ -547,3 +562,21 @@ function getUniqueXPath(
547
562
  function logLocatorError(strategy: string, error: any): void {
548
563
  log.error(`The most optimal ${strategy} could not be determined because an error was thrown: '${error}'`);
549
564
  }
565
+
566
+ /** XPath 1.0 has no backslash escaping; mixed quotes require concat(). */
567
+ function xpathLiteral(value: string): string {
568
+ if (!value.includes('"')) {
569
+ return `"${value}"`;
570
+ }
571
+ if (!value.includes("'")) {
572
+ return `'${value}'`;
573
+ }
574
+ return (
575
+ 'concat(' +
576
+ value
577
+ .split('"')
578
+ .map((part) => `"${part}"`)
579
+ .join(`, '"', `) +
580
+ ')'
581
+ );
582
+ }
@@ -0,0 +1,2 @@
1
+ /** A lowercase automation driver name, including custom drivers. */
2
+ export type DriverName = Lowercase<string>;
@@ -43,19 +43,12 @@ export const gestureSchema = z.object({
43
43
  .enum(GESTURE_ACTIONS)
44
44
  .describe(
45
45
  [
46
- 'Gesture to perform:',
47
- '- tap: tap an element or a coordinate.',
48
- '- double_tap: double-tap, for example to zoom an image or favorite a post.',
49
- '- long_press: press and hold to open a context menu or initiate a drag.',
50
- 'For tap/double_tap/long_press, provide elementUUID or both x and y.',
51
- '- scroll: browse a list, feed, or page to reveal content.',
52
- '- swipe: dismiss a card, switch screens or tabs, navigate a carousel, or pull-to-refresh (use speed=fast).',
53
- 'For scroll/swipe, provide direction or all four custom coordinates: x, y, endX, endY.',
54
- '- pinch_zoom: zoom in (scale > 1) or out (scale < 1) on maps, images, or other zoomable views. Requires scale.',
55
- '- scroll_to_element: scroll to find a target using strategy and selector. Direction is up/down, default down.',
56
- 'Stops when the element is found, page source is unchanged after a scroll (likely end of content), or maxScrollAttempts is reached.',
57
- 'Adjust distance with scrollDistance (0.05–1) or scrollDistancePreset (small/medium/large).',
58
- '- back: trigger system back navigation.',
46
+ 'tap/double_tap/long_press: requires elementUUID or both x/y.',
47
+ 'scroll/swipe: requires direction or x/y/endX/endY.',
48
+ 'pinch_zoom: requires scale (<1 out, >1 in).',
49
+ 'scroll_to_element: requires strategy/selector; direction up/down (default down).',
50
+ 'Stops on a match, unchanged page source, or maxScrollAttempts. Adjust distance with scrollDistance or scrollDistancePreset.',
51
+ 'back: system back navigation.',
59
52
  ].join('\n'),
60
53
  ),
61
54
 
@@ -130,10 +123,7 @@ export const gestureSchema = z.object({
130
123
  .min(0.01)
131
124
  .max(10)
132
125
  .optional()
133
- .describe(
134
- 'Required for pinch_zoom. Scale < 1 zooms out (fingers close); scale > 1 zooms in (fingers spread). ' +
135
- 'Examples: 0.5 zooms out; 2.0 zooms in 2x.',
136
- ),
126
+ .describe('Required for pinch_zoom: <1 zooms out, >1 zooms in (e.g. 0.5 or 2 for 2x).'),
137
127
  velocity: z
138
128
  .number()
139
129
  .min(0.1)
@@ -80,9 +80,12 @@ const screenRecordingSchema = z.object({
80
80
  videoScale: z
81
81
  .string()
82
82
  .regex(
83
- /^(?:[1-9]\d{0,4}|-[12]):(?:[1-9]\d{0,4}|-[12])(?![\s\S])/,
83
+ /^(?:[1-9]\d{0,4}|-[12]):(?:[1-9]\d{0,4}|-[12])$/,
84
84
  'Use width:height (e.g. 1280:720 or -2:720), without filter expressions.',
85
85
  )
86
+ // JavaScript's $ also matches before a final line terminator. Reject it at
87
+ // runtime so the advertised JSON Schema pattern stays free of lookaround.
88
+ .refine((value) => value === value.trim(), 'Dimensions must not contain surrounding whitespace.')
86
89
  .refine((value) => {
87
90
  const dimensions = value.split(':').map(Number);
88
91
  return dimensions.every((dimension) => dimension <= 16384) && dimensions.some((dimension) => dimension > 0);
@@ -14,6 +14,7 @@ import {z} from 'zod';
14
14
 
15
15
  import {getCurrentContext, getPageSource} from '../../command.js';
16
16
  import {generateAllElementLocators} from '../../locators/generate-all-locators.js';
17
+ import type {DriverName} from '../../locators/types.js';
17
18
  import {LOCATOR_GENERATOR_URI} from '../../resources/locator-generator.js';
18
19
  import {isAndroidUiautomator2DriverSession, isXCUITestDriverSession} from '../../session-store.js';
19
20
  import {clientSupportsMcpApps, isMcpAppsEnabled} from '../../ui/mcp-apps.js';
@@ -24,16 +25,37 @@ export default function generateLocators(server: FastMCP): void {
24
25
  const mcpAppsEnabled = isMcpAppsEnabled();
25
26
  server.addTool({
26
27
  name: 'generate_locators',
27
- description: `Generate locators for all interactable elements on the current page. [PRIORITY 3: Use this for debugging/inspection or when you need comprehensive element info with locator suggestions]`,
28
+ description: `Generate current-page locator candidates for inspection. Defaults: controls for UiAutomator2/XCUITest/Web; all elements except hierarchy for other native drivers.`,
28
29
  _meta: mcpAppsEnabled ? {ui: {resourceUri: LOCATOR_GENERATOR_URI}} : undefined,
29
30
  parameters: z.object({
31
+ query: z
32
+ .string()
33
+ .optional()
34
+ .describe(
35
+ 'Case-insensitive literal substring of an element tag or attribute value (name, label, text, ID, etc.). Searches all element types, including hidden elements. Blank or omitted keeps the default driver-specific filter.',
36
+ ),
37
+ xpathAttributes: z
38
+ .array(
39
+ z
40
+ .string()
41
+ .trim()
42
+ .regex(/^[A-Za-z_][A-Za-z0-9_.-]*$/),
43
+ )
44
+ .max(20)
45
+ .optional()
46
+ .describe(
47
+ 'Additional XPath attribute names in priority order, e.g. AutomationId or data-testid. Tried before built-in attributes; defaults remain as fallback. No namespace prefixes or XPath expressions.',
48
+ ),
30
49
  sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
31
50
  }),
32
51
  annotations: {
33
52
  readOnlyHint: true,
34
53
  openWorldHint: false,
35
54
  },
36
- execute: async (args: {sessionId?: string}, context: any): Promise<any> => {
55
+ execute: async (
56
+ args: {sessionId?: string; query?: string; xpathAttributes?: string[]},
57
+ context: any,
58
+ ): Promise<any> => {
37
59
  const {log} = context;
38
60
  log.info('Getting page source');
39
61
  const resolved = await resolveDriver(args.sessionId);
@@ -54,20 +76,22 @@ export default function generateLocators(server: FastMCP): void {
54
76
  : driver.capabilities;
55
77
  const driverName = String(
56
78
  capabilities['appium:automationName'] ?? capabilities.automationName ?? '',
57
- ).toLowerCase();
79
+ ).toLowerCase() as DriverName;
58
80
  // Read the driver's current context: a cached NATIVE_APP value can be stale
59
81
  // after attaching to a session that already has an active WebView.
60
82
  const isNative = ['uiautomator2', 'xcuitest'].includes(driverName)
61
83
  ? (await getCurrentContext(driver)) === 'NATIVE_APP'
62
84
  : !capabilities.browserName;
63
85
 
64
- const interactableElements = generateAllElementLocators(pageSource, isNative, driverName, {
65
- fetchableOnly: true,
86
+ const query = args.query?.trim();
87
+ const elementsWithLocators = generateAllElementLocators(pageSource, isNative, driverName, {
88
+ ...(query ? {query, fetchableOnly: false} : {fetchableOnly: true}),
89
+ ...(args.xpathAttributes?.length ? {xpathAttributes: [...new Set(args.xpathAttributes)]} : {}),
66
90
  });
67
91
 
68
92
  const textResponse = textResult(
69
93
  JSON.stringify({
70
- interactableElements,
94
+ interactableElements: elementsWithLocators,
71
95
  message: 'Page source retrieved successfully',
72
96
  instruction: `These are the locators for the current page. Use this to generate code for the current page.
73
97
  Using the template provided by generate://code-with-locators resource.`,
@@ -83,7 +107,7 @@ export default function generateLocators(server: FastMCP): void {
83
107
  return addUIResourceToResponse(textResponse, () =>
84
108
  createUIResource(
85
109
  `ui://appium-mcp/locator-generator/${Date.now()}`,
86
- createLocatorGeneratorUI(interactableElements),
110
+ createLocatorGeneratorUI(elementsWithLocators),
87
111
  ),
88
112
  );
89
113
  } catch (err: unknown) {
@@ -0,0 +1,163 @@
1
+ /** Browser controller for the optional screenshot and XML bounds overlay. */
2
+ export const INSPECTOR_SCREENSHOT_SCRIPT = String.raw`
3
+ function createScreenshotInspector(callTool, setSource, readSourceResult) {
4
+ const button = document.getElementById('takeScreenshotButton');
5
+ const panel = document.getElementById('screenshotPanel');
6
+ const image = document.getElementById('inspectorScreenshot');
7
+ const overlay = document.getElementById('elementOverlay');
8
+ const select = document.getElementById('screenshotElement');
9
+ const status = document.getElementById('screenshotStatus');
10
+ const details = document.getElementById('selectedXmlElement');
11
+ let elements = [];
12
+ let screen;
13
+ let query = '';
14
+
15
+ function readBounds(element) {
16
+ // Drivers differ in attribute casing. Prefer the exact lowercase spelling if both exist.
17
+ function attribute(name) {
18
+ if (element.hasAttribute(name)) return element.getAttribute(name);
19
+ return Array.from(element.attributes).find(attr => attr.name.toLowerCase() === name)?.value;
20
+ }
21
+ const android = (attribute('bounds') || '').match(/^\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]$/);
22
+ if (android) {
23
+ const [, x, y, right, bottom] = android.map(Number);
24
+ return {x, y, width: right - x, height: bottom - y};
25
+ }
26
+ const coordinates = ['x', 'y', 'width', 'height'].map(attribute);
27
+ if (!coordinates.every(value => value !== undefined && value.trim() !== '')) return;
28
+ const values = coordinates.map(Number);
29
+ if (!values.every(Number.isFinite)) return;
30
+ const [x, y, width, height] = values;
31
+ return {x, y, width, height};
32
+ }
33
+
34
+ function showSelection() {
35
+ overlay.hidden = true;
36
+ details.textContent = '';
37
+ if (!select.value) return;
38
+ const element = elements[Number(select.value) - 1];
39
+ if (!element) return;
40
+ // Display only the selected opening tag, not its entire subtree.
41
+ const clone = element.cloneNode(false);
42
+ details.textContent = new XMLSerializer().serializeToString(clone);
43
+ if (!screen) {
44
+ status.textContent = 'Take a screenshot to highlight this element.';
45
+ return;
46
+ }
47
+ const rect = readBounds(element);
48
+ if (!rect || rect.width <= 0 || rect.height <= 0) {
49
+ status.textContent = 'This element has no usable screen bounds.';
50
+ return;
51
+ }
52
+ if (element.getAttribute('visible') === 'false' || element.getAttribute('displayed') === 'false') {
53
+ status.textContent = 'This element is marked hidden in the XML.';
54
+ return;
55
+ }
56
+ const left = Math.max(0, rect.x);
57
+ const top = Math.max(0, rect.y);
58
+ const right = Math.min(screen.width, rect.x + rect.width);
59
+ const bottom = Math.min(screen.height, rect.y + rect.height);
60
+ if (right <= left || bottom <= top) {
61
+ status.textContent = 'This element is outside the captured screen.';
62
+ return;
63
+ }
64
+ overlay.style.left = (left / screen.width * 100) + '%';
65
+ overlay.style.top = (top / screen.height * 100) + '%';
66
+ overlay.style.width = ((right - left) / screen.width * 100) + '%';
67
+ overlay.style.height = ((bottom - top) / screen.height * 100) + '%';
68
+ overlay.hidden = false;
69
+ status.textContent = 'XML bounds: x=' + rect.x + ', y=' + rect.y + ', width=' + rect.width + ', height=' + rect.height;
70
+ }
71
+
72
+ function filter(nextQuery) {
73
+ query = nextQuery.trim().toLowerCase();
74
+ const previous = select.value;
75
+ select.textContent = '';
76
+ const placeholder = document.createElement('option');
77
+ placeholder.value = '';
78
+ placeholder.textContent = 'Select an XML element to highlight';
79
+ select.appendChild(placeholder);
80
+ let retained = false;
81
+ elements.forEach((element, index) => {
82
+ const attributes = Array.from(element.attributes).map(attr => attr.value);
83
+ if (query && ![element.tagName, ...attributes].some(value => value.toLowerCase().includes(query))) return;
84
+ const option = document.createElement('option');
85
+ option.value = String(index + 1);
86
+ const name = element.getAttribute('name') || element.getAttribute('label') || element.getAttribute('text') || element.getAttribute('resource-id') || element.getAttribute('id');
87
+ option.textContent = (index + 1) + '. ' + element.tagName + (name ? ' — ' + name : '');
88
+ select.appendChild(option);
89
+ if (option.value === previous) retained = true;
90
+ });
91
+ select.value = retained ? previous : '';
92
+ showSelection();
93
+ }
94
+
95
+ function updateSource(source) {
96
+ screen = undefined;
97
+ image.hidden = true;
98
+ overlay.hidden = true;
99
+ elements = [];
100
+ select.value = '';
101
+ if (source.trim().startsWith('<')) {
102
+ const doc = new DOMParser().parseFromString(source, 'text/xml');
103
+ if (!doc.getElementsByTagName('parsererror').length) elements = Array.from(doc.getElementsByTagName('*'));
104
+ }
105
+ filter(query);
106
+ status.textContent = 'XML updated. Take a screenshot to refresh the preview.';
107
+ }
108
+
109
+ function assertSuccess(result) {
110
+ if (result?.isError) throw new Error((result.content || []).filter(item => item.type === 'text').map(item => item.text).join('\n') || 'Tool failed');
111
+ return result;
112
+ }
113
+
114
+ async function capture() {
115
+ if (button.disabled) return;
116
+ button.disabled = true;
117
+ panel.hidden = false;
118
+ screen = undefined;
119
+ image.hidden = true;
120
+ overlay.hidden = true;
121
+ status.textContent = 'Capturing screenshot and refreshing XML…';
122
+ try {
123
+ const sourceResult = assertSuccess(await callTool('appium_get_page_source', {saveToFile: false}));
124
+ const sizeResult = assertSuccess(await callTool('appium_get_window_size', {}));
125
+ const result = assertSuccess(await callTool('appium_screenshot', {returnRawBase64: true}));
126
+ const sizeText = (sizeResult.content || []).filter(item => item.type === 'text').map(item => item.text).join(' ');
127
+ const size = sizeText.match(/Width:\s*([\d.]+),\s*Height:\s*([\d.]+)/);
128
+ if (!size || !(Number(size[1]) > 0 && Number(size[2]) > 0)) throw new Error('Screen size is unavailable');
129
+ const picture = result.structuredContent?.screenshot || (result.content || []).find(item => item.type === 'image');
130
+ if (!picture?.data || !['image/png', 'image/jpeg'].includes(picture.mimeType)) throw new Error('No supported screenshot returned');
131
+ setSource(readSourceResult(sourceResult));
132
+ screen = {width: Number(size[1]), height: Number(size[2])};
133
+ image.src = 'data:' + picture.mimeType + ';base64,' + picture.data;
134
+ image.hidden = false;
135
+ status.textContent = 'Select an XML element below. Search filters the list.';
136
+ } catch (error) {
137
+ status.textContent = 'Screenshot failed: ' + error.message;
138
+ } finally {
139
+ button.disabled = false;
140
+ }
141
+ }
142
+
143
+ image.addEventListener('load', () => {
144
+ if (!screen) return;
145
+ // Pixel density is handled by percentages; orientation changes are not.
146
+ const ratio = image.naturalWidth / image.naturalHeight;
147
+ if (Math.abs(ratio / (screen.width / screen.height) - 1) > 0.03) {
148
+ screen = undefined;
149
+ overlay.hidden = true;
150
+ status.textContent = 'Screenshot and screen dimensions differ. Capture again before highlighting.';
151
+ }
152
+ });
153
+ image.addEventListener('error', () => {
154
+ screen = undefined;
155
+ image.hidden = true;
156
+ overlay.hidden = true;
157
+ status.textContent = 'Unable to display screenshot.';
158
+ });
159
+ button.addEventListener('click', capture);
160
+ select.addEventListener('change', showSelection);
161
+ return {updateSource, filter};
162
+ }
163
+ `;
@@ -1,3 +1,5 @@
1
+ import {XML_FORMAT_SCRIPT, XML_SEARCH_SCRIPT} from './xml-inspector-scripts.js';
2
+
1
3
  /**
2
4
  * MCP-UI Utility Functions
3
5
  *
@@ -1022,6 +1024,10 @@ export function createPageSourceInspectorUI(pageSource: string): string {
1022
1024
  outline: none;
1023
1025
  border-color: #007AFF;
1024
1026
  }
1027
+ mark { background: #ffd700; color: #000; }
1028
+ mark[data-active] { outline: 2px solid #91baff; background: #ff963c; }
1029
+ .search-status { padding: 6px 16px; font-size: 12px; color: #bbb; }
1030
+ .search-status:empty { display: none; }
1025
1031
  </style>
1026
1032
  </head>
1027
1033
  <body>
@@ -1038,11 +1044,14 @@ export function createPageSourceInspectorUI(pageSource: string): string {
1038
1044
  <button class="btn" onclick="generateLocators()">Generate Locators</button>
1039
1045
  </div>
1040
1046
  </div>
1047
+ <div id="searchStatus" class="search-status" role="status" aria-live="polite"></div>
1041
1048
  <div class="viewer" title="Drag the bottom-right corner to resize vertically">
1042
1049
  <pre class="xml-content" id="xmlContent">${escapedSource}</pre>
1043
1050
  </div>
1044
1051
  </details>
1045
1052
  <script>
1053
+ ${XML_FORMAT_SCRIPT}
1054
+ ${XML_SEARCH_SCRIPT}
1046
1055
  function copyToClipboard() {
1047
1056
  const text = document.getElementById('xmlContent').textContent;
1048
1057
  navigator.clipboard.writeText(text).then(() => {
@@ -1052,44 +1061,7 @@ export function createPageSourceInspectorUI(pageSource: string): string {
1052
1061
 
1053
1062
  function formatXML() {
1054
1063
  try {
1055
- const parser = new DOMParser();
1056
- const xmlDoc = parser.parseFromString(originalSource, 'text/xml');
1057
- if (!xmlDoc.documentElement || xmlDoc.getElementsByTagName('parsererror').length) {
1058
- throw new Error('Invalid XML');
1059
- }
1060
-
1061
- function indentElement(element, depth) {
1062
- // Do not introduce whitespace into mixed content or preserved subtrees.
1063
- if (element.getAttribute('xml:space') === 'preserve') return;
1064
- const children = Array.from(element.childNodes);
1065
- if (children.some(child =>
1066
- child.nodeType === 4 || (child.nodeType === 3 && child.nodeValue.trim())
1067
- )) return;
1068
- if (!children.some(child => child.nodeType === 1)) return;
1069
-
1070
- for (const child of children) {
1071
- if (child.nodeType === 3) {
1072
- element.removeChild(child);
1073
- continue;
1074
- }
1075
- if (child.nodeType === 1) indentElement(child, depth + 1);
1076
- element.insertBefore(xmlDoc.createTextNode('\\n' + ' '.repeat(depth + 1)), child);
1077
- }
1078
- element.appendChild(xmlDoc.createTextNode('\\n' + ' '.repeat(depth)));
1079
- }
1080
-
1081
- indentElement(xmlDoc.documentElement, 0);
1082
- const serializer = new XMLSerializer();
1083
- let formatted = Array.from(xmlDoc.childNodes)
1084
- .filter(node => node.nodeType !== 3)
1085
- .map(node => serializer.serializeToString(node))
1086
- .join('\\n');
1087
- // Browser DOMParser does not retain the XML declaration.
1088
- const declaration = originalSource.match(/^\\s*(<\\?xml\\s[^?]*\\?>)/);
1089
- if (declaration && !formatted.startsWith('<?xml ')) {
1090
- formatted = declaration[1] + '\\n' + formatted;
1091
- }
1092
- displayedSource = formatted;
1064
+ displayedSource = formatXml(originalSource);
1093
1065
  renderSource(document.getElementById('searchBox').value);
1094
1066
  } catch (e) {
1095
1067
  alert('Failed to format XML');
@@ -1101,7 +1073,7 @@ export function createPageSourceInspectorUI(pageSource: string): string {
1101
1073
  type: 'tool',
1102
1074
  payload: {
1103
1075
  toolName: 'generate_locators',
1104
- params: {}
1076
+ params: {query: document.getElementById('searchBox').value.trim()}
1105
1077
  }
1106
1078
  }, '*');
1107
1079
  }
@@ -1110,42 +1082,12 @@ export function createPageSourceInspectorUI(pageSource: string): string {
1110
1082
  const originalSource = xmlContent.textContent;
1111
1083
  let displayedSource = originalSource;
1112
1084
 
1113
- function appendTextWithHighlights(container, text, searchTerm) {
1114
- const searchLower = searchTerm.toLowerCase();
1115
- const textLower = text.toLowerCase();
1116
- let position = 0;
1117
-
1118
- while (position < text.length) {
1119
- const matchIndex = textLower.indexOf(searchLower, position);
1120
- if (matchIndex === -1) {
1121
- container.appendChild(document.createTextNode(text.slice(position)));
1122
- return;
1123
- }
1124
-
1125
- if (matchIndex > position) {
1126
- container.appendChild(
1127
- document.createTextNode(text.slice(position, matchIndex))
1128
- );
1129
- }
1130
-
1131
- const mark = document.createElement('mark');
1132
- mark.style.background = '#ffd700';
1133
- mark.style.color = '#000';
1134
- mark.textContent = text.slice(matchIndex, matchIndex + searchTerm.length);
1135
- container.appendChild(mark);
1136
- position = matchIndex + searchTerm.length;
1137
- }
1138
- }
1139
-
1085
+ const searchBox = document.getElementById('searchBox');
1086
+ const xmlSearch = createXmlSearch(xmlContent, document.getElementById('searchStatus'));
1140
1087
  function renderSource(searchTerm = '') {
1141
- xmlContent.textContent = '';
1142
- if (!searchTerm) {
1143
- xmlContent.textContent = displayedSource;
1144
- return;
1145
- }
1146
-
1147
- appendTextWithHighlights(xmlContent, displayedSource, searchTerm);
1088
+ xmlSearch.render(displayedSource, searchTerm);
1148
1089
  }
1090
+ searchBox.addEventListener('keydown', xmlSearch.handleKeyDown);
1149
1091
 
1150
1092
  // Search functionality
1151
1093
  document.getElementById('searchBox').addEventListener('input', (e) => {