appium-mcp 1.8.11 → 1.8.13

package/src/tools/interactions/get-text.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 getText(server: FastMCP): void {
-  const getTextSchema = z.object({
-    elementUUID: elementUUIDScheme,
-  });
-
-  server.addTool({
-    name: 'appium_get_text',
-    description: 'Get text from an element',
-    parameters: getTextSchema,
-    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 text = isRemoteDriverSession(driver)
-          ? await (driver as Client).getElementText(args.elementUUID)
-          : await (driver as any).getText(args.elementUUID);
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Successfully got text ${text} from element ${args.elementUUID}`,
-            },
-          ],
-        };
-      } catch (err: any) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Failed to get text from element ${args.elementUUID}. err: ${err.toString()}`,
-            },
-          ],
-        };
-      }
-    },
-  });
-}

package/src/tools/interactions/long-press.ts

@@ -1,120 +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 longPress(server: FastMCP): void {
-  const longPressSchema = z.object({
-    elementUUID: elementUUIDScheme,
-    duration: z
-      .number()
-      .int()
-      .min(500)
-      .max(10000)
-      .default(2000)
-      .optional()
-      .describe(
-        'Duration of the long press in milliseconds. Default is 2000ms.'
-      ),
-  });
-
-  server.addTool({
-    name: 'appium_long_press',
-    description: 'Perform a long press (press and hold) gesture on an element',
-    parameters: longPressSchema,
-    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 || 2000;
-
-        if (platform === 'Android') {
-          const rect = await (driver as any).getElementRect(args.elementUUID);
-          const x = Math.floor(rect.x + rect.width / 2);
-          const y = Math.floor(rect.y + rect.height / 2);
-
-          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 },
-                { type: 'pointerUp', button: 0 },
-              ],
-            },
-          ]);
-        } else if (platform === 'iOS') {
-          try {
-            const _ok = isRemoteDriverSession(driver)
-              ? await (driver as Client).executeScript('mobile: touchAndHold', [
-                  {
-                    elementId: args.elementUUID,
-                    duration: duration / 1000,
-                  },
-                ])
-              : await (driver as any).execute('mobile: touchAndHold', {
-                  elementId: args.elementUUID,
-                  duration: duration / 1000,
-                });
-          } catch (touchAndHoldError) {
-            const rect = await (driver as any).getElementRect(args.elementUUID);
-            const x = Math.floor(rect.x + rect.width / 2);
-            const y = Math.floor(rect.y + rect.height / 2);
-
-            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 },
-                  { type: 'pointerUp', button: 0 },
-                ],
-              },
-            ]);
-          }
-        } else {
-          throw new Error(
-            `Unsupported platform: ${platform}. Only Android and iOS are supported.`
-          );
-        }
-
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Successfully performed long press on element ${args.elementUUID}`,
-            },
-          ],
-        };
-      } catch (err: any) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Failed to perform long press on element ${args.elementUUID}. err: ${err.toString()}`,
-            },
-          ],
-        };
-      }
-    },
-  });
-}

package/src/tools/interactions/screenshot.ts

@@ -1,119 +0,0 @@
-import { FastMCP } from 'fastmcp';
-import { getDriver, isRemoteDriverSession } from '../../session-store.js';
-import { writeFile, mkdir } from 'fs/promises';
-import { join, isAbsolute } from 'path';
-import * as os from 'node:os';
-import {
-  createUIResource,
-  createScreenshotViewerUI,
-  addUIResourceToResponse,
-} from '../../ui/mcp-ui-utils.js';
-import type { Client } from 'webdriver';
-import type { XCUITestDriver } from 'appium-xcuitest-driver';
-import type { AndroidUiautomator2Driver } from 'appium-uiautomator2-driver';
-
-/**
- * Resolves the screenshot directory path.
- * - If SCREENSHOTS_DIR is not set, returns process.cwd()
- * - If SCREENSHOTS_DIR is absolute, returns it as-is
- * - If SCREENSHOTS_DIR is relative, joins it with process.cwd()
- */
-export function resolveScreenshotDir(): string {
-  const screenshotDir = process.env.SCREENSHOTS_DIR;
-
-  if (!screenshotDir) {
-    return os.tmpdir();
-  }
-
-  if (isAbsolute(screenshotDir)) {
-    return screenshotDir;
-  }
-
-  return join(process.cwd(), screenshotDir);
-}
-
-export interface ScreenshotDeps {
-  getDriver: () => Client | AndroidUiautomator2Driver | XCUITestDriver | null;
-  writeFile: typeof writeFile;
-  mkdir: typeof mkdir;
-  resolveScreenshotDir: typeof resolveScreenshotDir;
-  dateNow: () => number;
-}
-
-const defaultDeps: ScreenshotDeps = {
-  getDriver,
-  writeFile,
-  mkdir,
-  resolveScreenshotDir,
-  dateNow: () => Date.now(),
-};
-
-export async function executeScreenshot(
-  deps: ScreenshotDeps = defaultDeps
-): Promise<any> {
-  const driver = deps.getDriver();
-  if (!driver) {
-    throw new Error('No driver found');
-  }
-
-  try {
-    const screenshotBase64 = isRemoteDriverSession(driver)
-      ? await (driver as Client).takeScreenshot()
-      : await (driver as any).getScreenshot();
-
-    // Convert base64 to buffer
-    const screenshotBuffer = Buffer.from(screenshotBase64, 'base64');
-
-    // Generate filename with timestamp
-    const timestamp = deps.dateNow();
-    const filename = `screenshot_${timestamp}.png`;
-    const screenshotDir = deps.resolveScreenshotDir();
-
-    // Create a directory if it doesn't exist
-    await deps.mkdir(screenshotDir, { recursive: true });
-
-    const filepath = join(screenshotDir, filename);
-
-    // Save screenshot to disk
-    await deps.writeFile(filepath, screenshotBuffer);
-
-    const textResponse = {
-      content: [
-        {
-          type: 'text',
-          text: `Screenshot saved successfully to: ${filepath}`,
-        },
-      ],
-    };
-
-    // Add interactive screenshot viewer UI
-    const uiResource = createUIResource(
-      `ui://appium-mcp/screenshot-viewer/${Date.now()}`,
-      createScreenshotViewerUI(screenshotBase64, filepath)
-    );
-
-    return addUIResourceToResponse(textResponse, uiResource);
-  } catch (err: any) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Failed to take screenshot. err: ${err.toString()}`,
-        },
-      ],
-    };
-  }
-}
-
-export default function screenshot(server: FastMCP): void {
-  server.addTool({
-    name: 'appium_screenshot',
-    description:
-      'Take a screenshot of the current screen and return as PNG image',
-    annotations: {
-      readOnlyHint: false,
-      openWorldHint: false,
-    },
-    execute: async (): Promise<any> => executeScreenshot(),
-  });
-}

package/src/tools/interactions/set-value.ts

@@ -1,54 +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 setValue(server: FastMCP): void {
-  const setValueSchema = z.object({
-    elementUUID: elementUUIDScheme,
-    text: z.string().describe('The text to enter'),
-  });
-
-  server.addTool({
-    name: 'appium_set_value',
-    description: 'Enter text into an element',
-    parameters: setValueSchema,
-    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).elementSendKeys(
-              args.elementUUID,
-              args.text
-            )
-          : await (driver as any).setValue(args.text, args.elementUUID);
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Successfully set value ${args.text} into element ${args.elementUUID}`,
-            },
-          ],
-        };
-      } catch (err: any) {
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Failed to set value ${args.text} into element ${args.elementUUID}. err: ${err.toString()}`,
-            },
-          ],
-        };
-      }
-    },
-  });
-}

package/src/tools/ios/boot-simulator.ts

@@ -1,88 +0,0 @@
-/**
- * Tool to boot iOS simulator
- */
-import { z } from 'zod';
-import { Simctl } from 'node-simctl';
-import { IOSManager } from '../../devicemanager/ios-manager.js';
-import log from '../../logger.js';
-
-export default function bootSimulator(server: any): void {
-  server.addTool({
-    name: 'boot_simulator',
-    description: `Boot an iOS simulator and wait for it to be ready.
-      This speeds up subsequent session creation by ensuring the simulator is already running.`,
-    parameters: z.object({
-      udid: z.string().describe(
-        `The UDID of the iOS simulator to boot.
-          Use select_platform and select_device tools first to get the UDID.`
-      ),
-    }),
-    annotations: {
-      readOnlyHint: false,
-      openWorldHint: false,
-    },
-    execute: async (args: any, context: any): Promise<any> => {
-      try {
-        const { udid } = args;
-
-        // Verify it's a macOS system
-        if (process.platform !== 'darwin') {
-          throw new Error('iOS simulators can only be booted on macOS systems');
-        }
-
-        const iosManager = IOSManager.getInstance();
-        const simulators = await iosManager.listSimulators();
-
-        // Find the simulator with the given UDID
-        const simulator = simulators.find((sim) => sim.udid === udid);
-
-        if (!simulator) {
-          throw new Error(
-            `Simulator with UDID "${udid}" not found. Please use select_platform and select_device tools to get a valid UDID.`
-          );
-        }
-
-        // Check current state
-        if (simulator.state === 'Booted') {
-          return {
-            content: [
-              {
-                type: 'text',
-                text: `✅ Simulator "${simulator.name}" is already booted and ready!\n\nUDID: ${udid}\niOS Version: ${simulator.platform || 'Unknown'}\nState: ${simulator.state}`,
-              },
-            ],
-          };
-        }
-
-        const simctl = new Simctl();
-        simctl.udid = udid;
-
-        // Boot the device and measure time
-        const bootStartTime = Date.now();
-        await simctl.bootDevice();
-        await simctl.startBootMonitor({ timeout: 120000 });
-        const bootDuration = ((Date.now() - bootStartTime) / 1000).toFixed(1);
-
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `${JSON.stringify(
-                {
-                  instruction:
-                    'You can now use the install_wda tool to install WDA on the simulator.',
-                  status: 'Simulator booted successfully!',
-                },
-                null,
-                2
-              )}`,
-            },
-          ],
-        };
-      } catch (error: any) {
-        log.error('Error booting simulator:', error);
-        throw new Error(`Failed to boot simulator: ${error.message}`);
-      }
-    },
-  });
-}

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

@@ -1,277 +0,0 @@
-/**
- * Tool to install and launch WebDriverAgent (WDA) on a booted iOS simulator
- */
-import { z } from 'zod';
-import { exec } from 'child_process';
-import { promisify } from 'util';
-import path from 'path';
-import { access, readdir, stat } from 'fs/promises';
-import { constants } from 'fs';
-import os from 'os';
-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> {
-  // Scan the cache directory to find the latest version
-  const wdaCacheDir = cachePath('wda');
-
-  try {
-    await access(wdaCacheDir, constants.F_OK);
-  } catch {
-    throw new Error('No WDA cache found. Please run setup_wda first.');
-  }
-
-  const entries = await readdir(wdaCacheDir);
-  const versions = await Promise.all(
-    entries.map(async (dir) => {
-      const dirPath = path.join(wdaCacheDir, dir);
-      const stats = await stat(dirPath);
-      return stats.isDirectory() ? dir : null;
-    })
-  );
-
-  const filteredVersions = versions
-    .filter((v): v is string => v !== null)
-    .sort((a, b) =>
-      // Simple version comparison - you might want to use semver for more complex versions
-      b.localeCompare(a, undefined, { numeric: true })
-    );
-
-  if (filteredVersions.length === 0) {
-    throw new Error(
-      'No WDA versions found in cache. Please run setup_wda first.'
-    );
-  }
-
-  return filteredVersions[0];
-}
-
-async function getBootedSimulators(): Promise<string[]> {
-  try {
-    const { stdout } = await execAsync('xcrun simctl list devices --json');
-    const data = JSON.parse(stdout);
-    const bootedSimulators: string[] = [];
-
-    for (const [runtime, devices] of Object.entries(data.devices)) {
-      if (Array.isArray(devices)) {
-        for (const device of devices as any[]) {
-          if (device.state === 'Booted') {
-            bootedSimulators.push(device.udid);
-          }
-        }
-      }
-    }
-
-    return bootedSimulators;
-  } catch (error) {
-    throw new Error(`Failed to list simulators: ${error}`);
-  }
-}
-
-async function installAppOnSimulator(
-  appPath: string,
-  simulatorUdid: string
-): Promise<void> {
-  try {
-    await execAsync(`xcrun simctl install "${simulatorUdid}" "${appPath}"`);
-  } catch (error) {
-    throw new Error(
-      `Failed to install app on simulator ${simulatorUdid}: ${error}`
-    );
-  }
-}
-
-async function launchAppOnSimulator(
-  bundleId: string,
-  simulatorUdid: string
-): Promise<void> {
-  try {
-    await execAsync(`xcrun simctl launch "${simulatorUdid}" "${bundleId}"`);
-  } catch (error) {
-    throw new Error(
-      `Failed to launch app on simulator ${simulatorUdid}: ${error}`
-    );
-  }
-}
-
-async function getAppBundleId(appPath: string): Promise<string> {
-  try {
-    const { stdout } = await execAsync(
-      `/usr/libexec/PlistBuddy -c "Print CFBundleIdentifier" "${path.join(appPath, 'Info.plist')}"`
-    );
-    return stdout.trim();
-  } catch (error) {
-    throw new Error(`Failed to get bundle ID for app at ${appPath}: ${error}`);
-  }
-}
-
-async function isWDAInstalled(simulatorUdid: string): Promise<boolean> {
-  try {
-    const { stdout } = await execAsync(
-      `xcrun simctl listapps "${simulatorUdid}" --json`
-    );
-    const data = JSON.parse(stdout);
-
-    // Check if any app has a bundle ID that looks like WDA
-    for (const [bundleId, appInfo] of Object.entries(data)) {
-      if (
-        bundleId.includes('WebDriverAgentRunner') ||
-        (appInfo as any)?.CFBundleName?.includes('WebDriverAgent')
-      ) {
-        return true;
-      }
-    }
-    return false;
-  } catch (error) {
-    // If we can't check, assume it's not installed
-    return false;
-  }
-}
-
-async function isWDARunning(simulatorUdid: string): Promise<boolean> {
-  try {
-    const { stdout } = await execAsync(
-      `xcrun simctl listapps "${simulatorUdid}" --json`
-    );
-    const data = JSON.parse(stdout);
-
-    // Check if WDA is running
-    for (const [bundleId, appInfo] of Object.entries(data)) {
-      if (
-        bundleId.includes('WebDriverAgentRunner') &&
-        (appInfo as any)?.ApplicationType === 'User'
-      ) {
-        return true;
-      }
-    }
-    return false;
-  } catch (error) {
-    return false;
-  }
-}
-
-export default function installWDA(server: any): void {
-  server.addTool({
-    name: 'install_wda',
-    description: `Install and launch the WebDriverAgent (WDA) app on a booted iOS simulator using the app path from setup_wda.
-      This tool requires WDA to be already set up using setup_wda and at least one simulator to be booted.
-      `,
-    parameters: z.object({
-      simulatorUdid: z
-        .string()
-        .optional()
-        .describe(
-          'The UDID of the simulator to install WDA on. If not provided, will use the first booted simulator found.'
-        ),
-      appPath: z
-        .string()
-        .optional()
-        .describe(
-          `The path to the WDA app bundle (.app file) that be generated by setup_wda tool.
-          If not provided, will try to find the latest cached WDA app.`
-        ),
-    }),
-    annotations: {
-      readOnlyHint: false,
-      openWorldHint: false,
-    },
-    execute: async (args: any, context: any): Promise<any> => {
-      try {
-        const { simulatorUdid, appPath: providedAppPath } = args;
-
-        // Verify it's a macOS system
-        if (process.platform !== 'darwin') {
-          throw new Error(
-            'WDA installation is only supported on macOS systems'
-          );
-        }
-
-        // Determine WDA app path
-        let appPath: string;
-        if (providedAppPath) {
-          appPath = providedAppPath;
-        } else {
-          // Try to find the latest cached WDA app
-          const version = await getLatestWDAVersion();
-          const extractDir = cachePath(`wda/${version}/extracted`);
-          appPath = path.join(extractDir, 'WebDriverAgentRunner-Runner.app');
-        }
-
-        // Verify WDA app exists
-        try {
-          await access(appPath, constants.F_OK);
-        } catch {
-          throw new Error(
-            `WDA app not found at ${appPath}. Please run setup_wda first to download and cache WDA, or provide a valid appPath.`
-          );
-        }
-
-        // Get booted simulators
-        const bootedSimulators = await getBootedSimulators();
-        if (bootedSimulators.length === 0) {
-          throw new Error(
-            'No booted simulators found. Please boot a simulator first using boot_simulator tool.'
-          );
-        }
-
-        // Determine target simulator
-        const targetSimulator = simulatorUdid || bootedSimulators[0];
-
-        if (!bootedSimulators.includes(targetSimulator)) {
-          throw new Error(
-            `Simulator ${targetSimulator} is not booted. Available booted simulators: ${bootedSimulators.join(', ')}`
-          );
-        }
-
-        log.info(
-          `Installing WDA from ${appPath} on simulator ${targetSimulator}...`
-        );
-
-        // Check if WDA is already installed and running
-        const isInstalled = await isWDAInstalled(targetSimulator);
-        const isRunning = await isWDARunning(targetSimulator);
-
-        if (isRunning) {
-          return {
-            content: [
-              {
-                type: 'text',
-                text: `✅ WebDriverAgent is already running on simulator ${targetSimulator}!\n\nSimulator: ${targetSimulator}\nApp Path: ${appPath}\nStatus: Running\n\n🚀 WDA is ready to accept connections from Appium.`,
-              },
-            ],
-          };
-        }
-
-        // Install the app (only if not already installed)
-        if (!isInstalled) {
-          await installAppOnSimulator(appPath, targetSimulator);
-          log.info('WDA app installed successfully');
-        } else {
-          log.info('WDA app already installed, skipping installation');
-        }
-
-        // Get bundle ID and launch the app
-        const bundleId = await getAppBundleId(appPath);
-        log.info(`Launching WDA with bundle ID: ${bundleId}`);
-        await launchAppOnSimulator(bundleId, targetSimulator);
-
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `✅ WebDriverAgent installed and launched successfully!\n\nSimulator: ${targetSimulator}\nBundle ID: ${bundleId}\nApp Path: ${appPath}\nInstallation: ${isInstalled ? 'Skipped (already installed)' : 'Completed'}\n\n🚀 WDA is now running on the simulator and ready to accept connections from Appium.\n\nNote: The WDA app should be visible on the simulator screen. You can now create an Appium session.`,
-            },
-          ],
-        };
-      } catch (error: any) {
-        log.error('Error installing WDA:', error);
-        throw new Error(`Failed to install WebDriverAgent: ${error.message}`);
-      }
-    },
-  });
-}