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
|
@@ -42,26 +42,29 @@ export const gestureSchema = z.object({
|
|
|
42
42
|
action: z
|
|
43
43
|
.enum(GESTURE_ACTIONS)
|
|
44
44
|
.describe(
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
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
|
-
|
|
62
|
-
|
|
63
|
-
|
|
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
|
-
|
|
74
|
-
|
|
75
|
-
|
|
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
|
-
|
|
85
|
-
|
|
86
|
-
|
|
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(
|
|
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(
|
|
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
|
-
|
|
107
|
-
|
|
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
|
-
|
|
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
|
-
|
|
125
|
-
|
|
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
|
-
|
|
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(
|
|
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
|
-
|
|
148
|
-
|
|
149
|
-
|
|
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(
|
|
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
|
-
|
|
169
|
-
|
|
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
|
-
|
|
177
|
-
|
|
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
|
|
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>;
|
package/src/tools/index.ts
CHANGED
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
import type {ContentResult, FastMCP} from 'fastmcp';
|
|
16
16
|
|
|
17
17
|
import log from '../logger.js';
|
|
18
|
-
import {
|
|
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}`,
|
|
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
|
|
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
|
|
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
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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
|
-
|
|
45
|
-
|
|
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
|
|
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:
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
'
|
|
138
|
-
'
|
|
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
|
|
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
|
|
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
|
|
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
|
|
425
|
-
'
|
|
426
|
-
'
|
|
427
|
-
'
|
|
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
|
-
'
|
|
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 {
|
|
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 {
|
|
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
|
|
26
|
+
sessionId: z.string().optional().describe('Session ID; defaults to the active session.'),
|
|
27
27
|
seconds: z
|
|
28
28
|
.number()
|
|
29
29
|
.int()
|