appium-mcp 1.64.0 → 1.65.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [1.65.0](https://github.com/appium/appium-mcp/compare/v1.64.0...v1.65.0) (2026-04-23)
+
+### Features
+
+* **tools:** consolidate driver settings into appium_driver_settings ([#284](https://github.com/appium/appium-mcp/issues/284)) ([65e5dcd](https://github.com/appium/appium-mcp/commit/65e5dcd49412c73a85f5b5794ade47b84647560c))
+
 ## [1.64.0](https://github.com/appium/appium-mcp/compare/v1.63.1...v1.64.0) (2026-04-23)
 
 ### Features

package/README.md

@@ -318,8 +318,7 @@ MCP Appium provides a comprehensive set of tools organized into the following ca
 | ---------------- | ----------------------------------------------------------------------------------------------------------- |
 | `appium_session_management` | Unified session management. `action=create`: start a new session for Android, iOS, or `general` capabilities (see 'general' mode above); forwards capabilities to a remote server via WebDriver `newSession` when `remoteServerUrl` is provided. `action=delete`: stop and clean up a session (defaults to active). `action=list`: show all active sessions. `action=select`: switch the active session by `sessionId`. |
 | `appium_mobile_device_control` | Control device behavior: lock/unlock the screen, shake the device, or open the notifications panel (`action`: `lock` \| `unlock` \| `shake` \| `open_notifications`). `shake` is iOS only; `open_notifications` is Android only; `seconds` is optional for timed lock. |
-| `appium_get_settings` | Read current Appium driver session settings (idle timeouts, animation-related flags, selector waits, etc.). Helps diagnose and tune flaky automation. |
-| `appium_update_settings` | Merge key-value updates into driver session settings (driver-specific keys; use `appium_get_settings` to inspect). |
+| `appium_driver_settings` | Read or update Appium driver session settings in one tool. `action=get` returns current settings as JSON; `action=update` merges a `settings` map (driver-specific keys; use `action=get` first to inspect). |
 
 The remote server URL in `appium_session_management` (action=create) can be set via the `remoteServerUrl` parameter.
 If `REMOTE_SERVER_URL_ALLOW_REGEX` is set, the URL must match the provided regex pattern for security reasons.

package/dist/tools/session/driver-settings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"driver-settings.d.ts","sourceRoot":"","sources":["../../../src/tools/session/driver-settings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,OAAO,EAAE,MAAM,SAAS,CAAC;AAwBtD,MAAM,CAAC,OAAO,UAAU,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAiE5D"}
+{"version":3,"file":"driver-settings.d.ts","sourceRoot":"","sources":["../../../src/tools/session/driver-settings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,OAAO,EAAE,MAAM,SAAS,CAAC;AA6DtD,MAAM,CAAC,OAAO,UAAU,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAkC5D"}

package/dist/tools/session/driver-settings.js

@@ -1,63 +1,66 @@
 import { z } from 'zod';
 import { getSessionDriverSettings, updateSessionDriverSettings, } from '../../command.js';
 import { errorResult, resolveDriver, textResult, toolErrorMessage, } from '../tool-response.js';
-const updateSettingsSchema = z.object({
+const schema = z.object({
+    action: z
+        .enum(['get', 'update'])
+        .describe('get: read current Appium driver session settings (timeouts, selector waits, flags). ' +
+        'update: merge a settings map into the session (requires settings).'),
     settings: z
         .record(z.string(), z.any())
-        .describe('Key-value map of Appium driver settings to merge into the current session. ' +
-        'Valid keys depend on the driver (e.g. Android UiAutomator2: waitForIdleTimeout, ' +
-        'waitForSelectorTimeout, ignoreUnimportantViews; iOS XCUITest has its own set). ' +
-        'Call appium_get_settings first to inspect current values.'),
+        .optional()
+        .describe('Required when action is update. Driver-specific keys (e.g. Android UiAutomator2: ' +
+        'waitForIdleTimeout, waitForSelectorTimeout, ignoreUnimportantViews; iOS XCUITest has its own set). ' +
+        'Use action=get first to inspect current values.'),
+    sessionId: z
+        .string()
+        .optional()
+        .describe('Session ID to target. If omitted, uses the active session.'),
 });
+async function handleGet(sessionId) {
+    const resolved = resolveDriver(sessionId);
+    if (!resolved.ok) {
+        return resolved.result;
+    }
+    const { driver } = resolved;
+    const settings = await getSessionDriverSettings(driver);
+    return textResult(JSON.stringify(settings, null, 2));
+}
+async function handleUpdate(sessionId, settings) {
+    const resolved = resolveDriver(sessionId);
+    if (!resolved.ok) {
+        return resolved.result;
+    }
+    const { driver } = resolved;
+    await updateSessionDriverSettings(driver, settings);
+    return textResult('Successfully updated driver settings.');
+}
 export default function driverSettings(server) {
     server.addTool({
-        name: 'appium_get_settings',
-        description: 'Read current Appium driver session settings (e.g. idle timeouts, animation flags, ' +
-            'selector waits). Use this to tune stability for agent-driven flows. Works for embedded ' +
-            'UiAutomator2/XCUITest sessions and remote WebDriver clients that support Appium settings.',
-        parameters: z.object({}),
-        annotations: {
-            readOnlyHint: true,
-            openWorldHint: false,
-        },
-        execute: async (_args, _context) => {
-            const resolved = resolveDriver();
-            if (!resolved.ok) {
-                return resolved.result;
-            }
-            const { driver } = resolved;
-            try {
-                const settings = await getSessionDriverSettings(driver);
-                return textResult(JSON.stringify(settings, null, 2));
-            }
-            catch (err) {
-                return errorResult(`Failed to get driver settings. Error: ${toolErrorMessage(err)}`);
-            }
-        },
-    });
-    server.addTool({
-        name: 'appium_update_settings',
-        description: 'Update Appium driver session settings by merging the provided map into the current ' +
-            'configuration. Useful to reduce flakiness (e.g. adjust waitForIdleTimeout) or toggle ' +
-            'driver-specific behavior. Keys are driver-specific; use appium_get_settings to see ' +
-            'what is supported.',
-        parameters: updateSettingsSchema,
+        name: 'appium_driver_settings',
+        description: 'Read or update Appium driver session settings (e.g. idle timeouts, selector waits). ' +
+            'Use action=get to return JSON settings; action=update merges a map into the session. ' +
+            'Works for embedded UiAutomator2/XCUITest sessions and remote WebDriver clients that support Appium settings.',
+        parameters: schema,
         annotations: {
             readOnlyHint: false,
             openWorldHint: false,
         },
         execute: async (args, _context) => {
-            const resolved = resolveDriver();
-            if (!resolved.ok) {
-                return resolved.result;
-            }
-            const { driver } = resolved;
             try {
-                await updateSessionDriverSettings(driver, args.settings);
-                return textResult('Successfully updated driver settings.');
+                switch (args.action) {
+                    case 'get':
+                        return await handleGet(args.sessionId);
+                    case 'update': {
+                        if (args.settings === undefined) {
+                            return errorResult('settings is required for update action');
+                        }
+                        return await handleUpdate(args.sessionId, args.settings);
+                    }
+                }
             }
             catch (err) {
-                return errorResult(`Failed to update driver settings. Error: ${toolErrorMessage(err)}`);
+                return errorResult(`Failed to ${args.action} driver settings. Error: ${toolErrorMessage(err)}`);
             }
         },
     });

package/dist/tools/session/driver-settings.js.map

@@ -1 +1 @@
-{"version":3,"file":"driver-settings.js","sourceRoot":"","sources":["../../../src/tools/session/driver-settings.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,WAAW,EACX,aAAa,EACb,UAAU,EACV,gBAAgB,GACjB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,QAAQ,EAAE,CAAC;SACR,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC;SAC3B,QAAQ,CACP,6EAA6E;QAC3E,kFAAkF;QAClF,iFAAiF;QACjF,2DAA2D,CAC9D;CACJ,CAAC,CAAC;AAEH,MAAM,CAAC,OAAO,UAAU,cAAc,CAAC,MAAe;IACpD,MAAM,CAAC,OAAO,CAAC;QACb,IAAI,EAAE,qBAAqB;QAC3B,WAAW,EACT,oFAAoF;YACpF,yFAAyF;YACzF,2FAA2F;QAC7F,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;QACxB,WAAW,EAAE;YACX,YAAY,EAAE,IAAI;YAClB,aAAa,EAAE,KAAK;SACrB;QACD,OAAO,EAAE,KAAK,EACZ,KAA4B,EAC5B,QAA6C,EACrB,EAAE;YAC1B,MAAM,QAAQ,GAAG,aAAa,EAAE,CAAC;YACjC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,OAAO,QAAQ,CAAC,MAAM,CAAC;YACzB,CAAC;YACD,MAAM,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC;YAE5B,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,wBAAwB,CAAC,MAAM,CAAC,CAAC;gBACxD,OAAO,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YACvD,CAAC;YAAC,OAAO,GAAY,EAAE,CAAC;gBACtB,OAAO,WAAW,CAChB,yCAAyC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CACjE,CAAC;YACJ,CAAC;QACH,CAAC;KACF,CAAC,CAAC;IAEH,MAAM,CAAC,OAAO,CAAC;QACb,IAAI,EAAE,wBAAwB;QAC9B,WAAW,EACT,qFAAqF;YACrF,uFAAuF;YACvF,qFAAqF;YACrF,oBAAoB;QACtB,UAAU,EAAE,oBAAoB;QAChC,WAAW,EAAE;YACX,YAAY,EAAE,KAAK;YACnB,aAAa,EAAE,KAAK;SACrB;QACD,OAAO,EAAE,KAAK,EACZ,IAA0C,EAC1C,QAA6C,EACrB,EAAE;YAC1B,MAAM,QAAQ,GAAG,aAAa,EAAE,CAAC;YACjC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,OAAO,QAAQ,CAAC,MAAM,CAAC;YACzB,CAAC;YACD,MAAM,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC;YAE5B,IAAI,CAAC;gBACH,MAAM,2BAA2B,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACzD,OAAO,UAAU,CAAC,uCAAuC,CAAC,CAAC;YAC7D,CAAC;YAAC,OAAO,GAAY,EAAE,CAAC;gBACtB,OAAO,WAAW,CAChB,4CAA4C,gBAAgB,CAAC,GAAG,CAAC,EAAE,CACpE,CAAC;YACJ,CAAC;QACH,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"driver-settings.js","sourceRoot":"","sources":["../../../src/tools/session/driver-settings.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appium-mcp",
   "mcpName": "io.github.appium/appium-mcp",
-  "version": "1.64.0",
+  "version": "1.65.0",
   "type": "module",
   "repository": {
     "type": "git",

package/server.json

@@ -3,12 +3,12 @@
   "name": "io.github.appium/appium-mcp",
   "title": "MCP Appium - Mobile Development and Automation Server",
   "description": "MCP server for Appium mobile automation on iOS and Android devices with test creation tools.",
-  "version": "1.64.0",
+  "version": "1.65.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "appium-mcp",
-      "version": "1.64.0",
+      "version": "1.65.0",
       "transport": {
         "type": "stdio"
       }

package/src/tools/README.md

@@ -14,7 +14,7 @@ This directory contains all MCP tools available in MCP Appium.
 - `select-device.ts` - Discover devices and select one (auto-selects if only one found)
 - `device-control.ts` - Device controls in one tool (`appium_mobile_device_control`; `action=lock|unlock|shake|open_notifications`)
 - `file-transfer.ts` - Push/pull files on device (`appium_mobile_file` with `action=push|pull`)
-- `driver-settings.ts` - Read/update Appium driver session settings (`appium_get_settings`, `appium_update_settings`)
+- `driver-settings.ts` - Read/update Appium driver session settings (`appium_driver_settings`, `action`: `get` \| `update`)
 
 ### iOS Setup (`ios/`)
 

package/src/tools/session/driver-settings.ts

@@ -11,78 +11,84 @@ import {
   toolErrorMessage,
 } from '../tool-response.js';
 
-const updateSettingsSchema = z.object({
+const schema = z.object({
+  action: z
+    .enum(['get', 'update'])
+    .describe(
+      'get: read current Appium driver session settings (timeouts, selector waits, flags). ' +
+        'update: merge a settings map into the session (requires settings).'
+    ),
   settings: z
     .record(z.string(), z.any())
+    .optional()
     .describe(
-      'Key-value map of Appium driver settings to merge into the current session. ' +
-        'Valid keys depend on the driver (e.g. Android UiAutomator2: waitForIdleTimeout, ' +
-        'waitForSelectorTimeout, ignoreUnimportantViews; iOS XCUITest has its own set). ' +
-        'Call appium_get_settings first to inspect current values.'
+      'Required when action is update. Driver-specific keys (e.g. Android UiAutomator2: ' +
+        'waitForIdleTimeout, waitForSelectorTimeout, ignoreUnimportantViews; iOS XCUITest has its own set). ' +
+        'Use action=get first to inspect current values.'
     ),
+  sessionId: z
+    .string()
+    .optional()
+    .describe('Session ID to target. If omitted, uses the active session.'),
 });
 
-export default function driverSettings(server: FastMCP): void {
-  server.addTool({
-    name: 'appium_get_settings',
-    description:
-      'Read current Appium driver session settings (e.g. idle timeouts, animation flags, ' +
-      'selector waits). Use this to tune stability for agent-driven flows. Works for embedded ' +
-      'UiAutomator2/XCUITest sessions and remote WebDriver clients that support Appium settings.',
-    parameters: z.object({}),
-    annotations: {
-      readOnlyHint: true,
-      openWorldHint: false,
-    },
-    execute: async (
-      _args: Record<string, never>,
-      _context: Record<string, unknown> | undefined
-    ): Promise<ContentResult> => {
-      const resolved = resolveDriver();
-      if (!resolved.ok) {
-        return resolved.result;
-      }
-      const { driver } = resolved;
+type DriverSettingsArgs = z.infer<typeof schema>;
 
-      try {
-        const settings = await getSessionDriverSettings(driver);
-        return textResult(JSON.stringify(settings, null, 2));
-      } catch (err: unknown) {
-        return errorResult(
-          `Failed to get driver settings. Error: ${toolErrorMessage(err)}`
-        );
-      }
-    },
-  });
+async function handleGet(sessionId?: string): Promise<ContentResult> {
+  const resolved = resolveDriver(sessionId);
+  if (!resolved.ok) {
+    return resolved.result;
+  }
+  const { driver } = resolved;
+
+  const settings = await getSessionDriverSettings(driver);
+  return textResult(JSON.stringify(settings, null, 2));
+}
 
+async function handleUpdate(
+  sessionId: string | undefined,
+  settings: Record<string, unknown>
+): Promise<ContentResult> {
+  const resolved = resolveDriver(sessionId);
+  if (!resolved.ok) {
+    return resolved.result;
+  }
+  const { driver } = resolved;
+
+  await updateSessionDriverSettings(driver, settings);
+  return textResult('Successfully updated driver settings.');
+}
+
+export default function driverSettings(server: FastMCP): void {
   server.addTool({
-    name: 'appium_update_settings',
+    name: 'appium_driver_settings',
     description:
-      'Update Appium driver session settings by merging the provided map into the current ' +
-      'configuration. Useful to reduce flakiness (e.g. adjust waitForIdleTimeout) or toggle ' +
-      'driver-specific behavior. Keys are driver-specific; use appium_get_settings to see ' +
-      'what is supported.',
-    parameters: updateSettingsSchema,
+      'Read or update Appium driver session settings (e.g. idle timeouts, selector waits). ' +
+      'Use action=get to return JSON settings; action=update merges a map into the session. ' +
+      'Works for embedded UiAutomator2/XCUITest sessions and remote WebDriver clients that support Appium settings.',
+    parameters: schema,
     annotations: {
       readOnlyHint: false,
       openWorldHint: false,
     },
     execute: async (
-      args: z.infer<typeof updateSettingsSchema>,
+      args: DriverSettingsArgs,
       _context: Record<string, unknown> | undefined
     ): Promise<ContentResult> => {
-      const resolved = resolveDriver();
-      if (!resolved.ok) {
-        return resolved.result;
-      }
-      const { driver } = resolved;
-
       try {
-        await updateSessionDriverSettings(driver, args.settings);
-        return textResult('Successfully updated driver settings.');
+        switch (args.action) {
+          case 'get':
+            return await handleGet(args.sessionId);
+          case 'update': {
+            if (args.settings === undefined) {
+              return errorResult('settings is required for update action');
+            }
+            return await handleUpdate(args.sessionId, args.settings);
+          }
+        }
       } catch (err: unknown) {
         return errorResult(
-          `Failed to update driver settings. Error: ${toolErrorMessage(err)}`
+          `Failed to ${args.action} driver settings. Error: ${toolErrorMessage(err)}`
         );
       }
     },