@browserstack/mcp-server 1.0.8 → 1.0.10

package/dist/config.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Config = void 0;
+if (!process.env.BROWSERSTACK_ACCESS_KEY ||
+    !process.env.BROWSERSTACK_USERNAME) {
+    throw new Error("Unable to start MCP server. Please set the BROWSERSTACK_ACCESS_KEY and BROWSERSTACK_USERNAME environment variables. Go to https://www.browserstack.com/accounts/profile/details to access them");
+}
+class Config {
+    browserstackUsername;
+    browserstackAccessKey;
+    constructor(browserstackUsername, browserstackAccessKey) {
+        this.browserstackUsername = browserstackUsername;
+        this.browserstackAccessKey = browserstackAccessKey;
+    }
+}
+exports.Config = Config;
+const config = new Config(process.env.BROWSERSTACK_USERNAME, process.env.BROWSERSTACK_ACCESS_KEY);
+exports.default = config;

package/dist/index.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const package_json_1 = __importDefault(require("../package.json"));
+require("dotenv/config");
+const logger_1 = __importDefault(require("./logger"));
+const bstack_sdk_1 = __importDefault(require("./tools/bstack-sdk"));
+const applive_1 = __importDefault(require("./tools/applive"));
+const observability_1 = __importDefault(require("./tools/observability"));
+const live_1 = __importDefault(require("./tools/live"));
+const accessibility_1 = __importDefault(require("./tools/accessibility"));
+const automate_1 = __importDefault(require("./tools/automate"));
+const testmanagement_1 = __importDefault(require("./tools/testmanagement"));
+function registerTools(server) {
+    (0, bstack_sdk_1.default)(server);
+    (0, applive_1.default)(server);
+    (0, live_1.default)(server);
+    (0, observability_1.default)(server);
+    (0, accessibility_1.default)(server);
+    (0, automate_1.default)(server);
+    (0, testmanagement_1.default)(server);
+}
+// Create an MCP server
+const server = new mcp_js_1.McpServer({
+    name: "BrowserStack MCP Server",
+    version: package_json_1.default.version,
+});
+registerTools(server);
+async function main() {
+    logger_1.default.info("Launching BrowserStack MCP server, version %s", package_json_1.default.version);
+    // Start receiving messages on stdin and sending messages on stdout
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    logger_1.default.info("MCP server started successfully");
+}
+main().catch(console.error);
+// Ensure logs are flushed before exit
+process.on("exit", () => {
+    logger_1.default.flush();
+});

package/dist/lib/api.js

@@ -0,0 +1,70 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLatestO11YBuildInfo = getLatestO11YBuildInfo;
+exports.retrieveNetworkFailures = retrieveNetworkFailures;
+const config_1 = __importDefault(require("../config"));
+async function getLatestO11YBuildInfo(buildName, projectName) {
+    const buildsUrl = `https://api-observability.browserstack.com/ext/v1/builds/latest?build_name=${encodeURIComponent(buildName)}&project_name=${encodeURIComponent(projectName)}`;
+    const buildsResponse = await fetch(buildsUrl, {
+        headers: {
+            Authorization: `Basic ${Buffer.from(`${config_1.default.browserstackUsername}:${config_1.default.browserstackAccessKey}`).toString("base64")}`,
+        },
+    });
+    if (!buildsResponse.ok) {
+        if (buildsResponse.statusText === "Unauthorized") {
+            throw new Error(`Failed to fetch builds: ${buildsResponse.statusText}. Please check if the BrowserStack credentials are correctly configured when installing the MCP server.`);
+        }
+        throw new Error(`Failed to fetch builds: ${buildsResponse.statusText}`);
+    }
+    return buildsResponse.json();
+}
+// Fetches network logs for a given session ID and returns only failure logs
+async function retrieveNetworkFailures(sessionId) {
+    if (!sessionId) {
+        throw new Error("Session ID is required");
+    }
+    const url = `https://api.browserstack.com/automate/sessions/${sessionId}/networklogs`;
+    const auth = Buffer.from(`${config_1.default.browserstackUsername}:${config_1.default.browserstackAccessKey}`).toString("base64");
+    const response = await fetch(url, {
+        method: "GET",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Basic ${auth}`,
+        },
+    });
+    if (!response.ok) {
+        if (response.status === 404) {
+            throw new Error("Invalid session ID");
+        }
+        throw new Error(`Failed to fetch network logs: ${response.statusText}`);
+    }
+    const networklogs = await response.json();
+    // Filter for failure logs
+    const failureEntries = networklogs.log.entries.filter((entry) => {
+        return (entry.response.status === 0 ||
+            entry.response.status >= 400 ||
+            entry.response._error !== undefined);
+    });
+    // Return only the failure entries with some context
+    return {
+        failures: failureEntries.map((entry) => ({
+            startedDateTime: entry.startedDateTime,
+            request: {
+                method: entry.request?.method,
+                url: entry.request?.url,
+                queryString: entry.request?.queryString,
+            },
+            response: {
+                status: entry.response?.status,
+                statusText: entry.response?.statusText,
+                _error: entry.response?._error,
+            },
+            serverIPAddress: entry.serverIPAddress,
+            time: entry.time,
+        })),
+        totalFailures: failureEntries.length,
+    };
+}

package/dist/lib/error.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatAxiosError = formatAxiosError;
+const axios_1 = require("axios");
+/**
+ * Formats an AxiosError into a CallToolResult with an appropriate message.
+ * @param err - The error object to format
+ * @param defaultText - The fallback error message
+ */
+function formatAxiosError(err, defaultText) {
+    let text = defaultText;
+    if (err instanceof axios_1.AxiosError && err.response?.data) {
+        const message = err.response.data.message ||
+            err.response.data.error ||
+            err.message ||
+            defaultText;
+        text = message;
+    }
+    else if (err instanceof Error) {
+        text = err.message;
+    }
+    return {
+        content: [{ type: "text", text }],
+        isError: true,
+    };
+}

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/lib/local.js

@@ -0,0 +1,109 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.killExistingBrowserStackLocalProcesses = killExistingBrowserStackLocalProcesses;
+exports.ensureLocalBinarySetup = ensureLocalBinarySetup;
+exports.isLocalURL = isLocalURL;
+const logger_1 = __importDefault(require("../logger"));
+const child_process_1 = require("child_process");
+const browserstack_local_1 = require("browserstack-local");
+const config_1 = __importDefault(require("../config"));
+async function isBrowserStackLocalRunning() {
+    // Check if BrowserStackLocal binary is already running
+    try {
+        if (process.platform === "win32") {
+            const result = (0, child_process_1.execSync)('tasklist /FI "IMAGENAME eq BrowserStackLocal.exe"', {
+                encoding: "utf8",
+            });
+            if (result.includes("BrowserStackLocal.exe")) {
+                logger_1.default.info("BrowserStackLocal binary is already running");
+                return true;
+            }
+        }
+        else {
+            const result = (0, child_process_1.execSync)("pgrep -f BrowserStackLocal", {
+                encoding: "utf8",
+                stdio: "pipe",
+            }).toString();
+            if (result) {
+                logger_1.default.info("BrowserStackLocal binary is already running");
+                return true;
+            }
+        }
+        logger_1.default.info("BrowserStackLocal binary is not running");
+        return false;
+    }
+    catch (error) {
+        logger_1.default.info("Error checking BrowserStackLocal status, assuming not running ... " +
+            error);
+        return false;
+    }
+}
+async function killExistingBrowserStackLocalProcesses() {
+    const isRunning = await isBrowserStackLocalRunning();
+    if (!isRunning) {
+        return;
+    }
+    // Check and kill any existing BrowserStackLocal processes before starting new one
+    try {
+        if (process.platform === "win32") {
+            // Check if process exists on Windows
+            const checkResult = (0, child_process_1.execSync)('tasklist /FI "IMAGENAME eq BrowserStackLocal.exe"', { encoding: "utf8" });
+            if (checkResult.includes("BrowserStackLocal.exe")) {
+                (0, child_process_1.execSync)("taskkill /F /IM BrowserStackLocal.exe", { stdio: "ignore" });
+                logger_1.default.info("Successfully killed existing BrowserStackLocal processes");
+            }
+        }
+        else {
+            // Check if process exists on Unix-like systems
+            const checkResult = (0, child_process_1.execSync)("pgrep -f BrowserStackLocal", {
+                encoding: "utf8",
+                stdio: "pipe",
+            }).toString();
+            if (checkResult) {
+                (0, child_process_1.execSync)("pkill -f BrowserStackLocal", { stdio: "ignore" });
+                logger_1.default.info("Successfully killed existing BrowserStackLocal processes");
+            }
+        }
+    }
+    catch (error) {
+        logger_1.default.info(`Error checking/killing BrowserStackLocal processes: ${error}`);
+        // Continue execution as there may not be any processes running
+    }
+}
+async function ensureLocalBinarySetup() {
+    logger_1.default.info("Ensuring local binary setup as it is required for private URLs...");
+    const localBinary = new browserstack_local_1.Local();
+    await killExistingBrowserStackLocalProcesses();
+    return await new Promise((resolve, reject) => {
+        localBinary.start({
+            key: config_1.default.browserstackAccessKey,
+            username: config_1.default.browserstackUsername,
+        }, (error) => {
+            if (error) {
+                logger_1.default.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}`));
+            }
+            else {
+                logger_1.default.info("Successfully started BrowserStack Local");
+                resolve();
+            }
+        });
+    });
+}
+function isLocalURL(url) {
+    try {
+        const urlObj = new URL(url);
+        const hostname = urlObj.hostname.toLowerCase();
+        return (hostname === "localhost" ||
+            hostname === "127.0.0.1" ||
+            hostname.endsWith(".local") ||
+            hostname.endsWith(".localhost"));
+    }
+    catch (error) {
+        logger_1.default.error(`Error checking if URL is local: ${error}`);
+        return false;
+    }
+}

package/dist/lib/utils.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeUrlParam = sanitizeUrlParam;
+function sanitizeUrlParam(param) {
+    // Remove any characters that could be used for command injection
+    return param.replace(/[;&|`$(){}[\]<>]/g, "");
+}

package/dist/logger.js

@@ -0,0 +1,40 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const pino_1 = __importDefault(require("pino"));
+let logger;
+if (process.env.NODE_ENV === "development") {
+    logger = (0, pino_1.default)({
+        level: "debug",
+        transport: {
+            targets: [
+                {
+                    level: "debug",
+                    target: "pino-pretty",
+                    options: {
+                        colorize: true,
+                        levelFirst: true,
+                        destination: process.platform === "win32"
+                            ? "C:\\Windows\\Temp\\browserstack-mcp-server.log"
+                            : "/tmp/browserstack-mcp-server.log",
+                    },
+                },
+            ],
+        },
+    });
+}
+else {
+    // NULL logger
+    logger = (0, pino_1.default)({
+        level: "info",
+        transport: {
+            target: "pino/file",
+            options: {
+                destination: process.platform === "win32" ? "NUL" : "/dev/null",
+            },
+        },
+    });
+}
+exports.default = logger;

package/dist/tools/accessibility.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = addAccessibilityTools;
+const zod_1 = require("zod");
+const accessibility_1 = require("./accessiblity-utils/accessibility");
+async function runAccessibilityScan(name, pageURL) {
+    try {
+        const response = await (0, accessibility_1.startAccessibilityScan)(name, [pageURL]);
+        const scanId = response.data?.id;
+        const scanRunId = response.data?.scanRunId;
+        if (!scanId || !scanRunId) {
+            throw new Error("Unable to start a accessibility scan, please try again later or open an issue on GitHub if the problem persists");
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Successfully queued accessibility scan, you will get a report via email within 5 minutes.`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to start accessibility scan: ${error instanceof Error ? error.message : "Unknown error"}. Please open an issue on GitHub if the problem persists`,
+                    isError: true,
+                },
+            ],
+            isError: true,
+        };
+    }
+}
+function addAccessibilityTools(server) {
+    server.tool("startAccessibilityScan", "Use this tool to start an accessibility scan for a list of URLs on BrowserStack.", {
+        name: zod_1.z.string().describe("Name of the accessibility scan"),
+        pageURL: zod_1.z.string().describe("The URL to scan for accessibility issues"),
+    }, async (args) => {
+        return runAccessibilityScan(args.name, args.pageURL);
+    });
+}

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

@@ -0,0 +1,82 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startAccessibilityScan = startAccessibilityScan;
+exports.pollScanStatus = pollScanStatus;
+exports.waitUntilScanComplete = waitUntilScanComplete;
+const axios_1 = __importDefault(require("axios"));
+const config_js_1 = __importDefault(require("../../config.js"));
+const axios_2 = require("axios");
+async function startAccessibilityScan(name, urlList) {
+    try {
+        const response = await axios_1.default.post("https://api-accessibility.browserstack.com/api/website-scanner/v1/scans", {
+            name,
+            urlList,
+            recurring: false,
+        }, {
+            auth: {
+                username: config_js_1.default.browserstackUsername,
+                password: config_js_1.default.browserstackAccessKey,
+            },
+        });
+        if (!response.data.success) {
+            throw new Error(`Unable to create an accessibility scan: ${response.data.errors?.join(", ")}`);
+        }
+        return response.data;
+    }
+    catch (error) {
+        if (error instanceof axios_2.AxiosError) {
+            if (error.response?.data?.error) {
+                throw new Error(`Failed to start accessibility scan: ${error.response?.data?.error}`);
+            }
+            else {
+                throw new Error(`Failed to start accessibility scan: ${error.response?.data?.message || error.message}`);
+            }
+        }
+        throw error;
+    }
+}
+async function pollScanStatus(scanId, scanRunId) {
+    try {
+        const response = await axios_1.default.get(`https://api-accessibility.browserstack.com/api/website-scanner/v1/scans/${scanId}/scan_runs/${scanRunId}/status`, {
+            auth: {
+                username: config_js_1.default.browserstackUsername,
+                password: config_js_1.default.browserstackAccessKey,
+            },
+        });
+        if (!response.data.success) {
+            throw new Error(`Failed to get scan status: ${response.data.errors?.join(", ")}`);
+        }
+        return response.data.data?.status || "unknown";
+    }
+    catch (error) {
+        if (error instanceof axios_2.AxiosError) {
+            throw new Error(`Failed to get scan status: ${error.response?.data?.message || error.message}`);
+        }
+        throw error;
+    }
+}
+async function waitUntilScanComplete(scanId, scanRunId) {
+    return new Promise((resolve, reject) => {
+        const interval = setInterval(async () => {
+            try {
+                const status = await pollScanStatus(scanId, scanRunId);
+                if (status === "completed") {
+                    clearInterval(interval);
+                    resolve();
+                }
+            }
+            catch (error) {
+                clearInterval(interval);
+                reject(error);
+            }
+        }, 5000); // Poll every 5 seconds
+        // Set a timeout of 5 minutes
+        setTimeout(() => {
+            clearInterval(interval);
+            reject(new Error("Scan timed out after 5 minutes"));
+        }, 5 * 60 * 1000);
+    });
+}

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;
+}