appium-mcp 1.8.14 → 1.8.16

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [1.8.16](https://github.com/appium/appium-mcp/compare/v1.8.15...v1.8.16) (2026-01-26)
+
+### Bug Fixes
+
+* publish src as well since mcp read documentation under that ([687cd71](https://github.com/appium/appium-mcp/commit/687cd711bdf85766f437aad3654bb978f4119bde))
+
+## [1.8.15](https://github.com/appium/appium-mcp/compare/v1.8.14...v1.8.15) (2026-01-26)
+
+### Bug Fixes
+
+* add @langchain/core explicitly ([#131](https://github.com/appium/appium-mcp/issues/131)) ([d0ff1ba](https://github.com/appium/appium-mcp/commit/d0ff1ba42fcc88301735eb1c53f722c1953f48db))
+
 ## [1.8.14](https://github.com/appium/appium-mcp/compare/v1.8.13...v1.8.14) (2026-01-25)
 
 ### Miscellaneous Chores

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appium-mcp",
   "mcpName": "io.github.appium/appium-mcp",
-  "version": "1.8.14",
+  "version": "1.8.16",
   "type": "module",
   "repository": {
     "type": "git",
@@ -41,6 +41,7 @@
   "description": "Intelligent MCP server providing AI assistants with powerful tools and resources for Appium mobile automation",
   "dependencies": {
     "@appium/support": "^7.0.2",
+    "@langchain/core": "^0.3.27",
     "@langfuse/otel": "^4.2.0",
     "@langfuse/tracing": "^4.2.0",
     "@modelcontextprotocol/sdk": "^1.22.0",
@@ -80,6 +81,7 @@
   },
   "files": [
     "scripts",
+    "src",
     "dist",
     "CHANGELOG.md",
     "README.md",

package/server.json

@@ -3,12 +3,12 @@
   "name": "io.github.appium/appium-mcp",
   "title": "MCP Appium - Mobile Development and Automation Server",
   "description": "MCP server for Appium mobile automation on iOS and Android devices with test creation tools.",
-  "version": "1.8.14",
+  "version": "1.8.16",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "appium-mcp",
-      "version": "1.8.14",
+      "version": "1.8.16",
       "transport": {
         "type": "stdio"
       }

package/src/command.ts

@@ -0,0 +1,249 @@
+import type { Client } from 'webdriver';
+import {
+  isAndroidUiautomator2DriverSession,
+  isXCUITestDriverSession,
+} from './session-store.js';
+import type { DriverInstance } from './session-store.js';
+import { StringRecord } from '@appium/types';
+
+/**
+ * Execute a driver command.
+ *
+ * This abstracts differences between Appium driver implementations and
+ * the WebDriver `Client` interface. Drivers are narrowed using the
+ * type-guard helpers from `session-store`.
+ *
+ * @param driver - The driver instance to execute the command on.
+ * @param cmd - The command or script name.
+ * @param params - Parameters for the command.
+ * @returns The result of the executed command.
+ */
+export async function execute(
+  driver: DriverInstance,
+  cmd: string,
+  params: any
+): Promise<any> {
+  if (isAndroidUiautomator2DriverSession(driver)) {
+    return await driver.execute(cmd, params);
+  } else if (isXCUITestDriverSession(driver)) {
+    return await driver.execute(cmd, params);
+  } else {
+    return await (driver as Client).executeScript(cmd, [params]);
+  }
+}
+
+/**
+ * Activate an application by its bundle/package id on the device.
+ *
+ * Works across Android and iOS driver implementations as well as remote
+ * WebDriver clients where supported.
+ *
+ * @param driver - The driver instance to use.
+ * @param appId - Application identifier to activate.
+ */
+export async function activateApp(
+  driver: DriverInstance,
+  appId: string
+): Promise<void> {
+  if (isAndroidUiautomator2DriverSession(driver)) {
+    await driver.activateApp(appId);
+  } else if (isXCUITestDriverSession(driver)) {
+    await driver.activateApp(appId);
+  } else {
+    await (driver as Client).activateApp(appId);
+  }
+}
+
+/**
+ * Retrieve the current context (for hybrid apps, e.g. NATIVE_APP or a webview).
+ *
+ * @param driver - The driver instance to query.
+ * @returns The name of the current context.
+ */
+export async function getCurrentContext(
+  driver: DriverInstance
+): Promise<string> {
+  if (isAndroidUiautomator2DriverSession(driver)) {
+    return await driver.getCurrentContext();
+  } else if (isXCUITestDriverSession(driver)) {
+    return await driver.getCurrentContext();
+  }
+  throw new Error('getCurrentContext is not supported');
+}
+
+/**
+ * List available contexts for the current session (native and webview contexts).
+ *
+ * @param driver - The driver instance to query.
+ * @returns Array of context names.
+ */
+export async function getContexts(driver: DriverInstance): Promise<string[]> {
+  if (isAndroidUiautomator2DriverSession(driver)) {
+    return await driver.getContexts();
+  } else if (isXCUITestDriverSession(driver)) {
+    return (await driver.getContexts()) as string[];
+  }
+  throw new Error('getContexts is not supported');
+}
+
+/**
+ * Switch the driver's context to the supplied context name.
+ *
+ * @param driver - The driver instance to operate on.
+ * @param name - The context name to switch to (if omitted, behavior depends on driver).
+ */
+export async function setContext(
+  driver: DriverInstance,
+  name?: string
+): Promise<void> {
+  if (isAndroidUiautomator2DriverSession(driver)) {
+    await driver.setContext(name);
+  } else if (isXCUITestDriverSession(driver)) {
+    await driver.setContext(name || null);
+  }
+  throw new Error('setContext is not supported');
+}
+
+/**
+ * Set the value of an element.
+ *
+ * @param driver - The driver instance to use.
+ * @param elementUUID - Element identifier.
+ * @param text - Text to set into the element.
+ * @returns Driver-specific result (often void or element value).
+ */
+export async function setValue(
+  driver: DriverInstance,
+  elementUUID: string,
+  text: string
+) {
+  if (isAndroidUiautomator2DriverSession(driver)) {
+    return await driver.setValue(text, elementUUID);
+  } else if (isXCUITestDriverSession(driver)) {
+    return await driver.setValue(text, elementUUID);
+  }
+  return await (driver as Client).elementSendKeys(elementUUID, text);
+}
+
+/**
+ * Click an element identified by UUID.
+ *
+ * @param driver - The driver instance to use.
+ * @param elementUUID - Identifier of the element to click.
+ */
+export async function elementClick(
+  driver: DriverInstance,
+  elementUUID: string
+): Promise<void> {
+  if (isAndroidUiautomator2DriverSession(driver)) {
+    return await driver.click(elementUUID);
+  } else if (isXCUITestDriverSession(driver)) {
+    return await driver.click(elementUUID);
+  }
+  return await driver.elementClick(elementUUID);
+}
+
+/**
+ * Get the bounding rectangle for an element.
+ *
+ * @param driver - The driver instance to query.
+ * @param elementUUID - Element identifier.
+ * @returns A `Rect` describing the element bounds.
+ */
+export async function getElementRect(
+  driver: DriverInstance,
+  elementUUID: string
+): Promise<import('@appium/types').Rect> {
+  if (isAndroidUiautomator2DriverSession(driver)) {
+    return await driver.getElementRect(elementUUID);
+  } else if (isXCUITestDriverSession(driver)) {
+    return await driver.getElementRect(elementUUID);
+  }
+  return await driver.getElementRect(elementUUID);
+}
+
+/**
+ * Get the window rectangle for the current session.
+ *
+ * @param driver - The driver instance to query.
+ * @returns A `Rect` describing the window bounds.
+ */
+export async function getWindowRect(
+  driver: DriverInstance
+): Promise<import('@appium/types').Rect> {
+  if (isAndroidUiautomator2DriverSession(driver)) {
+    return await driver.getWindowRect();
+  } else if (isXCUITestDriverSession(driver)) {
+    return await driver.getWindowRect();
+  }
+  return await driver.getWindowRect();
+}
+
+/**
+ * Perform low-level input actions (W3C Actions API) on the device.
+ *
+ * @param driver - The driver instance to use.
+ * @param operation - Actions or action sequences to perform.
+ */
+export async function performActions(
+  driver: DriverInstance,
+  operation: StringRecord<any>[] | import('@appium/types').ActionSequence[]
+): Promise<void> {
+  if (isAndroidUiautomator2DriverSession(driver)) {
+    return await driver.performActions(operation);
+  } else if (isXCUITestDriverSession(driver)) {
+    return await driver.performActions(
+      operation as import('@appium/types').ActionSequence[]
+    );
+  }
+  return await driver.performActions(operation);
+}
+
+/**
+ * Retrieve the current page/source (often XML for native screens).
+ *
+ * @param driver - The driver instance to query.
+ * @returns Page source as a string.
+ */
+export async function getPageSource(driver: DriverInstance): Promise<string> {
+  if (isAndroidUiautomator2DriverSession(driver)) {
+    return await driver.getPageSource();
+  } else if (isXCUITestDriverSession(driver)) {
+    return await driver.getPageSource();
+  }
+  return await driver.getPageSource();
+}
+
+/**
+ * Capture a screenshot from the device/session.
+ *
+ * @param driver - The driver instance to capture from.
+ * @returns Base64-encoded PNG string.
+ */
+export async function getScreenshot(driver: DriverInstance): Promise<string> {
+  if (isAndroidUiautomator2DriverSession(driver)) {
+    return await driver.getScreenshot();
+  } else if (isXCUITestDriverSession(driver)) {
+    return await driver.getScreenshot();
+  }
+  return await driver.takeScreenshot();
+}
+
+/**
+ * Get the visible text from an element.
+ *
+ * @param driver - The driver instance to query.
+ * @param elementUUID - Identifier of the element.
+ * @returns The element's text content.
+ */
+export async function getElementText(
+  driver: DriverInstance,
+  elementUUID: string
+): Promise<string> {
+  if (isAndroidUiautomator2DriverSession(driver)) {
+    return await driver.getText(elementUUID);
+  } else if (isXCUITestDriverSession(driver)) {
+    return await driver.getText(elementUUID);
+  }
+  return await driver.getElementText(elementUUID);
+}

package/src/devicemanager/adb-manager.ts

@@ -0,0 +1,164 @@
+import { ADB } from 'appium-adb';
+import log from '../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 '../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,
+        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,45 @@
+#!/usr/bin/env node
+
+import server from './server.js';
+import log from './logger.js';
+
+// Parse command line arguments
+const args = process.argv.slice(2);
+const useHttpStream = args.includes('--httpStream');
+const port =
+  args.find((arg) => arg.startsWith('--port='))?.split('=')[1] || '8080';
+
+async function startServer(): Promise<void> {
+  log.info('Starting MCP Appium MCP Server...');
+
+  try {
+    if (useHttpStream) {
+      server.start({
+        transportType: 'httpStream',
+        httpStream: {
+          endpoint: '/sse',
+          port: parseInt(port, 10),
+        },
+      });
+
+      log.info(
+        `Server started with httpStream 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();