appium-mcp 1.8.11 → 1.8.12

package/src/tools/session/select-device.ts

@@ -1,326 +0,0 @@
-/**
- * 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 '../../logger.js';
-import {
-  createUIResource,
-  createDevicePickerUI,
-  addUIResourceToResponse,
-} from '../../ui/mcp-ui-utils.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');
-
-  const textResponse = {
-    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.`,
-      },
-    ],
-  };
-
-  // Add interactive UI picker
-  const uiResource = createUIResource(
-    `ui://appium-mcp/device-picker/android-${Date.now()}`,
-    createDevicePickerUI(devices, 'android')
-  );
-
-  return addUIResourceToResponse(textResponse, uiResource);
-}
-
-/**
- * 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');
-
-  const textResponse = {
-    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.`,
-      },
-    ],
-  };
-
-  // Add interactive UI picker
-  const uiResource = createUIResource(
-    `ui://appium-mcp/device-picker/ios-${iosDeviceType}-${Date.now()}`,
-    createDevicePickerUI(devices, 'ios', iosDeviceType)
-  );
-
-  return addUIResourceToResponse(textResponse, uiResource);
-}
-
-/**
- * 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: `Select a specific device from available LOCAL devices. For LOCAL Appium servers ONLY.
-      DO NOT use this tool for REMOTE Appium servers - remoteServerUrl indicates a remote server.
-      WORKFLOW FOR LOCAL SERVERS:
-      - Use this tool ONLY when select_platform returns multiple devices
-      - For Android: Use before calling create_session if multiple devices are found
-      - For iOS: Use before calling boot_simulator or create_session if multiple simulators/devices are found
-      - Ask the user which device they want to use from the list provided
-      WORKFLOW FOR REMOTE SERVERS:
-      - SKIP this tool entirely
-      - Device selection should be handled via capabilities in create_session (e.g., appium:deviceName, appium:udid)
-      - The remote Appium server is already configured for specific device(s)
-      `,
-    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/session/select-platform.ts

@@ -1,250 +0,0 @@
-/**
- * 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 '../../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: `Select the mobile platform for LOCAL Appium servers ONLY.
-      DO NOT use this tool if the user mentions a REMOTE Appium server URL (e.g., http://localhost:4723, http://192.168.1.100:4723, or any other server address).
-      WORKFLOW FOR LOCAL SERVERS:
-      1. First, ASK THE USER which mobile platform they want to use (Android or iOS)
-      2. You MUST explicitly prompt the user to choose between Android or iOS
-      3. DO NOT assume or default to any platform
-      4. After platform selection, available devices will be listed
-      5. If multiple devices are available, use select_device to let the user choose
-      6. After device selection, proceed to create_session
-      WORKFLOW FOR REMOTE SERVERS:
-      If user provides a remote server URL, SKIP this tool entirely. Instead, infer the platform and device type from the user's request (e.g., 'ios xcuitest driver with iphone 17 simulator' means platform='ios') and call create_session directly with the remoteServerUrl parameter.
-      `,
-    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' (iOS Simulator on macOS) or 'real' (physical iOS 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/test-generation/generate-tests.ts

@@ -1,48 +0,0 @@
-import { FastMCP } from 'fastmcp';
-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> => ({
-      content: [
-        {
-          type: 'text',
-          text: instructions({
-            steps: args.steps,
-          }),
-        },
-      ],
-    }),
-  });
-}