appium-mcp 1.14.0 → 1.15.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [1.15.0](https://github.com/appium/appium-mcp/compare/v1.14.0...v1.15.0) (2026-02-15)
+
+### Features
+
+* **interactions:** add handle-alert tool ([#57](https://github.com/appium/appium-mcp/issues/57)) ([966d035](https://github.com/appium/appium-mcp/commit/966d035455c2767cc027e78bda592a01a3847c17))
+
 ## [1.14.0](https://github.com/appium/appium-mcp/compare/v1.13.0...v1.14.0) (2026-02-15)
 
 ### Features

package/README.md

@@ -265,6 +265,7 @@ MCP Appium provides a comprehensive set of tools organized into the following ca
 | `appium_drag_and_drop` | Perform a drag and drop gesture from a source location to a target location (supports element-to-element, element-to-coordinates, coordinates-to-element, and coordinates-to-coordinates) |
 | `appium_set_value`    | Enter text into an input field                                                               |
 | `appium_get_text`     | Get text content from an element                                                             |
+| `appium_handle_alert` | Accept or dismiss system/permission alerts, or click a dialog button by label |
 
 ### Screen & Navigation
 

package/dist/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAgClC,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAiH3D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAiClC,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAkH3D"}

package/dist/tools/index.js

@@ -20,6 +20,7 @@ import dragAndDrop from './interactions/drag-and-drop.js';
 import setValue from './interactions/set-value.js';
 import getText from './interactions/get-text.js';
 import getPageSource from './interactions/get-page-source.js';
+import handleAlert from './interactions/handle-alert.js';
 import { screenshot, elementScreenshot } from './interactions/screenshot.js';
 import activateApp from './app-management/activate-app.js';
 import installApp from './app-management/install-app.js';
@@ -112,6 +113,7 @@ export default function registerTools(server) {
     setValue(server);
     getText(server);
     getPageSource(server);
+    handleAlert(server);
     screenshot(server);
     elementScreenshot(server);
     // App Management

package/dist/tools/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAeA,OAAO,GAAG,MAAM,cAAc,CAAC;AAC/B,OAAO,YAAY,MAAM,kCAAkC,CAAC;AAC5D,OAAO,aAAa,MAAM,6BAA6B,CAAC;AACxD,OAAO,aAAa,MAAM,6BAA6B,CAAC;AACxD,OAAO,gBAAgB,MAAM,+BAA+B,CAAC;AAC7D,OAAO,cAAc,MAAM,8BAA8B,CAAC;AAC1D,OAAO,YAAY,MAAM,4BAA4B,CAAC;AACtD,OAAO,aAAa,MAAM,yBAAyB,CAAC;AACpD,OAAO,QAAQ,MAAM,oBAAoB,CAAC;AAC1C,OAAO,UAAU,MAAM,sBAAsB,CAAC;AAC9C,OAAO,YAAY,MAAM,qCAAqC,CAAC;AAC/D,OAAO,MAAM,MAAM,yBAAyB,CAAC;AAC7C,OAAO,eAAe,MAAM,oCAAoC,CAAC;AACjE,OAAO,KAAK,MAAM,wBAAwB,CAAC;AAC3C,OAAO,WAAW,MAAM,wBAAwB,CAAC;AACjD,OAAO,YAAY,MAAM,yBAAyB,CAAC;AACnD,OAAO,SAAS,MAAM,8BAA8B,CAAC;AACrD,OAAO,SAAS,MAAM,8BAA8B,CAAC;AACrD,OAAO,WAAW,MAAM,iCAAiC,CAAC;AAC1D,OAAO,QAAQ,MAAM,6BAA6B,CAAC;AACnD,OAAO,OAAO,MAAM,4BAA4B,CAAC;AACjD,OAAO,aAAa,MAAM,mCAAmC,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,WAAW,MAAM,kCAAkC,CAAC;AAC3D,OAAO,UAAU,MAAM,iCAAiC,CAAC;AACzD,OAAO,YAAY,MAAM,mCAAmC,CAAC;AAC7D,OAAO,YAAY,MAAM,mCAAmC,CAAC;AAC7D,OAAO,QAAQ,MAAM,+BAA+B,CAAC;AACrD,OAAO,WAAW,MAAM,2BAA2B,CAAC;AACpD,OAAO,aAAa,MAAM,6BAA6B,CAAC;AAExD,MAAM,CAAC,OAAO,UAAU,aAAa,CAAC,MAAe;IACnD,uDAAuD;IACvD,MAAM,eAAe,GAAI,MAAc,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5D,MAAc,CAAC,OAAO,GAAG,CAAC,OAAY,EAAE,EAAE;QACzC,MAAM,QAAQ,GAAG,OAAO,EAAE,IAAI,IAAI,cAAc,CAAC;QACjD,MAAM,eAAe,GAAG,OAAO,EAAE,OAAO,CAAC;QACzC,IAAI,OAAO,eAAe,KAAK,UAAU,EAAE,CAAC;YAC1C,OAAO,eAAe,CAAC,OAAO,CAAC,CAAC;QAClC,CAAC;QACD,MAAM,cAAc,GAAG;YACrB,UAAU;YACV,OAAO;YACP,aAAa;YACb,eAAe;YACf,QAAQ;YACR,QAAQ;YACR,QAAQ;YACR,cAAc;SACf,CAAC;QACF,MAAM,UAAU,GAAG,CAAC,GAAQ,EAAE,EAAE;YAC9B,IAAI,CAAC;gBACH,OAAO,IAAI,CAAC,KAAK,CACf,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;oBACjC,IACE,GAAG;wBACH,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EACzD,CAAC;wBACD,OAAO,YAAY,CAAC;oBACtB,CAAC;oBACD,gDAAgD;oBAChD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;wBAC9D,OAAO,WAAW,KAAK,CAAC,MAAM,GAAG,CAAC;oBACpC,CAAC;oBACD,IACE,KAAK;wBACL,OAAO,MAAM,KAAK,WAAW;wBAC7B,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EACtB,CAAC;wBACD,OAAO,WAAY,KAAgB,CAAC,MAAM,GAAG,CAAC;oBAChD,CAAC;oBACD,OAAO,KAAK,CAAC;gBACf,CAAC,CAAC,CACH,CAAC;YACJ,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,uBAAuB,CAAC;YACjC,CAAC;QACH,CAAC,CAAC;QACF,OAAO,eAAe,CAAC;YACrB,GAAG,OAAO;YACV,OAAO,EAAE,KAAK,EAAE,IAAS,EAAE,OAAY,EAAE,EAAE;gBACzC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;gBACzB,GAAG,CAAC,IAAI,CAAC,gBAAgB,QAAQ,EAAE,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;gBACvD,IAAI,CAAC;oBACH,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;oBACpD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;oBACpC,GAAG,CAAC,IAAI,CAAC,cAAc,QAAQ,KAAK,QAAQ,KAAK,CAAC,CAAC;oBACnD,OAAO,MAAM,CAAC;gBAChB,CAAC;gBAAC,OAAO,GAAQ,EAAE,CAAC;oBAClB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;oBACpC,MAAM,GAAG,GAAG,GAAG,EAAE,KAAK,IAAI,GAAG,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC;oBACtD,GAAG,CAAC,KAAK,CAAC,gBAAgB,QAAQ,KAAK,QAAQ,QAAQ,GAAG,EAAE,CAAC,CAAC;oBAC9D,MAAM,GAAG,CAAC;gBACZ,CAAC;YACH,CAAC;SACF,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,qBAAqB;IACrB,cAAc,CAAC,MAAM,CAAC,CAAC;IACvB,YAAY,CAAC,MAAM,CAAC,CAAC;IACrB,aAAa,CAAC,MAAM,CAAC,CAAC;IACtB,aAAa,CAAC,MAAM,CAAC,CAAC;IAEtB,YAAY;IACZ,aAAa,CAAC,MAAM,CAAC,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,CAAC;IACjB,UAAU,CAAC,MAAM,CAAC,CAAC;IAEnB,aAAa;IACb,MAAM,CAAC,MAAM,CAAC,CAAC;IACf,eAAe,CAAC,MAAM,CAAC,CAAC;IACxB,KAAK,CAAC,MAAM,CAAC,CAAC;IAEd,uBAAuB;IACvB,WAAW,CAAC,MAAM,CAAC,CAAC;IACpB,YAAY,CAAC,MAAM,CAAC,CAAC;IACrB,SAAS,CAAC,MAAM,CAAC,CAAC;IAClB,SAAS,CAAC,MAAM,CAAC,CAAC;IAClB,WAAW,CAAC,MAAM,CAAC,CAAC;IACpB,QAAQ,CAAC,MAAM,CAAC,CAAC;IACjB,OAAO,CAAC,MAAM,CAAC,CAAC;IAChB,aAAa,CAAC,MAAM,CAAC,CAAC;IACtB,UAAU,CAAC,MAAM,CAAC,CAAC;IACnB,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAE1B,iBAAiB;IACjB,WAAW,CAAC,MAAM,CAAC,CAAC;IACpB,UAAU,CAAC,MAAM,CAAC,CAAC;IACnB,YAAY,CAAC,MAAM,CAAC,CAAC;IACrB,YAAY,CAAC,MAAM,CAAC,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,CAAC;IAEjB,qBAAqB;IACrB,WAAW,CAAC,MAAM,CAAC,CAAC;IACpB,aAAa,CAAC,MAAM,CAAC,CAAC;IAEtB,kBAAkB;IAClB,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACzB,YAAY,CAAC,MAAM,CAAC,CAAC;IAErB,gBAAgB;IAChB,YAAY,CAAC,MAAM,CAAC,CAAC;IACrB,GAAG,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;AACnC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/interactions/handle-alert.d.ts

@@ -0,0 +1,11 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+export declare const handleAlertSchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        accept: "accept";
+        dismiss: "dismiss";
+    }>;
+    buttonLabel: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export default function handleAlert(server: FastMCP): void;
+//# sourceMappingURL=handle-alert.d.ts.map

package/dist/tools/interactions/handle-alert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle-alert.d.ts","sourceRoot":"","sources":["../../../src/tools/interactions/handle-alert.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,iBAAiB;;;;;;iBAe5B,CAAC;AAsFH,MAAM,CAAC,OAAO,UAAU,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CA6DzD"}

package/dist/tools/interactions/handle-alert.js

@@ -0,0 +1,134 @@
+import { z } from 'zod';
+import { generateAllElementLocators } from '../../locators/generate-all-locators.js';
+import { getDriver, getPlatformName, PLATFORM } from '../../session-store.js';
+export const handleAlertSchema = z.object({
+    action: z
+        .enum(['accept', 'dismiss'])
+        .describe('Action to perform on the alert: accept or dismiss'),
+    buttonLabel: z
+        .string()
+        .optional()
+        .describe(`Optional label of the button to click. Common permission dialog buttons:
+Android: "While using the app", "Only this time", "Don't allow"
+iOS: "Always" or "Allow Always", "Once" or "Allow Once", "Don't allow"
+Standard: "OK", "Cancel", "Allow", "Deny"
+If not provided, uses default button based on action.
+Use appium_get_page_source or generate_locators to inspect the screen and discover exact labels.`),
+});
+const ANDROID_LOCATOR_STRATEGY_ORDER = [
+    'id',
+    'accessibility id',
+    'xpath',
+    '-android uiautomator',
+    'class name',
+];
+async function handleAndroidAlert(driver, action, buttonLabel) {
+    if (buttonLabel) {
+        const pageSource = await driver.getPageSource();
+        const elements = generateAllElementLocators(pageSource, true, 'uiautomator2', {
+            fetchableOnly: true,
+        });
+        const normalizedLabel = buttonLabel.trim();
+        const match = elements.find((el) => (el.text?.trim() === normalizedLabel ||
+            el.contentDesc?.trim() === normalizedLabel) &&
+            el.clickable) ??
+            elements.find((el) => el.text?.trim() === normalizedLabel ||
+                el.contentDesc?.trim() === normalizedLabel);
+        if (!match) {
+            throw new Error(`No element found with text or content-desc "${buttonLabel}"`);
+        }
+        let button = null;
+        for (const strategy of ANDROID_LOCATOR_STRATEGY_ORDER) {
+            const selector = match.locators[strategy];
+            if (!selector) {
+                continue;
+            }
+            try {
+                button = await driver.findElement(strategy, selector);
+                break;
+            }
+            catch {
+                continue;
+            }
+        }
+        if (!button) {
+            throw new Error('Could not find element with any generated locator; it may have disappeared');
+        }
+        const buttonUUID = button.ELEMENT || button;
+        await driver.click(buttonUUID);
+    }
+    else {
+        if (action === 'accept') {
+            await driver.execute('mobile: acceptAlert', {});
+        }
+        else {
+            await driver.execute('mobile: dismissAlert', {});
+        }
+    }
+}
+async function handleiOSAlert(driver, action, buttonLabel) {
+    const params = { action };
+    if (buttonLabel) {
+        params.buttonLabel = buttonLabel;
+    }
+    await driver.execute('mobile: alert', params);
+}
+export default function handleAlert(server) {
+    server.addTool({
+        name: 'appium_handle_alert',
+        description: `Handle system alerts or dialogs that do not belong to the app.
+Use this to dismiss or accept alerts programmatically instead of using autoDismissAlerts capability.
+Supports permission dialogs with buttons like:
+- Android: "While using the app", "Only this time", "Don't allow"
+- iOS: "Always", "Allow Once", "Don't allow"
+For iOS: Uses mobile: alert execute command.
+For Android: Uses mobile: acceptAlert/dismissAlert or searches the current page source for an element whose text or content-desc matches the label, then uses generated locators to find and click it (no hardcoded resource IDs or XPaths).
+If no alert is present, the error is caught and returned gracefully.
+To discover button labels and screen structure first, use appium_get_page_source (XML hierarchy) or generate_locators (interactable elements with text/content-desc).`,
+        parameters: handleAlertSchema,
+        annotations: {
+            readOnlyHint: false,
+            openWorldHint: false,
+        },
+        execute: async (args, context) => {
+            const driver = getDriver();
+            if (!driver) {
+                throw new Error('No driver found');
+            }
+            try {
+                const platform = getPlatformName(driver);
+                if (platform === PLATFORM.android) {
+                    await handleAndroidAlert(driver, args.action, args.buttonLabel);
+                }
+                else if (platform === PLATFORM.ios) {
+                    await handleiOSAlert(driver, args.action, args.buttonLabel);
+                }
+                else {
+                    throw new Error(`Unsupported platform: ${platform}. Only Android and iOS are supported.`);
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Successfully ${args.action}ed alert${args.buttonLabel ? ` with button "${args.buttonLabel}"` : ''}`,
+                        },
+                    ],
+                };
+            }
+            catch (err) {
+                const contextStr = args.buttonLabel
+                    ? `action=${args.action}, buttonLabel="${args.buttonLabel}"`
+                    : `action=${args.action}`;
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Failed to handle alert (${contextStr}). err: ${err.toString()}`,
+                        },
+                    ],
+                };
+            }
+        },
+    });
+}
+//# sourceMappingURL=handle-alert.js.map

package/dist/tools/interactions/handle-alert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle-alert.js","sourceRoot":"","sources":["../../../src/tools/interactions/handle-alert.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AACrF,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAE9E,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,MAAM,EAAE,CAAC;SACN,IAAI,CAAC,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;SAC3B,QAAQ,CAAC,mDAAmD,CAAC;IAChE,WAAW,EAAE,CAAC;SACX,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACP;;;;;iGAK2F,CAC5F;CACJ,CAAC,CAAC;AAEH,MAAM,8BAA8B,GAAG;IACrC,IAAI;IACJ,kBAAkB;IAClB,OAAO;IACP,sBAAsB;IACtB,YAAY;CACb,CAAC;AAEF,KAAK,UAAU,kBAAkB,CAC/B,MAAW,EACX,MAAc,EACd,WAAoB;IAEpB,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,aAAa,EAAE,CAAC;QAChD,MAAM,QAAQ,GAAG,0BAA0B,CACzC,UAAU,EACV,IAAI,EACJ,cAAc,EACd;YACE,aAAa,EAAE,IAAI;SACpB,CACF,CAAC;QACF,MAAM,eAAe,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC;QAC3C,MAAM,KAAK,GACT,QAAQ,CAAC,IAAI,CACX,CAAC,EAAE,EAAE,EAAE,CACL,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,eAAe;YAClC,EAAE,CAAC,WAAW,EAAE,IAAI,EAAE,KAAK,eAAe,CAAC;YAC7C,EAAE,CAAC,SAAS,CACf;YACD,QAAQ,CAAC,IAAI,CACX,CAAC,EAAE,EAAE,EAAE,CACL,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,eAAe;gBACnC,EAAE,CAAC,WAAW,EAAE,IAAI,EAAE,KAAK,eAAe,CAC7C,CAAC;QAEJ,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CACb,+CAA+C,WAAW,GAAG,CAC9D,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,GAAQ,IAAI,CAAC;QACvB,KAAK,MAAM,QAAQ,IAAI,8BAA8B,EAAE,CAAC;YACtD,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAC1C,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,SAAS;YACX,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;gBACtD,MAAM;YACR,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS;YACX,CAAC;QACH,CAAC;QACD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,4EAA4E,CAC7E,CAAC;QACJ,CAAC;QACD,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC;QAC5C,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IACjC,CAAC;SAAM,CAAC;QACN,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;YACxB,MAAM,MAAM,CAAC,OAAO,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAC;QAClD,CAAC;aAAM,CAAC;YACN,MAAM,MAAM,CAAC,OAAO,CAAC,sBAAsB,EAAE,EAAE,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;AACH,CAAC;AAED,KAAK,UAAU,cAAc,CAC3B,MAAW,EACX,MAAc,EACd,WAAoB;IAEpB,MAAM,MAAM,GAAQ,EAAE,MAAM,EAAE,CAAC;IAC/B,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,CAAC,WAAW,GAAG,WAAW,CAAC;IACnC,CAAC;IACD,MAAM,MAAM,CAAC,OAAO,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,CAAC,OAAO,UAAU,WAAW,CAAC,MAAe;IACjD,MAAM,CAAC,OAAO,CAAC;QACb,IAAI,EAAE,qBAAqB;QAC3B,WAAW,EAAE;;;;;;;;sKAQqJ;QAClK,UAAU,EAAE,iBAAiB;QAC7B,WAAW,EAAE;YACX,YAAY,EAAE,KAAK;YACnB,aAAa,EAAE,KAAK;SACrB;QACD,OAAO,EAAE,KAAK,EAAE,IAAS,EAAE,OAAY,EAAgB,EAAE;YACvD,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;YAC3B,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAC;YACrC,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;gBAEzC,IAAI,QAAQ,KAAK,QAAQ,CAAC,OAAO,EAAE,CAAC;oBAClC,MAAM,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;gBAClE,CAAC;qBAAM,IAAI,QAAQ,KAAK,QAAQ,CAAC,GAAG,EAAE,CAAC;oBACrC,MAAM,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;gBAC9D,CAAC;qBAAM,CAAC;oBACN,MAAM,IAAI,KAAK,CACb,yBAAyB,QAAQ,uCAAuC,CACzE,CAAC;gBACJ,CAAC;gBAED,OAAO;oBACL,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAM;4BACZ,IAAI,EAAE,gBAAgB,IAAI,CAAC,MAAM,WAC/B,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,iBAAiB,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,EAC5D,EAAE;yBACH;qBACF;iBACF,CAAC;YACJ,CAAC;YAAC,OAAO,GAAQ,EAAE,CAAC;gBAClB,MAAM,UAAU,GAAG,IAAI,CAAC,WAAW;oBACjC,CAAC,CAAC,UAAU,IAAI,CAAC,MAAM,kBAAkB,IAAI,CAAC,WAAW,GAAG;oBAC5D,CAAC,CAAC,UAAU,IAAI,CAAC,MAAM,EAAE,CAAC;gBAC5B,OAAO;oBACL,OAAO,EAAE;wBACP;4BACE,IAAI,EAAE,MAAM;4BACZ,IAAI,EAAE,2BAA2B,UAAU,WAAW,GAAG,CAAC,QAAQ,EAAE,EAAE;yBACvE;qBACF;iBACF,CAAC;YACJ,CAAC;QACH,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appium-mcp",
   "mcpName": "io.github.appium/appium-mcp",
-  "version": "1.14.0",
+  "version": "1.15.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.14.0",
+  "version": "1.15.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "appium-mcp",
-      "version": "1.14.0",
+      "version": "1.15.0",
       "transport": {
         "type": "stdio"
       }

package/src/tools/index.ts

@@ -35,6 +35,7 @@ import dragAndDrop from './interactions/drag-and-drop.js';
 import setValue from './interactions/set-value.js';
 import getText from './interactions/get-text.js';
 import getPageSource from './interactions/get-page-source.js';
+import handleAlert from './interactions/handle-alert.js';
 import { screenshot, elementScreenshot } from './interactions/screenshot.js';
 import activateApp from './app-management/activate-app.js';
 import installApp from './app-management/install-app.js';
@@ -136,6 +137,7 @@ export default function registerTools(server: FastMCP): void {
   setValue(server);
   getText(server);
   getPageSource(server);
+  handleAlert(server);
   screenshot(server);
   elementScreenshot(server);
 

package/src/tools/interactions/handle-alert.ts

@@ -0,0 +1,168 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import { generateAllElementLocators } from '../../locators/generate-all-locators.js';
+import { getDriver, getPlatformName, PLATFORM } from '../../session-store.js';
+
+export const handleAlertSchema = z.object({
+  action: z
+    .enum(['accept', 'dismiss'])
+    .describe('Action to perform on the alert: accept or dismiss'),
+  buttonLabel: z
+    .string()
+    .optional()
+    .describe(
+      `Optional label of the button to click. Common permission dialog buttons:
+Android: "While using the app", "Only this time", "Don't allow"
+iOS: "Always" or "Allow Always", "Once" or "Allow Once", "Don't allow"
+Standard: "OK", "Cancel", "Allow", "Deny"
+If not provided, uses default button based on action.
+Use appium_get_page_source or generate_locators to inspect the screen and discover exact labels.`
+    ),
+});
+
+const ANDROID_LOCATOR_STRATEGY_ORDER = [
+  'id',
+  'accessibility id',
+  'xpath',
+  '-android uiautomator',
+  'class name',
+];
+
+async function handleAndroidAlert(
+  driver: any,
+  action: string,
+  buttonLabel?: string
+): Promise<void> {
+  if (buttonLabel) {
+    const pageSource = await driver.getPageSource();
+    const elements = generateAllElementLocators(
+      pageSource,
+      true,
+      'uiautomator2',
+      {
+        fetchableOnly: true,
+      }
+    );
+    const normalizedLabel = buttonLabel.trim();
+    const match =
+      elements.find(
+        (el) =>
+          (el.text?.trim() === normalizedLabel ||
+            el.contentDesc?.trim() === normalizedLabel) &&
+          el.clickable
+      ) ??
+      elements.find(
+        (el) =>
+          el.text?.trim() === normalizedLabel ||
+          el.contentDesc?.trim() === normalizedLabel
+      );
+
+    if (!match) {
+      throw new Error(
+        `No element found with text or content-desc "${buttonLabel}"`
+      );
+    }
+
+    let button: any = null;
+    for (const strategy of ANDROID_LOCATOR_STRATEGY_ORDER) {
+      const selector = match.locators[strategy];
+      if (!selector) {
+        continue;
+      }
+      try {
+        button = await driver.findElement(strategy, selector);
+        break;
+      } catch {
+        continue;
+      }
+    }
+    if (!button) {
+      throw new Error(
+        'Could not find element with any generated locator; it may have disappeared'
+      );
+    }
+    const buttonUUID = button.ELEMENT || button;
+    await driver.click(buttonUUID);
+  } else {
+    if (action === 'accept') {
+      await driver.execute('mobile: acceptAlert', {});
+    } else {
+      await driver.execute('mobile: dismissAlert', {});
+    }
+  }
+}
+
+async function handleiOSAlert(
+  driver: any,
+  action: string,
+  buttonLabel?: string
+): Promise<void> {
+  const params: any = { action };
+  if (buttonLabel) {
+    params.buttonLabel = buttonLabel;
+  }
+  await driver.execute('mobile: alert', params);
+}
+
+export default function handleAlert(server: FastMCP): void {
+  server.addTool({
+    name: 'appium_handle_alert',
+    description: `Handle system alerts or dialogs that do not belong to the app.
+Use this to dismiss or accept alerts programmatically instead of using autoDismissAlerts capability.
+Supports permission dialogs with buttons like:
+- Android: "While using the app", "Only this time", "Don't allow"
+- iOS: "Always", "Allow Once", "Don't allow"
+For iOS: Uses mobile: alert execute command.
+For Android: Uses mobile: acceptAlert/dismissAlert or searches the current page source for an element whose text or content-desc matches the label, then uses generated locators to find and click it (no hardcoded resource IDs or XPaths).
+If no alert is present, the error is caught and returned gracefully.
+To discover button labels and screen structure first, use appium_get_page_source (XML hierarchy) or generate_locators (interactable elements with text/content-desc).`,
+    parameters: handleAlertSchema,
+    annotations: {
+      readOnlyHint: false,
+      openWorldHint: false,
+    },
+    execute: async (args: any, context: any): Promise<any> => {
+      const driver = getDriver();
+      if (!driver) {
+        throw new Error('No driver found');
+      }
+
+      try {
+        const platform = getPlatformName(driver);
+
+        if (platform === PLATFORM.android) {
+          await handleAndroidAlert(driver, args.action, args.buttonLabel);
+        } else if (platform === PLATFORM.ios) {
+          await handleiOSAlert(driver, args.action, args.buttonLabel);
+        } else {
+          throw new Error(
+            `Unsupported platform: ${platform}. Only Android and iOS are supported.`
+          );
+        }
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Successfully ${args.action}ed alert${
+                args.buttonLabel ? ` with button "${args.buttonLabel}"` : ''
+              }`,
+            },
+          ],
+        };
+      } catch (err: any) {
+        const contextStr = args.buttonLabel
+          ? `action=${args.action}, buttonLabel="${args.buttonLabel}"`
+          : `action=${args.action}`;
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to handle alert (${contextStr}). err: ${err.toString()}`,
+            },
+          ],
+        };
+      }
+    },
+  });
+}