appium-mcp 1.8.15 → 1.8.16

package/src/tools/interactions/get-text.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 { getElementText } from '../../command.js';
+
+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 = getElementText(driver, 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

@@ -0,0 +1,111 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import { getDriver, getPlatformName, PLATFORM } from '../../session-store.js';
+import { elementUUIDScheme } from '../../schema.js';
+import { execute, getElementRect, performActions } from '../../command.js';
+
+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 === PLATFORM.android) {
+          const rect = await getElementRect(driver, args.elementUUID);
+          const x = Math.floor(rect.x + rect.width / 2);
+          const y = Math.floor(rect.y + rect.height / 2);
+
+          const operation = [
+            {
+              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 },
+              ],
+            },
+          ];
+          await performActions(driver, operation);
+        } else if (platform === PLATFORM.ios) {
+          try {
+            await execute(driver, 'mobile: touchAndHold', {
+              elementId: args.elementUUID,
+              duration: duration / 1000,
+            });
+          } catch (touchAndHoldError) {
+            const rect = await getElementRect(driver, args.elementUUID);
+            const x = Math.floor(rect.x + rect.width / 2);
+            const y = Math.floor(rect.y + rect.height / 2);
+
+            const operation = [
+              {
+                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 },
+                ],
+              },
+            ];
+            await performActions(driver, operation);
+          }
+        } 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

@@ -0,0 +1,116 @@
+import { FastMCP } from 'fastmcp';
+import { getDriver } from '../../session-store.js';
+import type { NullableDriverInstance } 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 { getScreenshot } from '../../command.js';
+
+/**
+ * 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: () => NullableDriverInstance;
+  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 = await getScreenshot(driver);
+
+    // 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

@@ -0,0 +1,49 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import { getDriver } from '../../session-store.js';
+import { elementUUIDScheme } from '../../schema.js';
+import { setValue as _setValue } from '../../command.js';
+
+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 {
+        await _setValue(driver, args.elementUUID, args.text);
+        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

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

@@ -0,0 +1,277 @@
+/**
+ * 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}`);
+      }
+    },
+  });
+}