Feat: Implement fuzzy search and caching for App Live devices

Author: ruturaj-browserstack

package-lock.json

@@ -39,6 +39,7 @@
     "browserstack-local": "^1.5.6",
     "dotenv": "^16.5.0",
     "form-data": "^4.0.2",
+    "fuse.js": "^7.1.0",
     "pino": "^9.6.0",
     "pino-pretty": "^13.0.0",
     "zod": "^3.24.3"

package.json

@@ -0,0 +1,39 @@
+/**
+ * Creates a configured Fuse instance for token-based fuzzy search.
+ * @param list Array of items to search
+ * @param keys Keys in each item to index
+ * @param options Optional Fuse.js options overrides
+ */
+export async function createFuzzySearcher<T>(
+  list: T[],
+  keys: Array<keyof T | string>,
+  options?: any,
+): Promise<any> {
+  const { default: Fuse } = await import("fuse.js");
+
+  const defaultOptions = {
+    keys: keys as string[],
+    threshold: 0.6,
+    includeScore: true,
+    useExtendedSearch: false,
+    tokenize: true,
+    matchAllTokens: false,
+    ...options,
+  };
+
+  return new Fuse(list, defaultOptions);
+}
+
+/**
+ * Performs a fuzzy token search over any list, with dynamic keys and options.
+ */
+export async function fuzzySearch<T>(
+  list: T[],
+  keys: Array<keyof T | string>,
+  query: string,
+  limit: number = 5,
+  options?: any,
+): Promise<T[]> {
+  const fuse = await createFuzzySearcher(list, keys, options);
+  return fuse.search(query, { limit }).map((result: any) => result.item);
+}

src/lib/fuzzy.ts

@@ -0,0 +1,31 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+const CACHE_DIR = path.join(os.homedir(), ".browserstack", "app_live_cache");
+const CACHE_FILE = path.join(CACHE_DIR, "app_live.json");
+const TTL_MS = 24 * 60 * 60 * 1000; // 1 day
+
+/**
+ * Fetches and caches the App Live devices JSON with a 1-day TTL.
+ */
+export async function getAppLiveData(): Promise<any> {
+  if (!fs.existsSync(CACHE_DIR)) {
+    fs.mkdirSync(CACHE_DIR, { recursive: true });
+  }
+  if (fs.existsSync(CACHE_FILE)) {
+    const stats = fs.statSync(CACHE_FILE);
+    if (Date.now() - stats.mtimeMs < TTL_MS) {
+      return JSON.parse(fs.readFileSync(CACHE_FILE, "utf8"));
+    }
+  }
+  const response = await fetch(
+    "https://www.browserstack.com/list-of-browsers-and-platforms/app_live.json",
+  );
+  if (!response.ok) {
+    throw new Error(`Failed to fetch app live list: ${response.statusText}`);
+  }
+  const data = await response.json();
+  fs.writeFileSync(CACHE_FILE, JSON.stringify(data), "utf8");
+  return data;
+}

src/tools/applive-utils/device-cache.ts

@@ -0,0 +1,20 @@
+import { fuzzySearch } from "../../lib/fuzzy";
+import { DeviceEntry } from "./start-session";
+
+/**
+ * Fuzzy searches App Live device entries by name.
+ */
+export async function fuzzySearchDevices(
+  devices: DeviceEntry[],
+  query: string,
+  limit: number = 5,
+): Promise<DeviceEntry[]> {
+  const top_match = await fuzzySearch(
+    devices,
+    ["device", "display_name"],
+    query,
+    limit,
+  );
+  console.error("[fuzzySearchDevices] Top match:", top_match);
+  return top_match;
+}

src/tools/applive-utils/fuzzy-search.ts

@@ -1,41 +1,100 @@
 import childProcess from "child_process";
 import logger from "../../logger";
+import { getAppLiveData } from "./device-cache";
+import { fuzzySearchDevices } from "./fuzzy-search";
 import { sanitizeUrlParam } from "../../lib/utils";
+import { uploadApp } from "./upload-app";
+
+export interface DeviceEntry {
+  device: string;
+  display_name: string;
+  os: string;
+  os_version: string;
+  real_mobile: boolean;
+}
 
 interface StartSessionArgs {
-  appUrl: string;
+  appPath: string;
   desiredPlatform: "android" | "ios";
   desiredPhone: string;
   desiredPlatformVersion: string;
 }
 
+/**
+ * Starts an App Live session after filtering, fuzzy matching, and launching.
+ */
 export async function startSession(args: StartSessionArgs): Promise<string> {
-  // Sanitize all input parameters
-  const sanitizedArgs = {
-    appUrl: sanitizeUrlParam(args.appUrl),
-    desiredPlatform: sanitizeUrlParam(args.desiredPlatform),
-    desiredPhone: sanitizeUrlParam(args.desiredPhone),
-    desiredPlatformVersion: sanitizeUrlParam(args.desiredPlatformVersion),
-  };
-
-  // Get app hash ID and format phone name
-  const appHashedId = sanitizedArgs.appUrl.split("bs://").pop();
-  const desiredPhoneWithSpaces = sanitizedArgs.desiredPhone.replace(
-    /\s+/g,
-    "+",
+  const { appPath, desiredPlatform, desiredPhone } = args;
+  let { desiredPlatformVersion } = args;
+
+  const data = await getAppLiveData();
+  const allDevices: DeviceEntry[] = data.mobile.flatMap((group: any) =>
+    group.devices.map((dev: any) => ({ ...dev, os: group.os })),
+  );
+
+  // Exact filter by platform and version
+  if (
+    desiredPlatformVersion == "latest" ||
+    desiredPlatformVersion == "oldest"
+  ) {
+    const filtered = allDevices.filter((d) => d.os === desiredPlatform);
+    filtered.sort((a, b) => {
+      const versionA = parseFloat(a.os_version);
+      const versionB = parseFloat(b.os_version);
+      return desiredPlatformVersion === "latest"
+        ? versionB - versionA // descending for "latest"
+        : versionA - versionB; // ascending for specific version
+    });
+
+    const requiredVersion = filtered[0].os_version;
+
+    desiredPlatformVersion = requiredVersion;
+  }
+  const filtered = allDevices.filter(
+    (d) => d.os === desiredPlatform && d.os_version === desiredPlatformVersion,
+  );
+
+  // Fuzzy match
+  const matches = await fuzzySearchDevices(filtered, desiredPhone);
+
+  if (matches.length === 0) {
+    throw new Error(
+      `No devices found matching "${desiredPhone}" for ${desiredPlatform} ${desiredPlatformVersion} ${JSON.stringify(matches, null, 2)}`,
+    );
+  }
+  const exactMatch = matches.find(
+    (d) => d.display_name.toLowerCase() === desiredPhone.toLowerCase(),
+  );
+
+  if (exactMatch) {
+    matches.splice(0, matches.length, exactMatch); // Replace matches with the exact match
+  } else if (matches.length > 1) {
+    const names = matches.map((d) => d.display_name).join(", ");
+    throw new Error(
+      `Multiple devices found: [${names}]. Select one out of them.`,
+    );
+  }
+
+  const { app_url } = await uploadApp(appPath);
+
+  if (!app_url.match("bs://")) {
+    throw new Error("The app path is not a valid BrowserStack app URL.");
+  }
+
+  const device = matches[0];
+  const deviceParam = sanitizeUrlParam(
+    device.display_name.replace(/\s+/g, "+"),
   );
 
-  // Construct URL with encoded parameters
   const params = new URLSearchParams({
-    os: sanitizedArgs.desiredPlatform,
-    os_version: sanitizedArgs.desiredPlatformVersion,
-    app_hashed_id: appHashedId || "",
+    os: desiredPlatform,
+    os_version: desiredPlatformVersion,
+    app_hashed_id: app_url.split("bs://").pop() || "",
     scale_to_fit: "true",
     speed: "1",
     start: "true",
   });
-
-  const launchUrl = `https://app-live.browserstack.com/dashboard#${params.toString()}&device=${desiredPhoneWithSpaces}`;
+  const launchUrl = `https://app-live.browserstack.com/dashboard#${params.toString()}&device=${deviceParam}`;
 
   try {
     // Use platform-specific commands with proper escaping

src/tools/applive-utils/start-session.ts

@@ -2,7 +2,6 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import fs from "fs";
-import { uploadApp } from "./applive-utils/upload-app";
 import { startSession } from "./applive-utils/start-session";
 import logger from "../logger";
 
@@ -45,14 +44,8 @@ export async function startAppLiveSession(args: {
     throw new Error("The app path does not exist or is not readable.");
   }
 
-  const { app_url } = await uploadApp(args.appPath);
-
-  if (!app_url.match("bs://")) {
-    throw new Error("The app path is not a valid BrowserStack app URL.");
-  }
-
   const launchUrl = await startSession({
-    appUrl: app_url,
+    appPath: args.appPath,
     desiredPlatform: args.desiredPlatform as "android" | "ios",
     desiredPhone: args.desiredPhone,
     desiredPlatformVersion: args.desiredPlatformVersion,
@@ -81,7 +74,7 @@ export default function addAppLiveTools(server: McpServer) {
       desiredPlatformVersion: z
         .string()
         .describe(
-          "The platform version to run the app on. Example: '12.0' for Android devices or '16.0' for iOS devices",
+          "Specifies the platform version to run the app on. For example, use '12.0' for Android or '16.0' for iOS. If the user says 'latest', 'newest', or similar, normalize it to 'latest'. Likewise, convert terms like 'earliest' or 'oldest' to 'oldest'.",
         ),
       desiredPlatform: z
         .enum(["android", "ios"])

src/tools/applive.ts

@@ -43,23 +43,20 @@ describe('startAppLiveSession', () => {
   it('should successfully start an Android app live session', async () => {
     const result = await startAppLiveSession(validAndroidArgs);
 
-    expect(uploadApp).toHaveBeenCalledWith(validAndroidArgs.appPath);
     expect(startSession).toHaveBeenCalledWith({
-      appUrl: 'bs://123456',
+      appPath: '/path/to/app.apk',
       desiredPlatform: 'android',
       desiredPhone: validAndroidArgs.desiredPhone,
       desiredPlatformVersion: validAndroidArgs.desiredPlatformVersion
     });
     expect(result.content[0].text).toContain('Successfully started a session');
-    expect(result.content[0].text).toContain('https://app-live.browserstack.com/123456');
   });
 
   it('should successfully start an iOS app live session', async () => {
     const result = await startAppLiveSession(validiOSArgs);
 
-    expect(uploadApp).toHaveBeenCalledWith(validiOSArgs.appPath);
     expect(startSession).toHaveBeenCalledWith({
-      appUrl: 'bs://123456',
+      appPath: '/path/to/app.ipa',
       desiredPlatform: 'ios',
       desiredPhone: validiOSArgs.desiredPhone,
       desiredPlatformVersion: validiOSArgs.desiredPlatformVersion
@@ -106,13 +103,8 @@ describe('startAppLiveSession', () => {
     expect(logger.error).toHaveBeenCalled();
   });
 
-  it('should handle upload failure', async () => {
-    (uploadApp as jest.Mock).mockRejectedValue(new Error('Upload failed'));
-    await expect(startAppLiveSession(validAndroidArgs)).rejects.toThrow('Upload failed');
-  });
-
   it('should handle session start failure', async () => {
     (startSession as jest.Mock).mockRejectedValue(new Error('Session start failed'));
     await expect(startAppLiveSession(validAndroidArgs)).rejects.toThrow('Session start failed');
   });
-}); 
+});