appium-mcp 1.8.11 → 1.8.13

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

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

@@ -1,198 +0,0 @@
-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 as any).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 as any).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

@@ -1,113 +0,0 @@
-import { z } from 'zod';
-import {
-  getDriver,
-  getPlatformName,
-  isRemoteDriverSession,
-} from '../../session-store.js';
-import log from '../../logger.js';
-import type { Client } from 'webdriver';
-
-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 { width, height } = await (driver as any).getWindowRect();
-        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) === 'Android') {
-          await (driver as any).performActions([
-            {
-              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 },
-              ],
-            },
-          ]);
-          log.info('Scroll action completed successfully.');
-        } else if (getPlatformName(driver) === 'iOS') {
-          const _ok = isRemoteDriverSession(driver)
-            ? await (driver as Client).executeScript('mobile: scroll', [
-                {
-                  direction: args.direction,
-                  startX,
-                  startY,
-                  endX: startX,
-                  endY,
-                },
-              ])
-            : await (driver as any).execute('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()}`,
-            },
-          ],
-        };
-      }
-    },
-  });
-}