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
@@ -42,26 +42,29 @@ export const gestureSchema = z.object({
42
42
  action: z
43
43
  .enum(GESTURE_ACTIONS)
44
44
  .describe(
45
- `Gesture to perform. ` +
46
- `tap: tap an element or a coordinate. ` +
47
- `double_tap: trigger a double-tap action (e.g. zoom in on an image, favorite a post). ` +
48
- `long_press: press and hold to open a context menu or initiate drag. ` +
49
- `scroll: browse a list, feed, or page to reveal content. ` +
50
- `swipe: dismiss a card, switch screens or tabs, navigate a carousel, or pull-to-refresh (use speed=fast). ` +
51
- `pinch_zoom: zoom in (scale > 1) or out (scale < 1) on maps, images, or any zoomable view. ` +
52
- `scroll_to_element: scroll until a specific element is on screen (strategy + selector + direction up|down). ` +
53
- `Stops when the element is found, page source is unchanged after a scroll (end of scrollable content), or maxScrollAttempts is reached. ` +
54
- `Optional scrollDistance (0.05–1) or scrollDistancePreset (small|medium|large). ` +
55
- `back: triggers the system back navigation (e.g., Android back button or iOS navigation controller pop).`,
45
+ [
46
+ 'Gesture to perform:',
47
+ '- tap: tap an element or a coordinate.',
48
+ '- double_tap: double-tap, for example to zoom an image or favorite a post.',
49
+ '- long_press: press and hold to open a context menu or initiate a drag.',
50
+ 'For tap/double_tap/long_press, provide elementUUID or both x and y.',
51
+ '- scroll: browse a list, feed, or page to reveal content.',
52
+ '- swipe: dismiss a card, switch screens or tabs, navigate a carousel, or pull-to-refresh (use speed=fast).',
53
+ 'For scroll/swipe, provide direction or all four custom coordinates: x, y, endX, endY.',
54
+ '- pinch_zoom: zoom in (scale > 1) or out (scale < 1) on maps, images, or other zoomable views. Requires scale.',
55
+ '- scroll_to_element: scroll to find a target using strategy and selector. Direction is up/down, default down.',
56
+ 'Stops when the element is found, page source is unchanged after a scroll (likely end of content), or maxScrollAttempts is reached.',
57
+ 'Adjust distance with scrollDistance (0.05–1) or scrollDistancePreset (small/medium/large).',
58
+ '- back: trigger system back navigation.',
59
+ ].join('\n'),
56
60
  ),
57
61
 
58
62
  elementUUID: elementUUIDScheme
59
63
  .optional()
60
64
  .describe(
61
- `UUID of the element to act on. ` +
62
- AI_UUID_HINT +
63
- `Used by: tap, double_tap, long_press, pinch_zoom. ` +
64
- `For scroll/swipe, when provided with direction, the gesture is calculated relative to this element instead of the whole screen.`,
65
+ AI_UUID_HINT +
66
+ 'Element UUID for tap, double_tap, long_press, or pinch_zoom; overrides x/y for these actions. ' +
67
+ 'For scroll/swipe with direction, coordinates are calculated relative to this element instead of the whole screen.',
65
68
  ),
66
69
 
67
70
  x: z
@@ -70,10 +73,9 @@ export const gestureSchema = z.object({
70
73
  .min(0)
71
74
  .optional()
72
75
  .describe(
73
- `X coordinate. ` +
74
- `For tap/double_tap/long_press: tap location (alternative to elementUUID). ` +
75
- `For scroll/swipe: starting X for custom-coordinate mode (requires y, endX, endY). ` +
76
- `For pinch_zoom: center X of the pinch. Requires y. Ignored if elementUUID is set.`,
76
+ 'X coordinate in pixels. For tap/double_tap/long_press: tap location, paired with y. ' +
77
+ 'For scroll/swipe: starting X in custom-coordinate mode; requires y, endX, endY. ' +
78
+ 'For pinch_zoom: center X, paired with y. Tap/double_tap/long_press/pinch_zoom ignore x/y when elementUUID is set.',
77
79
  ),
78
80
  y: z
79
81
  .number()
@@ -81,37 +83,38 @@ export const gestureSchema = z.object({
81
83
  .min(0)
82
84
  .optional()
83
85
  .describe(
84
- `Y coordinate. ` +
85
- `For tap/double_tap/long_press: tap location. ` +
86
- `For scroll/swipe: starting Y for custom-coordinate mode. ` +
87
- `For pinch_zoom: center Y of the pinch. Requires x. Ignored if elementUUID is set.`,
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.',
88
89
  ),
89
90
  endX: z
90
91
  .number()
91
92
  .int()
92
93
  .min(0)
93
94
  .optional()
94
- .describe(`Ending X coordinate. Used by: scroll, swipe (custom-coordinate mode).`),
95
+ .describe('Ending X coordinate in pixels for scroll/swipe; requires x, y, endY.'),
95
96
  endY: z
96
97
  .number()
97
98
  .int()
98
99
  .min(0)
99
100
  .optional()
100
- .describe(`Ending Y coordinate. Used by: scroll, swipe (custom-coordinate mode).`),
101
+ .describe('Ending Y coordinate in pixels for scroll/swipe; requires x, y, endX.'),
101
102
 
102
103
  direction: z
103
104
  .enum(['up', 'down', 'left', 'right'])
104
105
  .optional()
105
106
  .describe(
106
- `Direction for scroll or swipe. Coordinates are auto-calculated from screen or element bounds. ` +
107
- `Either direction OR custom coordinates (x, y, endX, endY) must be provided for these actions.`,
107
+ 'Direction for scroll/swipe. Coordinates are calculated from the screen or element bounds. ' +
108
+ 'Provide either direction or custom coordinates (x, y, endX, endY); direction takes precedence if both are given. ' +
109
+ 'For scroll_to_element, use up/down; default down.',
108
110
  ),
109
111
 
110
112
  speed: z
111
113
  .enum(SWIPE_SPEEDS)
112
114
  .optional()
113
115
  .describe(
114
- `Swipe speed. slow = deliberate drag; normal = default navigation speed; fast = flick with no hold, use for pull-to-refresh and other velocity-sensitive UIs. Used by: swipe.`,
116
+ 'Swipe only. slow: deliberate drag; normal: default navigation speed; fast: flick without an initial hold. ' +
117
+ 'Use fast for pull-to-refresh and other velocity-sensitive interfaces.',
115
118
  ),
116
119
 
117
120
  duration: z
@@ -121,8 +124,10 @@ export const gestureSchema = z.object({
121
124
  .max(10000)
122
125
  .optional()
123
126
  .describe(
124
- `Duration in milliseconds. long_press default 2000 (range 500-10000). scroll default 800. ` +
125
- `For swipe, prefer the speed parameter; duration overrides it if both are provided.`,
127
+ 'Duration in milliseconds. long_press defaults to 2000 (range 500–10000); scroll defaults to 800. ' +
128
+ 'For swipe, prefer speed unless a custom movement duration is needed. ' +
129
+ 'For W3C swipe, overrides movement time; speed still sets the initial hold. ' +
130
+ 'Ignored by iOS native mobile: swipe (direction, no elementUUID, speed != fast).',
126
131
  ),
127
132
 
128
133
  scale: z
@@ -131,22 +136,24 @@ export const gestureSchema = z.object({
131
136
  .max(10)
132
137
  .optional()
133
138
  .describe(
134
- `Pinch scale factor. < 1 = zoom out (pinch close), > 1 = zoom in (pinch open). Example: 0.5 = zoom out 50%, 2.0 = zoom in 2x. Required for: pinch_zoom.`,
139
+ 'Required for pinch_zoom. Scale < 1 zooms out (fingers close); scale > 1 zooms in (fingers spread). ' +
140
+ 'Examples: 0.5 zooms out; 2.0 zooms in 2x.',
135
141
  ),
136
142
  velocity: z
137
143
  .number()
138
144
  .min(0.1)
139
145
  .max(20)
140
146
  .optional()
141
- .describe(`Pinch velocity in scale factor per second. Default 2.2. Used by: pinch_zoom.`),
147
+ .describe('Pinch velocity in scale factor per second. Default 2.2. Used by pinch_zoom.'),
142
148
 
143
149
  strategy: z
144
150
  .enum(LOCATOR_STRATEGIES)
145
151
  .optional()
146
152
  .describe(
147
- `Locator strategy. Required for: scroll_to_element. ` +
148
- `Priority: accessibility id > id > platform-native (-ios predicate string / -ios class chain on iOS, -android uiautomator on Android) > xpath (LAST RESORT — slow on iOS XCUITest, brittle) > name > class name > css selector (webview only). ` +
149
- `Same ranking as appium_find_element.`,
153
+ 'Required for scroll_to_element. Prefer accessibility id > id > platform-native ' +
154
+ '(iOS: -ios predicate string / -ios class chain; Android: -android uiautomator) > xpath (last resort: slow/brittle). ' +
155
+ 'name is legacy; class name may match multiple elements; css selector is webview-only. ' +
156
+ 'Same priorities as appium_find_element.',
150
157
  ),
151
158
  selector: z.string().optional().describe(`Locator selector value. Required for: scroll_to_element.`),
152
159
 
@@ -157,7 +164,7 @@ export const gestureSchema = z.object({
157
164
  .max(80)
158
165
  .optional()
159
166
  .default(10)
160
- .describe(`scroll_to_element only: maximum scroll attempts after the element is not yet visible (default 10).`),
167
+ .describe('scroll_to_element only: maximum scroll attempts after the initial lookup fails. Default 10.'),
161
168
 
162
169
  scrollDistance: z
163
170
  .number()
@@ -165,19 +172,19 @@ export const gestureSchema = z.object({
165
172
  .max(1)
166
173
  .optional()
167
174
  .describe(
168
- `scroll_to_element only: vertical swipe length as a fraction 0.05–1 (same scale as legacy scroll). ` +
169
- `Ignored when scrollDistancePreset is set. Default 0.45 if neither preset nor scrollDistance is set.`,
175
+ 'scroll_to_element only: vertical swipe distance fraction (0.05–1). ' +
176
+ 'Ignored when scrollDistancePreset is set. Default 0.45 when neither option is supplied.',
170
177
  ),
171
178
 
172
179
  scrollDistancePreset: z
173
180
  .enum(SCROLL_DISTANCE_PRESETS)
174
181
  .optional()
175
182
  .describe(
176
- `scroll_to_element only: convenience preset — small ≈ light nudge (0.25), medium ≈ 0.45, large = full default swipe (1). ` +
177
- `When set, overrides scrollDistance.`,
183
+ 'scroll_to_element only: small is a light nudge (0.25), medium is 0.45, large is the full default swipe (1). ' +
184
+ 'Overrides scrollDistance when set.',
178
185
  ),
179
186
 
180
- sessionId: z.string().optional().describe('Session ID to target. If omitted, uses the active session.'),
187
+ sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
181
188
  });
182
189
 
183
190
  export type GestureArgs = z.infer<typeof gestureSchema>;
@@ -15,7 +15,7 @@
15
15
  import type {ContentResult, FastMCP} from 'fastmcp';
16
16
 
17
17
  import log from '../logger.js';
18
- import {isSensitiveKey} from '../utils/sensitive.js';
18
+ import {redactForLogging, redactUrlCredentials} from '../utils/sensitive.js';
19
19
  import ai from './ai/ai.js';
20
20
  import {isAIEnabled, assertAIConfig} from './ai/config.js';
21
21
  import app from './app-management/app.js';
@@ -61,35 +61,11 @@ export default function registerTools(server: FastMCP): void {
61
61
  if (typeof originalExecute !== 'function') {
62
62
  return originalAddTool(toolDef);
63
63
  }
64
- const redactArgs = (obj: unknown): unknown => {
65
- if (obj === undefined || obj === null) {
66
- return obj;
67
- }
68
- try {
69
- return JSON.parse(
70
- JSON.stringify(obj, (key, value) => {
71
- if (key && isSensitiveKey(key)) {
72
- return '[REDACTED]';
73
- }
74
- // Avoid logging extremely large buffers/strings
75
- if (value && typeof value === 'string' && value.length > 2000) {
76
- return `[string:${value.length}]`;
77
- }
78
- if (value && typeof Buffer !== 'undefined' && Buffer.isBuffer(value)) {
79
- return `[buffer:${(value as Buffer).length}]`;
80
- }
81
- return value;
82
- }),
83
- );
84
- } catch {
85
- return '[Unserializable args]';
86
- }
87
- };
88
64
  return originalAddTool({
89
65
  ...toolDef,
90
66
  execute: async (args, context) => {
91
67
  const start = Date.now();
92
- log.info(`[TOOL START] ${toolName}`, redactArgs(args));
68
+ log.info(`[TOOL START] ${toolName}`, redactForLogging(args));
93
69
  try {
94
70
  const result = await originalExecute(args, context);
95
71
  const durationMs = Date.now() - start;
@@ -113,7 +89,7 @@ export default function registerTools(server: FastMCP): void {
113
89
  }),
114
90
  );
115
91
  const msg = err instanceof Error ? err.stack || err.message : String(err);
116
- log.error(`[TOOL ERROR] ${toolName} (${durationMs}ms): ${msg}`);
92
+ log.error(`[TOOL ERROR] ${toolName} (${durationMs}ms): ${redactUrlCredentials(msg)}`);
117
93
  throw err;
118
94
  }
119
95
  },
@@ -12,7 +12,7 @@ import {
12
12
 
13
13
  export default function getActiveElement(server: FastMCP): void {
14
14
  const schema = z.object({
15
- sessionId: z.string().optional().describe('Session ID to target. If omitted, uses the active session.'),
15
+ sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
16
16
  });
17
17
 
18
18
  server.addTool({
@@ -9,7 +9,7 @@ const schema = z.object({
9
9
  .enum(['get', 'set'])
10
10
  .describe('get: read device clipboard as plain text. set: write plain text to the clipboard.'),
11
11
  content: z.string().optional().describe('Required when action is set. Plain text to put on the clipboard.'),
12
- sessionId: z.string().optional().describe('Session ID to target. If omitted, uses the active session.'),
12
+ sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
13
13
  });
14
14
 
15
15
  type ClipboardArgs = z.infer<typeof schema>;
@@ -25,40 +25,39 @@ export const findElementSchema = z.object({
25
25
  'css selector',
26
26
  ])
27
27
  .describe(
28
- `Locator strategy. Try in priority order: ` +
29
- `(1) accessibility id [cross-platform, fastest, most stable], ` +
30
- `(2) id [Android resource-id; iOS aliases accessibility id], ` +
31
- `(3) -ios predicate string [iOS native, fast], ` +
32
- `(4) -ios class chain [iOS native, hierarchy queries], ` +
33
- `(5) -android uiautomator [Android native, expressive UiSelector], ` +
34
- `(6) xpath [LAST RESORT — slow on iOS XCUITest, brittle to layout changes], ` +
35
- `(7) name [legacy; often aliased on iOS], ` +
36
- `(8) class name [too generic, usually multi-match], ` +
37
- `(9) css selector [webview/hybrid contexts only]. ` +
38
- `Platform tips: iOS prefer (1)→(3)→(4); Android prefer (1)→(2)→(5); xpath last on both. ` +
39
- `For natural-language / vision-based find, use the appium_ai tool (action=find_element), not this one.`,
28
+ [
29
+ 'Locator strategy. Prefer stable identifiers, then platform-native queries; xpath is the last resort.',
30
+ '- accessibility id: cross-platform, fast and stable when available.',
31
+ '- id: Android resource-id; an accessibility-id alias on iOS.',
32
+ '- -ios predicate string: fast native iOS queries on element attributes.',
33
+ '- -ios class chain: native iOS hierarchy queries.',
34
+ '- -android uiautomator: native Android queries using UiSelector.',
35
+ '- xpath: last resort; slow on iOS XCUITest and brittle to layout changes.',
36
+ '- name: legacy; often aliased on iOS.',
37
+ '- class name: usually too generic and may match multiple elements.',
38
+ '- css selector: webview/hybrid web contexts only, not native screens.',
39
+ 'iOS prefer accessibility id > -ios predicate string > -ios class chain; Android prefer accessibility id > id > -android uiautomator. Use xpath last on both.',
40
+ ].join('\n'),
40
41
  ),
41
42
  selector: z
42
43
  .string()
43
44
  .describe(
44
- `Selector string for the chosen strategy. ` +
45
- `Do not pass natural-language descriptions of the target here; use appium_ai (action=find_element) for that.`,
45
+ 'Selector string for the chosen strategy. Do not pass natural-language descriptions of the target here; ' +
46
+ 'use appium_ai action=find_element if enabled for vision-based finding.',
46
47
  ),
47
- sessionId: z.string().optional().describe('Session ID to target. If omitted, uses the active session.'),
48
+ sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
48
49
  });
49
50
 
50
51
  export default function findElement(server: FastMCP): void {
51
52
  server.addTool({
52
53
  name: 'appium_find_element',
53
- description: `Find a specific element by strategy and selector which will return a uuid that can be used for interactions.
54
-
55
- [PRIORITY 2: Use this to search for a target element.]
56
-
57
- **Strategy priority**: accessibility id > id > platform-native (\`-ios predicate string\` / \`-ios class chain\` on iOS, \`-android uiautomator\` on Android) > xpath (last resort — slow & brittle). See the \`strategy\` parameter for the full ranking.
58
-
59
- **Scrolling until an element appears**: use \`appium_gesture\` with \`action=scroll_to_element\` (same strategy + selector), not this tool.
60
-
61
- **Vision / natural-language find**: use \`appium_ai\` with \`action=find_element\`, not this tool.`,
54
+ description: [
55
+ 'Find an element by strategy and selector; the primary tool for locating a specific target. Returns its ID for interactions. ' +
56
+ 'Pass that ID as elementUUID to interaction tools.',
57
+ 'Prefer accessibility id > id > platform-native > xpath (last resort: slow/brittle). See strategy for platform-specific guidance.',
58
+ 'To scroll until a target is found, use appium_gesture action=scroll_to_element with the same strategy and selector, rather than repeatedly calling this tool.',
59
+ 'For natural-language/vision finding, use appium_ai action=find_element if enabled and stable locators do not work.',
60
+ ].join('\n'),
62
61
  parameters: findElementSchema,
63
62
  annotations: {
64
63
  readOnlyHint: true,
@@ -14,7 +14,7 @@ export default function getElementAttributeTool(server: FastMCP): void {
14
14
  .describe(
15
15
  'The attribute name to retrieve. Common attributes: "enabled", "selected", "displayed", "checked", "focused", "clickable", "scrollable", "focusable", "name", "value", "label", "text", "content-desc", "resource-id", "class", "package".',
16
16
  ),
17
- sessionId: z.string().optional().describe('Session ID to target. If omitted, uses the active session.'),
17
+ sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
18
18
  });
19
19
 
20
20
  server.addTool({
@@ -10,7 +10,7 @@ import {resolveDriver, textResult, errorResult, toolErrorMessage} from '../tool-
10
10
  export default function getPageSource(server: FastMCP): void {
11
11
  const mcpAppsEnabled = isMcpAppsEnabled();
12
12
  const pageSourceSchema = z.object({
13
- sessionId: z.string().optional().describe('Session ID to target. If omitted, uses the active session.'),
13
+ sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
14
14
  });
15
15
  server.addTool({
16
16
  name: 'appium_get_page_source',
@@ -9,7 +9,7 @@ import {resolveDriver, textResultWithPrimaryElementId, errorResult, toolErrorMes
9
9
  export default function getText(server: FastMCP): void {
10
10
  const getTextSchema = z.object({
11
11
  elementUUID: elementUUIDScheme,
12
- sessionId: z.string().optional().describe('Session ID to target. If omitted, uses the active session.'),
12
+ sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
13
13
  });
14
14
 
15
15
  server.addTool({
@@ -14,7 +14,7 @@ export default function alert(server: FastMCP): void {
14
14
  action: z
15
15
  .enum(['accept', 'dismiss', 'get_text'])
16
16
  .describe('Action to perform on alert: accept, dismiss, or get_text'),
17
- sessionId: z.string().optional().describe('Session ID to target. If omitted, uses the active session.'),
17
+ sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
18
18
  buttonLabel: z.string().optional().describe('Optional label of the button to click for accept/dismiss.'),
19
19
  });
20
20
 
@@ -18,7 +18,7 @@ const schema = z.object({
18
18
  'hide only: optional key names to dismiss the keyboard (e.g. "done"). ' +
19
19
  'Forwarded to mobile: hideKeyboard when non-empty. Ignored for is_shown.',
20
20
  ),
21
- sessionId: z.string().optional().describe('Session ID to target. If omitted, uses the active session.'),
21
+ sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
22
22
  });
23
23
 
24
24
  type KeyboardArgs = z.infer<typeof schema>;
@@ -7,7 +7,7 @@ import {resolveDriver, textResult, errorResult, toolErrorMessage} from '../tool-
7
7
  const orientationSchema = z.object({
8
8
  action: z.enum(['get', 'set']).describe('Use get to read current orientation, set to change orientation.'),
9
9
  orientation: z.enum(['LANDSCAPE', 'PORTRAIT']).optional().describe('Required when action is set.'),
10
- sessionId: z.string().optional().describe('Session ID to target. If omitted, uses the active session.'),
10
+ sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
11
11
  });
12
12
 
13
13
  export default function orientation(server: FastMCP): void {
@@ -37,7 +37,7 @@ const IOS_BUTTONS_DESCRIPTION = Object.keys(IOS_BUTTON_MAP).join(', ');
37
37
  export default function pressKey(server: FastMCP): void {
38
38
  const pressKeySchema = z
39
39
  .object({
40
- sessionId: z.string().optional().describe('Session ID to target. If omitted, uses the active session.'),
40
+ sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
41
41
  key: z
42
42
  .enum([
43
43
  'BACK',
@@ -88,7 +88,7 @@ const screenRecordingSchema = z.object({
88
88
  videoSize: z.string().optional().describe('Android only. Frame size in WIDTHxHEIGHT format (e.g. 1280x720).'),
89
89
  bitRate: z.number().int().optional().describe('Android only. Video bit rate in bits per second.'),
90
90
  bugReport: z.boolean().optional().describe('Android only. Display timestamp overlay. Requires API level 27+.'),
91
- sessionId: z.string().optional().describe('Session ID to target. If omitted, uses the active session.'),
91
+ sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
92
92
  });
93
93
 
94
94
  export default function screenRecording(server: FastMCP): void {
@@ -121,26 +121,16 @@ export async function executeScreenshot(opts: {
121
121
  }
122
122
 
123
123
  const screenshotSchema = z.object({
124
- elementUUID: elementUUIDScheme
125
- .optional()
126
- .describe('Optional element UUID. If provided, captures only this element. If omitted, captures full screen.'),
127
- maxWidth: z
128
- .number()
129
- .optional()
130
- .describe(
131
- 'Optional maximum width in pixels to resize the screenshot. The aspect ratio is preserved. Useful for reducing token usage when sending screenshots to LLMs.',
132
- ),
124
+ elementUUID: elementUUIDScheme.optional().describe('Capture this element; omit for the full screen.'),
125
+ maxWidth: z.number().optional().describe('Resize to at most this width in pixels, preserving aspect ratio.'),
133
126
  returnRawBase64: z
134
127
  .boolean()
135
128
  .default(false)
136
129
  .describe(
137
- 'When true, returns the raw base64-encoded PNG image instead of saving it to disk. ' +
138
- 'This should only be enabled when a human explicitly invokes the tool manually, ' +
139
- 'typically to view the screenshot on a different machine (e.g. when the server runs ' +
140
- 'on a remote machine and the saved file is not accessible). ' +
141
- 'An LLM must always keep this false and rely on the saved file path.',
130
+ 'Return inline PNG instead of saving, for explicit manual use when the server file is inaccessible. ' +
131
+ 'LLMs must keep false and use the saved path.',
142
132
  ),
143
- sessionId: z.string().optional().describe('Session ID to target. If omitted, uses the active session.'),
133
+ sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
144
134
  });
145
135
 
146
136
  export default function screenshot(server: FastMCP): void {
@@ -25,7 +25,7 @@ export default function setValue(server: FastMCP): void {
25
25
  'the driver-specific setValue. No elementUUID needed — key events are sent ' +
26
26
  'to whatever element currently has focus. Works on both Android and iOS.',
27
27
  ),
28
- sessionId: z.string().optional().describe('Session ID to target. If omitted, uses the active session.'),
28
+ sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
29
29
  })
30
30
  .refine((v) => v.w3cActions === true || v.elementUUID !== undefined, {
31
31
  message: 'elementUUID is required when w3cActions is not true',
@@ -10,7 +10,7 @@ export default function getWindowSize(server: FastMCP): void {
10
10
  description:
11
11
  'Get the width and height of the device screen in pixels. Useful for calculating coordinates for swipes, taps, and scrolls.',
12
12
  parameters: z.object({
13
- sessionId: z.string().optional().describe('Session ID to target. If omitted, uses the active session.'),
13
+ sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
14
14
  }),
15
15
  annotations: {
16
16
  readOnlyHint: true,
@@ -421,13 +421,10 @@ export default function prepareIosRealDevice(server: FastMCP): void {
421
421
  server.addTool({
422
422
  name: 'appium_prepare_ios_real_device',
423
423
  description:
424
- 'Prepare an iOS real device for Appium testing in a single call. Two-mode flow: ' +
425
- '(1) Call without provisioningProfileUuid to receive the list of available .mobileprovision profiles — ' +
426
- 'present them to the user (highlight any with recommendedForWda=true) and ask them to pick one. ' +
427
- '(2) Call again with the chosen UUID to download the matching WebDriverAgent release, package it as an IPA, ' +
428
- 'and resign it with the chosen profile (wildcard "*" profiles are supported — a concrete WDA bundle ID is substituted at sign time). ' +
429
- 'WDA download and unsigned IPA are cached per WDA version; the signed IPA is rebuilt every call. ' +
430
- 'Pass the returned capabilitiesHint to appium_session_management (action=create) so Appium installs and launches the signed prebuilt WDA instead of rebuilding. ' +
424
+ 'Prepare signed WDA for a real iOS device. Omit provisioningProfileUuid to list profiles; ' +
425
+ 'ask the user to choose, highlighting recommendedForWda. Pass the chosen UUID to download, package, and sign WDA; ' +
426
+ 'wildcard profiles use a concrete WDA bundle ID. Downloads/unsigned IPA are cached per version; signing always reruns. ' +
427
+ 'Pass capabilitiesHint to appium_session_management action=create to install/launch the signed WDA. ' +
431
428
  'Requires macOS, Xcode 16+, and a paired developer-mode device.',
432
429
  parameters: prepareRealDeviceSchema,
433
430
  annotations: {
@@ -469,7 +469,9 @@ export default function prepareIosSimulator(server: FastMCP): void {
469
469
  server.addTool({
470
470
  name: 'prepare_ios_simulator',
471
471
  description:
472
- 'Prepare an iOS/tvOS simulator for Appium testing in a single call. Automatically boots the simulator, downloads prebuilt WDA (if not cached), and installs/launches WDA on a free per-simulator port (so multiple simulators can run in parallel without colliding on the default 8100). Pass the returned capabilitiesHint (appium:webDriverAgentUrl) to appium_session_management (action=create) so the session reuses this running WDA instead of trying to start its own. Use skipWda=true to only boot without WDA. Set APPIUM_MCP_WDA_APP_PATH to an absolute path to a pre-extracted WebDriverAgentRunner-Runner.app to skip download entirely (useful in environments where external downloads are blocked).',
472
+ 'Boot an iOS/tvOS simulator, download/cache WDA, and launch it on a free per-simulator port. ' +
473
+ 'Pass capabilitiesHint (appium:webDriverAgentUrl) to appium_session_management action=create to reuse WDA. ' +
474
+ 'skipWda=true only boots. APPIUM_MCP_WDA_APP_PATH can point to an extracted WebDriverAgentRunner-Runner.app (absolute path) to skip download.',
473
475
  parameters: prepareIosSimulatorSchema,
474
476
  annotations: {
475
477
  readOnlyHint: false,
@@ -9,9 +9,9 @@ import {
9
9
  type SessionCapabilities,
10
10
  type SessionOwnership,
11
11
  } from '../../session-store.js';
12
- import {attachToRemoteSession, getPortFromUrl} from '../../utils/url.js';
12
+ import {redactUrlCredentials} from '../../utils/sensitive.js';
13
+ import {attachToRemoteSession, getPortFromUrl, validateRemoteServerUrl} from '../../utils/url.js';
13
14
  import {errorResult, textResult, toolErrorMessage} from '../tool-response.js';
14
- import {validateRemoteServerUrl} from './create-session.js';
15
15
 
16
16
  /**
17
17
  * Normalize capability payloads returned by Appium/WebdriverIO into a flat
@@ -84,7 +84,7 @@ export async function attachSessionAction(args: {
84
84
 
85
85
  if (sessionCapabilities === undefined && deprecatedSessionCapabilities === undefined) {
86
86
  return errorResult(
87
- `Failed to fetch capabilities for session ${args.sessionId} from ${args.remoteServerUrl}. ` +
87
+ `Failed to fetch capabilities for session ${args.sessionId} from ${redactUrlCredentials(args.remoteServerUrl)}. ` +
88
88
  `The server may be unreachable or the session may no longer exist.`,
89
89
  );
90
90
  }
@@ -160,7 +160,7 @@ async function fetchCapabilitiesFromServer(
160
160
  const url = new URL(remoteServerUrl);
161
161
  const port = getPortFromUrl(url);
162
162
  const basePath = url.pathname.replace(/\/$/, '');
163
- const path = `${basePath}/session/${sessionId}${endpoint ? '/' + endpoint : ''}`;
163
+ const path = `${basePath}/session/${encodeURIComponent(sessionId)}${endpoint ? '/' + endpoint : ''}`;
164
164
  const requestUrl = `${url.protocol}//${url.hostname}:${port}${path}`;
165
165
 
166
166
  const headers: Record<string, string> = {
@@ -175,6 +175,7 @@ async function fetchCapabilitiesFromServer(
175
175
 
176
176
  const response = await fetch(requestUrl, {
177
177
  headers,
178
+ redirect: 'error',
178
179
  signal: AbortSignal.timeout(5000),
179
180
  });
180
181
  if (!response.ok) {
@@ -11,7 +11,8 @@ import log from '../../logger.js';
11
11
  import {setSession, listSessions} from '../../session-store.js';
12
12
  import {createUIResource, createSessionDashboardUI, addUIResourceToResponse} from '../../ui/mcp-ui-utils.js';
13
13
  import {findFreePort, releaseReservedPorts} from '../../utils/ports.js';
14
- import {getPortFromUrl} from '../../utils/url.js';
14
+ import {redactForLogging, redactUrlCredentials} from '../../utils/sensitive.js';
15
+ import {getPortFromUrl, validateRemoteServerUrl} from '../../utils/url.js';
15
16
  import {withQuietWebDriverLogging} from '../../utils/webdriver-client-options.js';
16
17
  import {errorResult, textResult, toolErrorMessage} from '../tool-response.js';
17
18
  import {clearSelectedDevice, getSelectedLocalDevice} from './select-device.js';
@@ -270,21 +271,6 @@ export function validateLocalCreatePlatformMatch(
270
271
  return undefined;
271
272
  }
272
273
 
273
- /**
274
- * Validate the provided remote server URL.
275
- *
276
- * @param remoteServerUrl - The URL of the remote Appium server to validate.
277
- * @param regexRule - Optional regular expression string to further validate the URL format.
278
- * If the regexRule is provided, the URL must match the regex pattern to be considered valid.
279
- * @throws {Error} If the URL is invalid.
280
- */
281
- export function validateRemoteServerUrl(remoteServerUrl: string, regexRule?: string): void {
282
- const regexPattern = regexRule ? new RegExp(regexRule) : /^https?:\/\/.+$/;
283
- if (!regexPattern.test(remoteServerUrl)) {
284
- throw new Error(`Invalid remoteServerUrl: ${remoteServerUrl}.`);
285
- }
286
- }
287
-
288
274
  /**
289
275
  * Create a new mobile session with Android or iOS device.
290
276
  *
@@ -336,7 +322,7 @@ export async function createSessionAction(args: {
336
322
 
337
323
  log.info(
338
324
  `Creating new ${platform.toUpperCase()} session with capabilities:`,
339
- JSON.stringify(finalCapabilities, null, 2),
325
+ JSON.stringify(redactForLogging(finalCapabilities), null, 2),
340
326
  );
341
327
  let sessionId;
342
328
  if (remoteServerUrl) {
@@ -344,7 +330,7 @@ export async function createSessionAction(args: {
344
330
  validateRemoteServerUrl(remoteServerUrl, process.env.REMOTE_SERVER_URL_ALLOW_REGEX);
345
331
  } catch (err: unknown) {
346
332
  return errorResult(
347
- `Invalid remoteServerUrl "${remoteServerUrl}". ${toolErrorMessage(err)} Pass a valid http(s) URL, or omit remoteServerUrl to use the local embedded driver.`,
333
+ `Invalid remoteServerUrl "${redactUrlCredentials(remoteServerUrl)}". ${toolErrorMessage(err)} Pass a valid http(s) URL without a query or fragment, or omit remoteServerUrl to use the local embedded driver.`,
348
334
  );
349
335
  }
350
336
 
@@ -412,7 +398,7 @@ export async function createSessionAction(args: {
412
398
  ),
413
399
  );
414
400
  } catch (error: unknown) {
415
- log.error('Error creating session:', error);
401
+ log.error('Error creating session:', toolErrorMessage(error));
416
402
  return errorResult(
417
403
  buildCreateSessionFailureMessage(error, {
418
404
  platform: args.platform,
@@ -435,7 +421,7 @@ function buildCreateSessionFailureMessage(
435
421
  const base = `Failed to create session. ${detail}`;
436
422
 
437
423
  if (ctx.remoteServerUrl) {
438
- return `${base} remoteServerUrl="${ctx.remoteServerUrl}".`;
424
+ return `${base} remoteServerUrl="${redactUrlCredentials(ctx.remoteServerUrl)}".`;
439
425
  }
440
426
 
441
427
  if (/select_device/i.test(detail)) {
@@ -504,4 +490,4 @@ async function createDriverSession(driver: any, capabilities: Capabilities): Pro
504
490
  }
505
491
 
506
492
  // Re-export for backward compatibility with consumers that imported from this module.
507
- export {getPortFromUrl};
493
+ export {getPortFromUrl, validateRemoteServerUrl};
@@ -23,7 +23,7 @@ const deviceControlSchema = z.object({
23
23
  'shake: perform shake gesture (iOS only). ' +
24
24
  'open_notifications: open notifications panel (Android only).',
25
25
  ),
26
- sessionId: z.string().optional().describe('Session ID to target. If omitted, uses the active session.'),
26
+ sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
27
27
  seconds: z
28
28
  .number()
29
29
  .int()