@browserstack/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,117 @@
+# BrowserStack MCP Server
+<div style="display: flex; justify-content: space-between; padding: 20px;">
+<img src="assets/browserstack-logo.png" alt="BrowserStack Logo" height="100"> <img src="assets/mcp-logo.png" alt="MCP Server Logo" width="100">
+</div>
+
+
+*See it in action, check out the video below.*
+
+[![Watch the video](https://img.youtube.com/vi/vy1sx0J7sTk/0.jpg)](https://www.youtube.com/watch?v=vy1sx0J7sTk)
+
+## 🚀 Overview
+BrowserStack MCP Server brings the power of BrowserStack's [Test Platform](https://www.browserstack.com/test-platform) directly into your development workflow. It enables you to run tests, debug applications, and perform cross-browser testing through any [MCP-compliant client](https://modelcontextprotocol.io/clients#feature-support-matrix).
+
+## ✨ Features - More Coming Soon!
+
+### 📱 App Testing
+- **Real Device Testing**: Test your mobile apps on BrowserStack's extensive cloud of real devices
+- **Performance Testing**: Unlike emulators, test your app's real-world performance on actual devices
+- **Live Debugging**: Debug crashes and performance issues in real-time
+- **Comprehensive Device Coverage**: Access all major devices and OS versions from our [device grid](https://www.browserstack.com/list-of-browsers-and-platforms/app_live)
+
+### 🌐 Web Testing
+- **Local Testing**: Seamlessly test websites hosted on localhost
+- **Cross-Browser Testing**: Test websites across different browsers and devices
+- **Screenshot Testing**: Capture and compare screenshots across different environments
+
+### 🧪 Automated Testing
+- **Fix Test Failures**: Leverage AI to identify and fix test failures reported by your CI/CD pipeline by utilising our industry leading [Test Observability](https://www.browserstack.com/docs/test-observability) features. Find more info [here](https://www.browserstack.com/docs/test-observability/features/smart-tags).
+- **Run on BrowserStack**: Easily run tests written in Jest, Playwright, Selenium, and more on BrowserStack's [Test Platform](https://www.browserstack.com/test-platform)
+- **Accessibility Testing**: Ensure WCAG and ADA compliance with our [Accessibility Testing](https://www.browserstack.com/accessibility-testing) tool
+
+## 🛠️ Installation
+
+1. **Create a BrowserStack Account**
+   - Sign up at [BrowserStack](https://www.browserstack.com/signup)
+   - Get your credentials from [Account Settings](https://www.browserstack.com/accounts/profile/details)
+
+2. **Install the MCP Server**
+   - Sample MCP Server config for Cursor: `.cursor/mcp.json`:
+   ```json
+   {
+     "mcpServers": {
+       "browserstack_mcp_server": {
+         "command": "npx",
+         "args": ["@browserstack/mcp-server"],
+         "env": {
+           "BROWSERSTACK_USERNAME": "<username>",
+           "BROWSERSTACK_ACCESS_KEY": "<access_key>"
+         }
+       }
+     }
+   }
+   ```
+   - For Github Copilot users, ensure you are using the latest version of the VSCode with support for Copilot agent mode.
+
+## 💡 Usage Examples
+
+### App Testing
+```bash
+# Open app on specific device
+"open my app on a iPhone 15 Pro Max"
+
+# Debug app crashes
+"My app crashed on Android 14 device, can you help me debug?"
+```
+
+### Web Testing
+```bash
+# Test local website
+"open my website hosted on localhost:3001 on a Windows Edge browser and take a screenshot"
+
+# Check website compatibility
+"open test.com on Samsung Browser and check for readability issues"
+```
+
+### Automated Testing
+```bash
+# Run test suite
+"run my test suite on BrowserStack"
+
+# Debug test failures
+"My test suite failed, can you help me fix the new failures?"
+
+# Accessibility testing
+"check for accessibility issues on my www.mywebsite.com"
+```
+
+## 🤝 Recommended MCP Clients
+
+- **Github Copilot or Cursor** (Recommended for automated testing + debugging)
+- **Claude Desktop** (Recommended for manual testing)
+
+## ⚠️ Important Notes
+- The BrowserStack MCP Server is under active development and currently supports a subset of the MCP protocol, i.e. `tools`. More features will be added soon.
+- As tool invocation relies on the MCP Client which in turn rely on LLMs for tool calling. There can be some non-deterministic behaviour and can lead to unexpected results. If you have any suggestions or feedback, please open an issue to discuss.
+
+## 📝 Contributing
+
+We welcome contributions! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 📞 Support
+
+For support, please:
+- Check our [documentation](https://www.browserstack.com/docs)
+- Open an issue in our [GitHub repository](https://github.com/browserstack/mcp-server)
+- Contact our [support team](https://www.browserstack.com/contact)
+
+## 🔗 Resources
+
+- [BrowserStack Test Platform](https://www.browserstack.com/test-platform)
+- [MCP Protocol Documentation](https://modelcontextprotocol.io)
+- [Device Grid](https://www.browserstack.com/list-of-browsers-and-platforms/app_live)
+- [Accessibility Testing](https://www.browserstack.com/accessibility-testing)

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,40 @@
+"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"));
+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);
+}
+// 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,22 @@
+"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;
+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();
+}

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/constants.js

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

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

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