appium-mcp 1.95.8 → 1.97.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 (51) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +102 -2
  3. package/dist/command.d.ts +2 -0
  4. package/dist/command.d.ts.map +1 -1
  5. package/dist/command.js +12 -0
  6. package/dist/command.js.map +1 -1
  7. package/dist/tools/gestures/schema.d.ts.map +1 -1
  8. package/dist/tools/gestures/schema.js +3 -6
  9. package/dist/tools/gestures/schema.js.map +1 -1
  10. package/dist/tools/index.d.ts.map +1 -1
  11. package/dist/tools/index.js +2 -0
  12. package/dist/tools/index.js.map +1 -1
  13. package/dist/tools/interactions/find-elements.d.ts +3 -0
  14. package/dist/tools/interactions/find-elements.d.ts.map +1 -0
  15. package/dist/tools/interactions/find-elements.js +51 -0
  16. package/dist/tools/interactions/find-elements.js.map +1 -0
  17. package/dist/tools/interactions/find.d.ts.map +1 -1
  18. package/dist/tools/interactions/find.js +14 -18
  19. package/dist/tools/interactions/find.js.map +1 -1
  20. package/dist/tools/interactions/get-page-source.d.ts.map +1 -1
  21. package/dist/tools/interactions/get-page-source.js +12 -2
  22. package/dist/tools/interactions/get-page-source.js.map +1 -1
  23. package/dist/tools/interactions/page-source-file.d.ts +11 -0
  24. package/dist/tools/interactions/page-source-file.d.ts.map +1 -0
  25. package/dist/tools/interactions/page-source-file.js +18 -0
  26. package/dist/tools/interactions/page-source-file.js.map +1 -0
  27. package/dist/tools/interactions/page-source-summary.d.ts +9 -0
  28. package/dist/tools/interactions/page-source-summary.d.ts.map +1 -0
  29. package/dist/tools/interactions/page-source-summary.js +80 -0
  30. package/dist/tools/interactions/page-source-summary.js.map +1 -0
  31. package/dist/tools/tool-response.d.ts +2 -0
  32. package/dist/tools/tool-response.d.ts.map +1 -1
  33. package/dist/tools/tool-response.js +7 -0
  34. package/dist/tools/tool-response.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 +14 -0
  37. package/dist/ui/page-source-inspector-app.js.map +1 -1
  38. package/package.json +1 -1
  39. package/scripts/publish-mcp-registry.sh +31 -0
  40. package/server.json +2 -2
  41. package/src/command.ts +12 -0
  42. package/src/tools/README.md +11 -2
  43. package/src/tools/gestures/schema.ts +3 -8
  44. package/src/tools/index.ts +2 -0
  45. package/src/tools/interactions/find-elements.ts +61 -0
  46. package/src/tools/interactions/find.ts +23 -29
  47. package/src/tools/interactions/get-page-source.ts +14 -2
  48. package/src/tools/interactions/page-source-file.ts +20 -0
  49. package/src/tools/interactions/page-source-summary.ts +87 -0
  50. package/src/tools/tool-response.ts +8 -0
  51. package/src/ui/page-source-inspector-app.ts +14 -0
@@ -0,0 +1,87 @@
1
+ import {DOMParser} from '@xmldom/xmldom';
2
+ import type {Element, Node} from '@xmldom/xmldom';
3
+ import xpath from 'xpath';
4
+
5
+ const MAX_NODES = 100;
6
+ const FIELDS = [
7
+ 'type',
8
+ 'class',
9
+ 'name',
10
+ 'label',
11
+ 'value',
12
+ 'text',
13
+ 'resource-id',
14
+ 'content-desc',
15
+ 'visible',
16
+ 'displayed',
17
+ 'bounds',
18
+ 'x',
19
+ 'y',
20
+ 'width',
21
+ 'height',
22
+ ];
23
+
24
+ function isElement(node: unknown): node is Element {
25
+ return typeof node === 'object' && node !== null && (node as Node).nodeType === 1;
26
+ }
27
+
28
+ function summarize(node: Element): Record<string, string> {
29
+ const result: Record<string, string> = {
30
+ type: node.getAttribute('type') || node.getAttribute('class') || node.tagName,
31
+ };
32
+ for (const field of FIELDS) {
33
+ const value = node.getAttribute(field);
34
+ if (value !== null) {
35
+ result[field] = value;
36
+ }
37
+ }
38
+ return result;
39
+ }
40
+
41
+ /** Bounded node summaries; a pattern is a literal substring, never an executable expression. */
42
+ export function summarizePageSource(source: string, selector?: string, pattern?: string) {
43
+ const document = new DOMParser({
44
+ onError: (level, message) => {
45
+ if (level !== 'warning') {
46
+ throw new Error(message);
47
+ }
48
+ },
49
+ }).parseFromString(source, 'text/xml');
50
+ const selection = xpath.select(selector || '//*', document as never);
51
+ if (!Array.isArray(selection) || selection.some((node) => !isElement(node))) {
52
+ throw new Error('selector must be an XPath selecting elements');
53
+ }
54
+ const selected = (selection as unknown as Element[]).filter(
55
+ (node) =>
56
+ pattern === undefined ||
57
+ [node.tagName, ...Array.from(node.attributes).map((attr) => attr.value)].some((value) => value.includes(pattern)),
58
+ );
59
+ let remaining = MAX_NODES;
60
+ let truncated = false;
61
+ const matches = [];
62
+ for (const node of selected) {
63
+ if (remaining === 0) {
64
+ truncated = true;
65
+ break;
66
+ }
67
+ remaining--;
68
+ const visibleSiblings = [];
69
+ for (const sibling of Array.from(node.parentNode?.childNodes ?? [])) {
70
+ if (!isElement(sibling) || sibling === node) {
71
+ continue;
72
+ }
73
+ const visible = sibling.getAttribute('visible') ?? sibling.getAttribute('displayed');
74
+ if (visible !== 'true' && visible !== '1') {
75
+ continue;
76
+ }
77
+ if (remaining === 0) {
78
+ truncated = true;
79
+ break;
80
+ }
81
+ remaining--;
82
+ visibleSiblings.push(summarize(sibling));
83
+ }
84
+ matches.push({node: summarize(node), visibleSiblings});
85
+ }
86
+ return {matches, truncated};
87
+ }
@@ -34,6 +34,14 @@ export function readWebElementId(element: unknown): string | undefined {
34
34
  return typeof id === 'string' ? id : undefined;
35
35
  }
36
36
 
37
+ /** Additional driver fields, excluding duplicate protocol element IDs. */
38
+ export function readWebElementAttributes(element: unknown): Record<string, unknown> {
39
+ if (element === null || typeof element !== 'object') {
40
+ return {};
41
+ }
42
+ return Object.fromEntries(Object.entries(element).filter(([key]) => key !== 'ELEMENT' && key !== W3C_ELEMENT_ID));
43
+ }
44
+
37
45
  /**
38
46
  * Standard success ContentResult.
39
47
  */
@@ -117,6 +117,7 @@ export function createPageSourceInspectorAppUI(): string {
117
117
  const sourceInfo = document.getElementById('sourceInfo');
118
118
  const searchBox = document.getElementById('searchBox');
119
119
  let source = '';
120
+ let savedFile;
120
121
  let nextRequestId = 1;
121
122
  const pendingRequests = new Map();
122
123
 
@@ -131,6 +132,7 @@ export function createPageSourceInspectorAppUI(): string {
131
132
  }
132
133
 
133
134
  function sourceFromToolResult(result) {
135
+ savedFile = undefined;
134
136
  const textBlock = result && Array.isArray(result.content)
135
137
  ? result.content.find((item) => item && item.type === 'text' && typeof item.text === 'string')
136
138
  : undefined;
@@ -139,6 +141,13 @@ export function createPageSourceInspectorAppUI(): string {
139
141
  }
140
142
 
141
143
  let text = textBlock.text;
144
+ try {
145
+ const metadata = JSON.parse(text);
146
+ if (typeof metadata.filepath === 'string' && typeof metadata.bytes === 'number') {
147
+ savedFile = metadata;
148
+ return '';
149
+ }
150
+ } catch { /* Inline XML is not JSON. */ }
142
151
  if (text.startsWith(PAGE_SOURCE_PREFIX) && text.endsWith('\`\`\`')) {
143
152
  text = text.slice(PAGE_SOURCE_PREFIX.length, -3);
144
153
  }
@@ -170,6 +179,11 @@ export function createPageSourceInspectorAppUI(): string {
170
179
  const query = searchBox.value.trim();
171
180
  xmlContent.textContent = '';
172
181
  xmlContent.classList.toggle('empty', source.length === 0);
182
+ if (savedFile) {
183
+ sourceInfo.textContent = savedFile.bytes + ' bytes saved';
184
+ xmlContent.textContent = 'Saved on the MCP server: ' + savedFile.filepath + '\\nCall appium_get_page_source with saveToFile=false to inspect the XML here.';
185
+ return;
186
+ }
173
187
  if (!source) {
174
188
  xmlContent.textContent = 'No page source was returned.';
175
189
  } else if (!query) {