appium-mcp 0.0.1 → 1.1.4

package/src/tools/scroll.ts

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+import { getDriver, getPlatformName } from './session-store.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 { width, height } = await driver.getWindowSize();
+        console.log('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);
+
+        console.log('Going to scroll from:', { startX, startY });
+        console.log('Going to scroll to:', { startX, endY });
+
+        if (getPlatformName(driver) === 'Android') {
+          await driver.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 },
+              ],
+            },
+          ]);
+          console.log('Scroll action completed successfully.');
+        } else if (getPlatformName(driver) === 'iOS') {
+          await driver.execute('mobile: scroll', {
+            direction: args.direction,
+            startX: startX,
+            startY: startY,
+            endX: startX,
+            endY: 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()}`,
+            },
+          ],
+        };
+      }
+    },
+  });
+}

package/src/tools/select-device.ts

@@ -0,0 +1,298 @@
+/**
+ * Tool to select a specific device when multiple devices are available
+ */
+import { ADBManager } from '../devicemanager/adb-manager.js';
+import { IOSManager } from '../devicemanager/ios-manager.js';
+import { z } from 'zod';
+import log from '../locators/logger.js';
+
+// Store selected device globally
+let selectedDeviceUdid: string | null = null;
+let selectedDeviceType: 'simulator' | 'real' | null = null;
+let selectedDeviceInfo: any = null;
+
+export function getSelectedDevice(): string | null {
+  return selectedDeviceUdid;
+}
+
+export function getSelectedDeviceType(): 'simulator' | 'real' | null {
+  return selectedDeviceType;
+}
+
+export function getSelectedDeviceInfo(): any {
+  return selectedDeviceInfo;
+}
+
+export function clearSelectedDevice(): void {
+  selectedDeviceUdid = null;
+  selectedDeviceType = null;
+  selectedDeviceInfo = null;
+}
+
+/**
+ * Get and validate Android devices
+ */
+async function getAndroidDevices(): Promise<any[]> {
+  const adb = await ADBManager.getInstance().initialize();
+  const devices = await adb.getConnectedDevices();
+
+  if (devices.length === 0) {
+    throw new Error('No Android devices/emulators found');
+  }
+
+  return devices;
+}
+
+/**
+ * Validate and select Android device by UDID
+ */
+function selectAndroidDevice(deviceUdid: string, devices: any[]): void {
+  const selectedDevice = devices.find(d => d.udid === deviceUdid);
+  if (!selectedDevice) {
+    throw new Error(
+      `Device with UDID "${deviceUdid}" not found. Available devices: ${devices.map(d => d.udid).join(', ')}`
+    );
+  }
+
+  selectedDeviceUdid = deviceUdid;
+  log.info(`Device selected: ${deviceUdid}`);
+}
+
+/**
+ * Format device selection response for Android
+ */
+function formatAndroidSelectionResponse(deviceUdid: string): any {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(
+          {
+            message: `✅ Device selected: ${deviceUdid}`,
+            instructions:
+              '🚀 You can now create a session using the create_session tool with:',
+            platform: 'android',
+            capabilities: {
+              'appium:udid': deviceUdid,
+            },
+          },
+          null,
+          2
+        ),
+      },
+    ],
+  };
+}
+
+/**
+ * Format device list response for Android
+ */
+function formatAndroidListResponse(devices: any[]): any {
+  const deviceList = devices
+    .map((device, index) => `  ${index + 1}. ${device.udid}`)
+    .join('\n');
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `📱 Available Android devices/emulators (${devices.length}):\n${deviceList}\n\n⚠️ IMPORTANT: Please ask the user which device they want to use.\n\nOnce the user selects a device, call this tool again with the deviceUdid parameter set to their chosen device UDID.`,
+      },
+    ],
+  };
+}
+
+/**
+ * Validate iOS device type
+ */
+function validateIOSDeviceType(
+  iosDeviceType: 'simulator' | 'real' | undefined
+): void {
+  if (!iosDeviceType) {
+    throw new Error(
+      "For iOS platform, iosDeviceType ('simulator' or 'real') is required"
+    );
+  }
+}
+
+/**
+ * Get and validate iOS devices by type
+ */
+async function getIOSDevices(
+  iosDeviceType: 'simulator' | 'real'
+): Promise<any[]> {
+  const iosManager = IOSManager.getInstance();
+  const devices = await iosManager.getDevicesByType(iosDeviceType);
+
+  if (devices.length === 0) {
+    throw new Error(
+      `No iOS ${iosDeviceType === 'simulator' ? 'simulators' : 'devices'} found`
+    );
+  }
+
+  return devices;
+}
+
+/**
+ * Validate and select iOS device by UDID
+ */
+function selectIOSDevice(
+  deviceUdid: string,
+  devices: any[],
+  iosDeviceType: 'simulator' | 'real'
+): any {
+  const selectedDevice = devices.find(d => d.udid === deviceUdid);
+  if (!selectedDevice) {
+    const deviceList = devices.map(d => `${d.name} (${d.udid})`).join(', ');
+    throw new Error(
+      `Device with UDID "${deviceUdid}" not found. Available devices: ${deviceList}`
+    );
+  }
+
+  selectedDeviceUdid = deviceUdid;
+  selectedDeviceType = iosDeviceType;
+  selectedDeviceInfo = selectedDevice;
+  log.info(
+    `iOS ${iosDeviceType} selected: ${selectedDevice.name} (${deviceUdid})`
+  );
+
+  return selectedDevice;
+}
+
+/**
+ * Format device selection response for iOS
+ */
+function formatIOSSelectionResponse(
+  deviceName: string,
+  deviceUdid: string
+): any {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(
+          {
+            message: `✅ Device selected: ${deviceName} (${deviceUdid})`,
+            instructions:
+              '🚀 You can now call the setup_wda tool to setup WDA on the simulator.',
+            platform: 'ios',
+            capabilities: {
+              'appium:udid': deviceUdid,
+            },
+          },
+          null,
+          2
+        ),
+      },
+    ],
+  };
+}
+
+/**
+ * Format device list response for iOS
+ */
+function formatIOSListResponse(
+  devices: any[],
+  iosDeviceType: 'simulator' | 'real'
+): any {
+  const deviceList = devices
+    .map(
+      (device, index) =>
+        `  ${index + 1}. ${device.name} (${device.udid})${device.state ? ` - ${device.state}` : ''}`
+    )
+    .join('\n');
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `📱 Available iOS ${iosDeviceType === 'simulator' ? 'simulators' : 'devices'} (${devices.length}):\n${deviceList}\n\n⚠️ IMPORTANT: Please ask the user which device they want to use.\n\nOnce the user selects a device, call this tool again with the deviceUdid parameter set to their chosen device UDID.`,
+      },
+    ],
+  };
+}
+
+/**
+ * Handle Android device selection
+ */
+async function handleAndroidDeviceSelection(deviceUdid?: string): Promise<any> {
+  const devices = await getAndroidDevices();
+
+  if (deviceUdid) {
+    selectAndroidDevice(deviceUdid, devices);
+    return formatAndroidSelectionResponse(deviceUdid);
+  }
+
+  return formatAndroidListResponse(devices);
+}
+
+/**
+ * Handle iOS device selection
+ */
+async function handleIOSDeviceSelection(
+  iosDeviceType: 'simulator' | 'real' | undefined,
+  deviceUdid?: string
+): Promise<any> {
+  validateIOSDeviceType(iosDeviceType);
+
+  const devices = await getIOSDevices(iosDeviceType!);
+
+  if (deviceUdid) {
+    const selectedDevice = selectIOSDevice(deviceUdid, devices, iosDeviceType!);
+    return formatIOSSelectionResponse(selectedDevice.name, deviceUdid);
+  }
+
+  return formatIOSListResponse(devices, iosDeviceType!);
+}
+
+export default function selectDevice(server: any): void {
+  server.addTool({
+    name: 'select_device',
+    description: `REQUIRED when multiple devices are found: Ask the user to select which specific device they want to use from the available devices. 
+      This tool lists all available devices and allows selection by UDID. 
+      You MUST use this tool when select_platform returns multiple devices before calling create_session for android.
+      You MUST use this tool when select_platform returns multiple devices before calling boot_simulator for ios if the user has selected simulator device type.
+      `,
+    parameters: z.object({
+      platform: z
+        .enum(['ios', 'android'])
+        .describe(
+          'The platform to list devices for (must match previously selected platform)'
+        ),
+      iosDeviceType: z
+        .enum(['simulator', 'real'])
+        .optional()
+        .describe(
+          "For iOS only: Specify whether to use 'simulator' or 'real' device. REQUIRED when platform is 'ios'."
+        ),
+      deviceUdid: z
+        .string()
+        .optional()
+        .describe(
+          'The UDID of the device selected by the user. If not provided, this tool will list available devices for the user to choose from.'
+        ),
+    }),
+    annotations: {
+      readOnlyHint: false,
+      openWorldHint: false,
+    },
+    execute: async (args: any, context: any): Promise<any> => {
+      try {
+        const { platform, iosDeviceType, deviceUdid } = args;
+
+        if (platform === 'android') {
+          return await handleAndroidDeviceSelection(deviceUdid);
+        } else if (platform === 'ios') {
+          return await handleIOSDeviceSelection(iosDeviceType, deviceUdid);
+        } else {
+          throw new Error(
+            `Invalid platform: ${platform}. Please choose 'android' or 'ios'.`
+          );
+        }
+      } catch (error: any) {
+        log.error('Error selecting device:', error);
+        throw new Error(`Failed to select device: ${error.message}`);
+      }
+    },
+  });
+}

package/src/tools/select-platform.ts

@@ -0,0 +1,243 @@
+/**
+ * Tool to select mobile platform before creating a session
+ */
+import { ADBManager } from '../devicemanager/adb-manager.js';
+import { IOSManager } from '../devicemanager/ios-manager.js';
+import { z } from 'zod';
+import log from '../locators/logger.js';
+
+/**
+ * Get and validate Android devices
+ */
+async function getAndroidDevices(): Promise<any[]> {
+  const adb = await ADBManager.getInstance().initialize();
+  const devices = await adb.getConnectedDevices();
+
+  if (devices.length === 0) {
+    throw new Error('No Android devices/emulators found');
+  }
+
+  return devices;
+}
+
+/**
+ * Format multiple Android devices response
+ */
+function formatMultipleAndroidDevicesResponse(devices: any[]): any {
+  const deviceList = devices
+    .map((device, index) => `  ${index + 1}. ${device.udid}`)
+    .join('\n');
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `✅ Android platform selected\n\n⚠️ Multiple Android devices/emulators found (${devices.length}):\n${deviceList}\n\n🚨 IMPORTANT: You MUST use the select_device tool next to ask the user which device they want to use.\n\nDO NOT proceed to create_session until the user has selected a specific device using the select_device tool.`,
+      },
+    ],
+  };
+}
+
+/**
+ * Format single Android device response
+ */
+function formatSingleAndroidDeviceResponse(deviceUdid: string): any {
+  const platformInfo = `Android platform selected (Found device: ${deviceUdid})`;
+  const nextSteps =
+    `Found 1 Android device: ${deviceUdid}\n\n` +
+    "You can now create an Android session using the create_session tool with platform='android'. Make sure you have:\n" +
+    '• Android SDK installed\n' +
+    '• Android device connected or emulator running\n' +
+    '• USB debugging enabled (for real devices)';
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `✅ ${platformInfo}\n\n📋 Next Steps:\n${nextSteps}\n\n🚀 Ready to create a session? Use the create_session tool with platform='android'`,
+      },
+    ],
+  };
+}
+
+/**
+ * Validate macOS for iOS testing
+ */
+function validateMacOSForIOS(): void {
+  const iosManager = IOSManager.getInstance();
+  if (!iosManager.isMac()) {
+    throw new Error('iOS testing is only available on macOS');
+  }
+}
+
+/**
+ * Format iOS device type selection prompt
+ */
+function formatIOSDeviceTypePrompt(): any {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `✅ iOS platform selected\n\n📱 Please specify the device type:\n\n⚠️ IMPORTANT: You MUST call select_platform again with the iosDeviceType parameter.\n\nOptions:\n1. 'simulator' - Use iOS Simulator\n2. 'real' - Use real iOS device\n\n🚀 Call select_platform with:\n• platform='ios'\n• iosDeviceType='simulator' OR iosDeviceType='real'`,
+      },
+    ],
+  };
+}
+
+/**
+ * Get and validate iOS devices by type
+ */
+async function getIOSDevices(
+  iosDeviceType: 'simulator' | 'real'
+): Promise<any[]> {
+  const iosManager = IOSManager.getInstance();
+  const devices = await iosManager.getDevicesByType(iosDeviceType);
+
+  if (devices.length === 0) {
+    const deviceTypeText =
+      iosDeviceType === 'simulator' ? 'simulators' : 'real devices';
+    const helpText =
+      iosDeviceType === 'simulator'
+        ? 'Please start an iOS simulator using Xcode or use "xcrun simctl boot <SIMULATOR_UDID>"'
+        : 'Please connect an iOS device via USB and ensure it is trusted';
+    throw new Error(`No iOS ${deviceTypeText} found. ${helpText}`);
+  }
+
+  return devices;
+}
+
+/**
+ * Format multiple iOS devices response
+ */
+function formatMultipleIOSDevicesResponse(
+  devices: any[],
+  iosDeviceType: 'simulator' | 'real'
+): any {
+  const deviceList = devices
+    .map(
+      (device, index) =>
+        `  ${index + 1}. ${device.name} (${device.udid})${device.state ? ` - ${device.state}` : ''}`
+    )
+    .join('\n');
+  const deviceTypeText =
+    iosDeviceType === 'simulator' ? 'simulators' : 'devices';
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `✅ iOS platform selected (${iosDeviceType})\n\n⚠️ Multiple iOS ${deviceTypeText} found (${devices.length}):\n${deviceList}\n\n🚨 IMPORTANT: You MUST use the select_device tool next to ask the user which device they want to use.\n\nDO NOT proceed to create_session until the user has selected a specific device using the select_device tool.`,
+      },
+    ],
+  };
+}
+
+/**
+ * Format single iOS device response
+ */
+function formatSingleIOSDeviceResponse(
+  device: any,
+  iosDeviceType: 'simulator' | 'real'
+): any {
+  const platformInfo = `iOS ${iosDeviceType} selected (Found device: ${device.name} - ${device.udid})`;
+  const nextSteps =
+    `Found 1 iOS ${iosDeviceType}: ${device.name} (${device.udid})\n\n` +
+    "You can now create an iOS session using the create_session tool with platform='ios'. Make sure you have:\n" +
+    '• Xcode installed (macOS only)\n' +
+    (iosDeviceType === 'simulator'
+      ? '• iOS simulator running\n'
+      : '• iOS device connected via USB\n• Developer certificates configured\n• Device trusted on your Mac\n');
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: `✅ ${platformInfo}\n\n📋 Next Steps:\n${nextSteps}\n\n🚀 Ready to create a session? Use the create_session tool with platform='ios'`,
+      },
+    ],
+  };
+}
+
+/**
+ * Handle Android platform selection
+ */
+async function handleAndroidPlatformSelection(): Promise<any> {
+  const devices = await getAndroidDevices();
+
+  if (devices.length > 1) {
+    return formatMultipleAndroidDevicesResponse(devices);
+  }
+
+  return formatSingleAndroidDeviceResponse(devices[0].udid);
+}
+
+/**
+ * Handle iOS platform selection
+ */
+async function handleIOSPlatformSelection(
+  iosDeviceType?: 'simulator' | 'real'
+): Promise<any> {
+  validateMacOSForIOS();
+
+  if (!iosDeviceType) {
+    return formatIOSDeviceTypePrompt();
+  }
+
+  const devices = await getIOSDevices(iosDeviceType);
+
+  if (devices.length > 1) {
+    return formatMultipleIOSDevicesResponse(devices, iosDeviceType);
+  }
+
+  return formatSingleIOSDeviceResponse(devices[0], iosDeviceType);
+}
+
+export default function selectPlatform(server: any): void {
+  server.addTool({
+    name: 'select_platform',
+    description: `REQUIRED: First ASK THE USER which mobile platform they want to use (Android or iOS) before creating a session.
+      DO NOT assume or default to any platform.
+      You MUST explicitly prompt the user to choose between Android or iOS.
+      This is mandatory before proceeding to use the create_session tool.
+      `,
+    parameters: z.object({
+      platform: z
+        .enum(['ios', 'android'])
+        .describe(
+          "REQUIRED: The platform chosen by the user - 'android' for Android devices/emulators or 'ios' for iOS devices/simulators. This must be based on the user's explicit choice, NOT a default assumption."
+        ),
+      iosDeviceType: z
+        .enum(['simulator', 'real'])
+        .optional()
+        .describe(
+          "For iOS only: Specify whether to use 'simulator' or 'real' device. REQUIRED when platform is 'ios'."
+        ),
+    }),
+    annotations: {
+      readOnlyHint: false,
+      openWorldHint: false,
+    },
+    execute: async (args: any, context: any): Promise<any> => {
+      try {
+        const { platform, iosDeviceType } = args;
+
+        if (platform === 'android') {
+          log.info('Platform selected: ANDROID');
+          return await handleAndroidPlatformSelection();
+        } else if (platform === 'ios') {
+          log.info('Platform selected: IOS');
+          return await handleIOSPlatformSelection(iosDeviceType);
+        } else {
+          throw new Error(
+            `Invalid platform: ${platform}. Please choose 'android' or 'ios'.`
+          );
+        }
+      } catch (error: any) {
+        log.error(
+          `[select_platform] ${error?.stack || error?.message || String(error)}`
+        );
+        throw new Error(`Failed to select platform: ${error.message}`);
+      }
+    },
+  });
+}

package/src/tools/session-store.ts

@@ -0,0 +1,72 @@
+import { AndroidUiautomator2Driver } from 'appium-uiautomator2-driver';
+import { XCUITestDriver } from 'appium-xcuitest-driver';
+
+let driver: any = null;
+let sessionId: string | null = null;
+let isDeletingSession = false; // Lock to prevent concurrent deletion
+
+export function setSession(d: any, id: string | null) {
+  driver = d;
+  sessionId = id;
+  // Reset deletion flag when setting a new session
+  if (d && id) {
+    isDeletingSession = false;
+  }
+}
+
+export function getDriver() {
+  return driver;
+}
+
+export function getSessionId() {
+  return sessionId;
+}
+
+export function isDeletingSessionInProgress() {
+  return isDeletingSession;
+}
+
+export function hasActiveSession(): boolean {
+  return driver !== null && sessionId !== null && !isDeletingSession;
+}
+
+export async function safeDeleteSession(): Promise<boolean> {
+  // Check if there's no session to delete
+  if (!driver || !sessionId) {
+    console.log('No active session to delete.');
+    return false;
+  }
+
+  // Check if deletion is already in progress
+  if (isDeletingSession) {
+    console.log('Session deletion already in progress, skipping...');
+    return false;
+  }
+
+  // Set lock
+  isDeletingSession = true;
+
+  try {
+    console.log('Deleting current session');
+    await driver.deleteSession();
+
+    // Clear the session from store
+    driver = null;
+    sessionId = null;
+
+    console.log('Session deleted successfully.');
+    return true;
+  } catch (error) {
+    console.error('Error deleting session:', error);
+    throw error;
+  } finally {
+    // Always release lock
+    isDeletingSession = false;
+  }
+}
+
+export const getPlatformName = (driver: any): string => {
+  if (driver instanceof AndroidUiautomator2Driver) return 'Android';
+  if (driver instanceof XCUITestDriver) return 'iOS';
+  throw new Error('Unknown driver type');
+};