appium-mcp 1.9.3 → 1.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +6 -0
- package/README.md +18 -4
- package/dist/tools/session/create-session.d.ts.map +1 -1
- package/dist/tools/session/create-session.js +25 -14
- package/dist/tools/session/create-session.js.map +1 -1
- package/package.json +1 -1
- package/server.json +2 -2
- package/src/tools/session/create-session.ts +39 -29
package/CHANGELOG.md
CHANGED
|
@@ -1,3 +1,9 @@
|
|
|
1
|
+
## [1.10.0](https://github.com/appium/appium-mcp/compare/v1.9.3...v1.10.0) (2026-01-28)
|
|
2
|
+
|
|
3
|
+
### Features
|
|
4
|
+
|
|
5
|
+
* add non ios/android target as 'general' ([#135](https://github.com/appium/appium-mcp/issues/135)) ([7f9d948](https://github.com/appium/appium-mcp/commit/7f9d9485d112596c798b0dc61bae79e24edc0af3))
|
|
6
|
+
|
|
1
7
|
## [1.9.3](https://github.com/appium/appium-mcp/compare/v1.9.2...v1.9.3) (2026-01-28)
|
|
2
8
|
|
|
3
9
|
### Miscellaneous Chores
|
package/README.md
CHANGED
|
@@ -151,12 +151,26 @@ Create a `capabilities.json` file to define your device capabilities:
|
|
|
151
151
|
"appium:platformVersion": "17.0",
|
|
152
152
|
"appium:automationName": "XCUITest",
|
|
153
153
|
"appium:udid": "your-device-udid"
|
|
154
|
+
},
|
|
155
|
+
"general": {
|
|
156
|
+
"platformName": "mac",
|
|
157
|
+
"appium:automationName": "mac2",
|
|
158
|
+
"appium:bundleId": "com.apple.Safari"
|
|
154
159
|
}
|
|
155
160
|
}
|
|
156
161
|
```
|
|
157
162
|
|
|
158
163
|
Set the `CAPABILITIES_CONFIG` environment variable to point to your configuration file.
|
|
159
164
|
|
|
165
|
+
#### Platform names and "general" mode
|
|
166
|
+
|
|
167
|
+
- You can pass any platform name to `create_session`.
|
|
168
|
+
- If the platform is `ios` or `android`, the server builds capabilities for that platform (including selected device info when local).
|
|
169
|
+
- If the platform is any other value, it is treated internally as `general`:
|
|
170
|
+
- The session will use the provided `capabilities` exactly as given, or
|
|
171
|
+
- If `CAPABILITIES_CONFIG` is set, it will merge with the `general` section from your capabilities file.
|
|
172
|
+
- This allows custom setups and non-standard platforms to work without changing server logic.
|
|
173
|
+
|
|
160
174
|
### Screenshots
|
|
161
175
|
|
|
162
176
|
Set the `SCREENSHOTS_DIR` environment variable to specify where screenshots are saved. If not set, screenshots are saved to the current working directory. Supports both absolute and relative paths (relative paths are resolved from the current working directory). The directory is created automatically if it doesn't exist.
|
|
@@ -177,10 +191,10 @@ MCP Appium provides a comprehensive set of tools organized into the following ca
|
|
|
177
191
|
|
|
178
192
|
### Session Management
|
|
179
193
|
|
|
180
|
-
| Tool | Description
|
|
181
|
-
| ---------------- |
|
|
182
|
-
| `create_session` | Create a new mobile automation session for Android or
|
|
183
|
-
| `delete_session` | Delete the current mobile session and clean up resources
|
|
194
|
+
| Tool | Description |
|
|
195
|
+
| ---------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
196
|
+
| `create_session` | Create a new mobile automation session for Android, iOS, or general capabilities (see 'general' mode above) |
|
|
197
|
+
| `delete_session` | Delete the current mobile session and clean up resources |
|
|
184
198
|
|
|
185
199
|
### Context Management
|
|
186
200
|
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"create-session.d.ts","sourceRoot":"","sources":["../../../src/tools/session/create-session.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"create-session.d.ts","sourceRoot":"","sources":["../../../src/tools/session/create-session.ts"],"names":[],"mappings":"AAoNA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,MAAM,EAAE,GAAG,GAAG,IAAI,CAkJvD"}
|
|
@@ -19,7 +19,7 @@ import WebDriver from 'webdriver';
|
|
|
19
19
|
async function loadCapabilitiesConfig() {
|
|
20
20
|
const configPath = process.env.CAPABILITIES_CONFIG;
|
|
21
21
|
if (!configPath) {
|
|
22
|
-
return { android: {}, ios: {} };
|
|
22
|
+
return { android: {}, ios: {}, general: {} };
|
|
23
23
|
}
|
|
24
24
|
try {
|
|
25
25
|
await access(configPath, constants.F_OK);
|
|
@@ -28,7 +28,7 @@ async function loadCapabilitiesConfig() {
|
|
|
28
28
|
}
|
|
29
29
|
catch (error) {
|
|
30
30
|
log.warn(`Failed to parse capabilities config: ${error}`);
|
|
31
|
-
return { android: {}, ios: {} };
|
|
31
|
+
return { android: {}, ios: {}, general: {} };
|
|
32
32
|
}
|
|
33
33
|
}
|
|
34
34
|
/**
|
|
@@ -175,7 +175,7 @@ async function createDriverSession(driver, capabilities) {
|
|
|
175
175
|
export default function createSession(server) {
|
|
176
176
|
server.addTool({
|
|
177
177
|
name: 'create_session',
|
|
178
|
-
description: `Create a new
|
|
178
|
+
description: `Create a new Appium session with Android, iOS or any device/driver Appium supports.
|
|
179
179
|
WORKFLOW FOR LOCAL SERVERS (no remoteServerUrl):
|
|
180
180
|
- Use select_platform tool FIRST to ask the user which platform they want
|
|
181
181
|
- Then optionally use select_device tool if multiple devices are available
|
|
@@ -183,18 +183,21 @@ export default function createSession(server) {
|
|
|
183
183
|
- DO NOT assume or default to any platform
|
|
184
184
|
WORKFLOW FOR REMOTE SERVERS (remoteServerUrl provided):
|
|
185
185
|
- SKIP select_platform tool entirely
|
|
186
|
-
- Infer the platform from the user's request (e.g., 'ios', 'android')
|
|
186
|
+
- Infer the platform from the user's request (e.g., 'ios', 'android', or 'general')
|
|
187
|
+
- 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)
|
|
187
188
|
- Infer device type from context when possible (e.g., 'simulator', 'real device')
|
|
188
189
|
- Call create_session directly with platform, remoteServerUrl, and any other capabilities from the user's request
|
|
189
190
|
- Example: User says 'start session with http://localhost:4723 for ios with iphone 17' → infer platform='ios' and call create_session with remoteServerUrl and platform parameters
|
|
190
191
|
`,
|
|
191
192
|
parameters: z.object({
|
|
192
|
-
platform: z.enum(['ios', 'android']).describe(`REQUIRED: Platform to use.
|
|
193
|
-
|
|
193
|
+
platform: z.enum(['ios', 'android', 'general']).describe(`REQUIRED: Platform to use.
|
|
194
|
+
- For local servers, this must match the platform the user explicitly selected via the select_platform tool ('ios' or 'android').
|
|
195
|
+
- Use 'general' when you want the tool to treat capabilities as a pass-through Appium/W3C capability set (recommended for non-Android/iOS drivers such as Windows, macOS, or other custom Appium servers). 'general' will not apply any platform-specific defaults.
|
|
196
|
+
- If remoteServerUrl is provided, the assistant should confirm or infer the platform from the conversation; do not assume a default.`),
|
|
194
197
|
capabilities: z
|
|
195
198
|
.object({})
|
|
196
199
|
.optional()
|
|
197
|
-
.describe('Optional custom W3C format capabilities for the session. Common options include appium:app (app path), appium:deviceName, appium:platformVersion, appium:bundleId, appium:autoGrantPermissions, etc. Custom capabilities override default and config file settings.'),
|
|
200
|
+
.describe('Optional custom W3C format capabilities for the session. These are applied on top of defaults for ios/android or used as-is for platform="general". Common options include appium:app (app path), appium:deviceName, appium:platformVersion, appium:bundleId, appium:autoGrantPermissions, etc. Custom capabilities override default and config file settings.'),
|
|
198
201
|
remoteServerUrl: z
|
|
199
202
|
.string()
|
|
200
203
|
.optional()
|
|
@@ -217,14 +220,23 @@ export default function createSession(server) {
|
|
|
217
220
|
}
|
|
218
221
|
const { platform, capabilities: customCapabilities, remoteServerUrl, } = args;
|
|
219
222
|
const configCapabilities = await loadCapabilitiesConfig();
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
223
|
+
let finalCapabilities;
|
|
224
|
+
if (platform === 'android') {
|
|
225
|
+
finalCapabilities = buildAndroidCapabilities(configCapabilities.android, customCapabilities, !!remoteServerUrl);
|
|
226
|
+
}
|
|
227
|
+
else if (platform === 'ios') {
|
|
228
|
+
finalCapabilities = await buildIOSCapabilities(configCapabilities.ios, customCapabilities, !!remoteServerUrl);
|
|
229
|
+
}
|
|
230
|
+
else {
|
|
231
|
+
finalCapabilities = {
|
|
232
|
+
...configCapabilities.general,
|
|
233
|
+
...customCapabilities,
|
|
234
|
+
};
|
|
235
|
+
}
|
|
236
|
+
log.info(`Creating new ${platform.toUpperCase()} session with capabilities:`, JSON.stringify(finalCapabilities, null, 2));
|
|
226
237
|
let sessionId;
|
|
227
238
|
if (remoteServerUrl) {
|
|
239
|
+
log.info(`Sending the capabilities to the remote server: ${remoteServerUrl}`);
|
|
228
240
|
const remoteUrl = new URL(remoteServerUrl);
|
|
229
241
|
const client = await WebDriver.newSession({
|
|
230
242
|
protocol: remoteUrl.protocol.replace(':', ''),
|
|
@@ -237,7 +249,6 @@ export default function createSession(server) {
|
|
|
237
249
|
setSession(client, client.sessionId);
|
|
238
250
|
}
|
|
239
251
|
else {
|
|
240
|
-
log.info(`Creating new ${platform.toUpperCase()} session with capabilities:`, JSON.stringify(finalCapabilities, null, 2));
|
|
241
252
|
const driver = createDriverForPlatform(platform);
|
|
242
253
|
sessionId = await createDriverSession(driver, finalCapabilities);
|
|
243
254
|
setSession(driver, sessionId);
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"create-session.js","sourceRoot":"","sources":["../../../src/tools/session/create-session.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAC;AAChE,OAAO,GAAG,MAAM,iBAAiB,CAAC;AAClC,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,SAAS,MAAM,WAAW,CAAC;
|
|
1
|
+
{"version":3,"file":"create-session.js","sourceRoot":"","sources":["../../../src/tools/session/create-session.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
package/server.json
CHANGED
|
@@ -3,12 +3,12 @@
|
|
|
3
3
|
"name": "io.github.appium/appium-mcp",
|
|
4
4
|
"title": "MCP Appium - Mobile Development and Automation Server",
|
|
5
5
|
"description": "MCP server for Appium mobile automation on iOS and Android devices with test creation tools.",
|
|
6
|
-
"version": "1.
|
|
6
|
+
"version": "1.10.0",
|
|
7
7
|
"packages": [
|
|
8
8
|
{
|
|
9
9
|
"registryType": "npm",
|
|
10
10
|
"identifier": "appium-mcp",
|
|
11
|
-
"version": "1.
|
|
11
|
+
"version": "1.10.0",
|
|
12
12
|
"transport": {
|
|
13
13
|
"type": "stdio"
|
|
14
14
|
}
|
|
@@ -39,6 +39,7 @@ interface Capabilities {
|
|
|
39
39
|
interface CapabilitiesConfig {
|
|
40
40
|
android: Record<string, any>;
|
|
41
41
|
ios: Record<string, any>;
|
|
42
|
+
general: Record<string, any>;
|
|
42
43
|
}
|
|
43
44
|
|
|
44
45
|
/**
|
|
@@ -47,7 +48,7 @@ interface CapabilitiesConfig {
|
|
|
47
48
|
async function loadCapabilitiesConfig(): Promise<CapabilitiesConfig> {
|
|
48
49
|
const configPath = process.env.CAPABILITIES_CONFIG;
|
|
49
50
|
if (!configPath) {
|
|
50
|
-
return { android: {}, ios: {} };
|
|
51
|
+
return { android: {}, ios: {}, general: {} };
|
|
51
52
|
}
|
|
52
53
|
|
|
53
54
|
try {
|
|
@@ -56,7 +57,7 @@ async function loadCapabilitiesConfig(): Promise<CapabilitiesConfig> {
|
|
|
56
57
|
return JSON.parse(configContent);
|
|
57
58
|
} catch (error) {
|
|
58
59
|
log.warn(`Failed to parse capabilities config: ${error}`);
|
|
59
|
-
return { android: {}, ios: {} };
|
|
60
|
+
return { android: {}, ios: {}, general: {} };
|
|
60
61
|
}
|
|
61
62
|
}
|
|
62
63
|
|
|
@@ -242,7 +243,7 @@ async function createDriverSession(
|
|
|
242
243
|
export default function createSession(server: any): void {
|
|
243
244
|
server.addTool({
|
|
244
245
|
name: 'create_session',
|
|
245
|
-
description: `Create a new
|
|
246
|
+
description: `Create a new Appium session with Android, iOS or any device/driver Appium supports.
|
|
246
247
|
WORKFLOW FOR LOCAL SERVERS (no remoteServerUrl):
|
|
247
248
|
- Use select_platform tool FIRST to ask the user which platform they want
|
|
248
249
|
- Then optionally use select_device tool if multiple devices are available
|
|
@@ -250,21 +251,24 @@ export default function createSession(server: any): void {
|
|
|
250
251
|
- DO NOT assume or default to any platform
|
|
251
252
|
WORKFLOW FOR REMOTE SERVERS (remoteServerUrl provided):
|
|
252
253
|
- SKIP select_platform tool entirely
|
|
253
|
-
- Infer the platform from the user's request (e.g., 'ios', 'android')
|
|
254
|
+
- Infer the platform from the user's request (e.g., 'ios', 'android', or 'general')
|
|
255
|
+
- 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)
|
|
254
256
|
- Infer device type from context when possible (e.g., 'simulator', 'real device')
|
|
255
257
|
- Call create_session directly with platform, remoteServerUrl, and any other capabilities from the user's request
|
|
256
258
|
- Example: User says 'start session with http://localhost:4723 for ios with iphone 17' → infer platform='ios' and call create_session with remoteServerUrl and platform parameters
|
|
257
259
|
`,
|
|
258
260
|
parameters: z.object({
|
|
259
|
-
platform: z.enum(['ios', 'android']).describe(
|
|
260
|
-
`REQUIRED: Platform to use.
|
|
261
|
-
|
|
261
|
+
platform: z.enum(['ios', 'android', 'general']).describe(
|
|
262
|
+
`REQUIRED: Platform to use.
|
|
263
|
+
- For local servers, this must match the platform the user explicitly selected via the select_platform tool ('ios' or 'android').
|
|
264
|
+
- Use 'general' when you want the tool to treat capabilities as a pass-through Appium/W3C capability set (recommended for non-Android/iOS drivers such as Windows, macOS, or other custom Appium servers). 'general' will not apply any platform-specific defaults.
|
|
265
|
+
- If remoteServerUrl is provided, the assistant should confirm or infer the platform from the conversation; do not assume a default.`
|
|
262
266
|
),
|
|
263
267
|
capabilities: z
|
|
264
268
|
.object({})
|
|
265
269
|
.optional()
|
|
266
270
|
.describe(
|
|
267
|
-
'Optional custom W3C format capabilities for the session. Common options include appium:app (app path), appium:deviceName, appium:platformVersion, appium:bundleId, appium:autoGrantPermissions, etc. Custom capabilities override default and config file settings.'
|
|
271
|
+
'Optional custom W3C format capabilities for the session. These are applied on top of defaults for ios/android or used as-is for platform="general". Common options include appium:app (app path), appium:deviceName, appium:platformVersion, appium:bundleId, appium:autoGrantPermissions, etc. Custom capabilities override default and config file settings.'
|
|
268
272
|
),
|
|
269
273
|
remoteServerUrl: z
|
|
270
274
|
.string()
|
|
@@ -297,25 +301,36 @@ export default function createSession(server: any): void {
|
|
|
297
301
|
} = args;
|
|
298
302
|
|
|
299
303
|
const configCapabilities = await loadCapabilitiesConfig();
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
304
|
+
let finalCapabilities;
|
|
305
|
+
if (platform === 'android') {
|
|
306
|
+
finalCapabilities = buildAndroidCapabilities(
|
|
307
|
+
configCapabilities.android,
|
|
308
|
+
customCapabilities,
|
|
309
|
+
!!remoteServerUrl
|
|
310
|
+
);
|
|
311
|
+
} else if (platform === 'ios') {
|
|
312
|
+
finalCapabilities = await buildIOSCapabilities(
|
|
313
|
+
configCapabilities.ios,
|
|
314
|
+
customCapabilities,
|
|
315
|
+
!!remoteServerUrl
|
|
316
|
+
);
|
|
317
|
+
} else {
|
|
318
|
+
finalCapabilities = {
|
|
319
|
+
...configCapabilities.general,
|
|
320
|
+
...customCapabilities,
|
|
321
|
+
};
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
log.info(
|
|
325
|
+
`Creating new ${platform.toUpperCase()} session with capabilities:`,
|
|
326
|
+
JSON.stringify(finalCapabilities, null, 2)
|
|
327
|
+
);
|
|
316
328
|
|
|
317
329
|
let sessionId;
|
|
318
330
|
if (remoteServerUrl) {
|
|
331
|
+
log.info(
|
|
332
|
+
`Sending the capabilities to the remote server: ${remoteServerUrl}`
|
|
333
|
+
);
|
|
319
334
|
const remoteUrl = new URL(remoteServerUrl);
|
|
320
335
|
const client = await WebDriver.newSession({
|
|
321
336
|
protocol: remoteUrl.protocol.replace(':', ''),
|
|
@@ -327,11 +342,6 @@ export default function createSession(server: any): void {
|
|
|
327
342
|
sessionId = client.sessionId;
|
|
328
343
|
setSession(client, client.sessionId);
|
|
329
344
|
} else {
|
|
330
|
-
log.info(
|
|
331
|
-
`Creating new ${platform.toUpperCase()} session with capabilities:`,
|
|
332
|
-
JSON.stringify(finalCapabilities, null, 2)
|
|
333
|
-
);
|
|
334
|
-
|
|
335
345
|
const driver = createDriverForPlatform(platform);
|
|
336
346
|
sessionId = await createDriverSession(driver, finalCapabilities);
|
|
337
347
|
setSession(driver, sessionId);
|