appium-mcp 0.0.1 → 1.1.4

package/src/tools/interactions/get-text.ts

@@ -0,0 +1,47 @@
+import { FastMCP } from 'fastmcp/dist/FastMCP.js';
+import { z } from 'zod';
+import { getDriver } from '../session-store.js';
+import { elementUUIDScheme } from '../../schema.js';
+
+export default function getText(server: FastMCP): void {
+  const getTextSchema = z.object({
+    elementUUID: elementUUIDScheme,
+  });
+
+  server.addTool({
+    name: 'appium_get_text',
+    description: 'Get text from an element',
+    parameters: getTextSchema,
+    annotations: {
+      readOnlyHint: false,
+      openWorldHint: false,
+    },
+    execute: async (args: any, context: any): Promise<any> => {
+      const driver = getDriver();
+      if (!driver) {
+        throw new Error('No driver found');
+      }
+
+      try {
+        const text = await driver.getText(args.elementUUID);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Successfully got text ${text} from element ${args.elementUUID}`,
+            },
+          ],
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to get text from element ${args.elementUUID}. err: ${err.toString()}`,
+            },
+          ],
+        };
+      }
+    },
+  });
+}

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

@@ -0,0 +1,45 @@
+import { FastMCP } from 'fastmcp/dist/FastMCP.js';
+import { z } from 'zod';
+import { getDriver, getPlatformName } from '../session-store.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_installApp',
+    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 === 'Android' ? { appPath: path } : { app: path };
+        await (driver as any).execute('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/interactions/list-apps.ts

@@ -0,0 +1,65 @@
+import { FastMCP } from 'fastmcp/dist/FastMCP.js';
+import { z } from 'zod';
+import { getDriver, getPlatformName } from '../session-store.js';
+
+async function listAppsFromDevice(): Promise<any[]> {
+  const driver = await getDriver();
+  if (!driver) {
+    throw new Error('No driver found');
+  }
+
+  const platform = getPlatformName(driver);
+  if (platform === 'iOS') {
+    throw new Error('listApps is not yet implemented for iOS');
+  }
+
+  const appPackages = await driver.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();
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Installed apps: ${JSON.stringify(apps, null, 2)}`,
+            },
+          ],
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to list apps. err: ${err.toString()}`,
+            },
+          ],
+        };
+      }
+    },
+  });
+}

package/src/tools/interactions/screenshot.ts

@@ -0,0 +1,56 @@
+import { FastMCP } from 'fastmcp/dist/FastMCP.js';
+import { z } from 'zod';
+import { getDriver } from '../session-store.js';
+import { writeFile } from 'fs/promises';
+import { join } from 'path';
+
+export default function screenshot(server: FastMCP): void {
+  server.addTool({
+    name: 'appium_screenshot',
+    description:
+      'Take a screenshot of the current screen and return as PNG image',
+    annotations: {
+      readOnlyHint: false,
+      openWorldHint: false,
+    },
+    execute: async (args: any, context: any): Promise<any> => {
+      const driver = getDriver();
+      if (!driver) {
+        throw new Error('No driver found');
+      }
+
+      try {
+        const screenshotBase64 = await driver.getScreenshot();
+
+        // Convert base64 to buffer
+        const screenshotBuffer = Buffer.from(screenshotBase64, 'base64');
+
+        // Generate filename with timestamp
+        const timestamp = Date.now();
+        const filename = `screenshot_${timestamp}.png`;
+        const filepath = join(process.cwd(), filename);
+
+        // Save screenshot to disk
+        await writeFile(filepath, screenshotBuffer);
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Screenshot saved successfully to: ${filename}`,
+            },
+          ],
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to take screenshot. err: ${err.toString()}`,
+            },
+          ],
+        };
+      }
+    },
+  });
+}

package/src/tools/interactions/set-value.ts

@@ -0,0 +1,48 @@
+import { FastMCP } from 'fastmcp/dist/FastMCP.js';
+import { z } from 'zod';
+import { getDriver } from '../session-store.js';
+import { elementUUIDScheme } from '../../schema.js';
+
+export default function setValue(server: FastMCP): void {
+  const setValueSchema = z.object({
+    elementUUID: elementUUIDScheme,
+    text: z.string().describe('The text to enter'),
+  });
+
+  server.addTool({
+    name: 'appium_set_value',
+    description: 'Enter text into an element',
+    parameters: setValueSchema,
+    annotations: {
+      readOnlyHint: false,
+      openWorldHint: false,
+    },
+    execute: async (args: any, context: any): Promise<any> => {
+      const driver = getDriver();
+      if (!driver) {
+        throw new Error('No driver found');
+      }
+
+      try {
+        await driver.setValue(args.text, args.elementUUID);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Successfully set value ${args.text} into element ${args.elementUUID}`,
+            },
+          ],
+        };
+      } catch (err: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to set value ${args.text} into element ${args.elementUUID}. err: ${err.toString()}`,
+            },
+          ],
+        };
+      }
+    },
+  });
+}

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

@@ -0,0 +1,47 @@
+import { FastMCP } from 'fastmcp/dist/FastMCP.js';
+import { z } from 'zod';
+import { getDriver, getPlatformName } from '../session-store.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_terminateApp',
+    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 === 'Android' ? { appId: id } : { bundleId: id };
+        await (driver as any).execute('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/interactions/uninstall-app.ts

@@ -0,0 +1,47 @@
+import { FastMCP } from 'fastmcp/dist/FastMCP.js';
+import { z } from 'zod';
+import { getDriver, getPlatformName } from '../session-store.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_uninstallApp',
+    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 === 'Android' ? { appId: id } : { bundleId: id };
+        await (driver as any).execute('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/locators.ts

@@ -0,0 +1,83 @@
+/**
+ * Tool to get page source from the Android session
+ *
+ * TOOL EXTENSION GUIDE:
+ * This tool demonstrates the traditional approach where metadata is defined inline.
+ *
+ * ALTERNATIVE APPROACH: You can also use YAML metadata files for better separation.
+ * See src/tools/metadata/ for examples and src/tools/scroll-with-yaml.example.ts
+ *
+ * For detailed documentation on adding tools, see docs/CONTRIBUTING.md
+ */
+import { z } from 'zod';
+import { getDriver } from './session-store.js';
+import { generateAllElementLocators } from '../locators/generate-all-locators.js';
+
+export default function generateLocators(server: any): void {
+  server.addTool({
+    name: 'generate_locators',
+    description: `Generate locators for the current page.`,
+    parameters: z.object({}),
+    annotations: {
+      readOnlyHint: true,
+      openWorldHint: false,
+    },
+    execute: async (args: any, { log }: any): Promise<any> => {
+      log.info('Getting page source');
+      try {
+        // Check for active driver session
+
+        const driver = getDriver();
+        if (!driver) {
+          throw new Error(
+            'No active driver session. Please create a session first.'
+          );
+        }
+
+        console.log('Getting page source');
+
+        try {
+          // Get the page source from the driver
+          const pageSource = await driver.getPageSource();
+          const driverName = (await driver.caps.automationName).toLowerCase();
+          if (!pageSource) {
+            throw new Error('Page source is empty or null');
+          }
+          const sampleXML = pageSource;
+          const allElements = generateAllElementLocators(
+            sampleXML,
+            true,
+            driverName
+          );
+          const interactableElements = generateAllElementLocators(
+            sampleXML,
+            true,
+            driverName,
+            {
+              fetchableOnly: true,
+            }
+          );
+          return {
+            content: [
+              {
+                type: 'text',
+                text: JSON.stringify({
+                  interactableElements,
+                  message: 'Page source retrieved successfully',
+                  instruction: `This the locators for the current page. Use this to generate code for the current page.
+                     Using the template provided by generate://code-with-locators resource.`,
+                }),
+              },
+            ],
+          };
+        } catch (parseError: any) {
+          console.error('Error parsing XML:', parseError);
+          throw new Error(`Failed to parse XML: ${parseError.message}`);
+        }
+      } catch (error: any) {
+        console.error('Error getting page source:', error);
+        throw new Error(`Failed to get page source: ${error.message}`);
+      }
+    },
+  });
+}

package/src/tools/scroll-to-element.ts

@@ -0,0 +1,188 @@
+import { getDriver, getPlatformName } from './session-store.js';
+import { z } from 'zod';
+
+const scrollToElementSchema = z.object({
+  strategy: z.enum([
+    'xpath',
+    'id',
+    'name',
+    'class name',
+    'accessibility id',
+    'css selector',
+    '-android uiautomator',
+    '-ios predicate string',
+    '-ios class chain',
+  ]),
+  selector: z.string().describe('The selector to find the element'),
+  direction: z
+    .enum(['up', 'down'])
+    .default('down')
+    .describe('Direction to scroll when searching for the element'),
+});
+
+const getValue = (xpath: string, expression: string): string => {
+  // Extracts the value from an XPath expression.
+  let start = xpath.indexOf(expression) + expression.length;
+  start = xpath.indexOf("'", start) + 1;
+  let end = xpath.indexOf("'", start);
+  return xpath.substring(start, end);
+};
+
+const transformXPath = (
+  xpath: string
+): { strategy: string; selector: string } => {
+  // normalize xpath expression by replacing " by '
+  xpath = xpath.replace(/"/g, "'");
+  if (xpath.includes('@text='))
+    return { strategy: 'text', selector: getValue(xpath, '@text=') };
+
+  if (xpath.includes('@content-desc='))
+    return {
+      strategy: 'description',
+      selector: getValue(xpath, '@content-desc='),
+    };
+
+  if (xpath.includes('contains(@text,'))
+    return {
+      strategy: 'textContains',
+      selector: getValue(xpath, 'contains(@text,'),
+    };
+
+  if (xpath.includes('contains(@content-desc,'))
+    return {
+      strategy: 'descriptionContains',
+      selector: getValue(xpath, 'contains(@content-desc,'),
+    };
+
+  throw new Error(
+    `Unsupported XPath expression: ${xpath}. Supported expressions are: @text, @content-desc, contains(@text, ...), contains(@content-desc, ...)`
+  );
+};
+
+const transformLocator = (
+  strategy: string,
+  selector: string
+): { strategy: string; selector: string } => {
+  if (strategy === 'id') return { strategy: 'resourceId', selector };
+  if (strategy === 'xpath') return transformXPath(selector);
+  if (strategy === 'class name') return { strategy: 'className', selector };
+
+  return { strategy, selector };
+};
+
+async function performAndroidScroll(
+  driver: any,
+  args: any,
+  direction: string
+): Promise<void> {
+  // Use UiAutomator scroll gestures for Android
+  const scrollDirection =
+    direction === 'up' ? 'scrollBackward' : 'scrollForward';
+  const scrollCommand = `new UiScrollable(new UiSelector().scrollable(true)).${scrollDirection}()`;
+
+  try {
+    await driver.findElement('-android uiautomator', scrollCommand);
+  } catch (error) {
+    // If UiScrollable fails, try touch actions
+    const { width, height } = await driver.getWindowSize();
+    const startX = width / 2;
+    const startY = direction === 'up' ? height * 0.3 : height * 0.7;
+    const endY = direction === 'up' ? height * 0.7 : height * 0.3;
+
+    await driver.touchAction([
+      { action: 'press', x: startX, y: startY },
+      { action: 'wait', ms: 500 },
+      { action: 'moveTo', x: startX, y: endY },
+      { action: 'release' },
+    ]);
+  }
+}
+
+async function performiOSScroll(driver: any, direction: string): Promise<void> {
+  // Use iOS mobile commands for scrolling
+  const { width, height } = await driver.getWindowSize();
+
+  await driver.execute('mobile: scroll', {
+    direction: direction,
+    startX: width / 2,
+    startY: direction === 'up' ? height * 0.3 : height * 0.7,
+    endX: width / 2,
+    endY: direction === 'up' ? height * 0.7 : height * 0.3,
+  });
+}
+
+export default function scrollToElement(server: any): void {
+  server.addTool({
+    name: 'appium_scroll_to_element',
+    description: 'Scrolls the current screen till a certain element is visible',
+    parameters: scrollToElementSchema,
+    annotations: {
+      readOnlyHint: false,
+      openWorldHint: false,
+    },
+    execute: async (args: any, context: any): Promise<any> => {
+      const driver = getDriver();
+      if (!driver) {
+        throw new Error(
+          'No active driver session. Please create a session first.'
+        );
+      }
+
+      try {
+        const platform = getPlatformName(driver);
+
+        // First try to find the element directly (it might already be in viewport)
+        try {
+          const element = await driver.findElement(
+            args.strategy,
+            args.selector
+          );
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Element ${args.selector} is already visible on screen.`,
+              },
+            ],
+          };
+        } catch (error) {
+          const direction = args.direction || 'down';
+          switch (platform) {
+            case 'Android':
+              await performAndroidScroll(driver, args, direction);
+              break;
+            case 'iOS':
+              await performiOSScroll(driver, direction);
+              break;
+            default:
+              throw new Error(
+                'Unsupported driver type. This tool only supports Android and iOS drivers.'
+              );
+          }
+
+          const element = await driver.findElement(
+            args.strategy,
+            args.selector
+          );
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Successfully scrolled found element ${args.selector} after initial scroll.`,
+              },
+            ],
+          };
+        }
+      } catch (err: any) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Failed to scroll and find element. Error: ${err.toString()}`,
+            },
+          ],
+        };
+      }
+    },
+  });
+}