@browserstack/mcp-server 1.1.2 → 1.1.4

package/dist/config.js

@@ -1,7 +1,3 @@
-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");
-}
 export class Config {
     browserstackUsername;
     browserstackAccessKey;

package/dist/index.js

@@ -14,7 +14,7 @@ import addTestManagementTools from "./tools/testmanagement.js";
 import addAppAutomationTools from "./tools/appautomate.js";
 import addFailureLogsTools from "./tools/getFailureLogs.js";
 import addAutomateTools from "./tools/automate.js";
-import { trackMCP } from "./lib/instrumentation.js";
+import { setupOnInitialized } from "./oninitialized.js";
 function registerTools(server) {
     addSDKTools(server);
     addAppLiveTools(server);
@@ -30,14 +30,13 @@ const server = new McpServer({
     name: "BrowserStack MCP Server",
     version: packageJson.version,
 });
+setupOnInitialized(server);
 registerTools(server);
 async function main() {
     logger.info("Launching BrowserStack MCP server, version %s", packageJson.version);
     // Start receiving messages on stdin and sending messages on stdout
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    logger.info("MCP server started successfully");
-    trackMCP("started", server.server.getClientVersion());
 }
 main().catch(console.error);
 // Ensure logs are flushed before exit

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

@@ -24,9 +24,3 @@ export async function assertOkResponse(response, action) {
         throw new Error(`Failed to fetch logs for ${action}: ${response.statusText}`);
     }
 }
-export function filterLinesByKeywords(logText, keywords) {
-    return logText
-        .split(/\r?\n/)
-        .map((line) => line.trim())
-        .filter((line) => keywords.some((keyword) => line.toLowerCase().includes(keyword)));
-}

package/dist/oninitialized.js

@@ -0,0 +1,16 @@
+import config from "./config.js";
+import { trackMCP } from "./lib/instrumentation.js";
+export function setupOnInitialized(server) {
+    const nodeVersion = process.versions.node;
+    // Check for Node.js version
+    if (nodeVersion < "18.0.0") {
+        throw new Error("Node version is not supported. Please upgrade to 18.0.0 or later.");
+    }
+    // Check for BrowserStack credentials
+    if (!config.browserstackUsername || !config.browserstackAccessKey) {
+        throw new Error("BrowserStack credentials are missing. Please provide a valid username and access key.");
+    }
+    server.server.oninitialized = () => {
+        trackMCP("started", server.server.getClientVersion());
+    };
+}

package/dist/tools/accessibility.js

@@ -36,13 +36,17 @@ async function runAccessibilityScan(name, pageURL, context) {
     }
     // Fetch CSV report link
     const reportLink = await reportFetcher.getReportLink(scanId, scanRunId);
-    const { records } = await parseAccessibilityReportFromCSV(reportLink);
+    const { records, page_length, total_issues } = await parseAccessibilityReportFromCSV(reportLink);
     return {
         content: [
             {
                 type: "text",
                 text: `✅ Accessibility scan "${name}" completed. check the BrowserStack dashboard for more details [https://scanner.browserstack.com/site-scanner/scan-details/${name}].`,
             },
+            {
+                type: "text",
+                text: `We found ${total_issues} issues. Below are the details of the ${page_length} most critical issues.`,
+            },
             {
                 type: "text",
                 text: `Scan results: ${JSON.stringify(records, null, 2)}`,

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

@@ -17,6 +17,7 @@ export async function parseAccessibilityReportFromCSV(reportLink, { maxCharacter
         how_to_fix: row["How to fix this issue"],
         severity: (row["Severity"] || "unknown").trim(),
     }));
+    const totalIssues = all.length;
     // 2) Sort by severity
     const order = {
         critical: 0,
@@ -43,9 +44,12 @@ export async function parseAccessibilityReportFromCSV(reportLink, { maxCharacter
         page.push(all[i]);
         charCursor += recStr.length;
     }
-    const hasMore = idx + page.length < all.length;
+    const pageLength = page.length;
+    const hasMore = idx + pageLength < totalIssues;
     return {
         records: page,
         next_page: hasMore ? charCursor : null,
+        page_length: pageLength,
+        total_issues: totalIssues,
     };
 }

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/failurelogs-utils/app-automate.js

@@ -1,5 +1,5 @@
 import config from "../../config.js";
-import { assertOkResponse, filterLinesByKeywords } from "../../lib/utils.js";
+import { filterLinesByKeywords, validateLogResponse } from "./utils.js";
 const auth = Buffer.from(`${config.browserstackUsername}:${config.browserstackAccessKey}`).toString("base64");
 // DEVICE LOGS
 export async function retrieveDeviceLogs(sessionId, buildId) {
@@ -10,9 +10,14 @@ export async function retrieveDeviceLogs(sessionId, buildId) {
             Authorization: `Basic ${auth}`,
         },
     });
-    await assertOkResponse(response, "device logs");
+    const validationError = validateLogResponse(response, "device logs");
+    if (validationError)
+        return validationError.message;
     const logText = await response.text();
-    return filterDeviceFailures(logText);
+    const logs = filterDeviceFailures(logText);
+    return logs.length > 0
+        ? `Device Failures (${logs.length} found):\n${JSON.stringify(logs, null, 2)}`
+        : "No device failures found";
 }
 // APPIUM LOGS
 export async function retrieveAppiumLogs(sessionId, buildId) {
@@ -23,9 +28,14 @@ export async function retrieveAppiumLogs(sessionId, buildId) {
             Authorization: `Basic ${auth}`,
         },
     });
-    await assertOkResponse(response, "Appium logs");
+    const validationError = validateLogResponse(response, "Appium logs");
+    if (validationError)
+        return validationError.message;
     const logText = await response.text();
-    return filterAppiumFailures(logText);
+    const logs = filterAppiumFailures(logText);
+    return logs.length > 0
+        ? `Appium Failures (${logs.length} found):\n${JSON.stringify(logs, null, 2)}`
+        : "No Appium failures found";
 }
 // CRASH LOGS
 export async function retrieveCrashLogs(sessionId, buildId) {
@@ -36,9 +46,14 @@ export async function retrieveCrashLogs(sessionId, buildId) {
             Authorization: `Basic ${auth}`,
         },
     });
-    await assertOkResponse(response, "crash logs");
+    const validationError = validateLogResponse(response, "crash logs");
+    if (validationError)
+        return validationError.message;
     const logText = await response.text();
-    return filterCrashFailures(logText);
+    const logs = filterCrashFailures(logText);
+    return logs.length > 0
+        ? `Crash Failures (${logs.length} found):\n${JSON.stringify(logs, null, 2)}`
+        : "No crash failures found";
 }
 // FILTER HELPERS
 export function filterDeviceFailures(logText) {

package/dist/tools/failurelogs-utils/automate.js

@@ -1,5 +1,5 @@
 import config from "../../config.js";
-import { assertOkResponse, filterLinesByKeywords } from "../../lib/utils.js";
+import { filterLinesByKeywords, validateLogResponse, } from "./utils.js";
 const auth = Buffer.from(`${config.browserstackUsername}:${config.browserstackAccessKey}`).toString("base64");
 // NETWORK LOGS
 export async function retrieveNetworkFailures(sessionId) {
@@ -11,30 +11,30 @@ export async function retrieveNetworkFailures(sessionId) {
             Authorization: `Basic ${auth}`,
         },
     });
-    await assertOkResponse(response, "network logs");
+    const validationError = validateLogResponse(response, "network logs");
+    if (validationError)
+        return validationError.message;
     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 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,
-    }));
+    const failureEntries = networklogs.log.entries.filter((entry) => entry.response.status === 0 ||
+        entry.response.status >= 400 ||
+        entry.response._error !== undefined);
+    return failureEntries.length > 0
+        ? `Network Failures (${failureEntries.length} found):\n${JSON.stringify(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,
+        })), null, 2)}`
+        : "No network failures found";
 }
 // SESSION LOGS
 export async function retrieveSessionFailures(sessionId) {
@@ -45,9 +45,14 @@ export async function retrieveSessionFailures(sessionId) {
             Authorization: `Basic ${auth}`,
         },
     });
-    await assertOkResponse(response, "session logs");
+    const validationError = validateLogResponse(response, "session logs");
+    if (validationError)
+        return validationError.message;
     const logText = await response.text();
-    return filterSessionFailures(logText);
+    const logs = filterSessionFailures(logText);
+    return logs.length > 0
+        ? `Session Failures (${logs.length} found):\n${JSON.stringify(logs, null, 2)}`
+        : "No session failures found";
 }
 // CONSOLE LOGS
 export async function retrieveConsoleFailures(sessionId) {
@@ -58,9 +63,14 @@ export async function retrieveConsoleFailures(sessionId) {
             Authorization: `Basic ${auth}`,
         },
     });
-    await assertOkResponse(response, "console logs");
+    const validationError = validateLogResponse(response, "console logs");
+    if (validationError)
+        return validationError.message;
     const logText = await response.text();
-    return filterConsoleFailures(logText);
+    const logs = filterConsoleFailures(logText);
+    return logs.length > 0
+        ? `Console Failures (${logs.length} found):\n${JSON.stringify(logs, null, 2)}`
+        : "No console failures found";
 }
 // FILTER: session logs
 export function filterSessionFailures(logText) {

package/dist/tools/failurelogs-utils/utils.js

@@ -0,0 +1,20 @@
+export function validateLogResponse(response, logType) {
+    if (!response.ok) {
+        if (response.status === 404) {
+            return { message: `No ${logType} available for this session` };
+        }
+        if (response.status === 401 || response.status === 403) {
+            return {
+                message: `Unable to access ${logType} - please check your credentials`,
+            };
+        }
+        return { message: `Unable to fetch ${logType} at this time` };
+    }
+    return null;
+}
+export function filterLinesByKeywords(logText, keywords) {
+    return logText
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => keywords.some((keyword) => line.toLowerCase().includes(keyword)));
+}

package/dist/tools/getFailureLogs.js

@@ -1,8 +1,8 @@
 import { z } from "zod";
 import logger from "../logger.js";
+import { trackMCP } from "../lib/instrumentation.js";
 import { retrieveNetworkFailures, retrieveSessionFailures, retrieveConsoleFailures, } from "./failurelogs-utils/automate.js";
 import { retrieveDeviceLogs, retrieveAppiumLogs, retrieveCrashLogs, } from "./failurelogs-utils/app-automate.js";
-import { trackMCP } from "../lib/instrumentation.js";
 import { AppAutomateLogType, AutomateLogType, SessionType, } from "../lib/constants.js";
 // Main log fetcher function
 export async function getFailureLogs(args) {
@@ -47,68 +47,39 @@ export async function getFailureLogs(args) {
             ],
         };
     }
+    let response;
     // eslint-disable-next-line no-useless-catch
     try {
         for (const logType of validLogTypes) {
             switch (logType) {
                 case AutomateLogType.NetworkLogs: {
-                    const logs = await retrieveNetworkFailures(args.sessionId);
-                    results.push({
-                        type: "text",
-                        text: logs.length > 0
-                            ? `Network Failures (${logs.length} found):\n${JSON.stringify(logs, null, 2)}`
-                            : "No network failures found",
-                    });
+                    response = await retrieveNetworkFailures(args.sessionId);
+                    results.push({ type: "text", text: response });
                     break;
                 }
                 case AutomateLogType.SessionLogs: {
-                    const logs = await retrieveSessionFailures(args.sessionId);
-                    results.push({
-                        type: "text",
-                        text: logs.length > 0
-                            ? `Session Failures (${logs.length} found):\n${JSON.stringify(logs, null, 2)}`
-                            : "No session failures found",
-                    });
+                    response = await retrieveSessionFailures(args.sessionId);
+                    results.push({ type: "text", text: response });
                     break;
                 }
                 case AutomateLogType.ConsoleLogs: {
-                    const logs = await retrieveConsoleFailures(args.sessionId);
-                    results.push({
-                        type: "text",
-                        text: logs.length > 0
-                            ? `Console Failures (${logs.length} found):\n${JSON.stringify(logs, null, 2)}`
-                            : "No console failures found",
-                    });
+                    response = await retrieveConsoleFailures(args.sessionId);
+                    results.push({ type: "text", text: response });
                     break;
                 }
                 case AppAutomateLogType.DeviceLogs: {
-                    const logs = await retrieveDeviceLogs(args.sessionId, args.buildId);
-                    results.push({
-                        type: "text",
-                        text: logs.length > 0
-                            ? `Device Failures (${logs.length} found):\n${JSON.stringify(logs, null, 2)}`
-                            : "No device failures found",
-                    });
+                    response = await retrieveDeviceLogs(args.sessionId, args.buildId);
+                    results.push({ type: "text", text: response });
                     break;
                 }
                 case AppAutomateLogType.AppiumLogs: {
-                    const logs = await retrieveAppiumLogs(args.sessionId, args.buildId);
-                    results.push({
-                        type: "text",
-                        text: logs.length > 0
-                            ? `Appium Failures (${logs.length} found):\n${JSON.stringify(logs, null, 2)}`
-                            : "No Appium failures found",
-                    });
+                    response = await retrieveAppiumLogs(args.sessionId, args.buildId);
+                    results.push({ type: "text", text: response });
                     break;
                 }
                 case AppAutomateLogType.CrashLogs: {
-                    const logs = await retrieveCrashLogs(args.sessionId, args.buildId);
-                    results.push({
-                        type: "text",
-                        text: logs.length > 0
-                            ? `Crash Failures (${logs.length} found):\n${JSON.stringify(logs, null, 2)}`
-                            : "No crash failures found",
-                    });
+                    response = await retrieveCrashLogs(args.sessionId, args.buildId);
+                    results.push({ type: "text", text: response });
                     break;
                 }
             }

package/dist/tools/testmanagement-utils/create-project-folder.js

@@ -2,6 +2,7 @@ import axios from "axios";
 import config from "../../config.js";
 import { z } from "zod";
 import { formatAxiosError } from "../../lib/error.js"; // or correct path
+import { projectIdentifierToId } from "../testmanagement-utils/TCG-utils/api.js";
 // Schema for combined project/folder creation
 export const CreateProjFoldSchema = z.object({
     project_name: z
@@ -78,11 +79,16 @@ export async function createProjectOrFolder(args) {
             }
             // Folder created successfully
             const folder = res.data.folder;
+            const projectId = await projectIdentifierToId(projId);
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Folder created: ID=${folder.id}, name=${folder.name} in project with identifier ${projId}`,
+                        text: `Folder successfully created:
+              - ID: ${folder.id}
+              - Name: ${folder.name}
+              - Project Identifier: ${projId}
+            Access it here: https://test-management.browserstack.com/projects/${projectId}/folder/${folder.id}/`,
                     },
                 ],
             };

package/dist/tools/testmanagement-utils/create-testcase.js

@@ -2,6 +2,7 @@ import axios from "axios";
 import config from "../../config.js";
 import { z } from "zod";
 import { formatAxiosError } from "../../lib/error.js"; // or correct
+import { projectIdentifierToId } from "./TCG-utils/api.js";
 export const CreateTestCaseSchema = z.object({
     project_identifier: z
         .string()
@@ -90,13 +91,21 @@ export async function createTestCase(params) {
             };
         }
         const tc = data.test_case;
+        const projectId = await projectIdentifierToId(params.project_identifier);
         return {
             content: [
                 {
                     type: "text",
-                    text: `Successfully created test case ${tc.identifier}: ${tc.title}`,
+                    text: `Test case successfully created:
+            - Identifier: ${tc.identifier}
+            - Title: ${tc.title}
+
+          You can view it here: https://test-management.browserstack.com/projects/${projectId}/folder/search?q=${tc.identifier}`,
+                },
+                {
+                    type: "text",
+                    text: JSON.stringify(tc, null, 2),
                 },
-                { type: "text", text: JSON.stringify(tc, null, 2) },
             ],
         };
     }

package/package.json

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