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.
Files changed (156) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +6 -2
  3. package/dist/ai-finder/vision-finder.d.ts +2 -0
  4. package/dist/ai-finder/vision-finder.d.ts.map +1 -1
  5. package/dist/ai-finder/vision-finder.js +27 -9
  6. package/dist/ai-finder/vision-finder.js.map +1 -1
  7. package/dist/create-server.js +1 -1
  8. package/dist/create-server.js.map +1 -1
  9. package/dist/persistence.d.ts.map +1 -1
  10. package/dist/persistence.js +17 -4
  11. package/dist/persistence.js.map +1 -1
  12. package/dist/plugin.d.ts +4 -0
  13. package/dist/plugin.d.ts.map +1 -1
  14. package/dist/plugin.js +3 -9
  15. package/dist/plugin.js.map +1 -1
  16. package/dist/tools/ai/schema.js +1 -1
  17. package/dist/tools/ai/schema.js.map +1 -1
  18. package/dist/tools/app-management/app.js +1 -1
  19. package/dist/tools/app-management/app.js.map +1 -1
  20. package/dist/tools/app-management/permissions.js +1 -1
  21. package/dist/tools/app-management/permissions.js.map +1 -1
  22. package/dist/tools/context/context.js +1 -1
  23. package/dist/tools/context/context.js.map +1 -1
  24. package/dist/tools/gestures/drag-and-drop.js +1 -1
  25. package/dist/tools/gestures/drag-and-drop.js.map +1 -1
  26. package/dist/tools/gestures/perform-actions.js +1 -1
  27. package/dist/tools/gestures/perform-actions.js.map +1 -1
  28. package/dist/tools/gestures/schema.d.ts +1 -1
  29. package/dist/tools/gestures/schema.d.ts.map +1 -1
  30. package/dist/tools/gestures/schema.js +48 -41
  31. package/dist/tools/gestures/schema.js.map +1 -1
  32. package/dist/tools/index.d.ts.map +1 -1
  33. package/dist/tools/index.js +3 -26
  34. package/dist/tools/index.js.map +1 -1
  35. package/dist/tools/interactions/active-element.js +1 -1
  36. package/dist/tools/interactions/active-element.js.map +1 -1
  37. package/dist/tools/interactions/clipboard.js +1 -1
  38. package/dist/tools/interactions/clipboard.js.map +1 -1
  39. package/dist/tools/interactions/find.d.ts.map +1 -1
  40. package/dist/tools/interactions/find.js +23 -24
  41. package/dist/tools/interactions/find.js.map +1 -1
  42. package/dist/tools/interactions/get-element-attribute.js +1 -1
  43. package/dist/tools/interactions/get-element-attribute.js.map +1 -1
  44. package/dist/tools/interactions/get-page-source.js +1 -1
  45. package/dist/tools/interactions/get-page-source.js.map +1 -1
  46. package/dist/tools/interactions/get-text.js +1 -1
  47. package/dist/tools/interactions/get-text.js.map +1 -1
  48. package/dist/tools/interactions/handle-alert.js +1 -1
  49. package/dist/tools/interactions/handle-alert.js.map +1 -1
  50. package/dist/tools/interactions/keyboard.js +1 -1
  51. package/dist/tools/interactions/keyboard.js.map +1 -1
  52. package/dist/tools/interactions/orientation.js +1 -1
  53. package/dist/tools/interactions/orientation.js.map +1 -1
  54. package/dist/tools/interactions/press-key.js +1 -1
  55. package/dist/tools/interactions/press-key.js.map +1 -1
  56. package/dist/tools/interactions/screen-recording.js +1 -1
  57. package/dist/tools/interactions/screen-recording.js.map +1 -1
  58. package/dist/tools/interactions/screenshot.d.ts.map +1 -1
  59. package/dist/tools/interactions/screenshot.js +5 -13
  60. package/dist/tools/interactions/screenshot.js.map +1 -1
  61. package/dist/tools/interactions/set-value.js +1 -1
  62. package/dist/tools/interactions/set-value.js.map +1 -1
  63. package/dist/tools/interactions/window-size.js +1 -1
  64. package/dist/tools/interactions/window-size.js.map +1 -1
  65. package/dist/tools/ios/prepare-ios-real-device.d.ts.map +1 -1
  66. package/dist/tools/ios/prepare-ios-real-device.js +4 -7
  67. package/dist/tools/ios/prepare-ios-real-device.js.map +1 -1
  68. package/dist/tools/ios/prepare-ios-simulator.d.ts.map +1 -1
  69. package/dist/tools/ios/prepare-ios-simulator.js +3 -1
  70. package/dist/tools/ios/prepare-ios-simulator.js.map +1 -1
  71. package/dist/tools/session/attach-session.js +5 -4
  72. package/dist/tools/session/attach-session.js.map +1 -1
  73. package/dist/tools/session/create-session.d.ts +2 -11
  74. package/dist/tools/session/create-session.d.ts.map +1 -1
  75. package/dist/tools/session/create-session.js +7 -20
  76. package/dist/tools/session/create-session.js.map +1 -1
  77. package/dist/tools/session/device-control.js +1 -1
  78. package/dist/tools/session/device-control.js.map +1 -1
  79. package/dist/tools/session/device-info.js +1 -1
  80. package/dist/tools/session/device-info.js.map +1 -1
  81. package/dist/tools/session/driver-settings.js +1 -1
  82. package/dist/tools/session/driver-settings.js.map +1 -1
  83. package/dist/tools/session/file-transfer.js +1 -1
  84. package/dist/tools/session/file-transfer.js.map +1 -1
  85. package/dist/tools/session/geolocation.js +1 -1
  86. package/dist/tools/session/geolocation.js.map +1 -1
  87. package/dist/tools/session/select-device.d.ts.map +1 -1
  88. package/dist/tools/session/select-device.js +7 -24
  89. package/dist/tools/session/select-device.js.map +1 -1
  90. package/dist/tools/session/select-session.js +1 -1
  91. package/dist/tools/session/select-session.js.map +1 -1
  92. package/dist/tools/session/session.d.ts.map +1 -1
  93. package/dist/tools/session/session.js +32 -30
  94. package/dist/tools/session/session.js.map +1 -1
  95. package/dist/tools/test-generation/generate-tests.d.ts.map +1 -1
  96. package/dist/tools/test-generation/generate-tests.js +9 -20
  97. package/dist/tools/test-generation/generate-tests.js.map +1 -1
  98. package/dist/tools/test-generation/locators.js +1 -1
  99. package/dist/tools/test-generation/locators.js.map +1 -1
  100. package/dist/tools/tool-response.d.ts.map +1 -1
  101. package/dist/tools/tool-response.js +12 -4
  102. package/dist/tools/tool-response.js.map +1 -1
  103. package/dist/utils/sensitive.d.ts +7 -0
  104. package/dist/utils/sensitive.d.ts.map +1 -1
  105. package/dist/utils/sensitive.js +37 -0
  106. package/dist/utils/sensitive.js.map +1 -1
  107. package/dist/utils/url.d.ts +7 -0
  108. package/dist/utils/url.d.ts.map +1 -1
  109. package/dist/utils/url.js +23 -0
  110. package/dist/utils/url.js.map +1 -1
  111. package/package.json +11 -3
  112. package/scripts/audit-tool-footprint.mjs +76 -53
  113. package/server.json +2 -2
  114. package/src/ai-finder/vision-finder.ts +35 -10
  115. package/src/create-server.ts +1 -1
  116. package/src/persistence.ts +18 -4
  117. package/src/plugin.ts +7 -9
  118. package/src/tools/ai/schema.ts +1 -1
  119. package/src/tools/app-management/app.ts +1 -1
  120. package/src/tools/app-management/permissions.ts +1 -1
  121. package/src/tools/context/context.ts +1 -1
  122. package/src/tools/gestures/drag-and-drop.ts +1 -1
  123. package/src/tools/gestures/perform-actions.ts +1 -1
  124. package/src/tools/gestures/schema.ts +48 -41
  125. package/src/tools/index.ts +3 -27
  126. package/src/tools/interactions/active-element.ts +1 -1
  127. package/src/tools/interactions/clipboard.ts +1 -1
  128. package/src/tools/interactions/find.ts +23 -24
  129. package/src/tools/interactions/get-element-attribute.ts +1 -1
  130. package/src/tools/interactions/get-page-source.ts +1 -1
  131. package/src/tools/interactions/get-text.ts +1 -1
  132. package/src/tools/interactions/handle-alert.ts +1 -1
  133. package/src/tools/interactions/keyboard.ts +1 -1
  134. package/src/tools/interactions/orientation.ts +1 -1
  135. package/src/tools/interactions/press-key.ts +1 -1
  136. package/src/tools/interactions/screen-recording.ts +1 -1
  137. package/src/tools/interactions/screenshot.ts +5 -15
  138. package/src/tools/interactions/set-value.ts +1 -1
  139. package/src/tools/interactions/window-size.ts +1 -1
  140. package/src/tools/ios/prepare-ios-real-device.ts +4 -7
  141. package/src/tools/ios/prepare-ios-simulator.ts +3 -1
  142. package/src/tools/session/attach-session.ts +5 -4
  143. package/src/tools/session/create-session.ts +7 -21
  144. package/src/tools/session/device-control.ts +1 -1
  145. package/src/tools/session/device-info.ts +1 -1
  146. package/src/tools/session/driver-settings.ts +1 -1
  147. package/src/tools/session/file-transfer.ts +1 -1
  148. package/src/tools/session/geolocation.ts +1 -1
  149. package/src/tools/session/select-device.ts +8 -28
  150. package/src/tools/session/select-session.ts +1 -1
  151. package/src/tools/session/session.ts +32 -30
  152. package/src/tools/test-generation/generate-tests.ts +9 -20
  153. package/src/tools/test-generation/locators.ts +1 -1
  154. package/src/tools/tool-response.ts +14 -4
  155. package/src/utils/sensitive.ts +42 -0
  156. 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 target. If omitted, uses the active session.'),
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 target. If omitted, uses the active session.'),
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 target. If omitted, uses the active session.'),
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 target. If omitted, uses the active session.'),
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: `Discover and select a device for LOCAL Appium servers ONLY.
76
- DO NOT use this tool for REMOTE Appium servers - remoteServerUrl indicates a remote server.
77
- WORKFLOW FOR LOCAL SERVERS:
78
- 1. ASK THE USER which platform they want (Android or iOS) - do not assume
79
- 2. Call this tool with the chosen platform (and iosDeviceType for iOS)
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
- .enum(['ios', 'android'])
92
- .describe('The platform to list devices for (must match previously selected platform)'),
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 sessions(action=list) to see available IDs.`);
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 = `Create a new Appium session with Android, iOS or any device/driver Appium supports.
15
- DEFAULT MODE (no remoteServerUrl) — USE THIS UNLESS THE USER EXPLICITLY PROVIDES A SERVER URL:
16
- - Drivers run embedded inside this MCP server; no separate Appium process is needed
17
- - Use select_device tool FIRST to discover devices and let the user choose platform and device
18
- - Then call action=create with the selected platform (do NOT pass remoteServerUrl)
19
- - For iOS simulators, call prepare_ios_simulator before action=create
20
- - DO NOT assume or default to any platform
21
- - NEVER invent a localhost URL (e.g. http://localhost:4723) — omitting remoteServerUrl IS the local/embedded mode
22
- REMOTE SERVER MODE (only when user explicitly provides a URL like http://localhost:4723):
23
- - SKIP select_device tool entirely
24
- - Infer the platform from the user's request (e.g., 'ios', 'android', or 'general')
25
- - If platform is 'general', treat the provided capabilities as a pass-through W3C/Appium capability set (useful for non-Android/iOS drivers like Windows, macOS, or custom drivers)
26
- - Infer device type from context when possible (e.g., 'simulator', 'real device')
27
- - Call session with action=create directly with platform, remoteServerUrl, and any other capabilities from the user's request
28
- - Example: User says 'start session with http://localhost:4723 for ios with iphone 17' → infer platform='ios' and call session(action=create) with remoteServerUrl and platform parameters`;
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
- 'Action to perform. ' +
35
- `create: ${CREATE_SESSION_DESCRIPTION}` +
36
- 'attach: Attach MCP Appium to an existing remote Appium session without taking ownership of its lifecycle. Requires remoteServerUrl and sessionId. Always pass capabilities with at least platformName (e.g. \'{"platformName":"iOS"}\' or \'{"platformName":"Android"}\') so the client is configured with the correct protocol commands.' +
37
- 'detach: Remove an attached Appium session from MCP Appium without deleting the real remote session. Defaults to the active session.' +
38
- 'delete: Delete a mobile session and clean up resources. If sessionId is omitted, deletes the active session.' +
39
- 'list: List all active Appium sessions managed by this MCP server, including active flag, ownership, and current context.' +
40
- 'select: Set an existing Appium session as the active session for subsequent tool calls (requires sessionId).',
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 local servers, must match the platform selected via select_device. ' +
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 for create. Provide as a JSON string (e.g. \'{"appium:app":"/path/to/app","appium:platformVersion":"17.0"}\'). ' +
56
- 'For create: applied on top of defaults for ios/android, or used as-is for general. Common: appium:app, appium:deviceName, appium:platformVersion, appium:bundleId. When passing from a capabilitiesHint result, serialize the full object to JSON — do NOT drop boolean or numeric values. ' +
57
- 'For attach: always include platformName ("iOS" or "Android") so the WebDriver client loads the correct Appium protocol commands (e.g. \'{"platformName":"iOS"}\').',
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
- 'For attach: existing session to connect to. For delete: session to remove (defaults to active). For detach: attached session to remove from MCP (defaults to active). For select: session to activate. Required for attach and select.',
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
- `- You are an Appium test generator.`,
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 — choose platform/device (local/embedded mode). Skip if the user already connected to a remote Appium URL (then use appium_session_management only).`,
19
- `2. prepare_ios_simulator or appium_prepare_ios_real_device — only when iOS local setup requires it; otherwise skip.`,
20
- `3. appium_session_management with action=create — start a driver session (match platform to select_device unless using remote server mode; pass remoteServerUrl on create, and do not invent http://localhost:4723 unless the user asked).`,
21
- `4. appium_app_lifecycle or other session tools as needed (e.g. activate app, install, deep_link with url) — only if the scenario requires it.`,
22
- `5. Discover the target element — prefer appium_get_active_element when the focused field is enough; otherwise appium_find_element (strategy + selector). If the appium_ai tool is registered (vision-based fallback, opt-in via AI_VISION_ENABLED), use it only when no stable locator works. Use generate_locators only for broad inspection/debugging, not for every step.`,
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 to fetch interactable elements when you need full-screen locator lists for code generation; pairing with generate://code-with-locators is fine for templates.`,
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
- `- Interact with the app using the tools provided, then generate the test.`,
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
- 'Generate tests for a mobile app: follow the returned instructions to drive the real session with MCP tools (select_device, appium_session_management, appium_find_element, appium_gesture, appium_set_value, etc.), then emit code. Use generate_locators only when you need a full locator snapshot; prefer appium_find_element for normal steps.',
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 target. If omitted, uses the active session.'),
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 {attachToRemoteSession} from '../utils/url.js';
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 as Error).message}); pruning.`,
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 as Error).message}); pruning.`);
155
+ log.warn(`Persisted session ${entry.sessionId} no longer attachable (${toolErrorMessage(err)}); pruning.`);
146
156
  await removePersistedSession(entry.sessionId);
147
157
  }
148
158
  }
@@ -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
  *