appium-mcp 1.8.15 → 1.9.0

package/src/tools/index.ts

@@ -0,0 +1,159 @@
+/**
+ * Tools Registration Module
+ *
+ * This file registers all available MCP tools with the server.
+ *
+ * ADDING A NEW TOOL:
+ * 1. Create your tool file in src/tools/
+ * 2. Import it at the top of this file
+ * 3. Call it in the registerTools function below
+ *
+ * See docs/CONTRIBUTING.md for detailed instructions.
+ * See src/tools/README.md for tool organization.
+ * See src/tools/metadata/README.md for YAML metadata approach.
+ */
+import { FastMCP } from 'fastmcp';
+import log from '../logger.js';
+import answerAppium from './documentation/answer-appium.js';
+import createSession from './session/create-session.js';
+import deleteSession from './session/delete-session.js';
+import generateLocators from './test-generation/locators.js';
+import selectPlatform from './session/select-platform.js';
+import selectDevice from './session/select-device.js';
+import bootSimulator from './ios/boot-simulator.js';
+import setupWDA from './ios/setup-wda.js';
+import installWDA from './ios/install-wda.js';
+import generateTest from './test-generation/generate-tests.js';
+import scroll from './navigations/scroll.js';
+import scrollToElement from './navigations/scroll-to-element.js';
+import swipe from './navigations/swipe.js';
+import findElement from './interactions/find.js';
+import clickElement from './interactions/click.js';
+import doubleTap from './interactions/double-tap.js';
+import longPress from './interactions/long-press.js';
+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 screenshot from './interactions/screenshot.js';
+import activateApp from './app-management/activate-app.js';
+import installApp from './app-management/install-app.js';
+import uninstallApp from './app-management/uninstall-app.js';
+import terminateApp from './app-management/terminate-app.js';
+import listApps from './app-management/list-apps.js';
+import getContexts from './context/get-contexts.js';
+import switchContext from './context/switch-context.js';
+
+export default function registerTools(server: FastMCP): void {
+  // Wrap addTool to inject logging around tool execution
+  const originalAddTool = (server as any).addTool.bind(server);
+  (server as any).addTool = (toolDef: any) => {
+    const toolName = toolDef?.name ?? 'unknown_tool';
+    const originalExecute = toolDef?.execute;
+    if (typeof originalExecute !== 'function') {
+      return originalAddTool(toolDef);
+    }
+    const SENSITIVE_KEYS = [
+      'password',
+      'token',
+      'accessToken',
+      'authorization',
+      'apiKey',
+      'apikey',
+      'secret',
+      'clientSecret',
+    ];
+    const redactArgs = (obj: any) => {
+      try {
+        return JSON.parse(
+          JSON.stringify(obj, (key, value) => {
+            if (
+              key &&
+              SENSITIVE_KEYS.some((k) => key.toLowerCase().includes(k))
+            ) {
+              return '[REDACTED]';
+            }
+            // Avoid logging extremely large buffers/strings
+            if (value && typeof value === 'string' && value.length > 2000) {
+              return `[string:${value.length}]`;
+            }
+            if (
+              value &&
+              typeof Buffer !== 'undefined' &&
+              Buffer.isBuffer(value)
+            ) {
+              return `[buffer:${(value as Buffer).length}]`;
+            }
+            return value;
+          })
+        );
+      } catch {
+        return '[Unserializable args]';
+      }
+    };
+    return originalAddTool({
+      ...toolDef,
+      execute: async (args: any, context: any) => {
+        const start = Date.now();
+        log.info(`[TOOL START] ${toolName}`, redactArgs(args));
+        try {
+          const result = await originalExecute(args, context);
+          const duration = Date.now() - start;
+          log.info(`[TOOL END] ${toolName} (${duration}ms)`);
+          return result;
+        } catch (err: any) {
+          const duration = Date.now() - start;
+          const msg = err?.stack || err?.message || String(err);
+          log.error(`[TOOL ERROR] ${toolName} (${duration}ms): ${msg}`);
+          throw err;
+        }
+      },
+    });
+  };
+
+  // Session Management
+  selectPlatform(server);
+  selectDevice(server);
+  createSession(server);
+  deleteSession(server);
+
+  // iOS Setup
+  bootSimulator(server);
+  setupWDA(server);
+  installWDA(server);
+
+  // Navigation
+  scroll(server);
+  scrollToElement(server);
+  swipe(server);
+
+  // Element Interactions
+  findElement(server);
+  clickElement(server);
+  doubleTap(server);
+  longPress(server);
+  dragAndDrop(server);
+  setValue(server);
+  getText(server);
+  getPageSource(server);
+  screenshot(server);
+
+  // App Management
+  activateApp(server);
+  installApp(server);
+  uninstallApp(server);
+  terminateApp(server);
+  listApps(server);
+
+  // Context Management
+  getContexts(server);
+  switchContext(server);
+
+  // Test Generation
+  generateLocators(server);
+  generateTest(server);
+
+  // Documentation
+  answerAppium(server);
+  log.info('All tools registered');
+}

package/src/tools/interactions/click.ts

@@ -0,0 +1,48 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import { getDriver } from '../../session-store.js';
+import { elementUUIDScheme } from '../../schema.js';
+import { elementClick as _elementClick } from '../../command.js';
+
+export default function generateTest(server: FastMCP): void {
+  const clickActionSchema = z.object({
+    elementUUID: elementUUIDScheme,
+  });
+
+  server.addTool({
+    name: 'appium_click',
+    description: 'Click on an element',
+    parameters: clickActionSchema,
+    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 {
+        await _elementClick(driver, args.elementUUID);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Successfully clicked on element ${args.elementUUID}`,
+            },
+          ],
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to click on element ${args.elementUUID}. err: ${err.toString()}`,
+            },
+          ],
+        };
+      }
+    },
+  });
+}

package/src/tools/interactions/double-tap.ts

@@ -0,0 +1,96 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import {
+  getDriver,
+  getPlatformName,
+  isAndroidUiautomator2DriverSession,
+  PLATFORM,
+} from '../../session-store.js';
+import { elementUUIDScheme } from '../../schema.js';
+import type { Client } from 'webdriver';
+import { execute, getElementRect, performActions } from '../../command.js';
+
+export default function doubleTap(server: FastMCP): void {
+  const doubleTapActionSchema = z.object({
+    elementUUID: elementUUIDScheme,
+  });
+
+  server.addTool({
+    name: 'appium_double_tap',
+    description: 'Perform double tap on an element',
+    parameters: doubleTapActionSchema,
+    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) {
+          // Get element location for Android double tap
+          const element = await driver.findElement('id', args.elementUUID);
+          const elementRect = await getElementRect(
+            driver,
+            element['element-6066-11e4-a52e-4f735466cecf']
+          );
+
+          // Calculate center coordinates
+          const x = elementRect.x + elementRect.width / 2;
+          const y = elementRect.y + elementRect.height / 2;
+
+          // Perform double tap using performActions
+          const operation = [
+            {
+              type: 'pointer',
+              id: 'finger1',
+              parameters: { pointerType: 'touch' },
+              actions: [
+                { type: 'pointerMove', duration: 0, x, y },
+                { type: 'pointerDown', button: 0 },
+                { type: 'pause', duration: 50 },
+                { type: 'pointerUp', button: 0 },
+                { type: 'pause', duration: 100 },
+                { type: 'pointerDown', button: 0 },
+                { type: 'pause', duration: 50 },
+                { type: 'pointerUp', button: 0 },
+              ],
+            },
+          ];
+          await performActions(driver, operation);
+        } else if (platform === PLATFORM.ios) {
+          // Use iOS mobile: doubleTap execute method
+          await execute(driver, 'mobile: doubleTap', {
+            elementId: args.elementUUID,
+          });
+        } else {
+          throw new Error(
+            `Unsupported platform: ${platform}. Only Android and iOS are supported.`
+          );
+        }
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Successfully performed double tap on element ${args.elementUUID}`,
+            },
+          ],
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to perform double tap on element ${args.elementUUID}. Error: ${err.toString()}`,
+            },
+          ],
+        };
+      }
+    },
+  });
+}

package/src/tools/interactions/drag-and-drop.ts

@@ -0,0 +1,236 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import {
+  getDriver,
+  getPlatformName,
+  isAndroidUiautomator2DriverSession,
+  isRemoteDriverSession,
+  isXCUITestDriverSession,
+} from '../../session-store.js';
+import { elementUUIDScheme } from '../../schema.js';
+import type { Client } from 'webdriver';
+import { getElementRect, getWindowRect } from '../../command.js';
+
+const DROP_PAUSE_DURATION_MS = 150;
+
+async function performDragAndDrop(
+  driver: any,
+  startX: number,
+  startY: number,
+  endX: number,
+  endY: number,
+  duration: number,
+  longPressDuration: number
+): Promise<void> {
+  await driver.performActions([
+    {
+      type: 'pointer',
+      id: 'finger1',
+      parameters: { pointerType: 'touch' },
+      actions: [
+        { type: 'pointerMove', duration: 0, x: startX, y: startY },
+        { type: 'pointerDown', button: 0 },
+        { type: 'pause', duration: longPressDuration },
+        { type: 'pointerMove', duration, x: endX, y: endY },
+        { type: 'pause', duration: DROP_PAUSE_DURATION_MS },
+        { type: 'pointerUp', button: 0 },
+      ],
+    },
+  ]);
+}
+
+export default function dragAndDrop(server: FastMCP): void {
+  const dragAndDropSchema = z.object({
+    sourceElementUUID: elementUUIDScheme
+      .trim()
+      .min(1)
+      .optional()
+      .describe(
+        'UUID of the source element to drag from. Either sourceElementUUID or sourceX/sourceY must be provided.'
+      ),
+    sourceX: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe(
+        'Starting X coordinate. Required if sourceElementUUID is not provided.'
+      ),
+    sourceY: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe(
+        'Starting Y coordinate. Required if sourceElementUUID is not provided.'
+      ),
+    targetElementUUID: elementUUIDScheme
+      .trim()
+      .min(1)
+      .optional()
+      .describe(
+        'UUID of the target element to drop on. Either targetElementUUID or targetX/targetY must be provided.'
+      ),
+    targetX: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe(
+        'Ending X coordinate. Required if targetElementUUID is not provided.'
+      ),
+    targetY: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe(
+        'Ending Y coordinate. Required if targetElementUUID is not provided.'
+      ),
+    duration: z
+      .number()
+      .int()
+      .min(100)
+      .max(5000)
+      .default(1200)
+      .optional()
+      .describe(
+        'Duration of the drag movement in milliseconds. Default is 1200ms.'
+      ),
+    longPressDuration: z
+      .number()
+      .int()
+      .min(400)
+      .max(2000)
+      .default(600)
+      .optional()
+      .describe(
+        'Duration of the long press before dragging in milliseconds. Default is 600ms.'
+      ),
+  });
+
+  server.addTool({
+    name: 'appium_drag_and_drop',
+    description: `Perform a drag and drop gesture from a source location to a target location.
+      The gesture includes:
+      1. Long press (default 600ms, configurable) on the source to initiate drag mode
+      2. While holding, drag to the target location
+      3. Release at the target to complete the drop
+
+      Supports four modes:
+      1. Element to Element: Drag from one element to another element
+      2. Element to Coordinates: Drag from an element to specific coordinates
+      3. Coordinates to Element: Drag from coordinates to an element
+      4. Coordinates to Coordinates: Drag from coordinates to coordinates
+
+      This is useful for reordering lists, moving items, drag-to-delete, and other drag interactions.`,
+    parameters: dragAndDropSchema,
+    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);
+        const duration = args.duration || 1200;
+        const longPressDuration = args.longPressDuration || 600;
+
+        if (
+          !args.sourceElementUUID &&
+          (args.sourceX === undefined || args.sourceY === undefined)
+        ) {
+          throw new Error(
+            'Either sourceElementUUID or both sourceX and sourceY must be provided.'
+          );
+        }
+
+        if (
+          !args.targetElementUUID &&
+          (args.targetX === undefined || args.targetY === undefined)
+        ) {
+          throw new Error(
+            'Either targetElementUUID or both targetX and targetY must be provided.'
+          );
+        }
+
+        let startX: number, startY: number;
+        let endX: number, endY: number;
+        if (args.sourceElementUUID) {
+          const rect = await getElementRect(driver, args.sourceElementUUID);
+          startX = Math.floor(rect.x + rect.width / 2);
+          startY = Math.floor(rect.y + rect.height / 2);
+        } else {
+          startX = args.sourceX;
+          startY = args.sourceY;
+        }
+
+        if (args.targetElementUUID) {
+          const rect = await getElementRect(driver, args.targetElementUUID);
+          endX = Math.floor(rect.x + rect.width / 2);
+          endY = Math.floor(rect.y + rect.height / 2);
+        } else {
+          endX = args.targetX;
+          endY = args.targetY;
+        }
+
+        const { width, height } = await getWindowRect(driver);
+        if (startX < 0 || startX >= width || startY < 0 || startY >= height) {
+          throw new Error(
+            `Source coordinates (${startX}, ${startY}) are out of screen bounds (${width}x${height})`
+          );
+        }
+        if (endX < 0 || endX >= width || endY < 0 || endY >= height) {
+          throw new Error(
+            `Target coordinates (${endX}, ${endY}) are out of screen bounds (${width}x${height})`
+          );
+        }
+
+        if (platform === 'Android' || platform === 'iOS') {
+          await performDragAndDrop(
+            driver,
+            startX,
+            startY,
+            endX,
+            endY,
+            duration,
+            longPressDuration
+          );
+        } else {
+          throw new Error(
+            `Unsupported platform: ${platform}. Only Android and iOS are supported.`
+          );
+        }
+
+        const sourceDesc = args.sourceElementUUID
+          ? `element ${args.sourceElementUUID}`
+          : `coordinates (${startX}, ${startY})`;
+        const targetDesc = args.targetElementUUID
+          ? `element ${args.targetElementUUID}`
+          : `coordinates (${endX}, ${endY})`;
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Successfully performed drag and drop from ${sourceDesc} to ${targetDesc}.`,
+            },
+          ],
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to perform drag and drop. Error: ${err.toString()}`,
+            },
+          ],
+        };
+      }
+    },
+  });
+}

package/src/tools/interactions/find.ts

@@ -0,0 +1,58 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import { getDriver } from '../../session-store.js';
+
+export const findElementSchema = z.object({
+  strategy: z.enum([
+    'xpath',
+    'id',
+    'name',
+    'class name',
+    'accessibility id',
+    'css selector',
+    '-android uiautomator',
+    '-ios predicate string',
+    '-ios class chain',
+  ]),
+  selector: z.string().describe('The selector to find the element'),
+});
+
+export default function findElement(server: FastMCP): void {
+  server.addTool({
+    name: 'appium_find_element',
+    description:
+      'Find an element with the given strategy and selector which will return a uuid that can be used while interaction',
+    parameters: findElementSchema,
+    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 element = await driver.findElement(args.strategy, args.selector);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Successfully found element ${args.selector} with strategy ${args.strategy}. Element id ${element['element-6066-11e4-a52e-4f735466cecf']}`,
+            },
+          ],
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to find element ${args.selector} with strategy ${args.strategy}. err: ${err.toString()}`,
+            },
+          ],
+        };
+      }
+    },
+  });
+}

package/src/tools/interactions/get-page-source.ts

@@ -0,0 +1,65 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import { getDriver } from '../../session-store.js';
+import {
+  createUIResource,
+  createPageSourceInspectorUI,
+  addUIResourceToResponse,
+} from '../../ui/mcp-ui-utils.js';
+import { getPageSource as _getPageSource } from '../../command.js';
+
+export default function getPageSource(server: FastMCP): void {
+  server.addTool({
+    name: 'appium_get_page_source',
+    description: 'Get the page source (XML) from the current screen',
+    parameters: z.object({}),
+    annotations: {
+      readOnlyHint: true,
+      openWorldHint: false,
+    },
+    execute: async (args: any, context: any): Promise<any> => {
+      const driver = getDriver();
+      if (!driver) {
+        throw new Error('No driver found. Please create a session first.');
+      }
+
+      try {
+        const pageSource = await _getPageSource(driver);
+        if (!pageSource) {
+          throw new Error('Page source is empty or null');
+        }
+
+        const textResponse = {
+          content: [
+            {
+              type: 'text',
+              text:
+                'Page source retrieved successfully: \n' +
+                '```xml ' +
+                pageSource +
+                '```',
+            },
+          ],
+        };
+
+        // Add interactive page source inspector UI
+        const uiResource = createUIResource(
+          `ui://appium-mcp/page-source-inspector/${Date.now()}`,
+          createPageSourceInspectorUI(pageSource)
+        );
+
+        return addUIResourceToResponse(textResponse, uiResource);
+      } catch (err: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to get page source. Error: ${err.toString()}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    },
+  });
+}