appium-mcp 1.8.15 → 1.9.0

package/src/tools/app-management/activate-app.ts

@@ -0,0 +1,47 @@
+import { FastMCP } from 'fastmcp';
+import { getDriver } from '../../session-store.js';
+import { z } from 'zod';
+import { activateApp as _activateApp } from '../../command.js';
+
+export default function activateApp(server: FastMCP): void {
+  const activateAppSchema = z.object({
+    id: z.string().describe('The app id'),
+  });
+
+  server.addTool({
+    name: 'appium_activate_app',
+    description: 'Activate app by id',
+    parameters: activateAppSchema,
+    annotations: {
+      readOnlyHint: false,
+      openWorldHint: false,
+    },
+    execute: async (args: { id: string }, context: any): Promise<any> => {
+      const driver = getDriver();
+      if (!driver) {
+        throw new Error('No driver found');
+      }
+
+      try {
+        await _activateApp(driver, args.id);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `App ${args.id} activated correctly.`,
+            },
+          ],
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error activating the app ${args.id}: ${err.toString()}`,
+            },
+          ],
+        };
+      }
+    },
+  });
+}

package/src/tools/app-management/install-app.ts

@@ -0,0 +1,46 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import { getDriver, getPlatformName, PLATFORM } from '../../session-store.js';
+import { execute } from '../../command.js';
+
+export default function installApp(server: FastMCP): void {
+  const schema = z.object({
+    path: z.string().describe('Path to the app file to install'),
+  });
+
+  server.addTool({
+    name: 'appium_install_app',
+    description: 'Install an app on the device from a file path.',
+    parameters: schema,
+    execute: async (args: z.infer<typeof schema>) => {
+      const { path } = args;
+      const driver = await getDriver();
+      if (!driver) {
+        throw new Error('No driver found');
+      }
+      try {
+        const platform = getPlatformName(driver);
+        const params =
+          platform === PLATFORM.android ? { appPath: path } : { app: path };
+        await execute(driver, 'mobile: installApp', params);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: 'App installed successfully',
+            },
+          ],
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to install app. err: ${err.toString()}`,
+            },
+          ],
+        };
+      }
+    },
+  });
+}

package/src/tools/app-management/list-apps.ts

@@ -0,0 +1,87 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import {
+  getDriver,
+  getPlatformName,
+  isRemoteDriverSession,
+} from '../../session-store.js';
+import {
+  createUIResource,
+  createAppListUI,
+  addUIResourceToResponse,
+} from '../../ui/mcp-ui-utils.js';
+import type { AndroidUiautomator2Driver } from 'appium-uiautomator2-driver';
+
+async function listAppsFromDevice(): Promise<any[]> {
+  const driver = await getDriver();
+  if (!driver) {
+    throw new Error('No driver found');
+  }
+
+  if (isRemoteDriverSession(driver)) {
+    throw new Error('listApps is not yet implemented for the remote driver');
+  }
+
+  const platform = getPlatformName(driver);
+  if (platform === 'iOS') {
+    throw new Error('listApps is not yet implemented for iOS');
+  }
+
+  const appPackages = await (driver as AndroidUiautomator2Driver).adb.adbExec([
+    'shell',
+    'cmd',
+    'package',
+    'list',
+    'packages',
+  ]);
+
+  const apps: any[] = appPackages
+    .split('package:')
+    .filter((s: any) => s.trim())
+    .map((s: any) => ({
+      packageName: s.trim(),
+      appName: '',
+    }));
+
+  return apps;
+}
+
+export default function listApps(server: FastMCP): void {
+  const schema = z.object({});
+
+  server.addTool({
+    name: 'appium_list_apps',
+    description: 'List all installed apps on the device.',
+    parameters: schema,
+    execute: async () => {
+      try {
+        const apps = await listAppsFromDevice();
+        const textResponse = {
+          content: [
+            {
+              type: 'text',
+              text: `Installed apps: ${JSON.stringify(apps, null, 2)}`,
+            },
+          ],
+        };
+
+        // Add interactive app list UI
+        const uiResource = createUIResource(
+          `ui://appium-mcp/app-list/${Date.now()}`,
+          createAppListUI(apps)
+        );
+
+        return addUIResourceToResponse(textResponse, uiResource);
+      } catch (err: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to list apps. err: ${err.toString()}`,
+            },
+          ],
+        };
+      }
+    },
+  });
+}

package/src/tools/app-management/terminate-app.ts

@@ -0,0 +1,48 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import { getDriver, getPlatformName, PLATFORM } from '../../session-store.js';
+import { execute } from '../../command.js';
+
+export default function terminateApp(server: FastMCP): void {
+  const schema = z.object({
+    id: z
+      .string()
+      .describe('App identifier (package name for Android, bundle ID for iOS)'),
+  });
+
+  server.addTool({
+    name: 'appium_terminate_app',
+    description: 'Terminate an app on the device.',
+    parameters: schema,
+    execute: async (args: z.infer<typeof schema>) => {
+      const { id } = args;
+      const driver = await getDriver();
+      if (!driver) {
+        throw new Error('No driver found');
+      }
+      try {
+        const platform = getPlatformName(driver);
+        const params =
+          platform === PLATFORM.android ? { appId: id } : { bundleId: id };
+        await execute(driver, 'mobile: terminateApp', params);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: 'App terminated successfully',
+            },
+          ],
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to terminate app. err: ${err.toString()}`,
+            },
+          ],
+        };
+      }
+    },
+  });
+}

package/src/tools/app-management/uninstall-app.ts

@@ -0,0 +1,48 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import { getDriver, getPlatformName, PLATFORM } from '../../session-store.js';
+import { execute } from '../../command.js';
+
+export default function uninstallApp(server: FastMCP): void {
+  const schema = z.object({
+    id: z
+      .string()
+      .describe('App identifier (package name for Android, bundle ID for iOS)'),
+  });
+
+  server.addTool({
+    name: 'appium_uninstall_app',
+    description: 'Uninstall an app from the device.',
+    parameters: schema,
+    execute: async (args: z.infer<typeof schema>) => {
+      const { id } = args;
+      const driver = await getDriver();
+      if (!driver) {
+        throw new Error('No driver found');
+      }
+      try {
+        const platform = getPlatformName(driver);
+        const params =
+          platform === PLATFORM.android ? { appId: id } : { bundleId: id };
+        await execute(driver, 'mobile: removeApp', params);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: 'App uninstalled successfully',
+            },
+          ],
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to uninstall app. err: ${err.toString()}`,
+            },
+          ],
+        };
+      }
+    },
+  });
+}

package/src/tools/context/get-contexts.ts

@@ -0,0 +1,87 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import {
+  getDriver,
+  isAndroidUiautomator2DriverSession,
+  isRemoteDriverSession,
+} from '../../session-store.js';
+import {
+  createUIResource,
+  createContextSwitcherUI,
+  addUIResourceToResponse,
+} from '../../ui/mcp-ui-utils.js';
+import type { XCUITestDriver } from 'appium-xcuitest-driver';
+import {
+  getCurrentContext,
+  getContexts as _getContexts,
+} from '../../command.js';
+
+export default function getContexts(server: FastMCP): void {
+  server.addTool({
+    name: 'appium_get_contexts',
+    description:
+      'Get all available contexts in the current Appium session. Returns a list of context names including NATIVE_APP and any webview contexts (e.g., WEBVIEW_<id> or WEBVIEW_<package>).',
+    parameters: z.object({}),
+    annotations: {
+      readOnlyHint: true,
+      openWorldHint: false,
+    },
+    execute: async (args: any, context: any): Promise<any> => {
+      const driver = getDriver();
+      if (!driver) {
+        throw new Error('No driver found. Please create a session first.');
+      }
+
+      if (isRemoteDriverSession(driver)) {
+        throw new Error(
+          'Get context is not yet implemented for the remote driver'
+        );
+      }
+
+      try {
+        const [currentContext, contexts] = await Promise.all([
+          getCurrentContext(driver).catch(() => null),
+          _getContexts(driver).catch(() => []),
+        ]);
+
+        if (!contexts || contexts.length === 0) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: 'No contexts available.',
+              },
+            ],
+          };
+        }
+
+        const textResponse = {
+          content: [
+            {
+              type: 'text',
+              text: `Available contexts: ${JSON.stringify(contexts, null, 2)}\nCurrent context: ${currentContext || 'N/A'}`,
+            },
+          ],
+        };
+
+        // Add interactive context switcher UI
+        const uiResource = createUIResource(
+          `ui://appium-mcp/context-switcher/${Date.now()}`,
+          createContextSwitcherUI(contexts as string[], currentContext)
+        );
+
+        return addUIResourceToResponse(textResponse, uiResource);
+      } catch (err: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to get contexts. Error: ${err.toString()}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    },
+  });
+}

package/src/tools/context/switch-context.ts

@@ -0,0 +1,101 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import { getDriver, isRemoteDriverSession } from '../../session-store.js';
+import { getContexts, getCurrentContext, setContext } from '../../command.js';
+
+export default function switchContext(server: FastMCP): void {
+  const schema = z.object({
+    context: z
+      .string()
+      .describe(
+        'The name of the context to switch to. Common values: "NATIVE_APP" for native context, or "WEBVIEW_<id>" / "WEBVIEW_<package>" for webview contexts.'
+      ),
+  });
+
+  server.addTool({
+    name: 'appium_switch_context',
+    description:
+      'Switch to a specific context in the Appium session. Use this to switch between native app context (NATIVE_APP) and webview contexts (WEBVIEW_<id> or WEBVIEW_<package>). Use appium_get_contexts to see available contexts first.',
+    parameters: schema,
+    annotations: {
+      readOnlyHint: false,
+      openWorldHint: false,
+    },
+    execute: async (args: any, context: any): Promise<any> => {
+      const driver = getDriver();
+      if (!driver) {
+        throw new Error('No driver found. Please create a session first.');
+      }
+
+      if (isRemoteDriverSession(driver)) {
+        throw new Error(
+          'Get context is not yet implemented for the remote driver'
+        );
+      }
+
+      try {
+        const [currentContext, availableContexts] = await Promise.all([
+          getCurrentContext(driver).catch(() => null),
+          getContexts(driver).catch(() => [] as string[]),
+        ]);
+
+        if (currentContext === args.context) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Already on context "${args.context}".`,
+              },
+            ],
+          };
+        }
+
+        if (!availableContexts || availableContexts.length === 0) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: 'No contexts available. Cannot switch context.',
+              },
+            ],
+            isError: true,
+          };
+        }
+
+        if (!availableContexts.includes(args.context)) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Context "${args.context}" not found. Available contexts: ${JSON.stringify(availableContexts, null, 2)}`,
+              },
+            ],
+            isError: true,
+          };
+        }
+        await setContext(driver, args.context);
+        // Verify the switch was successful
+        const newContext = await getCurrentContext(driver);
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Successfully switched context from "${currentContext || 'N/A'}" to "${newContext}".`,
+            },
+          ],
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to switch context. Error: ${err.toString()}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    },
+  });
+}

package/src/tools/documentation/answer-appium.ts

@@ -0,0 +1,73 @@
+/**
+ * Tool to select mobile platform before creating a session
+ */
+import { z } from 'zod';
+import { answerAppiumQuery, initializeAppiumDocumentation } from './index.js';
+import log from '../../logger.js';
+
+export default function answerAppium(server: any): void {
+  server.addTool({
+    name: 'appium_documentation_query',
+    description: `Query Appium documentation using RAG (Retrieval-Augmented Generation).
+      This tool searches through indexed Appium documentation to answer questions about Appium features, setup, configuration, drivers, and usage.
+      `,
+    parameters: z.object({
+      query: z
+        .string()
+        .describe('The question or query about Appium documentation'),
+    }),
+    execute: async (args: any, context: any): Promise<any> => {
+      const query = args.query;
+      if (!query) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: 'Query parameter is required',
+            },
+          ],
+          isError: true,
+        };
+      }
+
+      try {
+        const result = await answerAppiumQuery({ query });
+        return {
+          content: [
+            {
+              type: 'text',
+              text: result.answer,
+            },
+          ],
+        };
+      } catch (docError) {
+        // If documentation query fails, try to initialize and retry once
+        try {
+          log.info('Documentation not initialized, initializing now...');
+          await initializeAppiumDocumentation();
+          const result = await answerAppiumQuery({ query });
+          return {
+            content: [
+              {
+                type: 'text',
+                text: result.answer,
+              },
+            ],
+          };
+        } catch (retryError) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Error querying Appium documentation: ${
+                  (retryError as Error).message
+                }. Please ensure the documentation is indexed first.`,
+              },
+            ],
+            isError: true,
+          };
+        }
+      }
+    },
+  });
+}

package/src/tools/documentation/index.ts

@@ -0,0 +1,98 @@
+/**
+ * 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';
+import log from '../../logger.js';
+
+/**
+ * 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');
+    log.info(`Initializing Appium documentation from: ${docsPath}`);
+    await indexAllMarkdownFiles(docsPath);
+    log.info('Appium documentation indexing completed');
+  } catch (error) {
+    log.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;
+    log.info(`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
+
+    log.info(
+      `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) {
+    log.error('Error querying Appium documentation:', error);
+    throw error;
+  }
+}