@mseep/ai-tech-app-agent 1.0.0

package/src/mcp/mcpClient.ts

@@ -0,0 +1,878 @@
+import { spawn, ChildProcess } from 'child_process';
+import axios, { AxiosInstance } from 'axios';
+import { XMLParser } from 'fast-xml-parser';
+import fs from 'fs';
+import path from 'path';
+import mcpConfig, { isToolEnabled } from '../config/mcp.config';
+import appConfig from '../config/app.config';
+import logger from '../utils/logger';
+import { Action, UIContext, UIElement, Selector } from '../models/testSpec';
+
+export class MCPClient {
+  private mcpProcess: ChildProcess | null = null;
+  private sessionId: string | null = null;
+  private appiumServerUrl: string;
+  private appiumClient: AxiosInstance;
+  private xmlParser: XMLParser;
+  private platform: 'android' | 'ios' | null = null;
+
+  constructor(sessionId?: string) {
+    this.appiumServerUrl = mcpConfig.appium.serverUrl;
+    this.sessionId = sessionId || null;
+
+    // Initialize Appium HTTP client
+    this.appiumClient = axios.create({
+      baseURL: this.appiumServerUrl,
+      timeout: 120000, // Increased to 2 minutes for LambdaTest session creation
+      headers: {
+        'Content-Type': 'application/json',
+      },
+    });
+
+    // Initialize XML parser
+    this.xmlParser = new XMLParser({
+      ignoreAttributes: false,
+      attributeNamePrefix: '',
+      textNodeName: 'text',
+      parseAttributeValue: true,
+    });
+
+    logger.info('MCPClient initialized');
+  }
+
+  /**
+   * Initialize MCP server and establish connection
+   */
+  async initialize(): Promise<void> {
+    try {
+      logger.info('Initializing MCP-Appium server...');
+
+      // If using stdio protocol, spawn the MCP server process
+      if (mcpConfig.server.protocol === 'stdio') {
+        await this.startMCPProcess();
+      }
+
+      // Verify Appium connection
+      await this.verifyAppiumConnection();
+
+      // If no session ID provided, create a new session
+      if (!this.sessionId) {
+        await this.createSession();
+      }
+
+      logger.info('MCP-Appium server initialized successfully');
+    } catch (error: any) {
+      logger.error(`Failed to initialize MCP server: ${error.message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Start MCP server process (if using stdio)
+   */
+  private async startMCPProcess(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      try {
+        // Start mcp-appium server
+        this.mcpProcess = spawn('npx', ['mcp-appium'], {
+          env: {
+            ...process.env,
+            APPIUM_SERVER_URL: this.appiumServerUrl,
+            APPIUM_SESSION_ID: this.sessionId || '',
+          },
+          stdio: ['pipe', 'pipe', 'pipe'],
+        });
+
+        this.mcpProcess.stdout?.on('data', (data) => {
+          logger.debug(`MCP stdout: ${data.toString()}`);
+        });
+
+        this.mcpProcess.stderr?.on('data', (data) => {
+          logger.debug(`MCP stderr: ${data.toString()}`);
+        });
+
+        this.mcpProcess.on('error', (error) => {
+          logger.error(`MCP process error: ${error.message}`);
+          reject(error);
+        });
+
+        // Give it a moment to start
+        setTimeout(() => resolve(), 2000);
+      } catch (error) {
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Verify Appium server connection
+   */
+  private async verifyAppiumConnection(): Promise<void> {
+    try {
+      const response = await this.appiumClient.get('/status');
+      logger.info('Appium server is reachable');
+      logger.debug(`Appium status: ${JSON.stringify(response.data)}`);
+    } catch (error: any) {
+      throw new Error(`Cannot connect to Appium server at ${this.appiumServerUrl}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Create a new Appium session with device capabilities
+   */
+  private async createSession(): Promise<void> {
+    const maxRetries = 3;
+    let lastError: any;
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        logger.info(`Creating new Appium session (attempt ${attempt}/${maxRetries})...`);
+
+        // LambdaTest capabilities matching the provided format
+        const capabilities: any = {
+          platformName: 'Android',
+          'appium:platformVersion': '13',
+          'appium:deviceName': 'Galaxy S23',
+          'appium:automationName': 'UiAutomator2',
+          'appium:app': 'lt://APP1016060671764436009495779', // Upload your app to LambdaTest
+          'appium:isRealMobile': true,
+          'appium:newCommandTimeout': 300,
+          'appium:autoGrantPermissions': true,
+          'appium:noReset': true,
+          'appium:fullReset': false,
+          
+          // LambdaTest authentication (kept for backward compatibility)
+          username: appConfig.lambdatest.username,
+          accessKey: appConfig.lambdatest.accessKey,
+          
+          // LambdaTest specific capabilities
+          'lt:options': {
+            build: 'Hybrid AI Automation',
+            name: 'AI Test Session - ' + Date.now(),
+            video: true,
+            visual: true,
+            network: false,
+            console: true,
+            w3c: true,
+            retry: 0  // No retry
+          }
+        };
+
+        const sessionPayload = {
+          desiredCapabilities: capabilities
+        };
+
+        logger.debug(`Creating session with capabilities: ${JSON.stringify(sessionPayload, null, 2)}`);
+
+        const response = await this.appiumClient.post('/session', sessionPayload);
+        
+        this.sessionId = response.data.sessionId || response.data.value?.sessionId;
+        
+        if (!this.sessionId) {
+          throw new Error('Failed to get session ID from response');
+        }
+
+        // Auto-detect platform
+        this.platform = this.detectPlatformFromCapabilities(capabilities);
+
+        logger.info(`Appium session created successfully: ${this.sessionId}`);
+        logger.info(`Platform detected: ${this.platform}`);
+        return; // Success, exit the retry loop
+      } catch (error: any) {
+        lastError = error;
+        
+        if (error.response) {
+          logger.error(`Session creation failed with status ${error.response.status}`);
+          logger.error(`Response body: ${JSON.stringify(error.response.data, null, 2)}`);
+        } else if (error.code === 'ECONNABORTED') {
+          logger.error(`Session creation timed out (attempt ${attempt}/${maxRetries})`);
+        } else {
+          logger.error(`Session creation failed: ${error.message} (attempt ${attempt}/${maxRetries})`);
+        }
+        
+        // If not the last attempt, wait before retrying
+        if (attempt < maxRetries) {
+          const waitTime = attempt * 10000; // 10s, 20s backoff
+          logger.info(`Waiting ${waitTime/1000}s before retry...`);
+          await this.delay(waitTime);
+        }
+      }
+    }
+    
+    // All retries failed
+    throw new Error(`Failed to create Appium session after ${maxRetries} attempts: ${lastError.message}`);
+  }
+
+  /**
+   * Detect platform from capabilities
+   */
+  private detectPlatformFromCapabilities(capabilities: any): 'android' | 'ios' {
+    const platformName = (capabilities.platformName || '').toLowerCase();
+    return platformName.includes('ios') ? 'ios' : 'android';
+  }
+
+  /**
+   * Set the active Appium session ID
+   */
+  setSessionId(sessionId: string, platform?: 'android' | 'ios'): void {
+    this.sessionId = sessionId;
+    this.platform = platform || null;
+    logger.info(`MCP client configured with session ID: ${sessionId}, platform: ${platform || 'auto-detect'}`);
+  }
+
+  /**
+   * Get current UI context (page source + parsed elements)
+   */
+  async getUIContext(): Promise<UIContext> {
+    try {
+      if (!this.sessionId) {
+        throw new Error('No active Appium session');
+      }
+
+      logger.debug('Fetching UI context from Appium...');
+
+      // Get page source (XML hierarchy)
+      const pageSource = await this.getPageSource();
+
+      // Parse visible elements from page source
+      const visibleElements = mcpConfig.uiContext.parseXML
+        ? this.parseUIElements(pageSource)
+        : [];
+
+      // Get current activity/package (Android) or bundle ID (iOS)
+      const currentActivity = await this.getCurrentActivity();
+
+      // Auto-detect platform if not set
+      if (!this.platform) {
+        this.platform = this.detectPlatformFromPageSource(pageSource);
+      }
+
+      const uiContext: UIContext = {
+        pageSource,
+        currentActivity,
+        visibleElements,
+        currentPackage: this.platform === 'android' ? await this.getCurrentPackage() : undefined,
+      };
+
+      logger.debug(`UI context fetched: ${visibleElements.length} elements found, activity: ${currentActivity}`);
+      return uiContext;
+    } catch (error: any) {
+      logger.error(`Failed to get UI context: ${error.message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Get page source (XML hierarchy)
+   */
+  private async getPageSource(): Promise<string> {
+    try {
+      const response = await this.appiumClient.get(`/session/${this.sessionId}/source`);
+      return response.data.value || '';
+    } catch (error: any) {
+      logger.error(`Failed to get page source: ${error.message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Get current activity (Android) or current view (iOS)
+   */
+  private async getCurrentActivity(): Promise<string> {
+    try {
+      if (!this.platform) {
+        this.platform = await this.detectPlatform();
+      }
+
+      if (this.platform === 'android') {
+        const response = await this.appiumClient.get(`/session/${this.sessionId}/appium/device/current_activity`);
+        return response.data.value || 'Unknown';
+      } else {
+        // For iOS, we can get the active app bundle ID
+        const response = await this.appiumClient.get(`/session/${this.sessionId}/appium/device/current_package`);
+        return response.data.value || 'Unknown';
+      }
+    } catch (error: any) {
+      logger.warn(`Could not get current activity: ${error.message}`);
+      return 'Unknown';
+    }
+  }
+
+  /**
+   * Get current package (Android only)
+   */
+  private async getCurrentPackage(): Promise<string | undefined> {
+    try {
+      if (this.platform === 'android') {
+        const response = await this.appiumClient.get(`/session/${this.sessionId}/appium/device/current_package`);
+        return response.data.value;
+      }
+    } catch (error: any) {
+      logger.warn(`Could not get current package: ${error.message}`);
+    }
+    return undefined;
+  }
+
+  /**
+   * Detect platform from session capabilities
+   */
+  private async detectPlatform(): Promise<'android' | 'ios'> {
+    try {
+      const response = await this.appiumClient.get(`/session/${this.sessionId}`);
+      const caps = response.data.value || response.data;
+      const platformName = (caps.platformName || '').toLowerCase();
+      
+      if (platformName.includes('android')) {
+        return 'android';
+      } else if (platformName.includes('ios')) {
+        return 'ios';
+      }
+    } catch (error: any) {
+      logger.warn(`Could not detect platform: ${error.message}`);
+    }
+    
+    // Default to android
+    return 'android';
+  }
+
+  /**
+   * Detect platform from page source XML
+   */
+  private detectPlatformFromPageSource(pageSource: string): 'android' | 'ios' {
+    if (pageSource.includes('XCUIElement') || pageSource.includes('AppiumAUT')) {
+      return 'ios';
+    }
+    return 'android';
+  }
+
+  /**
+   * Parse UI elements from XML page source
+   */
+  private parseUIElements(pageSource: string): UIElement[] {
+    try {
+      const parsed = this.xmlParser.parse(pageSource);
+      const elements: UIElement[] = [];
+
+      // Recursively extract elements
+      this.extractElementsRecursive(parsed, elements, 0);
+
+      // Apply filters
+      return this.filterElements(elements);
+    } catch (error: any) {
+      logger.error(`Failed to parse XML: ${error.message}`);
+      return [];
+    }
+  }
+
+  /**
+   * Recursively extract elements from parsed XML
+   */
+  private extractElementsRecursive(node: any, elements: UIElement[], depth: number): void {
+    if (depth > mcpConfig.uiContext.maxElementDepth) {
+      return;
+    }
+
+    if (!node || typeof node !== 'object') {
+      return;
+    }
+
+    // Check if this is an element node
+    if (node.class || node['resource-id'] || node['content-desc'] || node.name) {
+      const element: UIElement = {
+        type: node.class || node.type || 'Unknown',
+        text: node.text || node.label || node.value,
+        resourceId: node['resource-id'] || node.name,
+        contentDesc: node['content-desc'] || node.label,
+        className: node.class || node.type,
+        bounds: node.bounds,
+        clickable: node.clickable === 'true' || node.clickable === true,
+        enabled: node.enabled === 'true' || node.enabled === true || node.enabled === undefined,
+        index: node.index,
+      };
+
+      elements.push(element);
+    }
+
+    // Recursively process children
+    Object.keys(node).forEach(key => {
+      if (typeof node[key] === 'object') {
+        if (Array.isArray(node[key])) {
+          node[key].forEach((child: any) => {
+            this.extractElementsRecursive(child, elements, depth + 1);
+          });
+        } else {
+          this.extractElementsRecursive(node[key], elements, depth + 1);
+        }
+      }
+    });
+  }
+
+  /**
+   * Filter elements based on configuration
+   */
+  private filterElements(elements: UIElement[]): UIElement[] {
+    const { excludeClasses, includeOnlyInteractive, minTextLength } = mcpConfig.uiContext.elementFilters;
+
+    return elements.filter(element => {
+      // Exclude certain classes
+      if (excludeClasses.some(cls => element.className?.includes(cls))) {
+        return false;
+      }
+
+      // Include only interactive elements
+      if (includeOnlyInteractive && !element.clickable && !element.type.includes('Edit')) {
+        return false;
+      }
+
+      // Filter by text length
+      if (element.text && element.text.length < minTextLength) {
+        return false;
+      }
+
+      return true;
+    });
+  }
+
+  /**
+   * Execute an action
+   */
+  async executeAction(action: Action): Promise<boolean> {
+    try {
+      logger.info(`Executing action: ${action.type}`);
+
+      switch (action.type) {
+        case 'tap':
+          return await this.tap(action);
+        case 'type':
+          return await this.type(action);
+        case 'scroll':
+          return await this.scroll(action);
+        case 'swipe':
+          return await this.swipe(action);
+        case 'wait':
+          return await this.wait(action);
+        case 'assert':
+          return await this.assert(action);
+        case 'screenshot':
+          return await this.screenshot();
+        case 'launch':
+          return await this.launch(action);
+        default:
+          logger.warn(`Unknown action type: ${action.type}`);
+          return false;
+      }
+    } catch (error: any) {
+      logger.error(`Action execution failed: ${error.message}`);
+      
+      if (mcpConfig.errorHandling.captureScreenshotOnError) {
+        await this.screenshot().catch(() => {});
+      }
+      
+      return false;
+    }
+  }
+
+  /**
+   * Tap/click on an element
+   */
+  private async tap(action: Action): Promise<boolean> {
+    if (!action.selector) {
+      logger.error('Tap action requires a selector');
+      return false;
+    }
+
+    logger.debug(`Tapping element: ${action.selector.strategy}=${action.selector.value}`);
+
+    try {
+      const element = await this.findElement(action.selector);
+      
+      if (!element) {
+        throw new Error('Element not found');
+      }
+
+      await this.appiumClient.post(`/session/${this.sessionId}/element/${element}/click`, {});
+      
+      // Small delay after tap
+      await this.delay(appConfig.interaction.actionDelay);
+      
+      return true;
+    } catch (error: any) {
+      logger.error(`Tap failed: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Type text into an element
+   */
+  private async type(action: Action): Promise<boolean> {
+    if (!action.selector || !action.value) {
+      logger.error('Type action requires selector and value');
+      return false;
+    }
+
+    logger.debug(`Typing "${action.value}" into element: ${action.selector.strategy}=${action.selector.value}`);
+
+    try {
+      const element = await this.findElement(action.selector);
+      
+      if (!element) {
+        throw new Error('Element not found');
+      }
+
+      // Clear existing text if needed
+      await this.appiumClient.post(`/session/${this.sessionId}/element/${element}/clear`, {});
+      
+      // Type the text
+      await this.appiumClient.post(`/session/${this.sessionId}/element/${element}/value`, {
+        text: action.value,
+        value: action.value.split(''),
+      });
+
+      await this.delay(appConfig.interaction.actionDelay);
+      
+      return true;
+    } catch (error: any) {
+      logger.error(`Type failed: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Scroll the screen
+   */
+  private async scroll(action: Action): Promise<boolean> {
+    const direction = action.direction || 'down';
+    logger.debug(`Scrolling ${direction}`);
+
+    try {
+      // Get screen size
+      const size = await this.getScreenSize();
+      const { width, height } = size;
+
+      const centerX = width / 2;
+      const startY = direction === 'down' ? height * 0.8 : height * 0.2;
+      const endY = direction === 'down' ? height * 0.2 : height * 0.8;
+
+      await this.performSwipeGesture(centerX, startY, centerX, endY, appConfig.interaction.swipeSpeed);
+      
+      return true;
+    } catch (error: any) {
+      logger.error(`Scroll failed: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Swipe gesture
+   */
+  private async swipe(action: Action): Promise<boolean> {
+    const direction = action.direction || 'left';
+    logger.debug(`Swiping ${direction}`);
+
+    try {
+      const size = await this.getScreenSize();
+      const { width, height } = size;
+
+      let startX, startY, endX, endY;
+
+      switch (direction) {
+        case 'left':
+          startX = width * 0.8;
+          startY = height / 2;
+          endX = width * 0.2;
+          endY = height / 2;
+          break;
+        case 'right':
+          startX = width * 0.2;
+          startY = height / 2;
+          endX = width * 0.8;
+          endY = height / 2;
+          break;
+        case 'up':
+          startX = width / 2;
+          startY = height * 0.8;
+          endX = width / 2;
+          endY = height * 0.2;
+          break;
+        case 'down':
+          startX = width / 2;
+          startY = height * 0.2;
+          endX = width / 2;
+          endY = height * 0.8;
+          break;
+        default:
+          startX = width / 2;
+          startY = height / 2;
+          endX = width / 2;
+          endY = height / 2;
+      }
+
+      await this.performSwipeGesture(startX, startY, endX, endY, action.duration || appConfig.interaction.swipeSpeed);
+      
+      return true;
+    } catch (error: any) {
+      logger.error(`Swipe failed: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Perform swipe gesture using touch actions
+   */
+  private async performSwipeGesture(startX: number, startY: number, endX: number, endY: number, duration: number): Promise<void> {
+    const actions = [
+      {
+        type: 'pointer',
+        id: 'finger1',
+        parameters: { pointerType: 'touch' },
+        actions: [
+          { type: 'pointerMove', duration: 0, x: Math.round(startX), y: Math.round(startY) },
+          { type: 'pointerDown', button: 0 },
+          { type: 'pause', duration: 100 },
+          { type: 'pointerMove', duration, x: Math.round(endX), y: Math.round(endY) },
+          { type: 'pointerUp', button: 0 },
+        ],
+      },
+    ];
+
+    await this.appiumClient.post(`/session/${this.sessionId}/actions`, { actions });
+  }
+
+  /**
+   * Wait for duration or element
+   */
+  private async wait(action: Action): Promise<boolean> {
+    const duration = action.duration || 2000;
+    logger.debug(`Waiting for ${duration}ms`);
+
+    await this.delay(duration);
+    return true;
+  }
+
+  /**
+   * Assert element state
+   */
+  private async assert(action: Action): Promise<boolean> {
+    if (!action.selector || !action.assertionType) {
+      logger.error('Assert action requires selector and assertionType');
+      return false;
+    }
+
+    logger.debug(`Asserting: ${action.assertionType} on ${action.selector.value}`);
+
+    try {
+      const element = await this.findElement(action.selector);
+
+      switch (action.assertionType) {
+        case 'exists':
+          return element !== null;
+        
+        case 'visible':
+          if (!element) return false;
+          const displayed = await this.appiumClient.get(`/session/${this.sessionId}/element/${element}/displayed`);
+          return displayed.data.value === true;
+        
+        case 'enabled':
+          if (!element) return false;
+          const enabled = await this.appiumClient.get(`/session/${this.sessionId}/element/${element}/enabled`);
+          return enabled.data.value === true;
+        
+        case 'text':
+          if (!element) return false;
+          const text = await this.appiumClient.get(`/session/${this.sessionId}/element/${element}/text`);
+          return text.data.value === action.expectedValue;
+        
+        default:
+          logger.warn(`Unknown assertion type: ${action.assertionType}`);
+          return false;
+      }
+    } catch (error: any) {
+      logger.error(`Assertion failed: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Launch an app or return to home screen
+   */
+  private async launch(action: Action): Promise<boolean> {
+    logger.debug('Launching app or returning to home');
+
+    try {
+      // If no specific app package is specified, we're already in a session
+      // Just return true as the device is ready
+      if (!action.value) {
+        logger.info('Device session ready - no specific app launch required');
+        return true;
+      }
+
+      // If a specific app package is provided, try to launch it
+      const appPackage = action.value;
+      logger.debug(`Attempting to launch app: ${appPackage}`);
+      
+      // For Android, we can try to activate the app
+      if (this.platform === 'android') {
+        await this.appiumClient.post(`/session/${this.sessionId}/appium/device/activate_app`, {
+          appId: appPackage
+        });
+      } else {
+        // For iOS, we can try to launch the app by bundle ID
+        await this.appiumClient.post(`/session/${this.sessionId}/appium/device/activate_app`, {
+          bundleId: appPackage
+        });
+      }
+
+      await this.delay(appConfig.interaction.actionDelay);
+      return true;
+    } catch (error: any) {
+      logger.warn(`Launch action completed with warning: ${error.message}`);
+      // Return true anyway as the session is established
+      return true;
+    }
+  }
+
+  /**
+   * Take screenshot
+   */
+  private async screenshot(): Promise<boolean> {
+    logger.debug('Taking screenshot');
+
+    try {
+      const response = await this.appiumClient.get(`/session/${this.sessionId}/screenshot`);
+      const screenshotData = response.data.value;
+
+      // Save screenshot
+      const timestamp = Date.now();
+      const filename = `screenshot_${timestamp}.png`;
+      const filepath = path.join(appConfig.paths.screenshots, filename);
+
+      // Ensure directory exists
+      if (!fs.existsSync(appConfig.paths.screenshots)) {
+        fs.mkdirSync(appConfig.paths.screenshots, { recursive: true });
+      }
+
+      fs.writeFileSync(filepath, screenshotData, 'base64');
+      logger.info(`Screenshot saved: ${filepath}`);
+
+      return true;
+    } catch (error: any) {
+      logger.error(`Screenshot failed: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Find element using selector
+   */
+  private async findElement(selector: Selector): Promise<string | null> {
+    try {
+      const { strategy, value, index } = selector;
+      
+      // Map our strategy names to Appium's
+      const strategyMap: Record<string, string> = {
+        'text': this.platform === 'android' ? 'xpath' : '-ios predicate string',
+        'id': this.platform === 'android' ? 'id' : 'accessibility id',
+        'accessibility-id': 'accessibility id',
+        'xpath': 'xpath',
+        'class': 'class name',
+      };
+
+      let appiumStrategy = strategyMap[strategy] || strategy;
+      let appiumValue = value;
+
+      // Special handling for text search
+      if (strategy === 'text') {
+        if (this.platform === 'android') {
+          appiumStrategy = 'xpath';
+          appiumValue = `//*[@text='${value}' or contains(@text,'${value}')]`;
+        } else {
+          appiumStrategy = '-ios predicate string';
+          appiumValue = `label == "${value}" OR name == "${value}"`;
+        }
+      }
+
+      const payload = {
+        using: appiumStrategy,
+        value: appiumValue,
+      };
+
+      const response = await this.appiumClient.post(`/session/${this.sessionId}/element`, payload);
+      
+      if (index !== undefined && index > 0) {
+        // If index is specified, find multiple and return the one at index
+        const multiResponse = await this.appiumClient.post(`/session/${this.sessionId}/elements`, payload);
+        const elements = multiResponse.data.value;
+        
+        if (elements && elements.length > index) {
+          return elements[index].ELEMENT || elements[index]['element-6066-11e4-a52e-4f735466cecf'];
+        }
+        return null;
+      }
+
+      const elementId = response.data.value?.ELEMENT || response.data.value?.['element-6066-11e4-a52e-4f735466cecf'];
+      return elementId || null;
+    } catch (error: any) {
+      logger.debug(`Element not found: ${selector.strategy}=${selector.value}`);
+      return null;
+    }
+  }
+
+  /**
+   * Get screen size
+   */
+  private async getScreenSize(): Promise<{ width: number; height: number }> {
+    try {
+      const response = await this.appiumClient.get(`/session/${this.sessionId}/window/rect`);
+      return {
+        width: response.data.value.width,
+        height: response.data.value.height,
+      };
+    } catch (error: any) {
+      logger.warn(`Could not get screen size: ${error.message}`);
+      // Default fallback
+      return { width: 1080, height: 1920 };
+    }
+  }
+
+  /**
+   * Delay helper
+   */
+  private delay(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Stop the current Appium session
+   */
+  async stopSession(): Promise<void> {
+    if (this.sessionId) {
+      try {
+        logger.info(`Stopping Appium session: ${this.sessionId}`);
+        await this.appiumClient.delete(`/session/${this.sessionId}`);
+        logger.info('Appium session stopped successfully');
+      } catch (error: any) {
+        logger.warn(`Failed to stop session: ${error.message}`);
+      } finally {
+        this.sessionId = null;
+        this.platform = null;
+      }
+    }
+  }
+
+  /**
+   * Cleanup and shutdown
+   */
+  async cleanup(): Promise<void> {
+    // Stop the Appium session first
+    await this.stopSession();
+    
+    if (this.mcpProcess) {
+      logger.info('Shutting down MCP server...');
+      this.mcpProcess.kill();
+      this.mcpProcess = null;
+    }
+  }
+}
+
+export default MCPClient;