@browserstack/mcp-server 1.1.3 → 1.1.5

package/dist/lib/local.js

@@ -65,15 +65,19 @@ export async function killExistingBrowserStackLocalProcesses() {
         // Continue execution as there may not be any processes running
     }
 }
-export async function ensureLocalBinarySetup() {
+export async function ensureLocalBinarySetup(localIdentifier) {
     logger.info("Ensuring local binary setup as it is required for private URLs...");
     const localBinary = new Local();
     await killExistingBrowserStackLocalProcesses();
+    const requestBody = {
+        key: config.browserstackAccessKey,
+        username: config.browserstackUsername,
+    };
+    if (localIdentifier) {
+        requestBody.localIdentifier = localIdentifier;
+    }
     return await new Promise((resolve, reject) => {
-        localBinary.start({
-            key: config.browserstackAccessKey,
-            username: config.browserstackUsername,
-        }, (error) => {
+        localBinary.start(requestBody, (error) => {
             if (error) {
                 logger.error(`Unable to start BrowserStack Local... please check your credentials and try again. Error: ${error}`);
                 reject(new Error(`Unable to configure local tunnel binary, please check your credentials and try again. Error: ${error}`));

package/dist/tools/accessiblity-utils/report-parser.js

@@ -1,6 +1,6 @@
 import fetch from "node-fetch";
 import { parse } from "csv-parse/sync";
-export async function parseAccessibilityReportFromCSV(reportLink, { maxCharacterLength = 10_000, nextPage = 0 } = {}) {
+export async function parseAccessibilityReportFromCSV(reportLink, { maxCharacterLength = 5000, nextPage = 0 } = {}) {
     // 1) Download & parse
     const res = await fetch(reportLink);
     if (!res.ok)

package/dist/tools/accessiblity-utils/scanner.js

@@ -1,13 +1,55 @@
 import axios from "axios";
 import config from "../../config.js";
+import logger from "../../logger.js";
+import { isLocalURL, ensureLocalBinarySetup, killExistingBrowserStackLocalProcesses, } from "../../lib/local.js";
 export class AccessibilityScanner {
     auth = {
         username: config.browserstackUsername,
         password: config.browserstackAccessKey,
     };
     async startScan(name, urlList) {
+        // Check if any URL is local
+        const hasLocal = urlList.some(isLocalURL);
+        const localIdentifier = crypto.randomUUID();
+        const localHosts = new Set(["127.0.0.1", "localhost", "0.0.0.0"]);
+        const BS_LOCAL_DOMAIN = "bs-local.com";
+        if (hasLocal) {
+            await ensureLocalBinarySetup(localIdentifier);
+        }
+        else {
+            await killExistingBrowserStackLocalProcesses();
+        }
+        const transformedUrlList = urlList.map((url) => {
+            try {
+                const parsed = new URL(url);
+                if (localHosts.has(parsed.hostname)) {
+                    parsed.hostname = BS_LOCAL_DOMAIN;
+                    return parsed.toString();
+                }
+                return url;
+            }
+            catch (e) {
+                logger.warn(`[AccessibilityScan] Invalid URL skipped: ${e}`);
+                return url;
+            }
+        });
+        const baseRequestBody = {
+            name,
+            urlList: transformedUrlList,
+            recurring: false,
+        };
+        let requestBody = baseRequestBody;
+        if (hasLocal) {
+            const localConfig = {
+                localTestingInfo: {
+                    localIdentifier,
+                    localEnabled: true,
+                },
+            };
+            requestBody = { ...baseRequestBody, ...localConfig };
+        }
         try {
-            const { data } = await axios.post("https://api-accessibility.browserstack.com/api/website-scanner/v1/scans", { name, urlList, recurring: false }, { auth: this.auth });
+            const { data } = await axios.post("https://api-accessibility.browserstack.com/api/website-scanner/v1/scans", requestBody, { auth: this.auth });
             if (!data.success)
                 throw new Error(`Unable to start scan: ${data.errors?.join(", ")}`);
             return data;

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

@@ -0,0 +1,22 @@
+import { customFuzzySearch } from "../../lib/fuzzy.js";
+/**
+ * Find matching devices by name with exact match preference.
+ * Throws if none or multiple exact matches.
+ */
+export function findDeviceByName(devices, desiredPhone) {
+    const matches = customFuzzySearch(devices, ["display_name"], desiredPhone, 5);
+    if (matches.length === 0) {
+        const options = [...new Set(devices.map((d) => d.display_name))].join(", ");
+        throw new Error(`No devices matching "${desiredPhone}". Available devices: ${options}`);
+    }
+    // Exact-case-insensitive filter
+    const exact = matches.filter((m) => m.display_name.toLowerCase() === desiredPhone.toLowerCase());
+    if (exact)
+        return exact;
+    // If no exact but multiple fuzzy, ask user
+    if (matches.length > 1) {
+        const names = matches.map((d) => d.display_name).join(", ");
+        throw new Error(`Alternative Device/Device's found : ${names}. Please Select one.`);
+    }
+    return matches;
+}

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

@@ -1,129 +1,56 @@
-import childProcess from "child_process";
 import logger from "../../logger.js";
-import { BrowserStackProducts, getDevicesAndBrowsers, } from "../../lib/device-cache.js";
-import { fuzzySearchDevices } from "./fuzzy-search.js";
+import childProcess from "child_process";
+import { getDevicesAndBrowsers, BrowserStackProducts, } from "../../lib/device-cache.js";
 import { sanitizeUrlParam } from "../../lib/utils.js";
 import { uploadApp } from "./upload-app.js";
+import { findDeviceByName } from "./device-search.js";
+import { pickVersion } from "./version-utils.js";
 /**
- * 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.
+ * Start an App Live session: filter, select, upload, and open.
  */
 export async function startSession(args) {
-    const { appPath, desiredPlatform, desiredPhone } = args;
-    let { desiredPlatformVersion } = args;
+    const { appPath, desiredPlatform, desiredPhone, desiredPlatformVersion } = args;
+    // 1) Fetch devices for APP_LIVE
     const data = await getDevicesAndBrowsers(BrowserStackProducts.APP_LIVE);
-    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 fuzzySearchDevices(filteredDevices, desiredPhone);
-    const selectedDevice = validateAndSelectDevice(matches, desiredPhone, desiredPlatform, desiredPlatformVersion);
-    const { app_url } = await 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;
+    const all = data.mobile.flatMap((grp) => grp.devices.map((dev) => ({ ...dev, os: grp.os })));
+    // 2) Filter by OS
+    const osMatches = all.filter((d) => d.os === desiredPlatform);
+    if (!osMatches.length) {
+        throw new Error(`No devices for OS "${desiredPlatform}"`);
     }
-    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;
+    // 3) Select by name
+    const nameMatches = findDeviceByName(osMatches, desiredPhone);
+    // 4) Resolve version
+    const versions = [...new Set(nameMatches.map((d) => d.os_version))];
+    const version = pickVersion(versions, desiredPlatformVersion);
+    // 5) Final candidates for version
+    const final = nameMatches.filter((d) => d.os_version === version);
+    if (!final.length) {
+        throw new Error(`No devices for version "${version}" on ${desiredPlatform}`);
     }
-    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.");
+    const selected = final[0];
+    let note = "";
+    if (version != desiredPlatformVersion &&
+        desiredPlatformVersion !== "latest" &&
+        desiredPlatformVersion !== "oldest") {
+        note = `\n Note: The requested version "${desiredPlatformVersion}" is not available. Using "${version}" instead.`;
     }
-}
-/**
- * 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 = sanitizeUrlParam(device.display_name.replace(/\s+/g, "+"));
+    // 6) Upload app
+    const { app_url } = await uploadApp(appPath);
+    logger.info(`App uploaded: ${app_url}`);
+    // 7) Build URL & open
+    const deviceParam = sanitizeUrlParam(selected.display_name.replace(/\s+/g, "+"));
     const params = new URLSearchParams({
         os: desiredPlatform,
-        os_version: desiredPlatformVersion,
-        app_hashed_id: appUrl.split("bs://").pop() || "",
+        os_version: version,
+        app_hashed_id: app_url.split("bs://").pop() || "",
         scale_to_fit: "true",
         speed: "1",
         start: "true",
     });
-    return `https://app-live.browserstack.com/dashboard#${params.toString()}&device=${deviceParam}`;
+    const launchUrl = `https://app-live.browserstack.com/dashboard#${params.toString()}&device=${deviceParam}`;
+    openBrowser(launchUrl);
+    return launchUrl + note;
 }
 /**
  * Opens the launch URL in the default browser.

package/dist/tools/applive-utils/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/applive-utils/version-utils.js

@@ -0,0 +1,13 @@
+import { resolveVersion } from "../../lib/version-resolver.js";
+/**
+ * Resolve desired version against available list
+ */
+export function pickVersion(available, requested) {
+    try {
+        return resolveVersion(requested, available);
+    }
+    catch {
+        const opts = available.join(", ");
+        throw new Error(`Version "${requested}" not found. Available versions: ${opts}`);
+    }
+}

package/dist/tools/live-utils/desktop-filter.js

@@ -1,5 +1,5 @@
 import { getDevicesAndBrowsers, BrowserStackProducts, } from "../../lib/device-cache.js";
-import { resolveVersion } from "./version-resolver.js";
+import { resolveVersion } from "../../lib/version-resolver.js";
 import { customFuzzySearch } from "../../lib/fuzzy.js";
 export async function filterDesktop(args) {
     const data = await getDevicesAndBrowsers(BrowserStackProducts.LIVE);

package/dist/tools/live-utils/mobile-filter.js

@@ -1,5 +1,5 @@
 import { getDevicesAndBrowsers, BrowserStackProducts, } from "../../lib/device-cache.js";
-import { resolveVersion } from "./version-resolver.js";
+import { resolveVersion } from "../../lib/version-resolver.js";
 import { customFuzzySearch } from "../../lib/fuzzy.js";
 // Extract all mobile entries from the data
 function getAllMobileEntries(data) {

package/package.json

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

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

@@ -1,8 +0,0 @@
-import { customFuzzySearch } from "../../lib/fuzzy.js";
-/**
- * Fuzzy searches App Live device entries by name.
- */
-export async function fuzzySearchDevices(devices, query, limit = 5) {
-    const top_match = customFuzzySearch(devices, ["device", "display_name"], query, limit);
-    return top_match;
-}