@browserstack/mcp-server 1.1.8 → 1.2.0

package/dist/lib/version-resolver.d.ts

@@ -0,0 +1,6 @@
+/**
+ * If req === "latest" or "oldest", returns max/min numeric (or lex)
+ * Else if exact match, returns that
+ * Else picks the numerically closest (or first)
+ */
+export declare function resolveVersion(requested: string, available: string[]): string;

package/dist/logger.d.ts

@@ -0,0 +1,3 @@
+declare const logger: any;
+export declare function setLogger(customLogger: any): void;
+export default logger;

package/dist/logger.js

@@ -1,7 +1,8 @@
 import { pino } from "pino";
-let logger;
+// 1. The actual logger instance, swapped out as needed
+let currentLogger;
 if (process.env.NODE_ENV === "development") {
-    logger = pino({
+    currentLogger = pino({
         level: "debug",
         transport: {
             targets: [
@@ -21,8 +22,8 @@ if (process.env.NODE_ENV === "development") {
     });
 }
 else {
-    // NULL logger
-    logger = pino({
+    // Null logger (logs go to /dev/null or NUL)
+    currentLogger = pino({
         level: "info",
         transport: {
             target: "pino/file",
@@ -32,4 +33,19 @@ else {
         },
     });
 }
+// 2. Proxy logger: always delegates to the currentLogger
+const logger = new Proxy({}, {
+    get(_target, prop) {
+        // Forward function calls to currentLogger
+        if (typeof currentLogger[prop] === "function") {
+            return (...args) => currentLogger[prop](...args);
+        }
+        // Forward property gets
+        return currentLogger[prop];
+    },
+});
+// 3. Setter to update the logger instance everywhere
+export function setLogger(customLogger) {
+    currentLogger = customLogger;
+}
 export default logger;

package/dist/oninitialized.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function setupOnInitialized(server: McpServer, config?: any): void;

package/dist/oninitialized.js

@@ -1,16 +1,11 @@
-import config from "./config.js";
 import { trackMCP } from "./lib/instrumentation.js";
-export function setupOnInitialized(server) {
+export function setupOnInitialized(server, config) {
     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());
+        trackMCP("started", server.server.getClientVersion(), undefined, config);
     };
 }

package/dist/server-factory.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BrowserStackConfig } from "./lib/types.js";
+export declare function createMcpServer(config: BrowserStackConfig): McpServer;

package/dist/server-factory.js

@@ -0,0 +1,37 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+const packageJson = require("../package.json");
+import logger from "./logger.js";
+import addSDKTools from "./tools/bstack-sdk.js";
+import addBrowserLiveTools from "./tools/live.js";
+import addAccessibilityTools from "./tools/accessibility.js";
+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 addSelfHealTools from "./tools/selfheal.js";
+import addAppLiveTools from "./tools/applive.js";
+import { setupOnInitialized } from "./oninitialized.js";
+function registerTools(server, config) {
+    addAccessibilityTools(server, config);
+    addSDKTools(server, config);
+    addAppLiveTools(server, config);
+    addBrowserLiveTools(server, config);
+    addTestManagementTools(server, config);
+    addAppAutomationTools(server, config);
+    addFailureLogsTools(server, config);
+    addAutomateTools(server, config);
+    addSelfHealTools(server, config);
+}
+export function createMcpServer(config) {
+    logger.info("Creating BrowserStack MCP Server, version %s", packageJson.version);
+    // Create an MCP server
+    const server = new McpServer({
+        name: "BrowserStack MCP Server",
+        version: packageJson.version,
+    });
+    setupOnInitialized(server, config);
+    registerTools(server, config);
+    return server;
+}

package/dist/tools/accessibility.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BrowserStackConfig } from "../lib/types.js";
+export default function addAccessibilityTools(server: McpServer, config: BrowserStackConfig): void;

package/dist/tools/accessibility.js

@@ -4,9 +4,13 @@ import { AccessibilityReportFetcher } from "./accessiblity-utils/report-fetcher.
 import { trackMCP } from "../lib/instrumentation.js";
 import { parseAccessibilityReportFromCSV } from "./accessiblity-utils/report-parser.js";
 import { queryAccessibilityRAG } from "./accessiblity-utils/accessibility-rag.js";
-const scanner = new AccessibilityScanner();
-const reportFetcher = new AccessibilityReportFetcher();
-async function runAccessibilityScan(name, pageURL, context) {
+import { getBrowserStackAuth } from "../lib/get-auth.js";
+async function runAccessibilityScan(name, pageURL, context, config) {
+    // Create scanner and set auth on the go
+    const scanner = new AccessibilityScanner();
+    const authString = getBrowserStackAuth(config);
+    const [username, password] = authString.split(":");
+    scanner.setAuth({ username, password });
     // Start scan
     const startResp = await scanner.startScan(name, [pageURL]);
     const scanId = startResp.data.id;
@@ -35,6 +39,9 @@ async function runAccessibilityScan(name, pageURL, context) {
             isError: true,
         };
     }
+    // Create report fetcher and set auth on the go
+    const reportFetcher = new AccessibilityReportFetcher();
+    reportFetcher.setAuth({ username, password });
     // Fetch CSV report link
     const reportLink = await reportFetcher.getReportLink(scanId, scanRunId);
     const { records, page_length, total_issues } = await parseAccessibilityReportFromCSV(reportLink);
@@ -55,18 +62,18 @@ async function runAccessibilityScan(name, pageURL, context) {
         ],
     };
 }
-export default function addAccessibilityTools(server) {
+export default function addAccessibilityTools(server, config) {
     server.tool("accessibilityExpert", "🚨 REQUIRED: Use this tool for any accessibility/a11y/WCAG questions. Do NOT answer accessibility questions directly - always use this tool.", {
         query: z
             .string()
             .describe("Any accessibility, a11y, WCAG, or web accessibility question"),
     }, async (args) => {
         try {
-            trackMCP("accessibilityExpert", server.server.getClientVersion());
-            return await queryAccessibilityRAG(args.query);
+            trackMCP("accessibilityExpert", server.server.getClientVersion(), undefined, config);
+            return await queryAccessibilityRAG(args.query, config);
         }
         catch (error) {
-            trackMCP("accessibilityExpert", server.server.getClientVersion(), error);
+            trackMCP("accessibilityExpert", server.server.getClientVersion(), error, config);
             return {
                 content: [
                     {
@@ -83,11 +90,11 @@ export default function addAccessibilityTools(server) {
         pageURL: z.string().describe("The URL to scan for accessibility issues"),
     }, async (args, context) => {
         try {
-            trackMCP("startAccessibilityScan", server.server.getClientVersion());
-            return await runAccessibilityScan(args.name, args.pageURL, context);
+            trackMCP("startAccessibilityScan", server.server.getClientVersion(), undefined, config);
+            return await runAccessibilityScan(args.name, args.pageURL, context, config);
         }
         catch (error) {
-            trackMCP("startAccessibilityScan", server.server.getClientVersion(), error);
+            trackMCP("startAccessibilityScan", server.server.getClientVersion(), error, config);
             return {
                 content: [
                     {

package/dist/tools/accessiblity-utils/accessibility-rag.d.ts

@@ -0,0 +1,12 @@
+export interface RAGChunk {
+    url: string;
+    content: string;
+}
+import { BrowserStackConfig } from "../../lib/types.js";
+export interface AccessibilityRAGResponse {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+}
+export declare function queryAccessibilityRAG(userQuery: string, config: BrowserStackConfig): Promise<any>;

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

@@ -1,23 +1,27 @@
-import fetch from "node-fetch";
-import config from "../../config.js";
-export async function queryAccessibilityRAG(userQuery) {
+import { apiClient } from "../../lib/apiClient.js";
+import { getBrowserStackAuth } from "../../lib/get-auth.js";
+export async function queryAccessibilityRAG(userQuery, config) {
     const url = "https://accessibility.browserstack.com/api/tcg-proxy/search";
-    const auth = Buffer.from(`${config.browserstackUsername}:${config.browserstackAccessKey}`).toString("base64");
-    const response = await fetch(url, {
-        method: "POST",
+    const authString = getBrowserStackAuth(config);
+    const auth = Buffer.from(authString).toString("base64");
+    const response = await apiClient.post({
+        url,
         headers: {
             "Content-Type": "application/json",
             Authorization: `Basic ${auth}`,
         },
-        body: JSON.stringify({
+        body: {
             query: userQuery,
-        }),
+        },
+        raise_error: false,
     });
     if (!response.ok) {
-        const errorText = await response.text();
+        const errorText = typeof response.data === "string"
+            ? response.data
+            : JSON.stringify(response.data);
         throw new Error(`RAG endpoint error: ${response.status} ${errorText}`);
     }
-    const responseData = (await response.json());
+    const responseData = response.data;
     if (!responseData.success) {
         throw new Error("Something went wrong: " + responseData.message);
     }
@@ -26,8 +30,14 @@ export async function queryAccessibilityRAG(userQuery) {
     try {
         parsedData = JSON.parse(responseData.data);
     }
-    catch {
-        throw new Error("Failed to parse RAG response data as JSON");
+    catch (err) {
+        throw new Error("Failed to parse RAG response data as JSON: " +
+            (err instanceof Error ? err.message : String(err)));
+    }
+    if (!parsedData ||
+        !parsedData.data ||
+        !Array.isArray(parsedData.data.chunks)) {
+        throw new Error("RAG response data is missing expected 'data.chunks' array");
     }
     const chunks = parsedData.data.chunks;
     // Format the response properly

package/dist/tools/accessiblity-utils/report-fetcher.d.ts

@@ -0,0 +1,8 @@
+export declare class AccessibilityReportFetcher {
+    private auth;
+    setAuth(auth: {
+        username: string;
+        password: string;
+    }): void;
+    getReportLink(scanId: string, scanRunId: string): Promise<string>;
+}

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

@@ -1,28 +1,38 @@
-import axios from "axios";
-import config from "../../config.js";
+import { apiClient } from "../../lib/apiClient.js";
 export class AccessibilityReportFetcher {
-    auth = {
-        username: config.browserstackUsername,
-        password: config.browserstackAccessKey,
-    };
+    auth;
+    setAuth(auth) {
+        this.auth = auth;
+    }
     async getReportLink(scanId, scanRunId) {
         // Initiate CSV link generation
         const initUrl = `https://api-accessibility.browserstack.com/api/website-scanner/v1/scans/${scanId}/scan_runs/issues?scan_run_id=${scanRunId}`;
-        const initResp = await axios.get(initUrl, {
-            auth: this.auth,
+        let basicAuthHeader = undefined;
+        if (this.auth) {
+            const { username, password } = this.auth;
+            basicAuthHeader =
+                "Basic " + Buffer.from(`${username}:${password}`).toString("base64");
+        }
+        const initResp = await apiClient.get({
+            url: initUrl,
+            headers: basicAuthHeader ? { Authorization: basicAuthHeader } : undefined,
         });
-        if (!initResp.data.success) {
-            throw new Error(`Failed to initiate report: ${initResp.data.error || initResp.data.data.message}`);
+        const initData = initResp.data;
+        if (!initData.success) {
+            throw new Error(`Failed to initiate report: ${initData.error || initData.data.message}`);
         }
-        const taskId = initResp.data.data.task_id;
+        const taskId = initData.data.task_id;
         // Fetch the generated CSV link
         const reportUrl = `https://api-accessibility.browserstack.com/api/website-scanner/v1/scans/${scanId}/scan_runs/issues?task_id=${encodeURIComponent(taskId)}`;
-        const reportResp = await axios.get(reportUrl, {
-            auth: this.auth,
+        // Use apiClient for the report link request as well
+        const reportResp = await apiClient.get({
+            url: reportUrl,
+            headers: basicAuthHeader ? { Authorization: basicAuthHeader } : undefined,
         });
-        if (!reportResp.data.success) {
-            throw new Error(`Failed to fetch report: ${reportResp.data.error}`);
+        const reportData = reportResp.data;
+        if (!reportData.success) {
+            throw new Error(`Failed to fetch report: ${reportData.error}`);
         }
-        return reportResp.data.data.reportLink;
+        return reportData.data.reportLink;
     }
 }

package/dist/tools/accessiblity-utils/report-parser.d.ts

@@ -0,0 +1,23 @@
+type SimplifiedAccessibilityIssue = {
+    issue_type: string;
+    component: string;
+    issue_description: string;
+    HTML_snippet: string;
+    how_to_fix: string;
+    severity: string;
+};
+type PaginationOptions = {
+    /** How many JSON-chars max per “page” (default 10000) */
+    maxCharacterLength?: number;
+    /** Character offset to start from (default 0) */
+    nextPage?: number;
+};
+type PaginatedResult = {
+    records: SimplifiedAccessibilityIssue[];
+    /** Character offset for the next page, or null if done */
+    page_length: number;
+    total_issues: number;
+    next_page: number | null;
+};
+export declare function parseAccessibilityReportFromCSV(reportLink: string, { maxCharacterLength, nextPage }?: PaginationOptions): Promise<PaginatedResult>;
+export {};

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

@@ -1,11 +1,11 @@
-import fetch from "node-fetch";
+import { apiClient } from "../../lib/apiClient.js";
 import { parse } from "csv-parse/sync";
 export async function parseAccessibilityReportFromCSV(reportLink, { maxCharacterLength = 5000, nextPage = 0 } = {}) {
     // 1) Download & parse
-    const res = await fetch(reportLink);
+    const res = await apiClient.get({ url: reportLink });
     if (!res.ok)
         throw new Error(`Failed to download report: ${res.statusText}`);
-    const text = await res.text();
+    const text = typeof res.data === "string" ? res.data : JSON.stringify(res.data);
     const all = parse(text, {
         columns: true,
         skip_empty_lines: true,

package/dist/tools/accessiblity-utils/scanner.d.ts

@@ -0,0 +1,25 @@
+export interface AccessibilityScanResponse {
+    success: boolean;
+    data?: {
+        id: string;
+        scanRunId: string;
+    };
+    errors?: string[];
+}
+export interface AccessibilityScanStatus {
+    success: boolean;
+    data?: {
+        status: string;
+    };
+    errors?: string[];
+}
+export declare class AccessibilityScanner {
+    private auth;
+    setAuth(auth: {
+        username: string;
+        password: string;
+    }): void;
+    startScan(name: string, urlList: string[]): Promise<AccessibilityScanResponse>;
+    pollStatus(scanId: string, scanRunId: string): Promise<AccessibilityScanStatus>;
+    waitUntilComplete(scanId: string, scanRunId: string, context: any): Promise<string>;
+}

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

@@ -1,20 +1,30 @@
-import axios from "axios";
-import config from "../../config.js";
+import { apiClient } from "../../lib/apiClient.js";
+import { randomUUID } from "node:crypto";
 import logger from "../../logger.js";
 import { isLocalURL, ensureLocalBinarySetup, killExistingBrowserStackLocalProcesses, } from "../../lib/local.js";
+import config from "../../config.js";
 export class AccessibilityScanner {
-    auth = {
-        username: config.browserstackUsername,
-        password: config.browserstackAccessKey,
-    };
+    auth;
+    setAuth(auth) {
+        this.auth = auth;
+    }
     async startScan(name, urlList) {
+        if (!this.auth?.username || !this.auth?.password) {
+            throw new Error("BrowserStack credentials are not set for AccessibilityScanner.");
+        }
         // Check if any URL is local
         const hasLocal = urlList.some(isLocalURL);
-        const localIdentifier = crypto.randomUUID();
+        const localIdentifier = randomUUID();
         const localHosts = new Set(["127.0.0.1", "localhost", "0.0.0.0"]);
         const BS_LOCAL_DOMAIN = "bs-local.com";
+        if (config.USE_OWN_LOCAL_BINARY_PROCESS && hasLocal) {
+            throw new Error("Cannot start scan with local URLs when using own BrowserStack Local binary process. Please set USE_OWN_LOCAL_BINARY_PROCESS to false.");
+        }
+        if (config.REMOTE_MCP && hasLocal) {
+            throw new Error("Local URLs are not supported in this remote mcp. Please use a public URL.");
+        }
         if (hasLocal) {
-            await ensureLocalBinarySetup(localIdentifier);
+            await ensureLocalBinarySetup(this.auth.username, this.auth.password, localIdentifier);
         }
         else {
             await killExistingBrowserStackLocalProcesses();
@@ -49,37 +59,49 @@ export class AccessibilityScanner {
             requestBody = { ...baseRequestBody, ...localConfig };
         }
         try {
-            const { data } = await axios.post("https://api-accessibility.browserstack.com/api/website-scanner/v1/scans", requestBody, { auth: this.auth });
+            const response = await apiClient.post({
+                url: "https://api-accessibility.browserstack.com/api/website-scanner/v1/scans",
+                headers: {
+                    Authorization: "Basic " +
+                        Buffer.from(`${this.auth.username}:${this.auth.password}`).toString("base64"),
+                    "Content-Type": "application/json",
+                },
+                body: requestBody,
+            });
+            const data = response.data;
             if (!data.success)
                 throw new Error(`Unable to start scan: ${data.errors?.join(", ")}`);
             return data;
         }
         catch (err) {
-            if (axios.isAxiosError(err) && err.response?.data) {
-                if (err.response.status === 422) {
-                    throw new Error("A scan with this name already exists. please update the name and run again.");
-                }
-                const msg = err.response.data.error ||
-                    err.response.data.message ||
-                    err.message;
-                throw new Error(`Failed to start scan: ${msg}`);
+            // apiClient throws generic errors, try to extract message
+            if (err?.response?.status === 422) {
+                throw new Error("A scan with this name already exists. please update the name and run again.");
             }
-            throw err;
+            const msg = err?.response?.data?.error ||
+                err?.response?.data?.message ||
+                err?.message ||
+                String(err);
+            throw new Error(`Failed to start scan: ${msg}`);
         }
     }
     async pollStatus(scanId, scanRunId) {
         try {
-            const { data } = await axios.get(`https://api-accessibility.browserstack.com/api/website-scanner/v1/scans/${scanId}/scan_runs/${scanRunId}/status`, { auth: this.auth });
+            const response = await apiClient.get({
+                url: `https://api-accessibility.browserstack.com/api/website-scanner/v1/scans/${scanId}/scan_runs/${scanRunId}/status`,
+                headers: {
+                    Authorization: "Basic " +
+                        Buffer.from(`${this.auth?.username}:${this.auth?.password}`).toString("base64"),
+                },
+            });
+            const data = response.data;
             if (!data.success)
                 throw new Error(`Failed to get status: ${data.errors?.join(", ")}`);
             return data;
         }
         catch (err) {
-            if (axios.isAxiosError(err) && err.response?.data) {
-                const msg = err.response.data.message || err.message;
-                throw new Error(`Failed to get scan status: ${msg}`);
-            }
-            throw err;
+            const msg = err?.response?.data?.message || err?.message || String(err);
+            throw new Error(`Failed to get scan status: ${msg}`);
         }
     }
     async waitUntilComplete(scanId, scanRunId, context) {

package/dist/tools/appautomate-utils/appautomate.d.ts

@@ -0,0 +1,42 @@
+import { BrowserStackConfig } from "../../lib/types.js";
+interface Device {
+    device: string;
+    display_name: string;
+    os_version: string;
+    real_mobile: boolean;
+}
+/**
+ * Finds devices that exactly match the provided display name.
+ * Uses fuzzy search first, and then filters for exact case-insensitive match.
+ */
+export declare function findMatchingDevice(devices: Device[], deviceName: string): Device[];
+/**
+ * Extracts all unique OS versions from a device list and sorts them.
+ */
+export declare function getDeviceVersions(devices: Device[]): string[];
+/**
+ * Resolves the requested platform version against available versions.
+ * Supports 'latest' and 'oldest' as dynamic selectors.
+ */
+export declare function resolveVersion(versions: string[], requestedVersion: string): string;
+/**
+ * Validates the input arguments for taking app screenshots.
+ * Checks for presence and correctness of platform, device, and file types.
+ */
+export declare function validateArgs(args: {
+    desiredPlatform: string;
+    desiredPlatformVersion: string;
+    appPath: string;
+    desiredPhone: string;
+}): void;
+/**
+ * Uploads an application file to AppAutomate and returns the app URL
+ */
+export declare function uploadApp(appPath: string, username: string, password: string): Promise<string>;
+export declare function uploadEspressoApp(appPath: string, config: BrowserStackConfig): Promise<string>;
+export declare function uploadEspressoTestSuite(testSuitePath: string, config: BrowserStackConfig): Promise<string>;
+export declare function uploadXcuiApp(appPath: string, config: BrowserStackConfig): Promise<string>;
+export declare function uploadXcuiTestSuite(testSuitePath: string, config: BrowserStackConfig): Promise<string>;
+export declare function triggerEspressoBuild(app_url: string, test_suite_url: string, devices: string[], project: string): Promise<string>;
+export declare function triggerXcuiBuild(app_url: string, test_suite_url: string, devices: string[], project: string, config: BrowserStackConfig): Promise<string>;
+export {};