appium-mcp 0.0.1 → 1.1.5

package/src/devicemanager/adb-manager.ts

@@ -0,0 +1,164 @@
+import { ADB } from 'appium-adb';
+import log from '../locators/logger.js';
+/**
+ * Singleton ADB Manager to prevent multiple ADB instances
+ * This ensures only one ADB instance per host machine
+ */
+export class ADBManager {
+  private static instance: ADBManager;
+  private adbInstance: ADB | null = null;
+  private isInitialized = false;
+  private initializationPromise: Promise<ADB> | null = null;
+
+  private constructor() {}
+
+  /**
+   * Get the singleton instance of ADBManager
+   */
+  public static getInstance(): ADBManager {
+    if (!ADBManager.instance) {
+      ADBManager.instance = new ADBManager();
+    }
+    return ADBManager.instance;
+  }
+
+  /**
+   * Initialize ADB instance with configuration
+   * @param options ADB configuration options
+   * @returns Promise<ADB> The initialized ADB instance
+   */
+  public async initialize(
+    options: { adbExecTimeout?: number; udid?: string } = {}
+  ): Promise<ADB> {
+    // If already initialized, return existing instance
+    if (this.isInitialized && this.adbInstance) {
+      log.debug(
+        'ADB instance already initialized, returning existing instance'
+      );
+      return this.adbInstance;
+    }
+
+    // If initialization is in progress, wait for it
+    if (this.initializationPromise) {
+      log.debug('ADB initialization in progress, waiting for completion');
+      return await this.initializationPromise;
+    }
+
+    // Start initialization
+    this.initializationPromise = this._createADBInstance(options);
+
+    try {
+      this.adbInstance = await this.initializationPromise;
+      this.isInitialized = true;
+      log.info('ADB instance initialized successfully');
+      return this.adbInstance;
+    } catch (error) {
+      log.error(`Failed to initialize ADB instance: ${error}`);
+      this.initializationPromise = null;
+      throw error;
+    }
+  }
+
+  /**
+   * Get the current ADB instance
+   * @returns ADB instance or null if not initialized
+   */
+  public getADBInstance(): ADB | null {
+    return this.adbInstance;
+  }
+
+  /**
+   * Check if ADB is initialized
+   * @returns boolean indicating initialization status
+   */
+  public isADBInitialized(): boolean {
+    return this.isInitialized && this.adbInstance !== null;
+  }
+
+  /**
+   * Reset the ADB instance (for testing or cleanup)
+   */
+  public async reset(): Promise<void> {
+    if (this.adbInstance) {
+      try {
+        // Cleanup any existing ADB instance
+        log.info('Resetting ADB instance');
+        this.adbInstance = null;
+        this.isInitialized = false;
+        this.initializationPromise = null;
+      } catch (error) {
+        log.error(`Error resetting ADB instance: ${error}`);
+      }
+    }
+  }
+
+  /**
+   * Create ADB instance with proper error handling
+   * @param options ADB configuration options
+   * @returns Promise<ADB> The created ADB instance
+   */
+  private async _createADBInstance(
+    options: { adbExecTimeout?: number; udid?: string } = {}
+  ): Promise<ADB> {
+    const defaultOptions = {
+      adbExecTimeout: 60000,
+      ...options,
+    };
+
+    log.info(
+      `Creating ADB instance with options: ${JSON.stringify(defaultOptions)}`
+    );
+
+    try {
+      const adb = await ADB.createADB(defaultOptions);
+      log.info('ADB instance created successfully');
+      return adb;
+    } catch (error) {
+      log.error(`Failed to create ADB instance: ${error}`);
+      throw new Error(`ADB initialization failed: ${error}`);
+    }
+  }
+
+  /**
+   * Get ADB instance for specific device operations
+   * This method ensures we reuse the singleton instance
+   * @param udid Optional device UDID for device-specific operations
+   * @returns Promise<ADB> The ADB instance
+   */
+  public async getADBForDevice(udid?: string): Promise<ADB> {
+    if (!this.isADBInitialized()) {
+      await this.initialize({ udid });
+    }
+
+    if (!this.adbInstance) {
+      throw new Error('ADB instance not available');
+    }
+
+    return this.adbInstance;
+  }
+}
+
+/**
+ * Global ADB Manager instance
+ * Use this throughout the application to access ADB functionality
+ */
+export const adbManager = ADBManager.getInstance();
+
+/**
+ * Convenience function to get ADB instance
+ * @param options ADB configuration options
+ * @returns Promise<ADB> The ADB instance
+ */
+export async function getADBInstance(
+  options: { adbExecTimeout?: number; udid?: string } = {}
+): Promise<ADB> {
+  return await adbManager.getADBForDevice(options.udid);
+}
+
+/**
+ * Convenience function to get existing ADB instance (without initialization)
+ * @returns ADB instance or null if not initialized
+ */
+export function getExistingADBInstance(): ADB | null {
+  return adbManager.getADBInstance();
+}

package/src/devicemanager/ios-manager.ts

@@ -0,0 +1,145 @@
+import { Simctl } from 'node-simctl';
+import { utilities } from 'appium-ios-device';
+import log from '../locators/logger.js';
+
+export interface IOSDevice {
+  name: string;
+  udid: string;
+  state?: string;
+  type: 'simulator' | 'real';
+  platform?: string;
+}
+
+/**
+ * iOS Device Manager to list and manage iOS devices and simulators
+ */
+export class IOSManager {
+  private static instance: IOSManager;
+  private simctl: Simctl;
+
+  private constructor() {
+    this.simctl = new Simctl();
+  }
+
+  /**
+   * Get the singleton instance of IOSManager
+   */
+  public static getInstance(): IOSManager {
+    if (!IOSManager.instance) {
+      IOSManager.instance = new IOSManager();
+    }
+    return IOSManager.instance;
+  }
+
+  /**
+   * Check if running on macOS (required for iOS development)
+   */
+  public isMac(): boolean {
+    return process.platform === 'darwin';
+  }
+
+  /**
+   * List all iOS simulators
+   * @returns Array of iOS simulators
+   */
+  public async listSimulators(): Promise<IOSDevice[]> {
+    if (!this.isMac()) {
+      log.warn('iOS simulators are only available on macOS');
+      return [];
+    }
+
+    try {
+      const devices = await this.simctl.getDevices();
+      const simulators: IOSDevice[] = [];
+
+      // devices is an object with runtime as key (e.g., "18.2") and array of devices as value
+      // node-simctl returns simplified runtime keys that are already iOS versions
+      for (const [runtime, deviceList] of Object.entries(devices)) {
+        if (Array.isArray(deviceList)) {
+          for (const device of deviceList) {
+            simulators.push({
+              name: device.name,
+              udid: device.udid,
+              state: device.state,
+              type: 'simulator',
+              platform: runtime, // Runtime is already the iOS version (e.g., "18.2")
+            });
+          }
+        }
+      }
+
+      return simulators;
+    } catch (error) {
+      log.error(`Error listing iOS simulators: ${error}`);
+      return [];
+    }
+  }
+
+  /**
+   * List only booted (running) iOS simulators
+   * @returns Array of booted simulators
+   */
+  public async listBootedSimulators(): Promise<IOSDevice[]> {
+    const allSimulators = await this.listSimulators();
+    return allSimulators.filter(simulator => simulator.state === 'Booted');
+  }
+
+  /**
+   * List all connected real iOS devices
+   * @returns Array of real iOS devices
+   */
+  public async listRealDevices(): Promise<IOSDevice[]> {
+    if (!this.isMac()) {
+      log.warn('iOS real devices are only available on macOS');
+      return [];
+    }
+
+    try {
+      const devices = await utilities.getConnectedDevices();
+      return devices.map((udid: string) => ({
+        name: udid, // We'll use UDID as name for now
+        udid: udid,
+        type: 'real' as const,
+      }));
+    } catch (error) {
+      log.error(`Error listing iOS real devices: ${error}`);
+      return [];
+    }
+  }
+
+  /**
+   * Get all available iOS simulators
+   * @returns Array of all iOS simulators (both booted and shutdown)
+   */
+  public async getAvailableSimulators(): Promise<IOSDevice[]> {
+    return await this.listSimulators();
+  }
+
+  /**
+   * Get all available real devices
+   * @returns Array of real iOS devices
+   */
+  public async getAvailableRealDevices(): Promise<IOSDevice[]> {
+    return await this.listRealDevices();
+  }
+
+  /**
+   * Get devices based on device type
+   * @param deviceType 'simulator' or 'real'
+   * @returns Array of iOS devices
+   */
+  public async getDevicesByType(
+    deviceType: 'simulator' | 'real'
+  ): Promise<IOSDevice[]> {
+    if (deviceType === 'simulator') {
+      return await this.getAvailableSimulators();
+    } else {
+      return await this.getAvailableRealDevices();
+    }
+  }
+}
+
+/**
+ * Global iOS Manager instance
+ */
+export const iosManager = IOSManager.getInstance();

package/src/index.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+import server from './server.js';
+import log from './locators/logger.js';
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const useSSE = args.includes('--sse');
+const port =
+  args.find(arg => arg.startsWith('--port='))?.split('=')[1] || '8080';
+
+// Start the server with the appropriate transport
+async function startServer(): Promise<void> {
+  log.info('Starting MCP Appium MCP Server...');
+
+  try {
+    if (useSSE) {
+      // Start with SSE transport
+      server.start({
+        transportType: 'sse',
+        sse: {
+          endpoint: '/sse',
+          port: parseInt(port, 10),
+        },
+      });
+
+      log.info(
+        `Server started with SSE transport on http://localhost:${port}/sse`
+      );
+      log.info('Waiting for client connections...');
+    } else {
+      // Start with stdio transport
+      server.start({
+        transportType: 'stdio',
+      });
+
+      log.info('Server started with stdio transport');
+      log.info('Waiting for client connections...');
+    }
+  } catch (error: any) {
+    log.error('Error starting server:', error);
+    process.exit(1);
+  }
+}
+
+// Start the server
+startServer();

package/src/locators/element-filter.ts

@@ -0,0 +1,134 @@
+import { JSONElement } from './source-parsing.js';
+
+export interface FilterOptions {
+  includeTagNames?: string[];
+  excludeTagNames?: string[];
+  requireAttributes?: string[];
+  minAttributeCount?: number;
+  fetchableOnly?: boolean;
+  clickableOnly?: boolean;
+}
+
+/**
+ * Determines if an element matches the tag name filters
+ */
+function matchesTagFilters(
+  element: JSONElement,
+  includeTagNames: string[],
+  excludeTagNames: string[]
+): boolean {
+  if (
+    includeTagNames.length > 0 &&
+    !includeTagNames.includes(element.tagName)
+  ) {
+    return false;
+  }
+  if (excludeTagNames.includes(element.tagName)) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Determines if an element matches attribute-based filters
+ */
+function matchesAttributeFilters(
+  element: JSONElement,
+  requireAttributes: string[],
+  minAttributeCount: number
+): boolean {
+  if (requireAttributes.length > 0) {
+    const hasRequiredAttr = requireAttributes.some(
+      attr => element.attributes && element.attributes[attr]
+    );
+    if (!hasRequiredAttr) return false;
+  }
+
+  if (
+    element.attributes &&
+    Object.keys(element.attributes).length < minAttributeCount
+  ) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Determines if an element is interactable/fetchable based on platform
+ */
+function isInteractableElement(
+  element: JSONElement,
+  isNative: boolean,
+  automationName: string
+): boolean {
+  const interactableTags =
+    isNative && automationName === 'uiautomator2'
+      ? [
+          'EditText',
+          'Button',
+          'ImageButton',
+          'CheckBox',
+          'RadioButton',
+          'Switch',
+          'ToggleButton',
+          'TextView',
+        ]
+      : [
+          'XCUIElementTypeTextField',
+          'XCUIElementTypeSecureTextField',
+          'XCUIElementTypeButton',
+          'XCUIElementTypeImage',
+          'XCUIElementTypeSwitch',
+          'XCUIElementTypeStaticText',
+          'XCUIElementTypeTextView',
+          'XCUIElementTypeCell',
+          'XCUIElementTypeLink',
+        ];
+
+  return (
+    interactableTags.some(tag => element.tagName.includes(tag)) ||
+    element.attributes?.clickable === 'true' ||
+    element.attributes?.focusable === 'true'
+  );
+}
+
+/**
+ * Determines if an element should be included based on all filter criteria
+ */
+export function shouldIncludeElement(
+  element: JSONElement,
+  filters: FilterOptions,
+  isNative: boolean,
+  automationName: string
+): boolean {
+  const {
+    includeTagNames = [],
+    excludeTagNames = ['hierarchy'],
+    requireAttributes = [],
+    minAttributeCount = 0,
+    fetchableOnly = false,
+    clickableOnly = false,
+  } = filters;
+
+  if (!matchesTagFilters(element, includeTagNames, excludeTagNames)) {
+    return false;
+  }
+
+  if (!matchesAttributeFilters(element, requireAttributes, minAttributeCount)) {
+    return false;
+  }
+
+  if (clickableOnly && element.attributes?.clickable !== 'true') {
+    return false;
+  }
+
+  if (
+    fetchableOnly &&
+    !isInteractableElement(element, isNative, automationName)
+  ) {
+    return false;
+  }
+
+  return true;
+}

package/src/locators/generate-all-locators.ts

@@ -0,0 +1,149 @@
+// Standalone Node.js script to generate locators for all elements from sourceXML
+// Using existing functions from src/locators directory
+
+import { getSuggestedLocators } from './locator-generation.js';
+import { xmlToJSON, JSONElement } from './source-parsing.js';
+import { shouldIncludeElement, FilterOptions } from './element-filter.js';
+import * as fs from 'fs';
+
+export interface ElementWithLocators {
+  tagName: string;
+  locators: Record<string, string>;
+  text: string;
+  contentDesc: string;
+  resourceId: string;
+  clickable: boolean;
+  enabled: boolean;
+  displayed: boolean;
+}
+
+/**
+ * Transforms a JSONElement with locators into ElementWithLocators format
+ */
+function transformElementWithLocators(
+  element: JSONElement,
+  locators: [string, string][]
+): ElementWithLocators {
+  // Filter out any undefined or invalid entries before converting to object
+  const validLocators = locators.filter(
+    (locator): locator is [string, string] =>
+      Array.isArray(locator) &&
+      locator.length === 2 &&
+      typeof locator[0] === 'string' &&
+      typeof locator[1] === 'string'
+  );
+
+  return {
+    tagName: element.tagName,
+    locators: Object.fromEntries(validLocators),
+    text: element.attributes.text || '',
+    contentDesc: element.attributes['content-desc'] || '',
+    resourceId: element.attributes['resource-id'] || '',
+    clickable: element.attributes.clickable === 'true',
+    enabled: element.attributes.enabled === 'true',
+    displayed: element.attributes.displayed === 'true',
+  };
+}
+
+/**
+ * Processes a single element: generates locators if it passes filters
+ */
+function processElement(
+  element: JSONElement,
+  sourceXML: string,
+  isNative: boolean,
+  automationName: string,
+  filters: FilterOptions,
+  results: ElementWithLocators[]
+): void {
+  if (!shouldIncludeElement(element, filters, isNative, automationName)) {
+    return;
+  }
+
+  try {
+    const strategyMap = getSuggestedLocators(
+      element,
+      sourceXML,
+      isNative,
+      automationName
+    );
+    results.push(transformElementWithLocators(element, strategyMap));
+  } catch (error) {
+    console.error(
+      `Error generating locators for element at path ${element.path}:`,
+      error
+    );
+  }
+}
+
+/**
+ * Recursively traverses the element tree and processes each element
+ */
+function traverseAndProcessElements(
+  element: JSONElement | null,
+  sourceXML: string,
+  isNative: boolean,
+  automationName: string,
+  filters: FilterOptions,
+  results: ElementWithLocators[]
+): void {
+  if (!element) {
+    return;
+  }
+
+  // Process current element
+  processElement(
+    element,
+    sourceXML,
+    isNative,
+    automationName,
+    filters,
+    results
+  );
+
+  // Recursively process children (even if parent was filtered out)
+  if (element.children && element.children.length > 0) {
+    element.children.forEach(child =>
+      traverseAndProcessElements(
+        child,
+        sourceXML,
+        isNative,
+        automationName,
+        filters,
+        results
+      )
+    );
+  }
+}
+
+/**
+ * Main function to generate locators for all elements from sourceXML
+ *
+ * @param sourceXML - The XML page source to process
+ * @param isNative - Whether this is a native context
+ * @param automationName - The automation driver name (uiautomator2, xcuitest, etc.)
+ * @param filters - Optional filters to apply when selecting elements
+ * @returns Array of elements with their generated locators
+ */
+export function generateAllElementLocators(
+  sourceXML: string,
+  isNative: boolean = true,
+  automationName: string,
+  filters: FilterOptions = {}
+): ElementWithLocators[] {
+  const sourceJSON = xmlToJSON(sourceXML);
+  const results: ElementWithLocators[] = [];
+
+  if (sourceJSON) {
+    traverseAndProcessElements(
+      sourceJSON,
+      sourceXML,
+      isNative,
+      automationName,
+      filters,
+      results
+    );
+  }
+
+  return results;
+}