@browserstack/mcp-server 1.0.6 → 1.0.9

package/README.md

@@ -88,7 +88,7 @@ Use the following prompts to run/debug/fix your **automated tests** on BrowserSt
 
 1. **Create a BrowserStack Account**
 
-   - Sign up for [BrowserStack](https://www.browserstack.com/signup) if you don't have an account already.
+   - Sign up for [BrowserStack](https://www.browserstack.com/users/sign_up) if you don't have an account already.
 
    - ℹ️ If you have an open-source project, we'll be able to provide you with a [free plan](https://www.browserstack.com/open-source).
    <div align="center">
@@ -154,6 +154,14 @@ Use the following prompts to run/debug/fix your **automated tests** on BrowserSt
    }
    ```
 
+### Installing via Smithery
+
+To install BrowserStack Test Platform Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@browserstack/mcp-server):
+
+```bash
+npx -y @smithery/cli install @browserstack/mcp-server --client claude
+```
+
 ## 🤝 Recommended MCP Clients
 
 - We recommend using **Github Copilot or Cursor** for automated testing + debugging use cases.

package/dist/lib/fuzzy.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.customFuzzySearch = customFuzzySearch;
+// 1. Compute Levenshtein distance between two strings
+function levenshtein(a, b) {
+    const dp = Array(a.length + 1)
+        .fill(0)
+        .map(() => Array(b.length + 1).fill(0));
+    for (let i = 0; i <= a.length; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= b.length; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, // deletion
+            dp[i][j - 1] + 1, // insertion
+            dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+    }
+    return dp[a.length][b.length];
+}
+// 2. Score one item against the query (normalized score 0–1)
+function scoreItem(item, keys, queryTokens) {
+    let best = Infinity;
+    for (const key of keys) {
+        const field = String(item[key] ?? "").toLowerCase();
+        const fieldTokens = field.split(/\s+/);
+        const tokenScores = queryTokens.map((qt) => {
+            const minNormalized = Math.min(...fieldTokens.map((ft) => {
+                const rawDist = levenshtein(ft, qt);
+                const maxLen = Math.max(ft.length, qt.length);
+                return maxLen === 0 ? 0 : rawDist / maxLen; // normalized 0–1
+            }));
+            return minNormalized;
+        });
+        const avg = tokenScores.reduce((a, b) => a + b, 0) / tokenScores.length;
+        best = Math.min(best, avg);
+    }
+    return best;
+}
+// 3. The search entrypoint
+function customFuzzySearch(list, keys, query, limit = 5, maxDistance = 0.6) {
+    const q = query.toLowerCase().trim();
+    const queryTokens = q.split(/\s+/);
+    return list
+        .map((item) => ({ item, score: scoreItem(item, keys, queryTokens) }))
+        .filter((x) => x.score <= maxDistance)
+        .sort((a, b) => a.score - b.score)
+        .slice(0, limit)
+        .map((x) => x.item);
+}

package/dist/tools/applive-utils/device-cache.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAppLiveData = getAppLiveData;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const CACHE_DIR = path_1.default.join(os_1.default.homedir(), ".browserstack", "app_live_cache");
+const CACHE_FILE = path_1.default.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.
+ */
+async function getAppLiveData() {
+    if (!fs_1.default.existsSync(CACHE_DIR)) {
+        fs_1.default.mkdirSync(CACHE_DIR, { recursive: true });
+    }
+    if (fs_1.default.existsSync(CACHE_FILE)) {
+        const stats = fs_1.default.statSync(CACHE_FILE);
+        if (Date.now() - stats.mtimeMs < TTL_MS) {
+            return JSON.parse(fs_1.default.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_1.default.writeFileSync(CACHE_FILE, JSON.stringify(data), "utf8");
+    return data;
+}

package/dist/tools/applive-utils/fuzzy-search.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fuzzySearchDevices = fuzzySearchDevices;
+const fuzzy_1 = require("../../lib/fuzzy");
+/**
+ * Fuzzy searches App Live device entries by name.
+ */
+async function fuzzySearchDevices(devices, query, limit = 5) {
+    const top_match = (0, fuzzy_1.customFuzzySearch)(devices, ["device", "display_name"], query, limit);
+    return top_match;
+}

package/dist/tools/applive-utils/start-session.js

@@ -6,30 +6,138 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.startSession = startSession;
 const child_process_1 = __importDefault(require("child_process"));
 const logger_1 = __importDefault(require("../../logger"));
+const device_cache_1 = require("./device-cache");
+const fuzzy_search_1 = require("./fuzzy-search");
 const utils_1 = require("../../lib/utils");
+const upload_app_1 = require("./upload-app");
+/**
+ * Starts an App Live session after filtering, fuzzy matching, and launching.
+ * @param args - The arguments for starting the session.
+ * @returns The launch URL for the session.
+ * @throws Will throw an error if no devices are found or if the app URL is invalid.
+ */
 async function startSession(args) {
-    // Sanitize all input parameters
-    const sanitizedArgs = {
-        appUrl: (0, utils_1.sanitizeUrlParam)(args.appUrl),
-        desiredPlatform: (0, utils_1.sanitizeUrlParam)(args.desiredPlatform),
-        desiredPhone: (0, utils_1.sanitizeUrlParam)(args.desiredPhone),
-        desiredPlatformVersion: (0, utils_1.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, "+");
-    // Construct URL with encoded parameters
+    const { appPath, desiredPlatform, desiredPhone } = args;
+    let { desiredPlatformVersion } = args;
+    const data = await (0, device_cache_1.getAppLiveData)();
+    const allDevices = data.mobile.flatMap((group) => group.devices.map((dev) => ({ ...dev, os: group.os })));
+    desiredPlatformVersion = resolvePlatformVersion(allDevices, desiredPlatform, desiredPlatformVersion);
+    const filteredDevices = filterDevicesByPlatformAndVersion(allDevices, desiredPlatform, desiredPlatformVersion);
+    const matches = await (0, fuzzy_search_1.fuzzySearchDevices)(filteredDevices, desiredPhone);
+    const selectedDevice = validateAndSelectDevice(matches, desiredPhone, desiredPlatform, desiredPlatformVersion);
+    const { app_url } = await (0, upload_app_1.uploadApp)(appPath);
+    validateAppUrl(app_url);
+    const launchUrl = constructLaunchUrl(app_url, selectedDevice, desiredPlatform, desiredPlatformVersion);
+    openBrowser(launchUrl);
+    return launchUrl;
+}
+/**
+ * Resolves the platform version based on the desired platform and version.
+ * @param allDevices - The list of all devices.
+ * @param desiredPlatform - The desired platform (android or ios).
+ * @param desiredPlatformVersion - The desired platform version.
+ * @returns The resolved platform version.
+ * @throws Will throw an error if the platform version is not valid.
+ */
+function resolvePlatformVersion(allDevices, desiredPlatform, desiredPlatformVersion) {
+    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
+                : versionA - versionB;
+        });
+        return filtered[0].os_version;
+    }
+    return desiredPlatformVersion;
+}
+/**
+ * Filters devices based on the desired platform and version.
+ * @param allDevices - The list of all devices.
+ * @param desiredPlatform - The desired platform (android or ios).
+ * @param desiredPlatformVersion - The desired platform version.
+ * @returns The filtered list of devices.
+ * @throws Will throw an error if the platform version is not valid.
+ */
+function filterDevicesByPlatformAndVersion(allDevices, desiredPlatform, desiredPlatformVersion) {
+    return allDevices.filter((d) => {
+        if (d.os !== desiredPlatform)
+            return false;
+        try {
+            const versionA = parseFloat(d.os_version);
+            const versionB = parseFloat(desiredPlatformVersion);
+            return versionA === versionB;
+        }
+        catch {
+            return d.os_version === desiredPlatformVersion;
+        }
+    });
+}
+/**
+ * Validates the selected device and handles multiple matches.
+ * @param matches - The list of device matches.
+ * @param desiredPhone - The desired phone name.
+ * @param desiredPlatform - The desired platform (android or ios).
+ * @param desiredPlatformVersion - The desired platform version.
+ * @returns The selected device entry.
+ */
+function validateAndSelectDevice(matches, desiredPhone, desiredPlatform, desiredPlatformVersion) {
+    if (matches.length === 0) {
+        throw new Error(`No devices found matching "${desiredPhone}" for ${desiredPlatform} ${desiredPlatformVersion}`);
+    }
+    const exactMatch = matches.find((d) => d.display_name.toLowerCase() === desiredPhone.toLowerCase());
+    if (exactMatch) {
+        return exactMatch;
+    }
+    else if (matches.length >= 1) {
+        const names = matches.map((d) => d.display_name).join(", ");
+        const error_message = matches.length === 1
+            ? `Alternative device found: ${names}. Would you like to use it?`
+            : `Multiple devices found: ${names}. Please select one.`;
+        throw new Error(`${error_message}`);
+    }
+    return matches[0];
+}
+/**
+ * Validates the app URL.
+ * @param appUrl - The app URL to validate.
+ * @throws Will throw an error if the app URL is not valid.
+ */
+function validateAppUrl(appUrl) {
+    if (!appUrl.match("bs://")) {
+        throw new Error("The app path is not a valid BrowserStack app URL.");
+    }
+}
+/**
+ * Constructs the launch URL for the App Live session.
+ * @param appUrl - The app URL.
+ * @param device - The selected device entry.
+ * @param desiredPlatform - The desired platform (android or ios).
+ * @param desiredPlatformVersion - The desired platform version.
+ * @returns The constructed launch URL.
+ */
+function constructLaunchUrl(appUrl, device, desiredPlatform, desiredPlatformVersion) {
+    const deviceParam = (0, utils_1.sanitizeUrlParam)(device.display_name.replace(/\s+/g, "+"));
     const params = new URLSearchParams({
-        os: sanitizedArgs.desiredPlatform,
-        os_version: sanitizedArgs.desiredPlatformVersion,
-        app_hashed_id: appHashedId || "",
+        os: desiredPlatform,
+        os_version: desiredPlatformVersion,
+        app_hashed_id: appUrl.split("bs://").pop() || "",
         scale_to_fit: "true",
         speed: "1",
         start: "true",
     });
-    const launchUrl = `https://app-live.browserstack.com/dashboard#${params.toString()}&device=${desiredPhoneWithSpaces}`;
+    return `https://app-live.browserstack.com/dashboard#${params.toString()}&device=${deviceParam}`;
+}
+/**
+ * Opens the launch URL in the default browser.
+ * @param launchUrl - The URL to open.
+ * @throws Will throw an error if the browser fails to open.
+ */
+function openBrowser(launchUrl) {
     try {
-        // Use platform-specific commands with proper escaping
         const command = process.platform === "darwin"
             ? ["open", launchUrl]
             : process.platform === "win32"
@@ -40,16 +148,12 @@ async function startSession(args) {
             stdio: "ignore",
             detached: true,
         });
-        // Handle process errors
         child.on("error", (error) => {
             logger_1.default.error(`Failed to open browser automatically: ${error}. Please open this URL manually: ${launchUrl}`);
         });
-        // Unref the child process to allow the parent to exit
         child.unref();
-        return launchUrl;
     }
     catch (error) {
         logger_1.default.error(`Failed to open browser automatically: ${error}. Please open this URL manually: ${launchUrl}`);
-        return launchUrl;
     }
 }

package/dist/tools/applive.js

@@ -7,7 +7,6 @@ exports.startAppLiveSession = startAppLiveSession;
 exports.default = addAppLiveTools;
 const zod_1 = require("zod");
 const fs_1 = __importDefault(require("fs"));
-const upload_app_1 = require("./applive-utils/upload-app");
 const start_session_1 = require("./applive-utils/start-session");
 const logger_1 = __importDefault(require("../logger"));
 /**
@@ -40,12 +39,8 @@ async function startAppLiveSession(args) {
         logger_1.default.error("The app path does not exist or is not readable: %s", error);
         throw new Error("The app path does not exist or is not readable.");
     }
-    const { app_url } = await (0, upload_app_1.uploadApp)(args.appPath);
-    if (!app_url.match("bs://")) {
-        throw new Error("The app path is not a valid BrowserStack app URL.");
-    }
     const launchUrl = await (0, start_session_1.startSession)({
-        appUrl: app_url,
+        appPath: args.appPath,
         desiredPlatform: args.desiredPlatform,
         desiredPhone: args.desiredPhone,
         desiredPlatformVersion: args.desiredPlatformVersion,
@@ -66,7 +61,7 @@ function addAppLiveTools(server) {
             .describe("The full name of the device to run the app on. Example: 'iPhone 12 Pro' or 'Samsung Galaxy S20' or 'Google Pixel 6'. Always ask the user for the device they want to use, do not assume it. "),
         desiredPlatformVersion: zod_1.z
             .string()
-            .describe("The platform version to run the app on. Example: '12.0' for Android devices or '16.0' for iOS devices"),
+            .describe("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: zod_1.z
             .enum(["android", "ios"])
             .describe("Which platform to run on, examples: 'android', 'ios'. Set this based on the app path provided."),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserstack/mcp-server",
-  "version": "1.0.6",
+  "version": "1.0.9",
   "description": "BrowserStack's Official MCP Server",
   "main": "dist/index.js",
   "repository": {