appium-mcp 1.96.0 → 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.
- package/CHANGELOG.md +6 -0
- package/README.md +50 -2
- package/dist/tools/gestures/schema.d.ts.map +1 -1
- package/dist/tools/gestures/schema.js +3 -6
- package/dist/tools/gestures/schema.js.map +1 -1
- package/dist/tools/interactions/get-page-source.d.ts.map +1 -1
- package/dist/tools/interactions/get-page-source.js +12 -2
- package/dist/tools/interactions/get-page-source.js.map +1 -1
- package/dist/tools/interactions/page-source-file.d.ts +11 -0
- package/dist/tools/interactions/page-source-file.d.ts.map +1 -0
- package/dist/tools/interactions/page-source-file.js +18 -0
- package/dist/tools/interactions/page-source-file.js.map +1 -0
- package/dist/tools/interactions/page-source-summary.d.ts +9 -0
- package/dist/tools/interactions/page-source-summary.d.ts.map +1 -0
- package/dist/tools/interactions/page-source-summary.js +80 -0
- package/dist/tools/interactions/page-source-summary.js.map +1 -0
- package/dist/ui/page-source-inspector-app.d.ts.map +1 -1
- package/dist/ui/page-source-inspector-app.js +14 -0
- package/dist/ui/page-source-inspector-app.js.map +1 -1
- package/package.json +1 -1
- package/server.json +2 -2
- package/src/tools/README.md +9 -1
- package/src/tools/gestures/schema.ts +3 -8
- package/src/tools/interactions/get-page-source.ts +14 -2
- package/src/tools/interactions/page-source-file.ts +20 -0
- package/src/tools/interactions/page-source-summary.ts +87 -0
- package/src/ui/page-source-inspector-app.ts +14 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,9 @@
|
|
|
1
|
+
## [1.97.0](https://github.com/appium/appium-mcp/compare/v1.96.0...v1.97.0) (2026-10-12)
|
|
2
|
+
|
|
3
|
+
### Features
|
|
4
|
+
|
|
5
|
+
* add opt-in page source file output and summaries ([#573](https://github.com/appium/appium-mcp/issues/573)) ([07e7408](https://github.com/appium/appium-mcp/commit/07e74086e9afac5f01abf64d7dd61545b7ca9386))
|
|
6
|
+
|
|
1
7
|
## [1.96.0](https://github.com/appium/appium-mcp/compare/v1.95.8...v1.96.0) (2026-10-12)
|
|
2
8
|
|
|
3
9
|
### Features
|
package/README.md
CHANGED
|
@@ -149,6 +149,7 @@ This will automatically configure the MCP server for use with Claude Code. Make
|
|
|
149
149
|
| ----------------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
150
150
|
| `CAPABILITIES_CONFIG` | Optional | Absolute path to a `capabilities.json` file with per-platform capability presets |
|
|
151
151
|
| `SCREENSHOTS_DIR` | Optional | Directory where screenshots and screen recordings are saved. Defaults to the system temp directory (`os.tmpdir()`) |
|
|
152
|
+
| `PAGE_SOURCES_DIR` | Optional | Directory for fresh XML snapshots when `appium_get_page_source` uses `saveToFile: true`. Defaults to the OS temporary directory; relative paths resolve from the server working directory. Has no effect when file saving is disabled. |
|
|
152
153
|
| `NO_UI` | Optional | Set to `true` or `1` to disable HTML UI components — faster responses, fewer tokens. See [NO_UI Mode](#no_ui-mode) |
|
|
153
154
|
| `APPIUM_MCP_APPS_ENABLED` | Optional | MCP Apps static UI mode. Enabled by default. Set to `false` or `0` to force the embedded UI compatibility fallback. See [MCP Apps Mode](#mcp-apps-mode) |
|
|
154
155
|
| `APPIUM_MCP_ON_CLIENT_DISCONNECT` | Optional | Session cleanup when the MCP client disconnects: `delete_all` (default) deletes **MCP-owned** Appium sessions (`safeDeleteAllSessions`); `skip` keeps those sessions across disconnects (e.g. HTTP/stream clients that reconnect). Attached/remote sessions are not removed by this path. See [MCP disconnect behavior](#mcp-disconnect-behavior). |
|
|
@@ -409,7 +410,7 @@ Set the `NO_UI` environment variable to `true` or `1` to disable UI components a
|
|
|
409
410
|
The following tools return lightweight text-only responses when NO_UI is enabled:
|
|
410
411
|
|
|
411
412
|
- `appium_screenshot` - Screenshot files are still saved to disk, but base64 data is not embedded in responses
|
|
412
|
-
- `appium_get_page_source` - Returns XML as text without interactive inspector UI
|
|
413
|
+
- `appium_get_page_source` - Returns XML as text without interactive inspector UI by default. With `saveToFile: true`, returns the saved XML path and byte size instead; `NO_UI` does not enable file saving.
|
|
413
414
|
- `generate_locators` - Returns locator data as JSON without interactive UI
|
|
414
415
|
- `select_device` - Returns device list as text without picker UI
|
|
415
416
|
- `appium_session_management` (action=create) - Returns session info as text without dashboard UI
|
|
@@ -719,7 +720,7 @@ Without an allow regex, any syntactically valid HTTP(S) URL without a query stri
|
|
|
719
720
|
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
720
721
|
| `appium_screenshot` | Take a screenshot and save as PNG. Optionally provide `elementUUID` to capture a specific element. Pass `returnRawBase64: true` (default `false`) to return the raw base64 PNG inline instead of saving to disk — useful when the server runs on a remote machine where the saved file is not accessible. Intended for manual use only; an LLM should keep this `false`. |
|
|
721
722
|
| `appium_get_window_size` | Get the width and height of the device screen in pixels |
|
|
722
|
-
| `appium_get_page_source`
|
|
723
|
+
| `appium_get_page_source` | Return full XML inline by default. Set `saveToFile: true` to save a server-local file and return its path and byte size; optionally add `selector` (XPath) or `pattern` for bounded summaries with visible siblings. |
|
|
723
724
|
| `appium_orientation` | Get or set device/screen orientation with `action` = `get` or `set` (requires `orientation` for set). |
|
|
724
725
|
| `appium_geolocation` | Get, set, or reset the device GPS coordinates with `action` = `get`, `set`, or `reset`. For `set`, provide `latitude` and `longitude` (and optional `altitude` on Android). Not supported on Android emulators for `reset`. |
|
|
725
726
|
| `appium_screen_recording` | Start or stop screen recording with `action` = `start` or `stop`. On stop, returns the saved MP4 path. |
|
|
@@ -936,3 +937,50 @@ This project is licensed under the Apache-2.0. See the [LICENSE](LICENSE) file f
|
|
|
936
937
|
Model-dependent MCP tool-selection and argument evals are available separately from
|
|
937
938
|
`npm test`. See [evals/README.md](evals/README.md) for setup and `npm run eval:mcp`.
|
|
938
939
|
For local evaluation using Codex with ChatGPT login, use `npm run eval:codex`.
|
|
940
|
+
|
|
941
|
+
### Page source file output and filtered summaries
|
|
942
|
+
|
|
943
|
+
| Argument | Default | Behavior |
|
|
944
|
+
| --- | --- | --- |
|
|
945
|
+
| `saveToFile` | `false` | `false` returns full XML as before; `true` saves a fresh XML file and returns metadata. |
|
|
946
|
+
| `selector` | Omitted | XPath selecting elements; requires `saveToFile: true`. |
|
|
947
|
+
| `pattern` | Omitted | Case-sensitive literal substring of tag names or attribute values; requires `saveToFile: true`. Combines with `selector`. |
|
|
948
|
+
| `sessionId` | Active session | Selects the Appium session. |
|
|
949
|
+
|
|
950
|
+
|
|
951
|
+
`appium_get_page_source` keeps its existing behavior by default: full XML is returned inline, with the existing inspector behavior. Omit `saveToFile` or pass `saveToFile: false` to use this mode; it does not write a file.
|
|
952
|
+
|
|
953
|
+
To opt into file output, pass `saveToFile: true`. Each call retrieves a fresh page source and saves a new snapshot; it does not reuse previously saved XML. XML is saved on the **MCP server's filesystem** and the response is JSON `{filepath, bytes}`. Set `PAGE_SOURCES_DIR` to choose a directory (relative paths resolve from the server working directory); otherwise the OS temporary directory is used. Files have unique names and owner-only permissions. Remove saved files when no longer needed.
|
|
954
|
+
|
|
955
|
+
With `NO_UI=true`, the default response still contains full XML and omits the additional HTML UI, as before. File output requires `saveToFile: true` regardless of `NO_UI`; it does not embed XML or HTML. Use the default inline mode when the client cannot access server files.
|
|
956
|
+
|
|
957
|
+
Save the full XML without returning its contents:
|
|
958
|
+
|
|
959
|
+
```json
|
|
960
|
+
{
|
|
961
|
+
"tool": "appium_get_page_source",
|
|
962
|
+
"arguments": {"saveToFile": true}
|
|
963
|
+
}
|
|
964
|
+
```
|
|
965
|
+
|
|
966
|
+
Example response (the path and byte count vary):
|
|
967
|
+
|
|
968
|
+
```json
|
|
969
|
+
{"filepath": "/tmp/page-source-<uuid>.xml", "bytes": 41312}
|
|
970
|
+
```
|
|
971
|
+
|
|
972
|
+
To inspect only part of the tree, pass `saveToFile: true` together with `selector` (an XPath selecting elements), `pattern` (a case-sensitive literal substring of tag names or attribute values), or both. Matching nodes include identifying attributes, visibility and bounds when present, plus explicitly visible siblings. Summaries are capped at 100 nodes including siblings and report `truncated`; the saved XML always contains the full tree. No matches returns `matches: []`. Filters cannot be combined with `saveToFile: false`.
|
|
973
|
+
|
|
974
|
+
```json
|
|
975
|
+
{
|
|
976
|
+
"tool": "appium_get_page_source",
|
|
977
|
+
"arguments": {"saveToFile": true, "selector": "//*[@name='View All']"}
|
|
978
|
+
}
|
|
979
|
+
```
|
|
980
|
+
|
|
981
|
+
```json
|
|
982
|
+
{
|
|
983
|
+
"tool": "appium_get_page_source",
|
|
984
|
+
"arguments": {"saveToFile": false}
|
|
985
|
+
}
|
|
986
|
+
```
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/tools/gestures/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAStB,eAAO,MAAM,eAAe,4GASlB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,eAAO,MAAM,YAAY,qCAAsC,CAAC;AAChE,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,eAAO,MAAM,uBAAuB,uCAAwC,CAAC;AAC7E,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,eAAO,MAAM,kBAAkB,yJAUrB,CAAC;AAEX,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
|
|
1
|
+
{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/tools/gestures/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAStB,eAAO,MAAM,eAAe,4GASlB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,eAAO,MAAM,YAAY,qCAAsC,CAAC;AAChE,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,eAAO,MAAM,uBAAuB,uCAAwC,CAAC;AAC7E,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,eAAO,MAAM,kBAAkB,yJAUrB,CAAC;AAEX,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8IxB,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}
|
|
@@ -55,17 +55,14 @@ export const gestureSchema = z.object({
|
|
|
55
55
|
.int()
|
|
56
56
|
.min(0)
|
|
57
57
|
.optional()
|
|
58
|
-
.describe('X coordinate
|
|
59
|
-
'
|
|
60
|
-
'For pinch_zoom: center X, paired with y. Tap/double_tap/long_press/pinch_zoom ignore x/y when elementUUID is set.'),
|
|
58
|
+
.describe('X pixel coordinate, paired with y: tap location, pinch center, or scroll/swipe start (requires endX/endY). ' +
|
|
59
|
+
'elementUUID overrides x/y for tap/double_tap/long_press/pinch_zoom.'),
|
|
61
60
|
y: z
|
|
62
61
|
.number()
|
|
63
62
|
.int()
|
|
64
63
|
.min(0)
|
|
65
64
|
.optional()
|
|
66
|
-
.describe('Y coordinate
|
|
67
|
-
'For scroll/swipe: starting Y in custom-coordinate mode. For pinch_zoom: center Y. ' +
|
|
68
|
-
'The same elementUUID precedence as x applies.'),
|
|
65
|
+
.describe('Y pixel coordinate, paired with x; same action meanings and elementUUID precedence as x.'),
|
|
69
66
|
endX: z
|
|
70
67
|
.number()
|
|
71
68
|
.int()
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/tools/gestures/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,EAAC,iBAAiB,EAAC,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAC,WAAW,EAAC,MAAM,iBAAiB,CAAC;AAE5C,MAAM,YAAY,GAAG,WAAW,EAAE;IAChC,CAAC,CAAC,oFAAoF;IACtF,CAAC,CAAC,EAAE,CAAC;AAEP,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,KAAK;IACL,YAAY;IACZ,YAAY;IACZ,QAAQ;IACR,OAAO;IACP,YAAY;IACZ,mBAAmB;IACnB,MAAM;CACE,CAAC;AAIX,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAU,CAAC;AAGhE,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAU,CAAC;AAG7E,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,kBAAkB;IAClB,IAAI;IACJ,uBAAuB;IACvB,kBAAkB;IAClB,sBAAsB;IACtB,OAAO;IACP,MAAM;IACN,YAAY;IACZ,cAAc;CACN,CAAC;AAEX,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,MAAM,EAAE,CAAC;SACN,IAAI,CAAC,eAAe,CAAC;SACrB,QAAQ,CACP;QACE,qBAAqB;QACrB,wCAAwC;QACxC,4EAA4E;QAC5E,yEAAyE;QACzE,qEAAqE;QACrE,2DAA2D;QAC3D,4GAA4G;QAC5G,uFAAuF;QACvF,gHAAgH;QAChH,+GAA+G;QAC/G,oIAAoI;QACpI,4FAA4F;QAC5F,yCAAyC;KAC1C,CAAC,IAAI,CAAC,IAAI,CAAC,CACb;IAEH,WAAW,EAAE,iBAAiB;SAC3B,QAAQ,EAAE;SACV,QAAQ,CACP,YAAY;QACV,gGAAgG;QAChG,mHAAmH,CACtH;IAEH,CAAC,EAAE,CAAC;SACD,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,EAAE;SACV,QAAQ,CACP,
|
|
1
|
+
{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/tools/gestures/schema.ts"],"names":[],"mappings":"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"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"get-page-source.d.ts","sourceRoot":"","sources":["../../../src/tools/interactions/get-page-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,OAAO,EAAC,MAAM,SAAS,CAAC;
|
|
1
|
+
{"version":3,"file":"get-page-source.d.ts","sourceRoot":"","sources":["../../../src/tools/interactions/get-page-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,OAAO,EAAC,MAAM,SAAS,CAAC;AAUpD,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CA0D3D"}
|
|
@@ -4,18 +4,22 @@ import { PAGE_SOURCE_INSPECTOR_URI } from '../../resources/page-source-inspector
|
|
|
4
4
|
import { clientSupportsMcpApps, isMcpAppsEnabled } from '../../ui/mcp-apps.js';
|
|
5
5
|
import { createUIResource, createPageSourceInspectorUI, addUIResourceToResponse } from '../../ui/mcp-ui-utils.js';
|
|
6
6
|
import { resolveDriver, textResult, errorResult, toolErrorMessage } from '../tool-response.js';
|
|
7
|
+
import { savePageSourceToFile } from './page-source-file.js';
|
|
7
8
|
export default function getPageSource(server) {
|
|
8
9
|
const mcpAppsEnabled = isMcpAppsEnabled();
|
|
9
10
|
const pageSourceSchema = z.object({
|
|
11
|
+
saveToFile: z.boolean().default(false).describe('Save fresh XML to a file; return path/bytes instead of XML.'),
|
|
12
|
+
selector: z.string().optional().describe('XPath selecting elements.'),
|
|
13
|
+
pattern: z.string().min(1).optional().describe('Literal tag/attribute substring.'),
|
|
10
14
|
sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
|
|
11
15
|
});
|
|
12
16
|
server.addTool({
|
|
13
17
|
name: 'appium_get_page_source',
|
|
14
|
-
description: 'Get
|
|
18
|
+
description: 'Get current-screen XML. saveToFile=true returns server-local path/bytes and enables selector/pattern summaries.',
|
|
15
19
|
_meta: mcpAppsEnabled ? { ui: { resourceUri: PAGE_SOURCE_INSPECTOR_URI } } : undefined,
|
|
16
20
|
parameters: pageSourceSchema,
|
|
17
21
|
annotations: {
|
|
18
|
-
readOnlyHint:
|
|
22
|
+
readOnlyHint: false,
|
|
19
23
|
openWorldHint: false,
|
|
20
24
|
},
|
|
21
25
|
execute: async (args, context) => {
|
|
@@ -29,6 +33,12 @@ export default function getPageSource(server) {
|
|
|
29
33
|
if (!pageSource) {
|
|
30
34
|
return errorResult('Page source is empty or null');
|
|
31
35
|
}
|
|
36
|
+
if (args.saveToFile === true) {
|
|
37
|
+
return textResult(JSON.stringify(await savePageSourceToFile(pageSource, args)));
|
|
38
|
+
}
|
|
39
|
+
if (args.selector !== undefined || args.pattern !== undefined) {
|
|
40
|
+
return errorResult('Use saveToFile=true when selecting or filtering page source nodes.');
|
|
41
|
+
}
|
|
32
42
|
const textResponse = textResult('Page source retrieved successfully: \n' + '```xml ' + pageSource + '```');
|
|
33
43
|
// MCP Apps-capable clients fetch the static inspector once and pass
|
|
34
44
|
// this existing text result to it, avoiding a second copy of the XML.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"get-page-source.js","sourceRoot":"","sources":["../../../src/tools/interactions/get-page-source.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,EAAC,aAAa,IAAI,cAAc,EAAC,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAC,yBAAyB,EAAC,MAAM,0CAA0C,CAAC;AACnF,OAAO,EAAC,qBAAqB,EAAE,gBAAgB,EAAC,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EAAC,gBAAgB,EAAE,2BAA2B,EAAE,uBAAuB,EAAC,MAAM,0BAA0B,CAAC;AAChH,OAAO,EAAC,aAAa,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAC,MAAM,qBAAqB,CAAC;
|
|
1
|
+
{"version":3,"file":"get-page-source.js","sourceRoot":"","sources":["../../../src/tools/interactions/get-page-source.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/** Save a fresh XML snapshot and optionally summarize matching nodes.
|
|
2
|
+
* Invalid filters are evaluated before writing; filesystem errors propagate to the caller.
|
|
3
|
+
*/
|
|
4
|
+
export declare function savePageSourceToFile(pageSource: string, filters?: {
|
|
5
|
+
selector?: string;
|
|
6
|
+
pattern?: string;
|
|
7
|
+
}): Promise<{
|
|
8
|
+
filepath: string;
|
|
9
|
+
bytes: number;
|
|
10
|
+
}>;
|
|
11
|
+
//# sourceMappingURL=page-source-file.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"page-source-file.d.ts","sourceRoot":"","sources":["../../../src/tools/interactions/page-source-file.ts"],"names":[],"mappings":"AAOA;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAM;;;GASjH"}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import { randomUUID } from 'node:crypto';
|
|
2
|
+
import { mkdir, writeFile } from 'node:fs/promises';
|
|
3
|
+
import { tmpdir } from 'node:os';
|
|
4
|
+
import { join, resolve } from 'node:path';
|
|
5
|
+
import { summarizePageSource } from './page-source-summary.js';
|
|
6
|
+
/** Save a fresh XML snapshot and optionally summarize matching nodes.
|
|
7
|
+
* Invalid filters are evaluated before writing; filesystem errors propagate to the caller.
|
|
8
|
+
*/
|
|
9
|
+
export async function savePageSourceToFile(pageSource, filters = {}) {
|
|
10
|
+
const { selector, pattern } = filters;
|
|
11
|
+
const summary = selector !== undefined || pattern !== undefined ? summarizePageSource(pageSource, selector, pattern) : {};
|
|
12
|
+
const directory = process.env.PAGE_SOURCES_DIR ? resolve(process.env.PAGE_SOURCES_DIR) : tmpdir();
|
|
13
|
+
await mkdir(directory, { recursive: true });
|
|
14
|
+
const filepath = join(directory, `page-source-${randomUUID()}.xml`);
|
|
15
|
+
await writeFile(filepath, pageSource, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
|
|
16
|
+
return { filepath, bytes: Buffer.byteLength(pageSource, 'utf8'), ...summary };
|
|
17
|
+
}
|
|
18
|
+
//# sourceMappingURL=page-source-file.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"page-source-file.js","sourceRoot":"","sources":["../../../src/tools/interactions/page-source-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,aAAa,CAAC;AACvC,OAAO,EAAC,KAAK,EAAE,SAAS,EAAC,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAC,MAAM,EAAC,MAAM,SAAS,CAAC;AAC/B,OAAO,EAAC,IAAI,EAAE,OAAO,EAAC,MAAM,WAAW,CAAC;AAExC,OAAO,EAAC,mBAAmB,EAAC,MAAM,0BAA0B,CAAC;AAE7D;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,UAAkB,EAAE,UAAiD,EAAE;IAChH,MAAM,EAAC,QAAQ,EAAE,OAAO,EAAC,GAAG,OAAO,CAAC;IACpC,MAAM,OAAO,GACX,QAAQ,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,mBAAmB,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5G,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAClG,MAAM,KAAK,CAAC,SAAS,EAAE,EAAC,SAAS,EAAE,IAAI,EAAC,CAAC,CAAC;IAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,eAAe,UAAU,EAAE,MAAM,CAAC,CAAC;IACpE,MAAM,SAAS,CAAC,QAAQ,EAAE,UAAU,EAAE,EAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAC,CAAC,CAAC;IACnF,OAAO,EAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,UAAU,EAAE,MAAM,CAAC,EAAE,GAAG,OAAO,EAAC,CAAC;AAC9E,CAAC"}
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/** Bounded node summaries; a pattern is a literal substring, never an executable expression. */
|
|
2
|
+
export declare function summarizePageSource(source: string, selector?: string, pattern?: string): {
|
|
3
|
+
matches: {
|
|
4
|
+
node: Record<string, string>;
|
|
5
|
+
visibleSiblings: Record<string, string>[];
|
|
6
|
+
}[];
|
|
7
|
+
truncated: boolean;
|
|
8
|
+
};
|
|
9
|
+
//# sourceMappingURL=page-source-summary.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"page-source-summary.d.ts","sourceRoot":"","sources":["../../../src/tools/interactions/page-source-summary.ts"],"names":[],"mappings":"AAwCA,gGAAgG;AAChG,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;;;;;;EA6CtF"}
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
import { DOMParser } from '@xmldom/xmldom';
|
|
2
|
+
import xpath from 'xpath';
|
|
3
|
+
const MAX_NODES = 100;
|
|
4
|
+
const FIELDS = [
|
|
5
|
+
'type',
|
|
6
|
+
'class',
|
|
7
|
+
'name',
|
|
8
|
+
'label',
|
|
9
|
+
'value',
|
|
10
|
+
'text',
|
|
11
|
+
'resource-id',
|
|
12
|
+
'content-desc',
|
|
13
|
+
'visible',
|
|
14
|
+
'displayed',
|
|
15
|
+
'bounds',
|
|
16
|
+
'x',
|
|
17
|
+
'y',
|
|
18
|
+
'width',
|
|
19
|
+
'height',
|
|
20
|
+
];
|
|
21
|
+
function isElement(node) {
|
|
22
|
+
return typeof node === 'object' && node !== null && node.nodeType === 1;
|
|
23
|
+
}
|
|
24
|
+
function summarize(node) {
|
|
25
|
+
const result = {
|
|
26
|
+
type: node.getAttribute('type') || node.getAttribute('class') || node.tagName,
|
|
27
|
+
};
|
|
28
|
+
for (const field of FIELDS) {
|
|
29
|
+
const value = node.getAttribute(field);
|
|
30
|
+
if (value !== null) {
|
|
31
|
+
result[field] = value;
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
return result;
|
|
35
|
+
}
|
|
36
|
+
/** Bounded node summaries; a pattern is a literal substring, never an executable expression. */
|
|
37
|
+
export function summarizePageSource(source, selector, pattern) {
|
|
38
|
+
const document = new DOMParser({
|
|
39
|
+
onError: (level, message) => {
|
|
40
|
+
if (level !== 'warning') {
|
|
41
|
+
throw new Error(message);
|
|
42
|
+
}
|
|
43
|
+
},
|
|
44
|
+
}).parseFromString(source, 'text/xml');
|
|
45
|
+
const selection = xpath.select(selector || '//*', document);
|
|
46
|
+
if (!Array.isArray(selection) || selection.some((node) => !isElement(node))) {
|
|
47
|
+
throw new Error('selector must be an XPath selecting elements');
|
|
48
|
+
}
|
|
49
|
+
const selected = selection.filter((node) => pattern === undefined ||
|
|
50
|
+
[node.tagName, ...Array.from(node.attributes).map((attr) => attr.value)].some((value) => value.includes(pattern)));
|
|
51
|
+
let remaining = MAX_NODES;
|
|
52
|
+
let truncated = false;
|
|
53
|
+
const matches = [];
|
|
54
|
+
for (const node of selected) {
|
|
55
|
+
if (remaining === 0) {
|
|
56
|
+
truncated = true;
|
|
57
|
+
break;
|
|
58
|
+
}
|
|
59
|
+
remaining--;
|
|
60
|
+
const visibleSiblings = [];
|
|
61
|
+
for (const sibling of Array.from(node.parentNode?.childNodes ?? [])) {
|
|
62
|
+
if (!isElement(sibling) || sibling === node) {
|
|
63
|
+
continue;
|
|
64
|
+
}
|
|
65
|
+
const visible = sibling.getAttribute('visible') ?? sibling.getAttribute('displayed');
|
|
66
|
+
if (visible !== 'true' && visible !== '1') {
|
|
67
|
+
continue;
|
|
68
|
+
}
|
|
69
|
+
if (remaining === 0) {
|
|
70
|
+
truncated = true;
|
|
71
|
+
break;
|
|
72
|
+
}
|
|
73
|
+
remaining--;
|
|
74
|
+
visibleSiblings.push(summarize(sibling));
|
|
75
|
+
}
|
|
76
|
+
matches.push({ node: summarize(node), visibleSiblings });
|
|
77
|
+
}
|
|
78
|
+
return { matches, truncated };
|
|
79
|
+
}
|
|
80
|
+
//# sourceMappingURL=page-source-summary.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"page-source-summary.js","sourceRoot":"","sources":["../../../src/tools/interactions/page-source-summary.ts"],"names":[],"mappings":"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"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"page-source-inspector-app.d.ts","sourceRoot":"","sources":["../../src/ui/page-source-inspector-app.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,8BAA8B,IAAI,MAAM,
|
|
1
|
+
{"version":3,"file":"page-source-inspector-app.d.ts","sourceRoot":"","sources":["../../src/ui/page-source-inspector-app.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,8BAA8B,IAAI,MAAM,CA2QvD"}
|
|
@@ -117,6 +117,7 @@ export function createPageSourceInspectorAppUI() {
|
|
|
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() {
|
|
|
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() {
|
|
|
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() {
|
|
|
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) {
|
|
@@ -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
|
|
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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "appium-mcp",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.97.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"
|
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.
|
|
6
|
+
"version": "1.97.0",
|
|
7
7
|
"packages": [
|
|
8
8
|
{
|
|
9
9
|
"registryType": "npm",
|
|
10
10
|
"identifier": "appium-mcp",
|
|
11
|
-
"version": "1.
|
|
11
|
+
"version": "1.97.0",
|
|
12
12
|
"transport": {
|
|
13
13
|
"type": "stdio"
|
|
14
14
|
}
|
package/src/tools/README.md
CHANGED
|
@@ -39,7 +39,9 @@ This directory contains all MCP tools available in MCP Appium.
|
|
|
39
39
|
- `set-value.ts` - Enter text
|
|
40
40
|
- `keyboard.ts` - Soft keyboard (`appium_mobile_keyboard`; `action=hide` \| `is_shown`)
|
|
41
41
|
- `get-text.ts` - Get element text
|
|
42
|
-
- `get-page-source.ts` -
|
|
42
|
+
- `get-page-source.ts` - Return current-screen XML by default; opt into server-local file output with `saveToFile: true`
|
|
43
|
+
- `page-source-file.ts` - Save fresh XML snapshots and return path, UTF-8 byte size, and optional summaries
|
|
44
|
+
- `page-source-summary.ts` - Build bounded XPath/literal-filter summaries with visible siblings
|
|
43
45
|
- `screenshot.ts` - Capture screenshots
|
|
44
46
|
|
|
45
47
|
#### Element Search Priority Order
|
|
@@ -213,3 +215,9 @@ After adding a new tool:
|
|
|
213
215
|
- Read [docs/CONTRIBUTING.md](../../docs/CONTRIBUTING.md)
|
|
214
216
|
- Look at examples in `examples/` directory
|
|
215
217
|
- Open an issue for questions
|
|
218
|
+
|
|
219
|
+
### Page source file output
|
|
220
|
+
|
|
221
|
+
`appium_get_page_source` keeps full XML and the existing inspector behavior when `saveToFile` is omitted or false. `saveToFile: true` delegates file creation and optional summary generation to `savePageSourceToFile`. The helper validates filters before writing, creates unique XML files with owner-only permissions under `PAGE_SOURCES_DIR` (or the OS temporary directory), and returns metadata; the tool serializes it into an MCP text response and handles errors.
|
|
222
|
+
|
|
223
|
+
`selector` and `pattern` require `saveToFile: true`. They limit the returned summary, not the saved XML. Each call obtains fresh XML from the driver; this is file-backed snapshot storage, not response reuse. `NO_UI` controls UI resources independently. See [page source file output and filtered summaries](../../README.md#page-source-file-output-and-filtered-summaries) for arguments and usage examples.
|
|
@@ -73,20 +73,15 @@ export const gestureSchema = z.object({
|
|
|
73
73
|
.min(0)
|
|
74
74
|
.optional()
|
|
75
75
|
.describe(
|
|
76
|
-
'X coordinate
|
|
77
|
-
'
|
|
78
|
-
'For pinch_zoom: center X, paired with y. Tap/double_tap/long_press/pinch_zoom ignore x/y when elementUUID is set.',
|
|
76
|
+
'X pixel coordinate, paired with y: tap location, pinch center, or scroll/swipe start (requires endX/endY). ' +
|
|
77
|
+
'elementUUID overrides x/y for tap/double_tap/long_press/pinch_zoom.',
|
|
79
78
|
),
|
|
80
79
|
y: z
|
|
81
80
|
.number()
|
|
82
81
|
.int()
|
|
83
82
|
.min(0)
|
|
84
83
|
.optional()
|
|
85
|
-
.describe(
|
|
86
|
-
'Y coordinate in pixels, paired with x. For tap/double_tap/long_press: tap location. ' +
|
|
87
|
-
'For scroll/swipe: starting Y in custom-coordinate mode. For pinch_zoom: center Y. ' +
|
|
88
|
-
'The same elementUUID precedence as x applies.',
|
|
89
|
-
),
|
|
84
|
+
.describe('Y pixel coordinate, paired with x; same action meanings and elementUUID precedence as x.'),
|
|
90
85
|
endX: z
|
|
91
86
|
.number()
|
|
92
87
|
.int()
|
|
@@ -6,19 +6,24 @@ import {PAGE_SOURCE_INSPECTOR_URI} from '../../resources/page-source-inspector.j
|
|
|
6
6
|
import {clientSupportsMcpApps, isMcpAppsEnabled} from '../../ui/mcp-apps.js';
|
|
7
7
|
import {createUIResource, createPageSourceInspectorUI, addUIResourceToResponse} from '../../ui/mcp-ui-utils.js';
|
|
8
8
|
import {resolveDriver, textResult, errorResult, toolErrorMessage} from '../tool-response.js';
|
|
9
|
+
import {savePageSourceToFile} from './page-source-file.js';
|
|
9
10
|
|
|
10
11
|
export default function getPageSource(server: FastMCP): void {
|
|
11
12
|
const mcpAppsEnabled = isMcpAppsEnabled();
|
|
12
13
|
const pageSourceSchema = z.object({
|
|
14
|
+
saveToFile: z.boolean().default(false).describe('Save fresh XML to a file; return path/bytes instead of XML.'),
|
|
15
|
+
selector: z.string().optional().describe('XPath selecting elements.'),
|
|
16
|
+
pattern: z.string().min(1).optional().describe('Literal tag/attribute substring.'),
|
|
13
17
|
sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
|
|
14
18
|
});
|
|
15
19
|
server.addTool({
|
|
16
20
|
name: 'appium_get_page_source',
|
|
17
|
-
description:
|
|
21
|
+
description:
|
|
22
|
+
'Get current-screen XML. saveToFile=true returns server-local path/bytes and enables selector/pattern summaries.',
|
|
18
23
|
_meta: mcpAppsEnabled ? {ui: {resourceUri: PAGE_SOURCE_INSPECTOR_URI}} : undefined,
|
|
19
24
|
parameters: pageSourceSchema,
|
|
20
25
|
annotations: {
|
|
21
|
-
readOnlyHint:
|
|
26
|
+
readOnlyHint: false,
|
|
22
27
|
openWorldHint: false,
|
|
23
28
|
},
|
|
24
29
|
execute: async (
|
|
@@ -37,6 +42,13 @@ export default function getPageSource(server: FastMCP): void {
|
|
|
37
42
|
return errorResult('Page source is empty or null');
|
|
38
43
|
}
|
|
39
44
|
|
|
45
|
+
if (args.saveToFile === true) {
|
|
46
|
+
return textResult(JSON.stringify(await savePageSourceToFile(pageSource, args)));
|
|
47
|
+
}
|
|
48
|
+
if (args.selector !== undefined || args.pattern !== undefined) {
|
|
49
|
+
return errorResult('Use saveToFile=true when selecting or filtering page source nodes.');
|
|
50
|
+
}
|
|
51
|
+
|
|
40
52
|
const textResponse = textResult('Page source retrieved successfully: \n' + '```xml ' + pageSource + '```');
|
|
41
53
|
|
|
42
54
|
// MCP Apps-capable clients fetch the static inspector once and pass
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import {randomUUID} from 'node:crypto';
|
|
2
|
+
import {mkdir, writeFile} from 'node:fs/promises';
|
|
3
|
+
import {tmpdir} from 'node:os';
|
|
4
|
+
import {join, resolve} from 'node:path';
|
|
5
|
+
|
|
6
|
+
import {summarizePageSource} from './page-source-summary.js';
|
|
7
|
+
|
|
8
|
+
/** Save a fresh XML snapshot and optionally summarize matching nodes.
|
|
9
|
+
* Invalid filters are evaluated before writing; filesystem errors propagate to the caller.
|
|
10
|
+
*/
|
|
11
|
+
export async function savePageSourceToFile(pageSource: string, filters: {selector?: string; pattern?: string} = {}) {
|
|
12
|
+
const {selector, pattern} = filters;
|
|
13
|
+
const summary =
|
|
14
|
+
selector !== undefined || pattern !== undefined ? summarizePageSource(pageSource, selector, pattern) : {};
|
|
15
|
+
const directory = process.env.PAGE_SOURCES_DIR ? resolve(process.env.PAGE_SOURCES_DIR) : tmpdir();
|
|
16
|
+
await mkdir(directory, {recursive: true});
|
|
17
|
+
const filepath = join(directory, `page-source-${randomUUID()}.xml`);
|
|
18
|
+
await writeFile(filepath, pageSource, {encoding: 'utf8', mode: 0o600, flag: 'wx'});
|
|
19
|
+
return {filepath, bytes: Buffer.byteLength(pageSource, 'utf8'), ...summary};
|
|
20
|
+
}
|
|
@@ -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
|
+
}
|
|
@@ -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) {
|