appium-mcp 1.8.10 → 1.8.12

package/src/tools/index.ts

@@ -1,159 +0,0 @@
-/**
- * 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

@@ -1,50 +0,0 @@
-import { FastMCP } from 'fastmcp';
-import { z } from 'zod';
-import { getDriver, isRemoteDriverSession } from '../../session-store.js';
-import { elementUUIDScheme } from '../../schema.js';
-import type { Client } from 'webdriver';
-
-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 {
-        const _ok = isRemoteDriverSession(driver)
-          ? await (driver as Client).elementClick(args.elementUUID)
-          : await (driver as any).click(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

@@ -1,99 +0,0 @@
-import { FastMCP } from 'fastmcp';
-import { z } from 'zod';
-import {
-  getDriver,
-  getPlatformName,
-  isRemoteDriverSession,
-} from '../../session-store.js';
-import { elementUUIDScheme } from '../../schema.js';
-import type { Client } from 'webdriver';
-
-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 === 'Android') {
-          // Get element location for Android double tap
-          const element = await (driver as any).findElement(
-            'id',
-            args.elementUUID
-          );
-          const location = await element.getLocation();
-          const size = await element.getSize();
-
-          // Calculate center coordinates
-          const x = location.x + size.width / 2;
-          const y = location.y + size.height / 2;
-
-          // Perform double tap using performActions
-          await (driver as any).performActions([
-            {
-              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 },
-              ],
-            },
-          ]);
-        } else if (platform === 'iOS') {
-          // Use iOS mobile: doubleTap execute method
-          const _ok = isRemoteDriverSession(driver)
-            ? await (driver as Client).executeScript('mobile: doubleTap', [
-                { elementId: args.elementUUID },
-              ])
-            : await (driver as any).execute('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

@@ -1,238 +0,0 @@
-import { FastMCP } from 'fastmcp';
-import { z } from 'zod';
-import {
-  getDriver,
-  getPlatformName,
-  isRemoteDriverSession,
-} from '../../session-store.js';
-import { elementUUIDScheme } from '../../schema.js';
-import type { Client } from 'webdriver';
-
-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 (driver as any).getElementRect(
-            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 (driver as any).getElementRect(
-            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 (driver as any).getWindowRect();
-        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

@@ -1,61 +0,0 @@
-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 as any).findElement(
-          args.strategy,
-          args.selector
-        );
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Successfully found element ${args.selector} with strategy ${args.strategy}. Element id ${element.ELEMENT}`,
-            },
-          ],
-        };
-      } 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

@@ -1,65 +0,0 @@
-import { FastMCP } from 'fastmcp';
-import { z } from 'zod';
-import { getDriver } from '../../session-store.js';
-import {
-  createUIResource,
-  createPageSourceInspectorUI,
-  addUIResourceToResponse,
-} from '../../ui/mcp-ui-utils.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 (driver as any).getPageSource();
-
-        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,
-        };
-      }
-    },
-  });
-}