appium-mcp 0.0.1 → 1.1.5

package/src/tools/boot-simulator.ts

@@ -0,0 +1,87 @@
+/**
+ * Tool to boot iOS simulator
+ */
+import { z } from 'zod';
+import { Simctl } from 'node-simctl';
+import { IOSManager } from '../devicemanager/ios-manager.js';
+
+export default function bootSimulator(server: any): void {
+  server.addTool({
+    name: 'boot_simulator',
+    description: `Boot an iOS simulator and wait for it to be ready.
+      This speeds up subsequent session creation by ensuring the simulator is already running.`,
+    parameters: z.object({
+      udid: z.string().describe(
+        `The UDID of the iOS simulator to boot.
+          Use select_platform and select_device tools first to get the UDID.`
+      ),
+    }),
+    annotations: {
+      readOnlyHint: false,
+      openWorldHint: false,
+    },
+    execute: async (args: any, context: any): Promise<any> => {
+      try {
+        const { udid } = args;
+
+        // Verify it's a macOS system
+        if (process.platform !== 'darwin') {
+          throw new Error('iOS simulators can only be booted on macOS systems');
+        }
+
+        const iosManager = IOSManager.getInstance();
+        const simulators = await iosManager.listSimulators();
+
+        // Find the simulator with the given UDID
+        const simulator = simulators.find(sim => sim.udid === udid);
+
+        if (!simulator) {
+          throw new Error(
+            `Simulator with UDID "${udid}" not found. Please use select_platform and select_device tools to get a valid UDID.`
+          );
+        }
+
+        // Check current state
+        if (simulator.state === 'Booted') {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `✅ Simulator "${simulator.name}" is already booted and ready!\n\nUDID: ${udid}\niOS Version: ${simulator.platform || 'Unknown'}\nState: ${simulator.state}`,
+              },
+            ],
+          };
+        }
+
+        const simctl = new Simctl();
+        simctl.udid = udid;
+
+        // Boot the device and measure time
+        const bootStartTime = Date.now();
+        await simctl.bootDevice();
+        await simctl.startBootMonitor({ timeout: 120000 });
+        const bootDuration = ((Date.now() - bootStartTime) / 1000).toFixed(1);
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `${JSON.stringify(
+                {
+                  instruction:
+                    'You can now use the install_wda tool to install WDA on the simulator.',
+                  status: 'Simulator booted successfully!',
+                },
+                null,
+                2
+              )}`,
+            },
+          ],
+        };
+      } catch (error: any) {
+        console.error('Error booting simulator:', error);
+        throw new Error(`Failed to boot simulator: ${error.message}`);
+      }
+    },
+  });
+}

package/src/tools/create-session.ts

@@ -0,0 +1,270 @@
+/**
+ * Tool to create a new mobile session (Android or iOS)
+ */
+import { z } from 'zod';
+import { access, readFile } from 'fs/promises';
+import { constants } from 'fs';
+import { AndroidUiautomator2Driver } from 'appium-uiautomator2-driver';
+import { XCUITestDriver } from 'appium-xcuitest-driver';
+import {
+  setSession,
+  hasActiveSession,
+  safeDeleteSession,
+} from './session-store.js';
+import {
+  getSelectedDevice,
+  getSelectedDeviceType,
+  getSelectedDeviceInfo,
+  clearSelectedDevice,
+} from './select-device.js';
+import { IOSManager } from '../devicemanager/ios-manager.js';
+import log from '../locators/logger.js';
+
+// Define capabilities type
+interface Capabilities {
+  platformName: string;
+  'appium:automationName': string;
+  'appium:deviceName'?: string;
+  [key: string]: any;
+}
+
+// Define capabilities config type
+interface CapabilitiesConfig {
+  android: Record<string, any>;
+  ios: Record<string, any>;
+}
+
+/**
+ * Load capabilities configuration from file if specified in environment
+ */
+async function loadCapabilitiesConfig(): Promise<CapabilitiesConfig> {
+  const configPath = process.env.CAPABILITIES_CONFIG;
+  if (!configPath) {
+    return { android: {}, ios: {} };
+  }
+
+  try {
+    await access(configPath, constants.F_OK);
+    const configContent = await readFile(configPath, 'utf8');
+    return JSON.parse(configContent);
+  } catch (error) {
+    log.warn(`Failed to parse capabilities config: ${error}`);
+    return { android: {}, ios: {} };
+  }
+}
+
+/**
+ * Remove empty string values from capabilities object
+ */
+function filterEmptyCapabilities(capabilities: Capabilities): Capabilities {
+  const filtered = { ...capabilities };
+  Object.keys(filtered).forEach(key => {
+    if (filtered[key] === '') {
+      delete filtered[key];
+    }
+  });
+  return filtered;
+}
+
+/**
+ * Build Android capabilities by merging defaults, config, device selection, and custom capabilities
+ */
+function buildAndroidCapabilities(
+  configCaps: Record<string, any>,
+  customCaps: Record<string, any> | undefined
+): Capabilities {
+  const defaultCaps: Capabilities = {
+    platformName: 'Android',
+    'appium:automationName': 'UiAutomator2',
+    'appium:deviceName': 'Android Device',
+  };
+
+  const selectedDeviceUdid = getSelectedDevice();
+
+  const capabilities = {
+    ...defaultCaps,
+    ...configCaps,
+    ...(selectedDeviceUdid && { 'appium:udid': selectedDeviceUdid }),
+    ...customCaps,
+  };
+
+  if (selectedDeviceUdid) {
+    clearSelectedDevice();
+  }
+
+  return filterEmptyCapabilities(capabilities);
+}
+
+/**
+ * Validate iOS device selection when multiple devices are available
+ */
+async function validateIOSDeviceSelection(
+  deviceType: 'simulator' | 'real' | null
+): Promise<void> {
+  if (!deviceType) {
+    return;
+  }
+
+  const iosManager = IOSManager.getInstance();
+  const devices = await iosManager.getDevicesByType(deviceType);
+
+  if (devices.length > 1) {
+    const selectedDevice = getSelectedDevice();
+    if (!selectedDevice) {
+      throw new Error(
+        `Multiple iOS ${deviceType === 'simulator' ? 'simulators' : 'devices'} found (${devices.length}). Please use the select_device tool to choose which device to use before creating a session.`
+      );
+    }
+  }
+}
+
+/**
+ * Build iOS capabilities by merging defaults, config, device selection, and custom capabilities
+ */
+async function buildIOSCapabilities(
+  configCaps: Record<string, any>,
+  customCaps: Record<string, any> | undefined
+): Promise<Capabilities> {
+  const deviceType = getSelectedDeviceType();
+  await validateIOSDeviceSelection(deviceType);
+
+  const defaultCaps: Capabilities = {
+    platformName: 'iOS',
+    'appium:automationName': 'XCUITest',
+    'appium:deviceName': 'iPhone Simulator',
+  };
+
+  const selectedDeviceUdid = getSelectedDevice();
+  const selectedDeviceInfo = getSelectedDeviceInfo();
+
+  log.debug('Selected device info:', selectedDeviceInfo);
+
+  const platformVersion =
+    selectedDeviceInfo?.platform && selectedDeviceInfo.platform.trim() !== ''
+      ? selectedDeviceInfo.platform
+      : undefined;
+
+  log.debug('Platform version:', platformVersion);
+
+  const capabilities = {
+    ...defaultCaps,
+    ...configCaps,
+    ...(selectedDeviceUdid && { 'appium:udid': selectedDeviceUdid }),
+    ...(platformVersion && { 'appium:platformVersion': platformVersion }),
+    ...(deviceType === 'simulator' && {
+      'appium:usePrebuiltWDA': true,
+      'appium:wdaStartupRetries': 4,
+      'appium:wdaStartupRetryInterval': 20000,
+    }),
+    ...customCaps,
+  };
+
+  if (selectedDeviceUdid) {
+    clearSelectedDevice();
+  }
+
+  return filterEmptyCapabilities(capabilities);
+}
+
+/**
+ * Create the appropriate driver instance for the given platform
+ */
+function createDriverForPlatform(platform: 'android' | 'ios'): any {
+  if (platform === 'android') {
+    return new AndroidUiautomator2Driver();
+  }
+  if (platform === 'ios') {
+    return new XCUITestDriver();
+  }
+  throw new Error(
+    `Unsupported platform: ${platform}. Please choose 'android' or 'ios'.`
+  );
+}
+
+/**
+ * Create a new session with the given driver and capabilities
+ */
+async function createDriverSession(
+  driver: any,
+  capabilities: Capabilities
+): Promise<string> {
+  // @ts-ignore
+  const sessionId = await driver.createSession(null, {
+    alwaysMatch: capabilities,
+    firstMatch: [{}],
+  });
+  return sessionId;
+}
+
+export default function createSession(server: any): void {
+  server.addTool({
+    name: 'create_session',
+    description: `Create a new mobile session with Android or iOS device.
+      MUST use select_platform tool first to ask the user which platform they want.
+      DO NOT assume or default to any platform.
+      `,
+    parameters: z.object({
+      platform: z.enum(['ios', 'android']).describe(
+        `REQUIRED: Must match the platform the user explicitly selected via the select_platform tool.
+          DO NOT default to Android or iOS without asking the user first.`
+      ),
+      capabilities: z
+        .object({})
+        .optional()
+        .describe('Optional custom capabilities for the session (W3C format).'),
+    }),
+    annotations: {
+      readOnlyHint: false,
+      openWorldHint: false,
+    },
+    execute: async (args: any, context: any): Promise<any> => {
+      try {
+        if (hasActiveSession()) {
+          log.info(
+            'Existing session detected, cleaning up before creating new session...'
+          );
+          await safeDeleteSession();
+        }
+
+        const { platform, capabilities: customCapabilities } = args;
+
+        const configCapabilities = await loadCapabilitiesConfig();
+        const platformCaps =
+          platform === 'android'
+            ? configCapabilities.android
+            : configCapabilities.ios;
+
+        const finalCapabilities =
+          platform === 'android'
+            ? buildAndroidCapabilities(platformCaps, customCapabilities)
+            : await buildIOSCapabilities(platformCaps, customCapabilities);
+
+        const driver = createDriverForPlatform(platform);
+
+        log.info(
+          `Creating new ${platform.toUpperCase()} session with capabilities:`,
+          JSON.stringify(finalCapabilities, null, 2)
+        );
+
+        const sessionId = await createDriverSession(driver, finalCapabilities);
+        setSession(driver, sessionId);
+
+        log.info(
+          `${platform.toUpperCase()} session created successfully with ID: ${sessionId}`
+        );
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `${platform.toUpperCase()} session created successfully with ID: ${sessionId}\nPlatform: ${finalCapabilities.platformName}\nAutomation: ${finalCapabilities['appium:automationName']}\nDevice: ${finalCapabilities['appium:deviceName']}`,
+            },
+          ],
+        };
+      } catch (error: any) {
+        log.error('Error creating session:', error);
+        throw new Error(`Failed to create session: ${error.message}`);
+      }
+    },
+  });
+}

package/src/tools/delete-session.ts

@@ -0,0 +1,46 @@
+/**
+ * Tool to delete the current mobile session and clean up resources
+ */
+import { z } from 'zod';
+import { safeDeleteSession } from './session-store.js';
+
+export default function deleteSession(server: any): void {
+  server.addTool({
+    name: 'delete_session',
+    description: 'Delete the current mobile session and clean up resources.',
+    parameters: z.object({}),
+    annotations: {
+      destructiveHint: true,
+      readOnlyHint: false,
+      openWorldHint: false,
+    },
+    execute: async (): Promise<any> => {
+      try {
+        const deleted = await safeDeleteSession();
+
+        if (deleted) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: 'Session deleted successfully.',
+              },
+            ],
+          };
+        } else {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: 'No active session found or deletion already in progress.',
+              },
+            ],
+          };
+        }
+      } catch (error: any) {
+        console.error(`Error deleting session`, error);
+        throw new Error(`Failed to delete session: ${error.message}`);
+      }
+    },
+  });
+}

package/src/tools/documentation/index.ts

@@ -0,0 +1,97 @@
+/**
+ * Documentation tools for Appium
+ *
+ * This module provides tools for answering queries about Appium
+ * by retrieving relevant information from indexed documentation.
+ */
+
+import {
+  queryVectorStore,
+  indexAllMarkdownFiles,
+} from './simple-pdf-indexer.js';
+import * as path from 'path';
+
+/**
+ * Interface for the query response
+ */
+interface QueryResponse {
+  answer: string;
+  sources?: string[];
+  chunks?: string[];
+}
+
+/**
+ * Initialize the Appium documentation index
+ * @param resourcesPath Path to the resources directory containing markdown files
+ */
+export async function initializeAppiumDocumentation(
+  resourcesPath?: string
+): Promise<void> {
+  try {
+    // Default to submodules directory if not specified
+    const docsPath =
+      resourcesPath || path.resolve(__dirname, '../../resources/submodules');
+    console.log(`Initializing Appium documentation from: ${docsPath}`);
+    await indexAllMarkdownFiles(docsPath);
+    console.log('Appium documentation indexing completed');
+  } catch (error) {
+    console.error('Error initializing Appium documentation:', error);
+    throw error;
+  }
+}
+
+/**
+ * Answer a query about Appium using indexed documentation
+ * @param options Query options
+ * @returns Response with relevant chunks for the client LLM to process
+ */
+export async function answerAppiumQuery(options: {
+  query: string;
+}): Promise<QueryResponse> {
+  try {
+    const { query } = options;
+    console.log(`Querying vector store for: "${query}"`);
+    const results = await queryVectorStore(query); // Get relevant chunks
+
+    if (!results || results.length === 0) {
+      return {
+        answer:
+          'No relevant information found in the Appium documentation. Please try rephrasing your query.',
+        chunks: [],
+      };
+    }
+
+    // Extract the content from all retrieved documents
+    const chunks = results.map((doc: any) => doc.pageContent);
+    const sources = results
+      .map(
+        (doc: any) =>
+          doc.metadata?.relativePath ||
+          doc.metadata?.filename ||
+          doc.metadata?.source
+      )
+      .filter(
+        (source: any, index: number, arr: any[]) =>
+          source && arr.indexOf(source) === index
+      ); // Remove duplicates
+
+    console.log(
+      `Found ${results.length} relevant chunks from ${sources.length} sources`
+    );
+
+    // Return the chunks for the client LLM to process
+    // The client will use its own LLM to generate the final answer
+    return {
+      answer: `Found ${
+        results.length
+      } relevant documentation chunks. Here are the relevant sections:\n\n${chunks.join(
+        '\n\n---\n\n'
+      )}`,
+      sources,
+      chunks,
+    };
+  } catch (error) {
+    console.error('Error querying Appium documentation:', error);
+    throw error;
+  }
+}