appium-mcp 0.0.1 → 1.1.4

package/src/tools/generate-tests.ts

@@ -0,0 +1,50 @@
+import { FastMCP } from 'fastmcp/dist/FastMCP.js';
+import { z } from 'zod';
+
+export default function generateTest(server: FastMCP): void {
+  const generateTestSchema = z.object({
+    steps: z.array(z.string()).describe('The steps of the test'),
+  });
+
+  const instructions = (params: { steps: string[] }) =>
+    [
+      `## Instructions`,
+      `- You are an Appium test generator.`,
+      `- You are given a scenario and you need to generate a appium test for it.`,
+      `- Request user to select the platform first using select_platform tool and create a session`,
+      `- Use generate_locators tool to fetch all interactable elements from the current screen and use it to generate the tests`,
+      `- Element can only be clicked only if it is clickable.`,
+      `- Text can entered in the element only if it is focusable`,
+      `- If any interaction on element is failed, retry again with a differnt possible locator in the hierrarchy`,
+      `- Interact with the app using the tools provided and generate the test`,
+      '- DO NOT generate test code based on the scenario alone. DO run steps one by one using the tools provided instead.',
+      '- Only after all steps are completed, emit a Appium test based on message history',
+      '- Save generated test file in the tests directory',
+      `- Use generate://code-with-locators resource as reference for code generation`,
+      `- Always call find_element_tool to retrieve the element UUID before interacting with the element`,
+      `Steps:`,
+      ...params.steps.map((step, index) => `- ${index + 1}. ${step}`),
+    ].join('\n');
+
+  server.addTool({
+    name: 'appium_generate_tests',
+    description: 'Generate tests for a given mobile app',
+    parameters: generateTestSchema,
+    annotations: {
+      readOnlyHint: false,
+      openWorldHint: false,
+    },
+    execute: async (args: any, context: any): Promise<any> => {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: instructions({
+              steps: args.steps,
+            }),
+          },
+        ],
+      };
+    },
+  });
+}

package/src/tools/index.ts

@@ -0,0 +1,133 @@
+/**
+ * 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/dist/FastMCP.js';
+import log from '../locators/logger.js';
+import answerAppium from './answer-appium.js';
+import createSession from './create-session.js';
+import deleteSession from './delete-session.js';
+import generateLocators from './locators.js';
+import selectPlatform from './select-platform.js';
+import selectDevice from './select-device.js';
+import bootSimulator from './boot-simulator.js';
+import setupWDA from './setup-wda.js';
+import installWDA from './install-wda.js';
+import generateTest from './generate-tests.js';
+import scroll from './scroll.js';
+import scrollToElement from './scroll-to-element.js';
+import findElement from './interactions/find.js';
+import clickElement from './interactions/click.js';
+import doubleTap from './interactions/double-tap.js';
+import setValue from './interactions/set-value.js';
+import getText from './interactions/get-text.js';
+import screenshot from './interactions/screenshot.js';
+import activateApp from './interactions/activate-app.js';
+import installApp from './interactions/install-app.js';
+import uninstallApp from './interactions/uninstall-app.js';
+import terminateApp from './interactions/terminate-app.js';
+import listApps from './interactions/list-apps.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;
+        }
+      },
+    });
+  };
+
+  selectPlatform(server);
+  selectDevice(server);
+  bootSimulator(server);
+  setupWDA(server);
+  installWDA(server);
+  createSession(server);
+  deleteSession(server);
+  generateLocators(server);
+  answerAppium(server);
+  scroll(server);
+  scrollToElement(server);
+
+  activateApp(server);
+  installApp(server);
+  uninstallApp(server);
+  terminateApp(server);
+  listApps(server);
+  findElement(server);
+  clickElement(server);
+  doubleTap(server);
+  setValue(server);
+  getText(server);
+  screenshot(server);
+  generateTest(server);
+  log.info('All tools registered');
+}

package/src/tools/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 fs from 'fs'; // Keep for createWriteStream if used
+import os from 'os';
+
+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
+      return 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(', ')}`
+          );
+        }
+
+        console.log(
+          `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);
+          console.log('WDA app installed successfully');
+        } else {
+          console.log('WDA app already installed, skipping installation');
+        }
+
+        // Get bundle ID and launch the app
+        const bundleId = await getAppBundleId(appPath);
+        console.log(`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) {
+        console.error('Error installing WDA:', error);
+        throw new Error(`Failed to install WebDriverAgent: ${error.message}`);
+      }
+    },
+  });
+}

package/src/tools/interactions/activate-app.ts

@@ -0,0 +1,46 @@
+import { FastMCP } from 'fastmcp/dist/FastMCP.js';
+import { getDriver } from '../session-store.js';
+import { z } from 'zod';
+
+export default function activateApp(server: FastMCP): void {
+  const activateAppSchema = z.object({
+    id: z.string().describe('The app id'),
+  });
+
+  server.addTool({
+    name: 'appium_activate_app',
+    description: 'Activate app by id',
+    parameters: activateAppSchema,
+    annotations: {
+      readOnlyHint: false,
+      openWorldHint: false,
+    },
+    execute: async (args: { id: string }, context: any): Promise<any> => {
+      const driver = getDriver();
+      if (!driver) {
+        throw new Error('No driver found');
+      }
+
+      try {
+        await driver.activateApp(args.id);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `App ${args.id} activated correctly.`,
+            },
+          ],
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error activating the app ${args.id}: ${err.toString()}`,
+            },
+          ],
+        };
+      }
+    },
+  });
+}

package/src/tools/interactions/click.ts

@@ -0,0 +1,47 @@
+import { FastMCP } from 'fastmcp/dist/FastMCP.js';
+import { z } from 'zod';
+import { getDriver } from '../session-store.js';
+import { elementUUIDScheme } from '../../schema.js';
+
+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 {
+        await driver.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

@@ -0,0 +1,87 @@
+import { FastMCP } from 'fastmcp/dist/FastMCP.js';
+import { z } from 'zod';
+import { getDriver, getPlatformName } from '../session-store.js';
+import { elementUUIDScheme } from '../../schema.js';
+
+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.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.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
+          await driver.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/find.ts

@@ -0,0 +1,58 @@
+import { FastMCP } from 'fastmcp/dist/FastMCP.js';
+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.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()}`,
+            },
+          ],
+        };
+      }
+    },
+  });
+}