appium-mcp 1.92.13 → 1.93.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 +12 -0
- package/README.md +6 -2
- package/dist/ai-finder/vision-finder.d.ts +2 -0
- package/dist/ai-finder/vision-finder.d.ts.map +1 -1
- package/dist/ai-finder/vision-finder.js +27 -9
- package/dist/ai-finder/vision-finder.js.map +1 -1
- package/dist/create-server.js +1 -1
- package/dist/create-server.js.map +1 -1
- package/dist/persistence.d.ts.map +1 -1
- package/dist/persistence.js +17 -4
- package/dist/persistence.js.map +1 -1
- package/dist/plugin.d.ts +4 -0
- package/dist/plugin.d.ts.map +1 -1
- package/dist/plugin.js +3 -9
- package/dist/plugin.js.map +1 -1
- package/dist/tools/ai/schema.js +1 -1
- package/dist/tools/ai/schema.js.map +1 -1
- package/dist/tools/app-management/app.js +1 -1
- package/dist/tools/app-management/app.js.map +1 -1
- package/dist/tools/app-management/permissions.js +1 -1
- package/dist/tools/app-management/permissions.js.map +1 -1
- package/dist/tools/context/context.js +1 -1
- package/dist/tools/context/context.js.map +1 -1
- package/dist/tools/gestures/drag-and-drop.js +1 -1
- package/dist/tools/gestures/drag-and-drop.js.map +1 -1
- package/dist/tools/gestures/perform-actions.js +1 -1
- package/dist/tools/gestures/perform-actions.js.map +1 -1
- package/dist/tools/gestures/schema.d.ts +1 -1
- package/dist/tools/gestures/schema.d.ts.map +1 -1
- package/dist/tools/gestures/schema.js +48 -41
- package/dist/tools/gestures/schema.js.map +1 -1
- package/dist/tools/index.d.ts.map +1 -1
- package/dist/tools/index.js +3 -26
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/interactions/active-element.js +1 -1
- package/dist/tools/interactions/active-element.js.map +1 -1
- package/dist/tools/interactions/clipboard.js +1 -1
- package/dist/tools/interactions/clipboard.js.map +1 -1
- package/dist/tools/interactions/find.d.ts.map +1 -1
- package/dist/tools/interactions/find.js +23 -24
- package/dist/tools/interactions/find.js.map +1 -1
- package/dist/tools/interactions/get-element-attribute.js +1 -1
- package/dist/tools/interactions/get-element-attribute.js.map +1 -1
- package/dist/tools/interactions/get-page-source.js +1 -1
- package/dist/tools/interactions/get-page-source.js.map +1 -1
- package/dist/tools/interactions/get-text.js +1 -1
- package/dist/tools/interactions/get-text.js.map +1 -1
- package/dist/tools/interactions/handle-alert.js +1 -1
- package/dist/tools/interactions/handle-alert.js.map +1 -1
- package/dist/tools/interactions/keyboard.js +1 -1
- package/dist/tools/interactions/keyboard.js.map +1 -1
- package/dist/tools/interactions/orientation.js +1 -1
- package/dist/tools/interactions/orientation.js.map +1 -1
- package/dist/tools/interactions/press-key.js +1 -1
- package/dist/tools/interactions/press-key.js.map +1 -1
- package/dist/tools/interactions/screen-recording.js +1 -1
- package/dist/tools/interactions/screen-recording.js.map +1 -1
- package/dist/tools/interactions/screenshot.d.ts.map +1 -1
- package/dist/tools/interactions/screenshot.js +5 -13
- package/dist/tools/interactions/screenshot.js.map +1 -1
- package/dist/tools/interactions/set-value.js +1 -1
- package/dist/tools/interactions/set-value.js.map +1 -1
- package/dist/tools/interactions/window-size.js +1 -1
- package/dist/tools/interactions/window-size.js.map +1 -1
- package/dist/tools/ios/prepare-ios-real-device.d.ts.map +1 -1
- package/dist/tools/ios/prepare-ios-real-device.js +4 -7
- package/dist/tools/ios/prepare-ios-real-device.js.map +1 -1
- package/dist/tools/ios/prepare-ios-simulator.d.ts.map +1 -1
- package/dist/tools/ios/prepare-ios-simulator.js +3 -1
- package/dist/tools/ios/prepare-ios-simulator.js.map +1 -1
- package/dist/tools/session/attach-session.js +5 -4
- package/dist/tools/session/attach-session.js.map +1 -1
- package/dist/tools/session/create-session.d.ts +2 -11
- package/dist/tools/session/create-session.d.ts.map +1 -1
- package/dist/tools/session/create-session.js +7 -20
- package/dist/tools/session/create-session.js.map +1 -1
- package/dist/tools/session/device-control.js +1 -1
- package/dist/tools/session/device-control.js.map +1 -1
- package/dist/tools/session/device-info.js +1 -1
- package/dist/tools/session/device-info.js.map +1 -1
- package/dist/tools/session/driver-settings.js +1 -1
- package/dist/tools/session/driver-settings.js.map +1 -1
- package/dist/tools/session/file-transfer.js +1 -1
- package/dist/tools/session/file-transfer.js.map +1 -1
- package/dist/tools/session/geolocation.js +1 -1
- package/dist/tools/session/geolocation.js.map +1 -1
- package/dist/tools/session/select-device.d.ts.map +1 -1
- package/dist/tools/session/select-device.js +7 -24
- package/dist/tools/session/select-device.js.map +1 -1
- package/dist/tools/session/select-session.js +1 -1
- package/dist/tools/session/select-session.js.map +1 -1
- package/dist/tools/session/session.d.ts.map +1 -1
- package/dist/tools/session/session.js +32 -30
- package/dist/tools/session/session.js.map +1 -1
- package/dist/tools/test-generation/generate-tests.d.ts.map +1 -1
- package/dist/tools/test-generation/generate-tests.js +9 -20
- package/dist/tools/test-generation/generate-tests.js.map +1 -1
- package/dist/tools/test-generation/locators.js +1 -1
- package/dist/tools/test-generation/locators.js.map +1 -1
- package/dist/tools/tool-response.d.ts.map +1 -1
- package/dist/tools/tool-response.js +12 -4
- package/dist/tools/tool-response.js.map +1 -1
- package/dist/utils/sensitive.d.ts +7 -0
- package/dist/utils/sensitive.d.ts.map +1 -1
- package/dist/utils/sensitive.js +37 -0
- package/dist/utils/sensitive.js.map +1 -1
- package/dist/utils/url.d.ts +7 -0
- package/dist/utils/url.d.ts.map +1 -1
- package/dist/utils/url.js +23 -0
- package/dist/utils/url.js.map +1 -1
- package/package.json +11 -3
- package/scripts/audit-tool-footprint.mjs +76 -53
- package/server.json +2 -2
- package/src/ai-finder/vision-finder.ts +35 -10
- package/src/create-server.ts +1 -1
- package/src/persistence.ts +18 -4
- package/src/plugin.ts +7 -9
- package/src/tools/ai/schema.ts +1 -1
- package/src/tools/app-management/app.ts +1 -1
- package/src/tools/app-management/permissions.ts +1 -1
- package/src/tools/context/context.ts +1 -1
- package/src/tools/gestures/drag-and-drop.ts +1 -1
- package/src/tools/gestures/perform-actions.ts +1 -1
- package/src/tools/gestures/schema.ts +48 -41
- package/src/tools/index.ts +3 -27
- package/src/tools/interactions/active-element.ts +1 -1
- package/src/tools/interactions/clipboard.ts +1 -1
- package/src/tools/interactions/find.ts +23 -24
- package/src/tools/interactions/get-element-attribute.ts +1 -1
- package/src/tools/interactions/get-page-source.ts +1 -1
- package/src/tools/interactions/get-text.ts +1 -1
- package/src/tools/interactions/handle-alert.ts +1 -1
- package/src/tools/interactions/keyboard.ts +1 -1
- package/src/tools/interactions/orientation.ts +1 -1
- package/src/tools/interactions/press-key.ts +1 -1
- package/src/tools/interactions/screen-recording.ts +1 -1
- package/src/tools/interactions/screenshot.ts +5 -15
- package/src/tools/interactions/set-value.ts +1 -1
- package/src/tools/interactions/window-size.ts +1 -1
- package/src/tools/ios/prepare-ios-real-device.ts +4 -7
- package/src/tools/ios/prepare-ios-simulator.ts +3 -1
- package/src/tools/session/attach-session.ts +5 -4
- package/src/tools/session/create-session.ts +7 -21
- package/src/tools/session/device-control.ts +1 -1
- package/src/tools/session/device-info.ts +1 -1
- package/src/tools/session/driver-settings.ts +1 -1
- package/src/tools/session/file-transfer.ts +1 -1
- package/src/tools/session/geolocation.ts +1 -1
- package/src/tools/session/select-device.ts +8 -28
- package/src/tools/session/select-session.ts +1 -1
- package/src/tools/session/session.ts +32 -30
- package/src/tools/test-generation/generate-tests.ts +9 -20
- package/src/tools/test-generation/locators.ts +1 -1
- package/src/tools/tool-response.ts +14 -4
- package/src/utils/sensitive.ts +42 -0
- package/src/utils/url.ts +26 -0
|
@@ -36,7 +36,7 @@ export default function deviceInfo(server: FastMCP): void {
|
|
|
36
36
|
.describe(
|
|
37
37
|
'Only used when action is "time". moment.js format string for the returned time. Defaults to ISO 8601 (YYYY-MM-DDTHH:mm:ssZ).',
|
|
38
38
|
),
|
|
39
|
-
sessionId: z.string().optional().describe('Session ID to
|
|
39
|
+
sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
|
|
40
40
|
});
|
|
41
41
|
|
|
42
42
|
server.addTool({
|
|
@@ -19,7 +19,7 @@ const schema = z.object({
|
|
|
19
19
|
'waitForIdleTimeout, waitForSelectorTimeout, ignoreUnimportantViews; iOS XCUITest has its own set). ' +
|
|
20
20
|
'Use action=get first to inspect current values.',
|
|
21
21
|
),
|
|
22
|
-
sessionId: z.string().optional().describe('Session ID to
|
|
22
|
+
sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
|
|
23
23
|
});
|
|
24
24
|
|
|
25
25
|
type DriverSettingsArgs = z.infer<typeof schema>;
|
|
@@ -35,7 +35,7 @@ export default function fileTransfer(server: FastMCP): void {
|
|
|
35
35
|
action: z.enum(['push', 'pull']).describe('push uploads a file to device; pull downloads from device.'),
|
|
36
36
|
remotePath: z.string().min(1).describe(remotePathDescription),
|
|
37
37
|
payloadBase64: z.string().optional().describe('Required when action=push. Ignored when action=pull.'),
|
|
38
|
-
sessionId: z.string().optional().describe('Session ID to
|
|
38
|
+
sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
|
|
39
39
|
});
|
|
40
40
|
|
|
41
41
|
server.addTool({
|
|
@@ -33,7 +33,7 @@ const schema = z.object({
|
|
|
33
33
|
.optional()
|
|
34
34
|
.refine((v) => v === undefined || !isNaN(v), 'altitude must be a valid number')
|
|
35
35
|
.describe('Altitude value in meters. Android only, defaults to 0. Ignored on iOS. Used with: set.'),
|
|
36
|
-
sessionId: z.string().optional().describe('Session ID to
|
|
36
|
+
sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
|
|
37
37
|
});
|
|
38
38
|
|
|
39
39
|
type GeolocationArgs = z.infer<typeof schema>;
|
|
@@ -72,36 +72,16 @@ export function clearSelectedDevice(): void {
|
|
|
72
72
|
export default function selectDevice(server: any): void {
|
|
73
73
|
server.addTool({
|
|
74
74
|
name: 'select_device',
|
|
75
|
-
description:
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
3. If only one device is found, it is auto-selected - proceed to appium_session_management (action=create) (or prepare_ios_simulator for iOS simulators)
|
|
81
|
-
4. If multiple devices are found, ask the user which one they want, then call this tool again with deviceUdid
|
|
82
|
-
5. After selection, proceed to appium_session_management (action=create) (or prepare_ios_simulator for iOS simulators, then appium_session_management with action=create)
|
|
83
|
-
WORKFLOW FOR REMOTE SERVERS:
|
|
84
|
-
- SKIP this tool entirely
|
|
85
|
-
- Device selection should be handled via capabilities on appium_session_management (action=create) (e.g., appium:deviceName, appium:udid)
|
|
86
|
-
- The remote Appium server is already configured for specific device(s)
|
|
87
|
-
`,
|
|
75
|
+
description:
|
|
76
|
+
'Discover/select a LOCAL device. Ask for platform if unknown; one device is auto-selected. ' +
|
|
77
|
+
'For multiple devices, ask the user to choose, then pass deviceUdid. ' +
|
|
78
|
+
'Next: prepare_ios_simulator for iOS simulators, then appium_session_management action=create. ' +
|
|
79
|
+
'Skip for REMOTE servers: pass device capabilities (appium:deviceName/appium:udid) and the user-provided remoteServerUrl to session creation.',
|
|
88
80
|
parameters: z
|
|
89
81
|
.object({
|
|
90
|
-
platform: z
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
iosDeviceType: z
|
|
94
|
-
.enum(['simulator', 'real'])
|
|
95
|
-
.optional()
|
|
96
|
-
.describe(
|
|
97
|
-
"For iOS only: Specify whether to use 'simulator' or 'real' device. REQUIRED when platform is 'ios'.",
|
|
98
|
-
),
|
|
99
|
-
deviceUdid: z
|
|
100
|
-
.string()
|
|
101
|
-
.optional()
|
|
102
|
-
.describe(
|
|
103
|
-
'The UDID of the device selected by the user. If not provided, this tool will list available devices for the user to choose from.',
|
|
104
|
-
),
|
|
82
|
+
platform: z.enum(['ios', 'android']).describe('Platform chosen by the user.'),
|
|
83
|
+
iosDeviceType: z.enum(['simulator', 'real']).optional().describe('Required for ios: simulator or real device.'),
|
|
84
|
+
deviceUdid: z.string().optional().describe('User-selected UDID. Omit to discover devices.'),
|
|
105
85
|
})
|
|
106
86
|
.refine((data) => data.platform !== 'ios' || data.iosDeviceType !== undefined, {
|
|
107
87
|
message: "iosDeviceType ('simulator' or 'real') is required when platform is 'ios'",
|
|
@@ -4,7 +4,7 @@ import {textResult, errorResult} from '../tool-response.js';
|
|
|
4
4
|
export async function selectSessionAction(sessionId: string): Promise<any> {
|
|
5
5
|
const updated = setActiveSession(sessionId);
|
|
6
6
|
if (!updated) {
|
|
7
|
-
return errorResult(`Session ${sessionId} was not found. Use
|
|
7
|
+
return errorResult(`Session ${sessionId} was not found. Use appium_session_management (action=list) for IDs.`);
|
|
8
8
|
}
|
|
9
9
|
return textResult(`Session ${sessionId} is now active.`);
|
|
10
10
|
}
|
|
@@ -11,50 +11,50 @@ import {selectSessionAction} from './select-session.js';
|
|
|
11
11
|
|
|
12
12
|
const SESSION_ACTIONS = ['create', 'attach', 'detach', 'delete', 'list', 'select'] as const;
|
|
13
13
|
|
|
14
|
-
const CREATE_SESSION_DESCRIPTION =
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
14
|
+
const CREATE_SESSION_DESCRIPTION = [
|
|
15
|
+
'Create a new Appium session.',
|
|
16
|
+
'DEFAULT MODE (no remoteServerUrl): use unless the user explicitly provides a server URL.',
|
|
17
|
+
'- Drivers run embedded inside this MCP server; no separate Appium process is needed.',
|
|
18
|
+
'- Use select_device tool FIRST to discover devices. Ask for platform/device if unknown; do not assume a platform.',
|
|
19
|
+
'- For iOS simulators, run prepare_ios_simulator before creating the session.',
|
|
20
|
+
'- Call appium_session_management action=create with the selected platform and any returned capabilitiesHint serialized as capabilities.',
|
|
21
|
+
'- Do NOT pass remoteServerUrl for local/embedded mode. NEVER invent a localhost URL.',
|
|
22
|
+
'REMOTE SERVER MODE (only when user explicitly provides a URL):',
|
|
23
|
+
'- Skip local device selection and preparation; do not call select_device.',
|
|
24
|
+
'- Infer platform and device type from the request when possible; ask if unclear.',
|
|
25
|
+
'- Use platform=general for non-Android/iOS drivers (Windows, macOS, custom); capabilities pass through without platform defaults.',
|
|
26
|
+
'- Call appium_session_management action=create with platform, remoteServerUrl, and the requested capabilities.',
|
|
27
|
+
'- Example: "create an iOS session at http://localhost:4723" means platform=ios and remoteServerUrl=http://localhost:4723; do not discover local devices.',
|
|
28
|
+
].join('\n');
|
|
29
29
|
|
|
30
30
|
const schema = z.object({
|
|
31
31
|
action: z
|
|
32
32
|
.enum(SESSION_ACTIONS)
|
|
33
33
|
.describe(
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
'
|
|
37
|
-
'detach:
|
|
38
|
-
'delete:
|
|
39
|
-
'list:
|
|
40
|
-
'select:
|
|
34
|
+
`create: ${CREATE_SESSION_DESCRIPTION}\n` +
|
|
35
|
+
'attach: connect to an existing remote Appium session without taking ownership of its lifecycle. ' +
|
|
36
|
+
'Requires remoteServerUrl and sessionId; capabilities are fetched from the remote server.\n' +
|
|
37
|
+
'detach: remove an attached session from MCP without deleting the real remote session. Defaults to the active session.\n' +
|
|
38
|
+
'delete: delete a session and clean up resources. Defaults to the active session.\n' +
|
|
39
|
+
'list: list managed sessions with active flag, ownership, and current context.\n' +
|
|
40
|
+
'select: set sessionId as the active session for subsequent calls; requires sessionId.',
|
|
41
41
|
),
|
|
42
42
|
platform: z
|
|
43
43
|
.enum(DRIVER_MODE_PLATFORMS)
|
|
44
44
|
.optional()
|
|
45
45
|
.describe(
|
|
46
|
-
'Required for create. ' +
|
|
47
|
-
'For
|
|
48
|
-
'Use "general" for non-Android/iOS drivers (Windows, macOS, custom). ' +
|
|
49
|
-
'For remote servers, infer from context.',
|
|
46
|
+
'Required for create. For local sessions, match the platform selected via select_device. ' +
|
|
47
|
+
'For remote sessions, infer from the request; general supports non-Android/iOS drivers (Windows, macOS, custom) and requires remoteServerUrl.',
|
|
50
48
|
),
|
|
51
49
|
capabilities: z
|
|
52
50
|
.string()
|
|
53
51
|
.optional()
|
|
54
52
|
.describe(
|
|
55
|
-
'Optional W3C capabilities
|
|
56
|
-
'
|
|
57
|
-
'
|
|
53
|
+
'Optional W3C capabilities as a JSON string, e.g. \'{"appium:app":"/path/to/app","appium:platformVersion":"17.0"}\'. ' +
|
|
54
|
+
'Create: overrides defaults for ios/android; passed through as-is for general. ' +
|
|
55
|
+
'Common keys: appium:app, appium:deviceName, appium:udid, appium:platformVersion, appium:bundleId. ' +
|
|
56
|
+
'When using capabilitiesHint from a preparation tool, serialize the full object to JSON; preserve boolean and numeric values. ' +
|
|
57
|
+
'Attach: optional fallback values (e.g. \'{"platformName":"iOS"}\'); capabilities fetched from the server take precedence.',
|
|
58
58
|
),
|
|
59
59
|
remoteServerUrl: z
|
|
60
60
|
.string()
|
|
@@ -66,7 +66,9 @@ const schema = z.object({
|
|
|
66
66
|
.string()
|
|
67
67
|
.optional()
|
|
68
68
|
.describe(
|
|
69
|
-
'
|
|
69
|
+
'Required for attach and select: the existing session to connect to or activate. ' +
|
|
70
|
+
'For delete: session to delete. For detach: attached session to forget without stopping it. ' +
|
|
71
|
+
'Delete/detach default to the active session when omitted.',
|
|
70
72
|
),
|
|
71
73
|
});
|
|
72
74
|
|
|
@@ -11,33 +11,22 @@ export default function generateTest(server: FastMCP): void {
|
|
|
11
11
|
const instructions = (params: {steps: string[]}) =>
|
|
12
12
|
[
|
|
13
13
|
`## Instructions`,
|
|
14
|
-
`-
|
|
15
|
-
`- You are given a scenario and you need to generate an Appium test for it.`,
|
|
14
|
+
`- Generate an Appium test from the scenario after executing it on a real session.`,
|
|
16
15
|
``,
|
|
17
16
|
`### Ordered workflow (use these exact MCP tool names)`,
|
|
18
|
-
`1. select_device
|
|
19
|
-
`2.
|
|
20
|
-
`3.
|
|
21
|
-
`4.
|
|
22
|
-
|
|
23
|
-
`6. Interact using the same tool names the server exposes, for example:`,
|
|
24
|
-
` - appium_gesture with action=tap (or double_tap, long_press, scroll, swipe, scroll_to_element, pinch_zoom) — use the element id from appium_find_element when required`,
|
|
25
|
-
` - appium_drag_and_drop — drag between source and target elementUUID or coordinates`,
|
|
26
|
-
` - appium_set_value — type into an element; optionally appium_mobile_press_key for special keys`,
|
|
27
|
-
` - appium_get_text / appium_get_element_attribute when assertions need visible state`,
|
|
28
|
-
`- After appium_find_element or appium_get_active_element, the first line of the response is elementId:<uuid> (or an ai-element coordinate token). Pass that value as elementUUID to gestures, appium_set_value, or appium_drag_and_drop as documented in each tool. Do not pass ai-element tokens to tools that require a real WebDriver element id.`,
|
|
17
|
+
`1. If no session is ready: locally use select_device, then prepare_ios_simulator or appium_prepare_ios_real_device when needed. Create via appium_session_management action=create with the selected platform. For a user-provided remoteServerUrl, skip local setup and infer platform from context; never invent a URL.`,
|
|
18
|
+
`2. Use appium_app_lifecycle to install, activate, or deep_link only as needed.`,
|
|
19
|
+
`3. Get the target ID with appium_find_element (strategy + selector), or appium_get_active_element when the focused field suffices. Use appium_ai only if registered and no stable locator works.`,
|
|
20
|
+
`4. Interact with appium_gesture (tap, double_tap, long_press, scroll, swipe, scroll_to_element, pinch_zoom), appium_drag_and_drop, appium_set_value, or appium_mobile_press_key. Read assertions with appium_get_text / appium_get_element_attribute.`,
|
|
21
|
+
`- Find responses start with elementId '<value>'; pass the value as elementUUID where supported. ai-element IDs from appium_ai are coordinates, not WebDriver IDs; use them only with tools that support them.`,
|
|
29
22
|
``,
|
|
30
|
-
`- Use generate_locators
|
|
23
|
+
`- Use generate_locators for broad inspection or full-screen code generation, not every step. Consult generate://code-with-locators for templates.`,
|
|
31
24
|
`- An element can only be clicked if it is clickable.`,
|
|
32
25
|
`- Text can only be entered into an element if it is focusable (or use appium_set_value with w3cActions when typing into the focused element).`,
|
|
33
26
|
`- If an interaction fails, retry with a more stable locator or appium_gesture with action=scroll_to_element.`,
|
|
34
|
-
`-
|
|
35
|
-
`- DO NOT generate test code from the scenario alone. DO run steps one by one with the tools listed above.`,
|
|
36
|
-
`- Only after all steps are completed, emit an Appium/WebdriverIO-style test based on the message history.`,
|
|
27
|
+
`- Execute all steps in order before emitting an Appium/WebdriverIO-style test based on the observed interactions; never generate from the scenario alone.`,
|
|
37
28
|
`- Prefer explicit waits (waitForDisplayed, waitForExist, or equivalent) in generated code over fixed sleep or Thread.sleep.`,
|
|
38
29
|
`- Save the generated test file in the tests directory.`,
|
|
39
|
-
`- Use the generate://code-with-locators resource as reference for code generation.`,
|
|
40
|
-
`- Always call appium_find_element (or appium_get_active_element when sufficient) to obtain elementId before tapping or setting value on a specific element.`,
|
|
41
30
|
`Steps:`,
|
|
42
31
|
...params.steps.map((step, index) => `- ${index + 1}. ${step}`),
|
|
43
32
|
].join('\n');
|
|
@@ -45,7 +34,7 @@ export default function generateTest(server: FastMCP): void {
|
|
|
45
34
|
server.addTool({
|
|
46
35
|
name: 'appium_generate_tests',
|
|
47
36
|
description:
|
|
48
|
-
'
|
|
37
|
+
'Return a workflow to execute the scenario with MCP tools, then generate test code from observed interactions. Prefer appium_find_element; generate_locators is for broad inspection.',
|
|
49
38
|
parameters: generateTestSchema,
|
|
50
39
|
annotations: {
|
|
51
40
|
readOnlyHint: false,
|
|
@@ -27,7 +27,7 @@ export default function generateLocators(server: FastMCP): void {
|
|
|
27
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
28
|
_meta: mcpAppsEnabled ? {ui: {resourceUri: LOCATOR_GENERATOR_URI}} : undefined,
|
|
29
29
|
parameters: z.object({
|
|
30
|
-
sessionId: z.string().optional().describe('Session ID to
|
|
30
|
+
sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
|
|
31
31
|
}),
|
|
32
32
|
annotations: {
|
|
33
33
|
readOnlyHint: true,
|
|
@@ -4,7 +4,8 @@ import {type Client} from 'webdriver';
|
|
|
4
4
|
import log from '../logger.js';
|
|
5
5
|
import {readAllPersistedSessions, removePersistedSession} from '../persistence.js';
|
|
6
6
|
import {getDriver, setSession, type DriverInstance, type SessionCapabilities} from '../session-store.js';
|
|
7
|
-
import {
|
|
7
|
+
import {redactUrlCredentials} from '../utils/sensitive.js';
|
|
8
|
+
import {attachToRemoteSession, validateRemoteServerUrl} from '../utils/url.js';
|
|
8
9
|
|
|
9
10
|
const W3C_ELEMENT_ID = 'element-6066-11e4-a52e-4f735466cecf';
|
|
10
11
|
|
|
@@ -14,7 +15,7 @@ export type DriverOrError = {ok: true; driver: DriverInstance} | {ok: false; res
|
|
|
14
15
|
* Normalizes unknown errors into a message string for tool responses.
|
|
15
16
|
*/
|
|
16
17
|
export function toolErrorMessage(err: unknown): string {
|
|
17
|
-
return err instanceof Error ? err.message : String(err);
|
|
18
|
+
return redactUrlCredentials(err instanceof Error ? err.message : String(err));
|
|
18
19
|
}
|
|
19
20
|
|
|
20
21
|
/**
|
|
@@ -111,6 +112,15 @@ async function rehydrateAttachedSession(sessionId: string): Promise<{sessionId:
|
|
|
111
112
|
}
|
|
112
113
|
const candidates = persisted.filter((p) => p.sessionId === sessionId);
|
|
113
114
|
for (const entry of candidates) {
|
|
115
|
+
try {
|
|
116
|
+
validateRemoteServerUrl(entry.remoteServerUrl, process.env.REMOTE_SERVER_URL_ALLOW_REGEX);
|
|
117
|
+
} catch (err) {
|
|
118
|
+
log.warn(
|
|
119
|
+
`Persisted session ${entry.sessionId} has a disallowed remoteServerUrl (${toolErrorMessage(err)}); skipping.`,
|
|
120
|
+
);
|
|
121
|
+
continue;
|
|
122
|
+
}
|
|
123
|
+
|
|
114
124
|
try {
|
|
115
125
|
const client = await attachToRemoteSession({
|
|
116
126
|
remoteServerUrl: entry.remoteServerUrl,
|
|
@@ -123,7 +133,7 @@ async function rehydrateAttachedSession(sessionId: string): Promise<{sessionId:
|
|
|
123
133
|
await (client as Client).getTimeouts();
|
|
124
134
|
} catch (verifyErr) {
|
|
125
135
|
log.warn(
|
|
126
|
-
`Persisted session ${entry.sessionId} failed liveness check (${(verifyErr
|
|
136
|
+
`Persisted session ${entry.sessionId} failed liveness check (${toolErrorMessage(verifyErr)}); pruning.`,
|
|
127
137
|
);
|
|
128
138
|
await removePersistedSession(entry.sessionId);
|
|
129
139
|
continue;
|
|
@@ -142,7 +152,7 @@ async function rehydrateAttachedSession(sessionId: string): Promise<{sessionId:
|
|
|
142
152
|
log.info(`Rehydrated attached session ${entry.sessionId} from persisted store.`);
|
|
143
153
|
return {sessionId: entry.sessionId};
|
|
144
154
|
} catch (err) {
|
|
145
|
-
log.warn(`Persisted session ${entry.sessionId} no longer attachable (${(err
|
|
155
|
+
log.warn(`Persisted session ${entry.sessionId} no longer attachable (${toolErrorMessage(err)}); pruning.`);
|
|
146
156
|
await removePersistedSession(entry.sessionId);
|
|
147
157
|
}
|
|
148
158
|
}
|
package/src/utils/sensitive.ts
CHANGED
|
@@ -1,17 +1,22 @@
|
|
|
1
1
|
const SENSITIVE_KEY_PARTS = [
|
|
2
|
+
'access_key',
|
|
2
3
|
'api_key',
|
|
3
4
|
'apikey',
|
|
4
5
|
'authorization',
|
|
5
6
|
'client_secret',
|
|
6
7
|
'clientsecret',
|
|
7
8
|
'credential',
|
|
9
|
+
'passphrase',
|
|
8
10
|
'password',
|
|
11
|
+
'private_key',
|
|
9
12
|
'remote_server_url',
|
|
10
13
|
'remoteserverurl',
|
|
11
14
|
'secret',
|
|
12
15
|
'token',
|
|
13
16
|
];
|
|
14
17
|
|
|
18
|
+
const URL_USERINFO_PATTERN = /\b([a-z][a-z0-9+.-]*:\/\/)([^\s/@]+)@/gi;
|
|
19
|
+
|
|
15
20
|
/**
|
|
16
21
|
* Determines if a given key is considered sensitive based on whether it includes any of the defined sensitive key parts.
|
|
17
22
|
* The check is case-insensitive and ignores non-alphanumeric characters, so keys like "API-Key", "client secret", or "remote_server_url" would all be correctly identified as sensitive.
|
|
@@ -23,6 +28,43 @@ export function isSensitiveKey(key: string): boolean {
|
|
|
23
28
|
return SENSITIVE_KEY_PARTS.some((part) => normalized.includes(normalizeKey(part)));
|
|
24
29
|
}
|
|
25
30
|
|
|
31
|
+
/** Removes username/password URL userinfo from text intended for logs or errors. */
|
|
32
|
+
export function redactUrlCredentials(value: string): string {
|
|
33
|
+
return value.replace(URL_USERINFO_PATTERN, '$1[REDACTED]@');
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Produces a JSON-safe copy for logs, redacting sensitive keys, URL userinfo,
|
|
38
|
+
* and values large enough to make logs unsafe or impractical.
|
|
39
|
+
*/
|
|
40
|
+
export function redactForLogging(value: unknown): unknown {
|
|
41
|
+
if (value === undefined || value === null) {
|
|
42
|
+
return value;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
try {
|
|
46
|
+
return JSON.parse(
|
|
47
|
+
JSON.stringify(value, (key, nestedValue) => {
|
|
48
|
+
if (key && isSensitiveKey(key)) {
|
|
49
|
+
return '[REDACTED]';
|
|
50
|
+
}
|
|
51
|
+
if (typeof nestedValue === 'string') {
|
|
52
|
+
if (nestedValue.length > 2000) {
|
|
53
|
+
return `[string:${nestedValue.length}]`;
|
|
54
|
+
}
|
|
55
|
+
return redactUrlCredentials(nestedValue);
|
|
56
|
+
}
|
|
57
|
+
if (typeof Buffer !== 'undefined' && Buffer.isBuffer(nestedValue)) {
|
|
58
|
+
return `[buffer:${(nestedValue as Buffer).length}]`;
|
|
59
|
+
}
|
|
60
|
+
return nestedValue;
|
|
61
|
+
}),
|
|
62
|
+
);
|
|
63
|
+
} catch {
|
|
64
|
+
return '[Unserializable value]';
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
|
|
26
68
|
function normalizeKey(key: string): string {
|
|
27
69
|
return key.replace(/[^a-zA-Z0-9]/g, '').toLowerCase();
|
|
28
70
|
}
|
package/src/utils/url.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import WebDriver, {type Client} from 'webdriver';
|
|
2
2
|
|
|
3
|
+
import {redactUrlCredentials} from './sensitive.js';
|
|
3
4
|
import {withQuietWebDriverLogging} from './webdriver-client-options.js';
|
|
4
5
|
|
|
5
6
|
export interface RemoteAttachOptions {
|
|
@@ -17,6 +18,31 @@ export function getPortFromUrl(url: URL): number {
|
|
|
17
18
|
return Number(url.port) || (url.protocol === 'https:' ? 443 : 80);
|
|
18
19
|
}
|
|
19
20
|
|
|
21
|
+
/**
|
|
22
|
+
* Validate a remote Appium server URL and an optional deployment allowlist.
|
|
23
|
+
*
|
|
24
|
+
* The allowlist can only narrow the built-in HTTP(S)-only policy. Queries and
|
|
25
|
+
* fragments are rejected because WebDriver requests use the URL as a base path.
|
|
26
|
+
*/
|
|
27
|
+
export function validateRemoteServerUrl(remoteServerUrl: string, regexRule?: string): void {
|
|
28
|
+
const invalidUrl = (): Error => new Error(`Invalid remoteServerUrl: ${redactUrlCredentials(remoteServerUrl)}.`);
|
|
29
|
+
|
|
30
|
+
let parsed: URL;
|
|
31
|
+
try {
|
|
32
|
+
parsed = new URL(remoteServerUrl);
|
|
33
|
+
} catch {
|
|
34
|
+
throw invalidUrl();
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
if (!['http:', 'https:'].includes(parsed.protocol) || !parsed.hostname || parsed.search || parsed.hash) {
|
|
38
|
+
throw invalidUrl();
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
if (regexRule && !new RegExp(regexRule).test(remoteServerUrl)) {
|
|
42
|
+
throw invalidUrl();
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
|
|
20
46
|
/**
|
|
21
47
|
* Attach to an existing remote Appium session given its server URL and id.
|
|
22
48
|
*
|