appium-mcp 1.97.2 → 1.99.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 (55) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +55 -2
  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/telemetry/init.d.ts +2 -0
  20. package/dist/telemetry/init.d.ts.map +1 -1
  21. package/dist/telemetry/init.js +14 -1
  22. package/dist/telemetry/init.js.map +1 -1
  23. package/dist/tools/gestures/schema.d.ts.map +1 -1
  24. package/dist/tools/gestures/schema.js +7 -15
  25. package/dist/tools/gestures/schema.js.map +1 -1
  26. package/dist/tools/test-generation/locators.d.ts.map +1 -1
  27. package/dist/tools/test-generation/locators.js +19 -5
  28. package/dist/tools/test-generation/locators.js.map +1 -1
  29. package/dist/ui/inspector-screenshot-script.d.ts +3 -0
  30. package/dist/ui/inspector-screenshot-script.d.ts.map +1 -0
  31. package/dist/ui/inspector-screenshot-script.js +164 -0
  32. package/dist/ui/inspector-screenshot-script.js.map +1 -0
  33. package/dist/ui/mcp-ui-utils.d.ts.map +1 -1
  34. package/dist/ui/mcp-ui-utils.js +21 -44
  35. package/dist/ui/mcp-ui-utils.js.map +1 -1
  36. package/dist/ui/page-source-inspector-app.d.ts.map +1 -1
  37. package/dist/ui/page-source-inspector-app.js +198 -119
  38. package/dist/ui/page-source-inspector-app.js.map +1 -1
  39. package/dist/ui/xml-inspector-scripts.d.ts +4 -0
  40. package/dist/ui/xml-inspector-scripts.d.ts.map +1 -0
  41. package/dist/ui/xml-inspector-scripts.js +91 -0
  42. package/dist/ui/xml-inspector-scripts.js.map +1 -0
  43. package/package.json +2 -1
  44. package/server.json +2 -2
  45. package/src/locators/element-filter.ts +50 -16
  46. package/src/locators/generate-all-locators.ts +13 -7
  47. package/src/locators/locator-generation.ts +43 -10
  48. package/src/locators/types.ts +2 -0
  49. package/src/telemetry/init.ts +18 -1
  50. package/src/tools/gestures/schema.ts +7 -17
  51. package/src/tools/test-generation/locators.ts +31 -7
  52. package/src/ui/inspector-screenshot-script.ts +163 -0
  53. package/src/ui/mcp-ui-utils.ts +22 -44
  54. package/src/ui/page-source-inspector-app.ts +199 -119
  55. package/src/ui/xml-inspector-scripts.ts +91 -0
@@ -1,3 +1,5 @@
1
+ import { INSPECTOR_SCREENSHOT_SCRIPT } from './inspector-screenshot-script.js';
2
+ import { XML_FORMAT_SCRIPT, XML_SEARCH_SCRIPT } from './xml-inspector-scripts.js';
1
3
  /**
2
4
  * Static MCP App used by appium_get_page_source.
3
5
  *
@@ -13,114 +15,122 @@ export function createPageSourceInspectorAppUI() {
13
15
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
14
16
  <title>Page Source Inspector</title>
15
17
  <style>
18
+ :root { color-scheme: dark; --bg: #17191d; --panel: #202329; --line: #343941; --text: #e5e8ee; --muted: #a3acba; --accent: #91baff; }
16
19
  * { box-sizing: border-box; }
17
- body {
18
- margin: 0;
19
- overflow: hidden;
20
- background: #1e1e1e;
21
- color: #d4d4d4;
22
- font-family: Monaco, Menlo, "Courier New", monospace;
23
- }
24
- summary {
25
- padding: 12px 16px;
26
- background: #2d2d2d;
27
- cursor: pointer;
28
- font-size: 14px;
29
- }
30
- summary .info { margin-left: 8px; }
31
- .toolbar {
32
- display: flex;
33
- flex-wrap: wrap;
34
- align-items: center;
35
- justify-content: space-between;
36
- gap: 12px;
37
- padding: 12px 16px;
38
- border-bottom: 1px solid #3e3e3e;
39
- background: #2d2d2d;
40
- }
41
- .toolbar-right {
42
- flex-wrap: wrap;
43
- display: flex;
44
- align-items: center;
45
- gap: 8px;
46
- }
47
- .title { font-size: 14px; font-weight: 500; }
48
- .info { color: #999; font-size: 12px; }
49
- .btn {
50
- padding: 6px 12px;
51
- border: 0;
52
- border-radius: 4px;
53
- background: #007aff;
54
- color: #fff;
55
- cursor: pointer;
56
- font: 13px -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
57
- }
58
- .btn:hover { background: #0056b3; }
59
- .btn-secondary { background: #444; }
60
- .btn-secondary:hover { background: #555; }
61
- .search-box {
62
- width: 200px;
63
- padding: 6px 12px;
64
- border: 1px solid #555;
65
- border-radius: 4px;
66
- outline: none;
67
- background: #3e3e3e;
68
- color: #d4d4d4;
69
- font-size: 13px;
70
- }
71
- .search-box:focus { border-color: #007aff; }
72
- .viewer {
73
- max-height: 320px;
74
- overflow: auto;
75
- padding: 16px;
76
- }
77
- .xml-content {
78
- margin: 0;
79
- white-space: pre;
80
- color: #d4d4d4;
81
- font-size: 13px;
82
- line-height: 1.6;
83
- }
84
- mark {
85
- border-radius: 2px;
86
- background: #ffd54f;
87
- color: #1e1e1e;
88
- }
89
- .empty {
90
- color: #999;
91
- font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
92
- }
20
+ [hidden] { display: none !important; }
21
+ body { margin: 0; overflow: auto; background: var(--bg); color: var(--text); font: 13px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
22
+ summary { cursor: pointer; padding: 16px 20px; }
23
+ summary::marker { color: var(--muted); }
24
+ .title { font-size: 15px; font-weight: 600; letter-spacing: -.2px; }
25
+ .info { color: var(--muted); font-size: 12px; margin-left: 10px; }
26
+ .toolbar, .section-header { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 12px; }
27
+ .toolbar { padding: 12px 20px; border-block: 1px solid var(--line); background: var(--panel); }
28
+ .toolbar-right { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; }
29
+ .btn { padding: 8px 12px; border: 1px solid transparent; border-radius: 7px; background: #a7c7ff; color: #14243d; cursor: pointer; font: inherit; font-weight: 600; }
30
+ .btn:hover { background: #c2d8ff; }
31
+ .btn:disabled { opacity: .55; cursor: wait; }
32
+ .btn-secondary { background: transparent; border-color: #48505d; color: var(--text); }
33
+ .btn-secondary:hover { background: #303641; }
34
+ .btn:focus-visible, summary:focus-visible, input:focus-visible { outline: 2px solid var(--accent); outline-offset: 3px; }
35
+ .search-box { width: min(240px, 100%); min-width: 0; padding: 8px 12px; border: 1px solid #48505d; border-radius: 7px; background: var(--bg); color: var(--text); font: inherit; }
36
+ .search-box::placeholder { color: var(--muted); }
37
+ .viewer { height: 320px; min-height: 160px; resize: vertical; overflow: auto; padding: 20px; }
38
+ .xml-content, .selector { margin: 0; font: 12px/1.75 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
39
+ .xml-content { white-space: pre; color: #c5d3e7; }
40
+ mark[data-active] { outline: 2px solid #91baff; background: #ff963c; }
41
+ .search-status { padding: 6px 20px; color: var(--muted); font-size: 12px; }
42
+ .search-status:empty { display: none; }
43
+ mark { border-radius: 3px; background: #eac77a; color: #252019; }
44
+ .empty, .hint { color: var(--muted); }
45
+ .empty { font-family: inherit; }
46
+ .hint { margin: 6px 0 0; font-size: 12px; }
47
+ .screenshot-panel { border-top: 1px solid var(--line); padding: 20px; }
48
+ .screenshot-frame { position: relative; width: fit-content; max-width: 100%; margin: 12px auto; }
49
+ .screenshot-frame img { display: block; max-width: 100%; max-height: 480px; }
50
+ .element-overlay { position: absolute; border: 2px solid #ff963c; background: #ff963c33; pointer-events: none; }
51
+ #screenshotElement { width: 100%; margin: 10px 0; padding: 8px; background: var(--panel); color: var(--text); border: 1px solid var(--line); }
52
+ #selectedXmlElement { white-space: pre-wrap; overflow-wrap: anywhere; font-size: 12px; }
53
+ .locators { border-top: 1px solid var(--line); padding: 20px; }
54
+ h2 { margin: 0; font-size: 14px; font-weight: 600; }
55
+ #locatorStatus { margin: 16px 0 10px; color: var(--accent); font-size: 12px; }
56
+ .locator-results { max-height: 480px; overflow: auto; }
57
+ .locator-card { margin: 8px 0; border: 1px solid var(--line); border-radius: 8px; background: var(--panel); overflow: hidden; }
58
+ .locator-card summary { padding: 12px 14px; overflow-wrap: anywhere; }
59
+ .element-type { margin-left: 8px; color: var(--muted); font-size: 11px; }
60
+ .locator-row { margin: 0 14px 14px; }
61
+ .strategy { display: block; margin-bottom: 5px; color: var(--muted); font-size: 11px; font-weight: 600; }
62
+ .selector { padding: 10px 12px; background: var(--bg); border-radius: 5px; white-space: pre-wrap; overflow-wrap: anywhere; user-select: all; }
63
+ @media (max-width: 420px) { .toolbar, .locators { padding: 12px; } .toolbar-right { width: 100%; } .search-box { width: 100%; } .info { display: block; margin: 4px 0 0 18px; } }
93
64
  </style>
94
65
  </head>
95
66
  <body>
96
- <details>
67
+ <details open>
97
68
  <summary>
98
- <span class="title">📄 Page Source Inspector</span>
69
+ <span class="title">Page Source Inspector</span>
99
70
  <span class="info" id="sourceInfo">Waiting for page source…</span>
100
71
  </summary>
101
72
  <div class="toolbar">
73
+ <input type="search" class="search-box" id="searchBox" placeholder="Search elements…" aria-label="Search elements" title="Highlight XML text and find locator candidates by element tag or attribute value">
102
74
  <div class="toolbar-right">
103
- <input type="text" class="search-box" id="searchBox" placeholder="Search…">
104
- <button class="btn btn-secondary" id="copyButton">Copy</button>
105
- <button class="btn btn-secondary" id="formatButton">Format</button>
106
- <button class="btn" id="generateButton">Generate Locators</button>
75
+ <button class="btn btn-secondary" id="takeScreenshotButton">Take screenshot</button>
76
+ <button class="btn btn-secondary" id="formatButton">Format XML</button>
77
+ <button class="btn btn-secondary" id="copyButton">Copy XML</button>
107
78
  </div>
108
79
  </div>
109
- <div class="viewer">
80
+ <div id="searchStatus" class="search-status" role="status" aria-live="polite"></div>
81
+ <div class="viewer" title="Drag the bottom-right corner to resize vertically">
110
82
  <pre class="xml-content empty" id="xmlContent">Waiting for page source…</pre>
111
83
  </div>
84
+ <section id="screenshotPanel" class="screenshot-panel" hidden aria-label="Screenshot preview">
85
+ <h2>Screenshot &amp; XML elements</h2>
86
+ <p class="hint">Capture refreshes XML too. Select an element to overlay its bounds. Images and XML are captured sequentially; keep the screen still. Supports x/y/width/height and Android bounds.</p>
87
+ <p id="screenshotStatus" role="status" aria-live="polite"></p>
88
+ <div class="screenshot-frame">
89
+ <img id="inspectorScreenshot" alt="Device screenshot" hidden>
90
+ <div id="elementOverlay" class="element-overlay" hidden></div>
91
+ </div>
92
+ <label for="screenshotElement">XML element (filtered by Search)</label>
93
+ <select id="screenshotElement"><option value="">Select an XML element to highlight</option></select>
94
+ <pre id="selectedXmlElement"></pre>
95
+ </section>
96
+ <section class="locators" aria-labelledby="locatorsHeading">
97
+ <div class="section-header">
98
+ <h2 id="locatorsHeading">Locator candidates</h2>
99
+ <button class="btn" id="generateButton">Find locators</button>
100
+ </div>
101
+ <p class="hint">Find locators for elements matching the search text in their type or attributes (name, label, text, ID, etc.). Matches ignore case and may include hidden elements. Fetches fresh XML; leave search blank for the default candidate list.</p>
102
+ <label class="hint" for="xpathAttributes">Preferred XPath attributes (optional)</label>
103
+ <input type="text" class="search-box" id="xpathAttributes" placeholder="AutomationId, data-testid" aria-describedby="xpathAttributesHelp" style="display:block;width:100%;margin-top:6px">
104
+ <p class="hint" id="xpathAttributesHelp">Comma-separated attribute names, in priority order. Existing attributes remain as fallback.</p>
105
+ <div id="locatorResults" hidden>
106
+ <p id="locatorStatus" role="status" aria-live="polite"></p>
107
+ <div class="locator-results" id="locatorOutput"></div>
108
+ </div>
109
+ </section>
112
110
  </details>
113
111
  <script>
114
112
  (() => {
113
+ ${XML_FORMAT_SCRIPT}
114
+ ${XML_SEARCH_SCRIPT}
115
+ ${INSPECTOR_SCREENSHOT_SCRIPT}
115
116
  const PAGE_SOURCE_PREFIX = 'Page source retrieved successfully: \\n\\\`\\\`\\\`xml ';
116
117
  const xmlContent = document.getElementById('xmlContent');
117
118
  const sourceInfo = document.getElementById('sourceInfo');
118
119
  const searchBox = document.getElementById('searchBox');
120
+ const generateButton = document.getElementById('generateButton');
121
+ const locatorResults = document.getElementById('locatorResults');
122
+ const locatorStatus = document.getElementById('locatorStatus');
123
+ const locatorOutput = document.getElementById('locatorOutput');
124
+ const xmlSearch = createXmlSearch(xmlContent, document.getElementById('searchStatus'));
119
125
  let source = '';
120
126
  let savedFile;
121
127
  let nextRequestId = 1;
122
128
  const pendingRequests = new Map();
123
129
 
130
+ const screenshotInspector = createScreenshotInspector(
131
+ (name, args) => sendRequest('tools/call', {name, arguments: args}), setSource, sourceFromToolResult,
132
+ );
133
+
124
134
  function sendRequest(method, params) {
125
135
  const id = nextRequestId++;
126
136
  window.parent.postMessage({jsonrpc: '2.0', id, method, params}, '*');
@@ -154,30 +164,9 @@ export function createPageSourceInspectorAppUI() {
154
164
  return text;
155
165
  }
156
166
 
157
- function appendHighlightedText(container, text, query) {
158
- const lowerText = text.toLowerCase();
159
- const lowerQuery = query.toLowerCase();
160
- let position = 0;
161
-
162
- while (position < text.length) {
163
- const matchIndex = lowerText.indexOf(lowerQuery, position);
164
- if (matchIndex === -1) {
165
- container.appendChild(document.createTextNode(text.slice(position)));
166
- return;
167
- }
168
- if (matchIndex > position) {
169
- container.appendChild(document.createTextNode(text.slice(position, matchIndex)));
170
- }
171
- const mark = document.createElement('mark');
172
- mark.textContent = text.slice(matchIndex, matchIndex + query.length);
173
- container.appendChild(mark);
174
- position = matchIndex + query.length;
175
- }
176
- }
177
-
178
167
  function renderSource() {
179
168
  const query = searchBox.value.trim();
180
- xmlContent.textContent = '';
169
+ xmlSearch.render('', '');
181
170
  xmlContent.classList.toggle('empty', source.length === 0);
182
171
  if (savedFile) {
183
172
  sourceInfo.textContent = savedFile.bytes + ' bytes saved';
@@ -186,28 +175,22 @@ export function createPageSourceInspectorAppUI() {
186
175
  }
187
176
  if (!source) {
188
177
  xmlContent.textContent = 'No page source was returned.';
189
- } else if (!query) {
190
- xmlContent.textContent = source;
191
178
  } else {
192
- appendHighlightedText(xmlContent, source, query);
179
+ xmlSearch.render(source, query);
193
180
  }
194
181
  sourceInfo.textContent = source.length + ' characters';
195
182
  }
196
183
 
197
184
  function setSource(nextSource) {
198
185
  source = nextSource;
186
+ screenshotInspector.updateSource(source);
199
187
  renderSource();
200
188
  }
201
189
 
202
190
  function formatXML() {
203
191
  if (!source) return;
204
192
  try {
205
- const parser = new DOMParser();
206
- const documentNode = parser.parseFromString(source, 'text/xml');
207
- if (documentNode.querySelector('parsererror')) {
208
- throw new Error('Invalid XML');
209
- }
210
- source = new XMLSerializer().serializeToString(documentNode);
193
+ source = formatXml(source);
211
194
  renderSource();
212
195
  } catch {
213
196
  window.alert('Failed to format XML');
@@ -223,11 +206,89 @@ export function createPageSourceInspectorAppUI() {
223
206
  }
224
207
  }
225
208
 
209
+ function renderLocators(elements) {
210
+ locatorOutput.textContent = '';
211
+ elements.forEach((element, index) => {
212
+ const card = document.createElement('details');
213
+ card.className = 'locator-card';
214
+ card.open = index === 0;
215
+ const heading = document.createElement('summary');
216
+ const label = element.text || element.contentDesc || element.resourceId;
217
+ heading.textContent = (index + 1) + '. ' + (label || element.tagName || 'Element');
218
+ if (label && element.tagName) {
219
+ const type = document.createElement('span');
220
+ type.className = 'element-type';
221
+ type.textContent = element.tagName;
222
+ heading.appendChild(type);
223
+ }
224
+ card.appendChild(heading);
225
+ const entries = Object.entries(element.locators || {}).filter(([, value]) => typeof value === 'string');
226
+ entries.forEach(([strategy, selector]) => {
227
+ const row = document.createElement('div');
228
+ row.className = 'locator-row';
229
+ const name = document.createElement('span');
230
+ name.className = 'strategy';
231
+ name.textContent = strategy;
232
+ const code = document.createElement('pre');
233
+ code.className = 'selector';
234
+ code.textContent = selector;
235
+ row.appendChild(name);
236
+ row.appendChild(code);
237
+ card.appendChild(row);
238
+ });
239
+ if (!entries.length) {
240
+ const empty = document.createElement('p');
241
+ empty.className = 'locator-row hint';
242
+ empty.textContent = 'No candidate selectors for this element.';
243
+ card.appendChild(empty);
244
+ }
245
+ locatorOutput.appendChild(card);
246
+ });
247
+ }
248
+
249
+ function parseLocatorResult(result) {
250
+ const text = (result?.content || [])
251
+ .filter(item => item.type === 'text')
252
+ .map(item => item.text)
253
+ .join('\\n');
254
+ if (result?.isError) throw new Error(text || 'Tool returned an error');
255
+ const data = JSON.parse(text);
256
+ if (!Array.isArray(data.interactableElements)) throw new Error('No locator data returned');
257
+ return data.interactableElements;
258
+ }
259
+
260
+ function describeLocatorResults(count, query) {
261
+ if (query) {
262
+ const matches = count ? count + ' matching elements' : 'No matching elements';
263
+ return matches + ' for “' + query + '” in freshly fetched XML.';
264
+ }
265
+ if (!count) return 'No supported elements found in the fetched XML.';
266
+ return 'Candidates generated for ' + count + ' elements from freshly fetched XML.';
267
+ }
268
+
226
269
  async function generateLocators() {
270
+ if (generateButton.disabled) return;
271
+ const query = searchBox.value.trim();
272
+ generateButton.disabled = true;
273
+ locatorResults.hidden = false;
274
+ locatorStatus.textContent = 'Fetching XML and generating candidates…';
275
+ locatorOutput.textContent = '';
227
276
  try {
228
- await sendRequest('tools/call', {name: 'generate_locators', arguments: {}});
229
- } catch {
230
- window.alert('Failed to generate locators');
277
+ const xpathAttributes = [...new Set((document.getElementById('xpathAttributes').value || '')
278
+ .split(',').map(name => name.trim()).filter(Boolean))];
279
+ if (xpathAttributes.length > 20 || xpathAttributes.some(name => !/^[A-Za-z_][A-Za-z0-9_.-]*$/.test(name))) {
280
+ throw new Error('Enter up to 20 attribute names, separated by commas (no XPath expressions or namespace prefixes).');
281
+ }
282
+ const args = query ? {query} : {};
283
+ if (xpathAttributes.length) args.xpathAttributes = xpathAttributes;
284
+ const result = await sendRequest('tools/call', {name: 'generate_locators', arguments: args});
285
+ const elements = parseLocatorResult(result);
286
+ locatorStatus.textContent = describeLocatorResults(elements.length, query);
287
+ renderLocators(elements);
288
+ } catch (error) {
289
+ locatorStatus.textContent = 'Failed to generate locators: ' + error.message;
290
+ } finally {
291
+ generateButton.disabled = false;
231
292
  }
232
293
  }
233
294
 
@@ -252,7 +313,11 @@ export function createPageSourceInspectorAppUI() {
252
313
  }
253
314
  });
254
315
 
255
- searchBox.addEventListener('input', renderSource);
316
+ searchBox.addEventListener('input', () => {
317
+ renderSource();
318
+ screenshotInspector.filter(searchBox.value);
319
+ });
320
+ searchBox.addEventListener('keydown', xmlSearch.handleKeyDown);
256
321
  document.getElementById('copyButton').addEventListener('click', copyToClipboard);
257
322
  document.getElementById('formatButton').addEventListener('click', formatXML);
258
323
  document.getElementById('generateButton').addEventListener('click', generateLocators);
@@ -262,7 +327,21 @@ export function createPageSourceInspectorAppUI() {
262
327
  appInfo: {name: 'Appium Page Source Inspector', version: '1.0.0'},
263
328
  appCapabilities: {availableDisplayModes: ['inline', 'fullscreen']},
264
329
  })
265
- .then(() => sendNotification('ui/notifications/initialized', {}))
330
+ .then(() => {
331
+ sendNotification('ui/notifications/initialized', {});
332
+ // Let flexible MCP App hosts follow resizing and details expansion.
333
+ if (typeof ResizeObserver !== 'undefined') {
334
+ let previousHeight;
335
+ const observer = new ResizeObserver(() => {
336
+ const height = Math.ceil(document.body.getBoundingClientRect().height);
337
+ if (height !== previousHeight) {
338
+ previousHeight = height;
339
+ sendNotification('ui/notifications/size-changed', {height});
340
+ }
341
+ });
342
+ observer.observe(document.body);
343
+ }
344
+ })
266
345
  .catch(() => {
267
346
  sourceInfo.textContent = 'Unable to initialize inspector';
268
347
  });
@@ -1 +1 @@
1
- {"version":3,"file":"page-source-inspector-app.js","sourceRoot":"","sources":["../../src/ui/page-source-inspector-app.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,8BAA8B;IAC5C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyQN,CAAC;AACJ,CAAC"}
1
+ {"version":3,"file":"page-source-inspector-app.js","sourceRoot":"","sources":["../../src/ui/page-source-inspector-app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,2BAA2B,EAAC,MAAM,kCAAkC,CAAC;AAC7E,OAAO,EAAC,iBAAiB,EAAE,iBAAiB,EAAC,MAAM,4BAA4B,CAAC;AAEhF;;;;;GAKG;AACH,MAAM,UAAU,8BAA8B;IAC5C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAuGD,iBAAiB;QACjB,iBAAiB;QACjB,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6OhC,CAAC;AACJ,CAAC"}
@@ -0,0 +1,4 @@
1
+ /** Shared browser helpers embedded by both inspector transports. Keep these scripts data-free. */
2
+ export declare const XML_FORMAT_SCRIPT: string;
3
+ export declare const XML_SEARCH_SCRIPT: string;
4
+ //# sourceMappingURL=xml-inspector-scripts.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"xml-inspector-scripts.d.ts","sourceRoot":"","sources":["../../src/ui/xml-inspector-scripts.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,eAAO,MAAM,iBAAiB,QAsC7B,CAAC;AAEF,eAAO,MAAM,iBAAiB,QAiD7B,CAAC"}
@@ -0,0 +1,91 @@
1
+ /** Shared browser helpers embedded by both inspector transports. Keep these scripts data-free. */
2
+ export const XML_FORMAT_SCRIPT = String.raw `
3
+ function formatXml(source) {
4
+ const documentNode = new DOMParser().parseFromString(source, 'text/xml');
5
+ if (!documentNode.documentElement || documentNode.getElementsByTagName('parsererror').length) {
6
+ throw new Error('Invalid XML');
7
+ }
8
+
9
+ function indentElement(element, depth) {
10
+ // Whitespace can be meaningful in mixed content, CDATA and preserved subtrees.
11
+ if (element.getAttribute('xml:space') === 'preserve') return;
12
+ const children = Array.from(element.childNodes);
13
+ const hasText = children.some(child =>
14
+ child.nodeType === 4 || (child.nodeType === 3 && (child.nodeValue || '').trim())
15
+ );
16
+ if (hasText || !children.some(child => child.nodeType === 1)) return;
17
+ for (const child of children) {
18
+ if (child.nodeType === 3) {
19
+ element.removeChild(child);
20
+ continue;
21
+ }
22
+ if (child.nodeType === 1) indentElement(child, depth + 1);
23
+ element.insertBefore(documentNode.createTextNode('\n' + ' '.repeat(depth + 1)), child);
24
+ }
25
+ element.appendChild(documentNode.createTextNode('\n' + ' '.repeat(depth)));
26
+ }
27
+
28
+ indentElement(documentNode.documentElement, 0);
29
+ const serializer = new XMLSerializer();
30
+ let formatted = Array.from(documentNode.childNodes)
31
+ .filter(node => node.nodeType !== 3)
32
+ .map(node => serializer.serializeToString(node))
33
+ .join('\n');
34
+ const declaration = source.match(/^\s*(<\?xml\s[^?]*\?>)/);
35
+ if (declaration && !formatted.startsWith('<?xml ')) {
36
+ formatted = declaration[1] + '\n' + formatted;
37
+ }
38
+ return formatted;
39
+ }
40
+ `;
41
+ export const XML_SEARCH_SCRIPT = String.raw `
42
+ function createXmlSearch(container, status) {
43
+ let matches = [];
44
+ let activeIndex = -1;
45
+
46
+ function render(text, query) {
47
+ container.textContent = '';
48
+ matches = [];
49
+ activeIndex = -1;
50
+ query = query.trim();
51
+ status.textContent = '';
52
+ if (!query) {
53
+ container.textContent = text;
54
+ return;
55
+ }
56
+ const lowerText = text.toLowerCase();
57
+ const lowerQuery = query.toLowerCase();
58
+ let position = 0;
59
+ while (position < text.length) {
60
+ const index = lowerText.indexOf(lowerQuery, position);
61
+ if (index === -1) break;
62
+ container.appendChild(document.createTextNode(text.slice(position, index)));
63
+ const mark = document.createElement('mark');
64
+ mark.textContent = text.slice(index, index + query.length);
65
+ container.appendChild(mark);
66
+ matches.push(mark);
67
+ position = index + query.length;
68
+ }
69
+ container.appendChild(document.createTextNode(text.slice(position)));
70
+ status.textContent = matches.length ? matches.length + ' matches · Enter / Shift+Enter to navigate' : 'No matches';
71
+ }
72
+
73
+ function handleKeyDown(event) {
74
+ if (event.key !== 'Enter' || event.isComposing) return;
75
+ event.preventDefault();
76
+ if (!matches.length) return;
77
+ if (activeIndex >= 0) matches[activeIndex].removeAttribute('data-active');
78
+ const step = event.shiftKey ? -1 : 1;
79
+ activeIndex = activeIndex < 0
80
+ ? (event.shiftKey ? matches.length - 1 : 0)
81
+ : (activeIndex + step + matches.length) % matches.length;
82
+ const match = matches[activeIndex];
83
+ match.setAttribute('data-active', 'true');
84
+ match.scrollIntoView({block: 'nearest', inline: 'nearest'});
85
+ status.textContent = (activeIndex + 1) + ' / ' + matches.length + ' · Enter / Shift+Enter to navigate';
86
+ }
87
+
88
+ return {render, handleKeyDown};
89
+ }
90
+ `;
91
+ //# sourceMappingURL=xml-inspector-scripts.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"xml-inspector-scripts.js","sourceRoot":"","sources":["../../src/ui/xml-inspector-scripts.ts"],"names":[],"mappings":"AAAA,kGAAkG;AAClG,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsC1C,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiD1C,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "appium-mcp",
3
- "version": "1.97.2",
3
+ "version": "1.99.0",
4
4
  "description": "Intelligent MCP server providing AI assistants with powerful tools and resources for Appium mobile automation",
5
5
  "bugs": {
6
6
  "url": "https://github.com/appium/appium-mcp/issues"
@@ -114,6 +114,7 @@
114
114
  },
115
115
  "optionalDependencies": {
116
116
  "@opentelemetry/api": "^1.9.1",
117
+ "@opentelemetry/exporter-trace-otlp-grpc": "^0.223.0",
117
118
  "@opentelemetry/exporter-trace-otlp-http": "^0.223.0",
118
119
  "@opentelemetry/sdk-node": "^0.223.0",
119
120
  "applesign": "^5.0.0"
package/server.json CHANGED
@@ -3,12 +3,12 @@
3
3
  "name": "io.github.appium/appium-mcp",
4
4
  "title": "MCP Appium - Mobile Development and Automation Server",
5
5
  "description": "MCP server for Appium mobile automation on iOS and Android devices with test creation tools.",
6
- "version": "1.97.2",
6
+ "version": "1.99.0",
7
7
  "packages": [
8
8
  {
9
9
  "registryType": "npm",
10
10
  "identifier": "appium-mcp",
11
- "version": "1.97.2",
11
+ "version": "1.99.0",
12
12
  "transport": {
13
13
  "type": "stdio"
14
14
  }
@@ -1,6 +1,8 @@
1
1
  import type {JSONElement} from './source-parsing.js';
2
+ import type {DriverName} from './types.js';
2
3
 
3
4
  export interface FilterOptions {
5
+ query?: string;
4
6
  includeTagNames?: string[];
5
7
  excludeTagNames?: string[];
6
8
  requireAttributes?: string[];
@@ -16,9 +18,10 @@ export function shouldIncludeElement(
16
18
  element: JSONElement,
17
19
  filters: FilterOptions,
18
20
  isNative: boolean,
19
- automationName: string,
21
+ automationName: DriverName,
20
22
  ): boolean {
21
23
  const {
24
+ query,
22
25
  includeTagNames = [],
23
26
  excludeTagNames = ['hierarchy'],
24
27
  requireAttributes = [],
@@ -27,6 +30,10 @@ export function shouldIncludeElement(
27
30
  clickableOnly = false,
28
31
  } = filters;
29
32
 
33
+ if (!matchesSearchQuery(element, query)) {
34
+ return false;
35
+ }
36
+
30
37
  if (!matchesTagFilters(element, includeTagNames, excludeTagNames)) {
31
38
  return false;
32
39
  }
@@ -46,6 +53,15 @@ export function shouldIncludeElement(
46
53
  return true;
47
54
  }
48
55
 
56
+ /** Literal substring matching applies only to this element, never its descendants. */
57
+ function matchesSearchQuery(element: JSONElement, query?: string): boolean {
58
+ const search = query?.trim().toLowerCase();
59
+ if (!search) {
60
+ return true;
61
+ }
62
+ return [element.tagName, ...Object.values(element.attributes)].some((value) => value.toLowerCase().includes(search));
63
+ }
64
+
49
65
  /**
50
66
  * Determines if an element matches the tag name filters
51
67
  */
@@ -84,7 +100,7 @@ function matchesAttributeFilters(
84
100
  /**
85
101
  * Determines if an element is interactable/fetchable based on platform
86
102
  */
87
- function isInteractableElement(element: JSONElement, isNative: boolean, automationName: string): boolean {
103
+ function isInteractableElement(element: JSONElement, isNative: boolean, automationName: DriverName): boolean {
88
104
  if (!isNative) {
89
105
  const tag = element.tagName.toLowerCase();
90
106
  const attrs = element.attributes;
@@ -99,20 +115,38 @@ function isInteractableElement(element: JSONElement, isNative: boolean, automati
99
115
  (attrs.tabindex !== undefined && Number(attrs.tabindex) >= 0)
100
116
  );
101
117
  }
102
- const interactableTags =
103
- automationName === 'uiautomator2'
104
- ? ['EditText', 'Button', 'ImageButton', 'CheckBox', 'RadioButton', 'Switch', 'ToggleButton', 'TextView']
105
- : [
106
- 'XCUIElementTypeTextField',
107
- 'XCUIElementTypeSecureTextField',
108
- 'XCUIElementTypeButton',
109
- 'XCUIElementTypeImage',
110
- 'XCUIElementTypeSwitch',
111
- 'XCUIElementTypeStaticText',
112
- 'XCUIElementTypeTextView',
113
- 'XCUIElementTypeCell',
114
- 'XCUIElementTypeLink',
115
- ];
118
+ let interactableTags: string[];
119
+ switch (automationName) {
120
+ case 'uiautomator2':
121
+ interactableTags = [
122
+ 'EditText',
123
+ 'Button',
124
+ 'ImageButton',
125
+ 'CheckBox',
126
+ 'RadioButton',
127
+ 'Switch',
128
+ 'ToggleButton',
129
+ 'TextView',
130
+ ];
131
+ break;
132
+ case 'xcuitest':
133
+ interactableTags = [
134
+ 'XCUIElementTypeTextField',
135
+ 'XCUIElementTypeSecureTextField',
136
+ 'XCUIElementTypeButton',
137
+ 'XCUIElementTypeImage',
138
+ 'XCUIElementTypeSwitch',
139
+ 'XCUIElementTypeStaticText',
140
+ 'XCUIElementTypeTextView',
141
+ 'XCUIElementTypeCell',
142
+ 'XCUIElementTypeLink',
143
+ ];
144
+ break;
145
+ default:
146
+ // Other native drivers use their own XML schemas. Do not require mobile
147
+ // element types or clickable/focusable attributes before generating XPath.
148
+ return true;
149
+ }
116
150
 
117
151
  return (
118
152
  interactableTags.some((tag) => element.tagName.includes(tag)) ||