@browserstack/mcp-server 1.0.6 → 1.0.8

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/package.json

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

package/dist/config.js

@@ -1,18 +0,0 @@
-"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

@@ -1,45 +0,0 @@
-#!/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

@@ -1,70 +0,0 @@
-"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

@@ -1,26 +0,0 @@
-"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/local.js

@@ -1,109 +0,0 @@
-"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

@@ -1,7 +0,0 @@
-"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

@@ -1,40 +0,0 @@
-"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

@@ -1,43 +0,0 @@
-"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

@@ -1,82 +0,0 @@
-"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/constants.js

@@ -1,82 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SUPPORTED_LIVE_CONFIGURATIONS = void 0;
-exports.SUPPORTED_LIVE_CONFIGURATIONS = {
-    android: {
-        chrome: {
-            version: "100",
-        },
-        firefox: {
-            version: "100",
-        },
-        safari: {
-            version: "100",
-        },
-        "samsung browser": {
-            version: "100",
-        },
-        "internet-explorer": {
-            version: "100",
-        },
-    },
-    ios: {
-        chrome: {
-            version: "100",
-        },
-        firefox: {
-            version: "100",
-        },
-        edge: {
-            version: "100",
-        },
-        safari: {
-            version: "100",
-        },
-        "samsung browser": {
-            version: "100",
-        },
-        "internet-explorer": {
-            version: "100",
-        },
-    },
-    windows: {
-        chrome: {
-            version: "100",
-        },
-        firefox: {
-            version: "100",
-        },
-        edge: {
-            version: "100",
-        },
-        safari: {
-            version: "100",
-        },
-        "samsung browser": {
-            version: "100",
-        },
-        "internet-explorer": {
-            version: "100",
-        },
-    },
-    macos: {
-        chrome: {
-            version: "100",
-        },
-        firefox: {
-            version: "100",
-        },
-        edge: {
-            version: "100",
-        },
-        safari: {
-            version: "100",
-        },
-        "samsung browser": {
-            version: "100",
-        },
-        "internet-explorer": {
-            version: "100",
-        },
-    },
-};

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

@@ -1,55 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.startSession = startSession;
-const child_process_1 = __importDefault(require("child_process"));
-const logger_1 = __importDefault(require("../../logger"));
-const utils_1 = require("../../lib/utils");
-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 params = new URLSearchParams({
-        os: sanitizedArgs.desiredPlatform,
-        os_version: sanitizedArgs.desiredPlatformVersion,
-        app_hashed_id: appHashedId || "",
-        scale_to_fit: "true",
-        speed: "1",
-        start: "true",
-    });
-    const launchUrl = `https://app-live.browserstack.com/dashboard#${params.toString()}&device=${desiredPhoneWithSpaces}`;
-    try {
-        // Use platform-specific commands with proper escaping
-        const command = process.platform === "darwin"
-            ? ["open", launchUrl]
-            : process.platform === "win32"
-                ? ["cmd", "/c", "start", launchUrl]
-                : ["xdg-open", launchUrl];
-        // nosemgrep:javascript.lang.security.detect-child-process.detect-child-process
-        const child = child_process_1.default.spawn(command[0], command.slice(1), {
-            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-utils/types.js

@@ -1,2 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });