appium-mcp 1.8.15 → 1.9.0

package/src/tools/ios/setup-wda.ts

@@ -0,0 +1,217 @@
+/**
+ * Tool to download and setup WebDriverAgent (WDA) for iOS simulators
+ */
+import { z } from 'zod';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+import path from 'path';
+import { access, mkdir, unlink } from 'fs/promises';
+import { constants, createWriteStream } from 'fs';
+import { pipeline } from 'stream/promises';
+import os from 'os';
+import axios from 'axios';
+import log from '../../logger.js';
+
+const execAsync = promisify(exec);
+
+function cachePath(folder: string): string {
+  return path.join(os.homedir(), '.cache', 'appium-mcp', folder);
+}
+
+async function getLatestWDAVersion(): Promise<string> {
+  try {
+    const response = await axios.get(
+      'https://api.github.com/repos/appium/WebDriverAgent/releases/latest',
+      {
+        headers: {
+          'User-Agent': 'mcp-appium',
+          Accept: 'application/vnd.github.v3+json',
+        },
+      }
+    );
+
+    const release = response.data;
+    if (release.tag_name) {
+      return release.tag_name.replace(/^v/, '');
+    } else {
+      throw new Error('No tag_name found in release data');
+    }
+  } catch (error: any) {
+    if (error.response) {
+      throw new Error(
+        `Failed to fetch WDA version: ${error.response.status} ${error.response.statusText}`
+      );
+    }
+    throw error;
+  }
+}
+
+async function cleanupFile(path: string): Promise<void> {
+  try {
+    await access(path, constants.F_OK);
+    await unlink(path);
+  } catch {
+    // File doesn't exist or already deleted
+  }
+}
+
+async function downloadFile(url: string, destPath: string): Promise<void> {
+  try {
+    const response = await axios({
+      url,
+      method: 'GET',
+      responseType: 'stream',
+      maxRedirects: 5,
+    });
+
+    const writer = createWriteStream(destPath);
+
+    try {
+      await pipeline(response.data, writer);
+    } catch (streamError: any) {
+      writer.close();
+      await cleanupFile(destPath);
+      throw streamError;
+    }
+  } catch (error: any) {
+    // Clean up partial file on error
+    await cleanupFile(destPath);
+
+    if (error.response) {
+      throw new Error(
+        `Failed to download: ${error.response.status} ${error.response.statusText}`
+      );
+    }
+    throw error;
+  }
+}
+
+async function unzipFile(zipPath: string, destDir: string): Promise<void> {
+  await execAsync(`unzip -q "${zipPath}" -d "${destDir}"`);
+}
+
+export default function setupWDA(server: any): void {
+  server.addTool({
+    name: 'setup_wda',
+    description: `Download and setup prebuilt WebDriverAgent (WDA) for iOS/tvOS simulators only (not for real devices).
+      This significantly speeds up the first Appium session by avoiding the need to build WDA from source.
+      Downloads the latest version from GitHub and caches it locally.
+      `,
+    parameters: z.object({
+      platform: z
+        .enum(['ios', 'tvos'])
+        .optional()
+        .default('ios')
+        .describe(
+          `The simulator platform to download WDA for.
+          Default is "ios".
+          Use "tvos" for Apple TV simulators.
+          Note: This tool only works with simulators, not real devices.`
+        ),
+    }),
+    annotations: {
+      readOnlyHint: false,
+      openWorldHint: false,
+    },
+    execute: async (args: any, context: any): Promise<any> => {
+      try {
+        const { platform = 'ios' } = args;
+
+        // Verify it's a macOS system
+        if (process.platform !== 'darwin') {
+          throw new Error(
+            'WebDriverAgent setup is only supported on macOS systems'
+          );
+        }
+
+        // Get the architecture
+        const arch = os.arch();
+        const archStr = arch === 'arm64' ? 'arm64' : 'x86_64';
+
+        // Fetch latest WDA version from GitHub
+        const wdaVersion = await getLatestWDAVersion();
+
+        // Create cache directory structure
+        const versionCacheDir = cachePath(`wda/${wdaVersion}`);
+        const extractDir = path.join(versionCacheDir, 'extracted');
+        const zipPath = path.join(
+          versionCacheDir,
+          `WebDriverAgentRunner-Build-Sim-${archStr}.zip`
+        );
+        const appPath = path.join(
+          extractDir,
+          'WebDriverAgentRunner-Runner.app'
+        );
+
+        // Check if this version is already cached
+        try {
+          await access(appPath, constants.F_OK);
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `✅ WebDriverAgent is already set up!\n\nVersion: ${wdaVersion}\nPlatform: ${platform} (simulator only)\nArchitecture: ${archStr}\nLocation: ${appPath}\nCache: ~/.cache/appium-mcp/wda/${wdaVersion}\n\n🚀 You can now create an Appium session without needing to build WDA from source.`,
+              },
+            ],
+          };
+        } catch {
+          // File doesn't exist, continue to download
+        }
+
+        // Version not cached, download it
+        const startTime = Date.now();
+
+        // Create cache directories
+        await mkdir(versionCacheDir, { recursive: true });
+        await mkdir(extractDir, { recursive: true });
+
+        // Download URL - use architecture-specific filename
+        const downloadUrl = `https://github.com/appium/WebDriverAgent/releases/download/v${wdaVersion}/WebDriverAgentRunner-Build-Sim-${archStr}.zip`;
+
+        log.info(
+          `Downloading prebuilt WDA v${wdaVersion} for ${platform} simulator...`
+        );
+
+        await downloadFile(downloadUrl, zipPath);
+
+        log.info('Extracting WebDriverAgent...');
+        await unzipFile(zipPath, extractDir);
+
+        const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+
+        // Verify extraction
+        try {
+          await access(appPath, constants.F_OK);
+        } catch {
+          throw new Error(
+            'WebDriverAgent extraction failed - app bundle not found'
+          );
+        }
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `${JSON.stringify(
+                {
+                  version: wdaVersion,
+                  platform,
+                  architecture: archStr,
+                  wdaAppPath: appPath,
+                  wdaCachePath: `~/.cache/appium-mcp/wda/${wdaVersion}`,
+                  simulatorOnly: true,
+                  ready: true,
+                },
+                null,
+                2
+              )}`,
+            },
+          ],
+        };
+      } catch (error: any) {
+        log.error('Error setting up WDA:', error);
+        throw new Error(`Failed to setup WebDriverAgent: ${error.message}`);
+      }
+    },
+  });
+}

package/src/tools/navigations/scroll-to-element.ts

@@ -0,0 +1,198 @@
+import { getDriver, getPlatformName } from '../../session-store.js';
+import { z } from 'zod';
+
+const scrollToElementSchema = 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'),
+  direction: z
+    .enum(['up', 'down'])
+    .default('down')
+    .describe('Direction to scroll when searching for the element'),
+});
+
+const getValue = (xpath: string, expression: string): string => {
+  // Extracts the value from an XPath expression.
+  let start = xpath.indexOf(expression) + expression.length;
+  start = xpath.indexOf("'", start) + 1;
+  const end = xpath.indexOf("'", start);
+  return xpath.substring(start, end);
+};
+
+const transformXPath = (
+  xpath: string
+): { strategy: string; selector: string } => {
+  // normalize xpath expression by replacing " by '
+  xpath = xpath.replace(/"/g, "'");
+  if (xpath.includes('@text=')) {
+    return { strategy: 'text', selector: getValue(xpath, '@text=') };
+  }
+
+  if (xpath.includes('@content-desc=')) {
+    return {
+      strategy: 'description',
+      selector: getValue(xpath, '@content-desc='),
+    };
+  }
+
+  if (xpath.includes('contains(@text,')) {
+    return {
+      strategy: 'textContains',
+      selector: getValue(xpath, 'contains(@text,'),
+    };
+  }
+
+  if (xpath.includes('contains(@content-desc,')) {
+    return {
+      strategy: 'descriptionContains',
+      selector: getValue(xpath, 'contains(@content-desc,'),
+    };
+  }
+
+  throw new Error(
+    `Unsupported XPath expression: ${xpath}. Supported expressions are: @text, @content-desc, contains(@text, ...), contains(@content-desc, ...)`
+  );
+};
+
+const transformLocator = (
+  strategy: string,
+  selector: string
+): { strategy: string; selector: string } => {
+  if (strategy === 'id') {
+    return { strategy: 'resourceId', selector };
+  }
+  if (strategy === 'xpath') {
+    return transformXPath(selector);
+  }
+  if (strategy === 'class name') {
+    return { strategy: 'className', selector };
+  }
+
+  return { strategy, selector };
+};
+
+async function performAndroidScroll(
+  driver: any,
+  args: any,
+  direction: string
+): Promise<void> {
+  // Use UiAutomator scroll gestures for Android
+  const scrollDirection =
+    direction === 'up' ? 'scrollBackward' : 'scrollForward';
+  const scrollCommand = `new UiScrollable(new UiSelector().scrollable(true)).${scrollDirection}()`;
+
+  try {
+    await driver.findElement('-android uiautomator', scrollCommand);
+  } catch (error) {
+    // If UiScrollable fails, try touch actions
+    const { width, height } = await driver.getWindowRect();
+    const startX = width / 2;
+    const startY = direction === 'up' ? height * 0.3 : height * 0.7;
+    const endY = direction === 'up' ? height * 0.7 : height * 0.3;
+
+    await driver.touchAction([
+      { action: 'press', x: startX, y: startY },
+      { action: 'wait', ms: 500 },
+      { action: 'moveTo', x: startX, y: endY },
+      { action: 'release' },
+    ]);
+  }
+}
+
+async function performiOSScroll(driver: any, direction: string): Promise<void> {
+  // Use iOS mobile commands for scrolling
+  const { width, height } = await driver.getWindowRect();
+
+  await driver.execute('mobile: scroll', {
+    direction,
+    startX: width / 2,
+    startY: direction === 'up' ? height * 0.3 : height * 0.7,
+    endX: width / 2,
+    endY: direction === 'up' ? height * 0.7 : height * 0.3,
+  });
+}
+
+export default function scrollToElement(server: any): void {
+  server.addTool({
+    name: 'appium_scroll_to_element',
+    description: 'Scrolls the current screen till a certain element is visible',
+    parameters: scrollToElementSchema,
+    annotations: {
+      readOnlyHint: false,
+      openWorldHint: false,
+    },
+    execute: async (args: any, context: any): Promise<any> => {
+      const driver = getDriver();
+      if (!driver) {
+        throw new Error(
+          'No active driver session. Please create a session first.'
+        );
+      }
+
+      try {
+        const platform = getPlatformName(driver);
+
+        // First try to find the element directly (it might already be in viewport)
+        try {
+          const element = await driver.findElement(
+            args.strategy,
+            args.selector
+          );
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Element ${args.selector} is already visible on screen.`,
+              },
+            ],
+          };
+        } catch (error) {
+          const direction = args.direction || 'down';
+          switch (platform) {
+            case 'Android':
+              await performAndroidScroll(driver, args, direction);
+              break;
+            case 'iOS':
+              await performiOSScroll(driver, direction);
+              break;
+            default:
+              throw new Error(
+                'Unsupported driver type. This tool only supports Android and iOS drivers.'
+              );
+          }
+
+          const element = await driver.findElement(
+            args.strategy,
+            args.selector
+          );
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Successfully scrolled found element ${args.selector} after initial scroll.`,
+              },
+            ],
+          };
+        }
+      } catch (err: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to scroll and find element. Error: ${err.toString()}`,
+            },
+          ],
+        };
+      }
+    },
+  });
+}

package/src/tools/navigations/scroll.ts

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+import { getDriver, getPlatformName, PLATFORM } from '../../session-store.js';
+import log from '../../logger.js';
+import { execute, getWindowRect, performActions } from '../../command.js';
+
+export default function scroll(server: any): void {
+  server.addTool({
+    name: 'appium_scroll',
+    description: 'Scrolls the current screen up or down',
+    parameters: z.object({
+      direction: z
+        .enum(['up', 'down'])
+        .default('down')
+        .describe('Scroll direction'),
+    }),
+    annotations: {
+      readOnlyHint: false,
+      openWorldHint: false,
+    },
+    execute: async (args: any, context: any): Promise<any> => {
+      const driver = getDriver();
+      if (!driver) {
+        throw new Error(
+          'No active driver session. Please create a session first.'
+        );
+      }
+
+      try {
+        const rect = await getWindowRect(driver);
+        const { width, height } = rect;
+        log.info('Device screen size:', { width, height });
+        const startX = Math.floor(width / 2);
+        // calculate start and end Y positions for scrolling depending on the direction
+        // startY is at 80% of the height, endY is at 20% of the height for downward scroll
+        // and vice versa for upward scroll
+        // this ensures that the scroll starts from the bottom of the screen and goes to the top
+        // or starts from the top and goes to the bottom
+        // Adjust these percentages as needed for your specific use case
+        const startY =
+          args.direction === 'down'
+            ? Math.floor(height * 0.8)
+            : Math.floor(height * 0.2);
+        const endY =
+          args.direction === 'down'
+            ? Math.floor(height * 0.2)
+            : Math.floor(height * 0.8);
+
+        log.info('Going to scroll from:', { startX, startY });
+        log.info('Going to scroll to:', { startX, endY });
+
+        if (getPlatformName(driver) === PLATFORM.android) {
+          const operation = [
+            {
+              type: 'pointer',
+              id: 'finger1',
+              parameters: { pointerType: 'touch' },
+              actions: [
+                { type: 'pointerMove', duration: 0, x: startX, y: startY },
+                { type: 'pointerDown', button: 0 },
+                { type: 'pause', duration: 250 },
+                { type: 'pointerMove', duration: 600, x: startX, y: endY },
+                { type: 'pointerUp', button: 0 },
+              ],
+            },
+          ];
+          await performActions(driver, operation);
+          log.info('Scroll action completed successfully.');
+        } else if (getPlatformName(driver) === PLATFORM.ios) {
+          await execute(driver, 'mobile: scroll', {
+            direction: args.direction,
+            startX,
+            startY,
+            endX: startX,
+            endY,
+          });
+        } else {
+          throw new Error(
+            `Unsupported platform: ${getPlatformName(driver)}. Only Android and iOS are supported.`
+          );
+        }
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Scrolled ${args.direction} successfully.`,
+            },
+          ],
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to scroll ${args.direction}. Error: ${err.toString()}`,
+            },
+          ],
+        };
+      }
+    },
+  });
+}