Feat: Add App Automate + Appium tool for BrowserStack integration

Author: tech-sushant

src/index.ts

@@ -12,6 +12,7 @@ import addBrowserLiveTools from "./tools/live";
 import addAccessibilityTools from "./tools/accessibility";
 import addAutomateTools from "./tools/automate";
 import addTestManagementTools from "./tools/testmanagement";
+import addAppAutomationTools from "./tools/appautomate";
 import { trackMCP } from "./lib/instrumentation";
 
 function registerTools(server: McpServer) {
@@ -22,6 +23,7 @@ function registerTools(server: McpServer) {
   addAccessibilityTools(server);
   addAutomateTools(server);
   addTestManagementTools(server);
+  addAppAutomationTools(server);
 }
 
 // Create an MCP server

src/lib/device-cache.ts

@@ -6,17 +6,26 @@ const CACHE_DIR = path.join(os.homedir(), ".browserstack", "combined_cache");
 const CACHE_FILE = path.join(CACHE_DIR, "data.json");
 const TTL_MS = 24 * 60 * 60 * 1000; // 1 day
 
-const URLS = {
-  live: "https://www.browserstack.com/list-of-browsers-and-platforms/live.json",
-  app_live:
+export enum BrowserStackProducts {
+  LIVE = "live",
+  APP_LIVE = "app_live",
+  APP_AUTOMATE = "app_automate",
+}
+
+const URLS: Record<BrowserStackProducts, string> = {
+  [BrowserStackProducts.LIVE]:
+    "https://www.browserstack.com/list-of-browsers-and-platforms/live.json",
+  [BrowserStackProducts.APP_LIVE]:
     "https://www.browserstack.com/list-of-browsers-and-platforms/app_live.json",
+  [BrowserStackProducts.APP_AUTOMATE]:
+    "https://www.browserstack.com/list-of-browsers-and-platforms/app_automate.json",
 };
 
 /**
- * Fetches and caches both BrowserStack datasets (live + app_live) with a shared TTL.
+ * Fetches and caches BrowserStack datasets (live + app_live + app_automate) with a shared TTL.
  */
 export async function getDevicesAndBrowsers(
-  type: "live" | "app_live",
+  type: BrowserStackProducts,
 ): Promise<any> {
   if (!fs.existsSync(CACHE_DIR)) {
     fs.mkdirSync(CACHE_DIR, { recursive: true });
@@ -37,23 +46,19 @@ export async function getDevicesAndBrowsers(
     }
   }
 
-  const [liveRes, appLiveRes] = await Promise.all([
-    fetch(URLS.live),
-    fetch(URLS.app_live),
-  ]);
+  const liveRes = await fetch(URLS[type]);
 
-  if (!liveRes.ok || !appLiveRes.ok) {
+  if (!liveRes.ok) {
     throw new Error(
-      `Failed to fetch configuration from BrowserStack : live=${liveRes.statusText}, app_live=${appLiveRes.statusText}`,
+      `Failed to fetch configuration from BrowserStack : ${type}=${liveRes.statusText}`,
     );
   }
 
-  const [liveData, appLiveData] = await Promise.all([
-    liveRes.json(),
-    appLiveRes.json(),
-  ]);
+  const data = await liveRes.json();
 
-  cache = { live: liveData, app_live: appLiveData };
+  cache = {
+    [type]: data,
+  };
   fs.writeFileSync(CACHE_FILE, JSON.stringify(cache), "utf8");
 
   return cache[type];

src/tools/appautomate-utils/appautomate.ts

@@ -0,0 +1,156 @@
+import fs from "fs";
+import axios from "axios";
+import config from "../../config";
+import FormData from "form-data";
+import { customFuzzySearch } from "../../lib/fuzzy";
+
+interface Device {
+  device: string;
+  display_name: string;
+  os_version: string;
+  real_mobile: boolean;
+}
+
+interface UploadResponse {
+  app_url: string;
+  custom_id?: string;
+  shareable_id?: string;
+}
+
+/**
+ * Finds devices that exactly match the provided display name.
+ * Uses fuzzy search first, and then filters for exact case-insensitive match.
+ */
+export function findMatchingDevice(
+  devices: Device[],
+  deviceName: string,
+): Device[] {
+  const matches = customFuzzySearch(devices, ["display_name"], deviceName, 5);
+
+  if (matches.length === 0) {
+    const availableDevices = [
+      ...new Set(devices.map((d) => d.display_name)),
+    ].join(", ");
+    throw new Error(
+      `No devices found matching "${deviceName}". Available devices: ${availableDevices}`,
+    );
+  }
+
+  const exactMatches = matches.filter(
+    (m) => m.display_name.toLowerCase() === deviceName.toLowerCase(),
+  );
+
+  if (exactMatches.length === 0) {
+    const suggestions = [...new Set(matches.map((d) => d.display_name))].join(
+      ", ",
+    );
+    throw new Error(
+      `Alternative devices found: ${suggestions}. Please select one of these exact device names.`,
+    );
+  }
+  return exactMatches;
+}
+
+/**
+ * Extracts all unique OS versions from a device list and sorts them.
+ */
+export function getDeviceVersions(devices: Device[]): string[] {
+  return [...new Set(devices.map((d) => d.os_version))].sort();
+}
+
+/**
+ * Resolves the requested platform version against available versions.
+ * Supports 'latest' and 'oldest' as dynamic selectors.
+ */
+export function resolveVersion(
+  versions: string[],
+  requestedVersion: string,
+): string {
+  if (requestedVersion === "latest") {
+    return versions[versions.length - 1];
+  }
+
+  if (requestedVersion === "oldest") {
+    return versions[0];
+  }
+
+  const match = versions.find((v) => v === requestedVersion);
+  if (!match) {
+    throw new Error(
+      `Version "${requestedVersion}" not found. Available versions: ${versions.join(", ")}`,
+    );
+  }
+  return match;
+}
+
+/**
+ * Validates the input arguments for taking app screenshots.
+ * Checks for presence and correctness of platform, device, and file types.
+ */
+export function validateArgs(args: {
+  desiredPlatform: string;
+  desiredPlatformVersion: string;
+  appPath: string;
+  desiredPhone: string;
+}): void {
+  const { desiredPlatform, desiredPlatformVersion, appPath, desiredPhone } =
+    args;
+
+  if (!desiredPlatform || !desiredPhone) {
+    throw new Error(
+      "Missing required arguments: desiredPlatform and desiredPhone are required",
+    );
+  }
+
+  if (!desiredPlatformVersion) {
+    throw new Error(
+      "Missing required arguments: desiredPlatformVersion is required",
+    );
+  }
+
+  if (!appPath) {
+    throw new Error("You must provide an appPath.");
+  }
+
+  if (desiredPlatform === "android" && !appPath.endsWith(".apk")) {
+    throw new Error("You must provide a valid Android app path (.apk).");
+  }
+
+  if (desiredPlatform === "ios" && !appPath.endsWith(".ipa")) {
+    throw new Error("You must provide a valid iOS app path (.ipa).");
+  }
+}
+
+/**
+ * Uploads an application file to Automate and returns the app URL
+ */
+export async function uploadApp(appPath: string): Promise<string> {
+  const filePath = appPath;
+
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`File not found at path: ${filePath}`);
+  }
+
+  const formData = new FormData();
+  formData.append("file", fs.createReadStream(filePath));
+
+  const response = await axios.post<UploadResponse>(
+    "https://api-cloud.browserstack.com/app-automate/upload",
+    formData,
+    {
+      headers: {
+        ...formData.getHeaders(),
+      },
+      auth: {
+        username: config.browserstackUsername,
+        password: config.browserstackAccessKey,
+      },
+    },
+  );
+
+  if (response.data.app_url) {
+    return response.data.app_url;
+  } else {
+    throw new Error(`Failed to upload app: ${response.data}`);
+  }
+}