@browserstack/mcp-server 1.2.1 → 1.2.2-beta.1

package/dist/tools/accessibility.js

@@ -1,66 +1,211 @@
 import { z } from "zod";
 import { AccessibilityScanner } from "./accessiblity-utils/scanner.js";
 import { AccessibilityReportFetcher } from "./accessiblity-utils/report-fetcher.js";
+import { AccessibilityAuthConfig } from "./accessiblity-utils/auth-config.js";
 import { trackMCP } from "../lib/instrumentation.js";
 import { parseAccessibilityReportFromCSV } from "./accessiblity-utils/report-parser.js";
 import { queryAccessibilityRAG } from "./accessiblity-utils/accessibility-rag.js";
 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();
+import logger from "../logger.js";
+function setupAuth(config) {
     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;
-    const scanRunId = startResp.data.scanRunId;
-    // Notify scan start
+    return { username, password };
+}
+function createErrorResponse(message, isError = true) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: message,
+                isError,
+            },
+        ],
+        isError,
+    };
+}
+function createSuccessResponse(messages) {
+    return {
+        content: messages.map((text) => ({
+            type: "text",
+            text,
+        })),
+    };
+}
+function handleMCPError(toolName, server, config, error) {
+    trackMCP(toolName, server.server.getClientVersion(), error, config);
+    const errorMessage = error instanceof Error ? error.message : "Unknown error";
+    return createErrorResponse(`Failed to ${toolName.replace(/([A-Z])/g, " $1").toLowerCase()}: ${errorMessage}. Please open an issue on GitHub if the problem persists`);
+}
+async function notifyScanProgress(context, message, progress = 0) {
     await context.sendNotification({
         method: "notifications/progress",
         params: {
-            progressToken: context._meta?.progressToken ?? "NOT_FOUND",
-            message: `Accessibility scan "${name}" started`,
-            progress: 0,
+            progressToken: context._meta?.progressToken?.toString() ?? "NOT_FOUND",
+            message,
+            progress,
             total: 100,
         },
     });
-    // Wait until scan completes
+}
+async function initializeScanner(config) {
+    const scanner = new AccessibilityScanner();
+    const auth = setupAuth(config);
+    scanner.setAuth(auth);
+    return scanner;
+}
+async function initializeReportFetcher(config) {
+    const reportFetcher = new AccessibilityReportFetcher();
+    const auth = setupAuth(config);
+    reportFetcher.setAuth(auth);
+    return reportFetcher;
+}
+async function executeAccessibilityRAG(args, server, config) {
+    try {
+        trackMCP("accessibilityExpert", server.server.getClientVersion(), undefined, config);
+        return await queryAccessibilityRAG(args.query, config);
+    }
+    catch (error) {
+        return handleMCPError("accessibilityExpert", server, config, error);
+    }
+}
+async function executeFetchAccessibilityIssues(args, server, config) {
+    try {
+        trackMCP("fetchAccessibilityIssues", server.server.getClientVersion(), undefined, config);
+        return await fetchAccessibilityIssues(args.scanId, args.scanRunId, config, args.cursor);
+    }
+    catch (error) {
+        return handleMCPError("fetchAccessibilityIssues", server, config, error);
+    }
+}
+async function fetchAccessibilityIssues(scanId, scanRunId, config, cursor = 0) {
+    const reportFetcher = await initializeReportFetcher(config);
+    const reportLink = await reportFetcher.getReportLink(scanId, scanRunId);
+    const { records, page_length, total_issues, next_page } = await parseAccessibilityReportFromCSV(reportLink, { nextPage: cursor });
+    const currentlyShown = cursor === 0
+        ? page_length
+        : Math.floor(cursor / JSON.stringify(records[0] || {}).length) +
+            page_length;
+    const remainingIssues = total_issues - currentlyShown;
+    const messages = [
+        `Retrieved ${page_length} accessibility issues (Total: ${total_issues})`,
+        `Issues: ${JSON.stringify(records, null, 2)}`,
+    ];
+    if (next_page !== null) {
+        messages.push(`${remainingIssues} more issues available. Use fetchAccessibilityIssues with cursor: ${next_page} to get the next batch.`);
+    }
+    else {
+        messages.push(`✅ All issues retrieved.`);
+    }
+    return createSuccessResponse(messages);
+}
+async function executeAccessibilityScan(args, context, server, config) {
+    try {
+        trackMCP("startAccessibilityScan", server.server.getClientVersion(), undefined, config);
+        return await runAccessibilityScan(args.name, args.pageURL, context, config, args.authConfigId);
+    }
+    catch (error) {
+        return handleMCPError("startAccessibilityScan", server, config, error);
+    }
+}
+function validateFormAuthArgs(args) {
+    return (args.type === "form" &&
+        "usernameSelector" in args &&
+        "passwordSelector" in args &&
+        "submitSelector" in args &&
+        !!args.usernameSelector &&
+        !!args.passwordSelector &&
+        !!args.submitSelector);
+}
+async function createAuthConfig(args, config) {
+    const authConfig = new AccessibilityAuthConfig();
+    const auth = setupAuth(config);
+    authConfig.setAuth(auth);
+    if (args.type === "form") {
+        if (!validateFormAuthArgs(args)) {
+            throw new Error("Form authentication requires usernameSelector, passwordSelector, and submitSelector");
+        }
+        return await authConfig.createFormAuthConfig(args.name, {
+            username: args.username,
+            usernameSelector: args.usernameSelector,
+            password: args.password,
+            passwordSelector: args.passwordSelector,
+            submitSelector: args.submitSelector,
+            url: args.url,
+        });
+    }
+    else {
+        return await authConfig.createBasicAuthConfig(args.name, {
+            url: args.url,
+            username: args.username,
+            password: args.password,
+        });
+    }
+}
+async function executeCreateAuthConfig(args, server, config) {
+    try {
+        trackMCP("createAccessibilityAuthConfig", server.server.getClientVersion(), undefined, config);
+        logger.info(`Creating auth config: ${JSON.stringify(args)}`);
+        const result = await createAuthConfig(args, config);
+        return createSuccessResponse([
+            `✅ Auth config "${args.name}" created successfully with ID: ${result.data?.id}`,
+            `Auth config details: ${JSON.stringify(result.data, null, 2)}`,
+        ]);
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            error.message.includes("Form authentication requires")) {
+            return createErrorResponse(error.message);
+        }
+        return handleMCPError("createAccessibilityAuthConfig", server, config, error);
+    }
+}
+async function executeGetAuthConfig(args, server, config) {
+    try {
+        trackMCP("getAccessibilityAuthConfig", server.server.getClientVersion(), undefined, config);
+        const authConfig = new AccessibilityAuthConfig();
+        const auth = setupAuth(config);
+        authConfig.setAuth(auth);
+        const result = await authConfig.getAuthConfig(args.configId);
+        return createSuccessResponse([
+            `✅ Auth config retrieved successfully`,
+            `Auth config details: ${JSON.stringify(result.data, null, 2)}`,
+        ]);
+    }
+    catch (error) {
+        return handleMCPError("getAccessibilityAuthConfig", server, config, error);
+    }
+}
+function createScanFailureResponse(name, status) {
+    return createErrorResponse(`❌ Accessibility scan "${name}" failed with status: ${status} , check the BrowserStack dashboard for more details [https://scanner.browserstack.com/site-scanner/scan-details/${name}].`);
+}
+function createScanSuccessResponse(name, totalIssues, pageLength, records, scanId, scanRunId, reportUrl, cursor) {
+    const messages = [
+        `Accessibility scan "${name}" completed. check the BrowserStack dashboard for more details [https://scanner.browserstack.com/site-scanner/scan-details/${name}].`,
+        `Scan ID: ${scanId} and Scan Run ID: ${scanRunId}`,
+        `You can also download the full report from the following link: ${reportUrl}`,
+        `We found ${totalIssues} issues. Below are the details of the ${pageLength} most critical issues.`,
+        `Scan results: ${JSON.stringify(records, null, 2)}`,
+    ];
+    if (cursor !== null) {
+        messages.push(`More issues available. Use fetchAccessibilityIssues tool with scanId: "${scanId}", scanRunId: "${scanRunId}", and cursor: ${cursor} to get the next batch.`);
+    }
+    return createSuccessResponse(messages);
+}
+async function runAccessibilityScan(name, pageURL, context, config, authConfigId) {
+    const scanner = await initializeScanner(config);
+    const startResp = await scanner.startScan(name, [pageURL], authConfigId);
+    const scanId = startResp.data.id;
+    const scanRunId = startResp.data.scanRunId;
+    await notifyScanProgress(context, `Accessibility scan "${name}" started`, 0);
     const status = await scanner.waitUntilComplete(scanId, scanRunId, context);
     if (status !== "completed") {
-        return {
-            content: [
-                {
-                    type: "text",
-                    text: `❌ Accessibility scan "${name}" failed with status: ${status} , check the BrowserStack dashboard for more details [https://scanner.browserstack.com/site-scanner/scan-details/${name}].`,
-                    isError: true,
-                },
-            ],
-            isError: true,
-        };
-    }
-    // Create report fetcher and set auth on the go
-    const reportFetcher = new AccessibilityReportFetcher();
-    reportFetcher.setAuth({ username, password });
-    // Fetch CSV report link
+        return createScanFailureResponse(name, status);
+    }
+    const reportFetcher = await initializeReportFetcher(config);
     const reportLink = await reportFetcher.getReportLink(scanId, scanRunId);
-    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)}`,
-            },
-        ],
-    };
+    const { records, page_length, total_issues, next_page } = await parseAccessibilityReportFromCSV(reportLink);
+    return createScanSuccessResponse(name, total_issues, page_length, records, scanId, scanRunId, reportLink, next_page);
 }
 export default function addAccessibilityTools(server, config) {
     const tools = {};
@@ -69,44 +214,59 @@ export default function addAccessibilityTools(server, config) {
             .string()
             .describe("Any accessibility, a11y, WCAG, or web accessibility question"),
     }, async (args) => {
-        try {
-            trackMCP("accessibilityExpert", server.server.getClientVersion(), undefined, config);
-            return await queryAccessibilityRAG(args.query, config);
-        }
-        catch (error) {
-            trackMCP("accessibilityExpert", server.server.getClientVersion(), error, config);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `Failed to query accessibility RAG: ${error instanceof Error ? error.message : "Unknown error"}. Please open an issue on GitHub if the problem persists`,
-                    },
-                ],
-                isError: true,
-            };
-        }
+        return await executeAccessibilityRAG(args, server, config);
     });
     tools.startAccessibilityScan = server.tool("startAccessibilityScan", "Start an accessibility scan via BrowserStack and retrieve a local CSV report path.", {
         name: z.string().describe("Name of the accessibility scan"),
         pageURL: z.string().describe("The URL to scan for accessibility issues"),
+        authConfigId: z
+            .number()
+            .optional()
+            .describe("Optional auth config ID for authenticated scans"),
     }, async (args, context) => {
-        try {
-            trackMCP("startAccessibilityScan", server.server.getClientVersion(), undefined, config);
-            return await runAccessibilityScan(args.name, args.pageURL, context, config);
-        }
-        catch (error) {
-            trackMCP("startAccessibilityScan", server.server.getClientVersion(), error, config);
-            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,
-            };
-        }
+        return await executeAccessibilityScan(args, context, server, config);
+    });
+    tools.createAccessibilityAuthConfig = server.tool("createAccessibilityAuthConfig", "Create an authentication configuration for accessibility scans. Supports both form-based and basic authentication.", {
+        name: z.string().describe("Name for the auth configuration"),
+        type: z
+            .enum(["form", "basic"])
+            .describe("Authentication type: 'form' for form-based auth, 'basic' for HTTP basic auth"),
+        url: z.string().describe("URL of the authentication page"),
+        username: z.string().describe("Username for authentication"),
+        password: z.string().describe("Password for authentication"),
+        usernameSelector: z
+            .string()
+            .optional()
+            .describe("CSS selector for username field (required for form auth)"),
+        passwordSelector: z
+            .string()
+            .optional()
+            .describe("CSS selector for password field (required for form auth)"),
+        submitSelector: z
+            .string()
+            .optional()
+            .describe("CSS selector for submit button (required for form auth)"),
+    }, async (args) => {
+        return await executeCreateAuthConfig(args, server, config);
+    });
+    tools.getAccessibilityAuthConfig = server.tool("getAccessibilityAuthConfig", "Retrieve an existing authentication configuration by ID.", {
+        configId: z.number().describe("ID of the auth configuration to retrieve"),
+    }, async (args) => {
+        return await executeGetAuthConfig(args, server, config);
+    });
+    tools.fetchAccessibilityIssues = server.tool("fetchAccessibilityIssues", "Fetch accessibility issues from a completed scan with pagination support. Use cursor parameter to get subsequent pages of results.", {
+        scanId: z
+            .string()
+            .describe("The scan ID from a completed accessibility scan"),
+        scanRunId: z
+            .string()
+            .describe("The scan run ID from a completed accessibility scan"),
+        cursor: z
+            .number()
+            .optional()
+            .describe("Character offset for pagination (default: 0)"),
+    }, async (args) => {
+        return await executeFetchAccessibilityIssues(args, server, config);
     });
     return tools;
 }

package/dist/tools/accessiblity-utils/auth-config.d.ts

@@ -0,0 +1,39 @@
+export interface AuthConfigResponse {
+    success: boolean;
+    data?: {
+        id: number;
+        name: string;
+        type: string;
+        username?: string;
+        password?: string;
+        url?: string;
+        usernameSelector?: string;
+        passwordSelector?: string;
+        submitSelector?: string;
+    };
+    errors?: string[];
+}
+export interface FormAuthData {
+    username: string;
+    usernameSelector: string;
+    password: string;
+    passwordSelector: string;
+    submitSelector: string;
+    url: string;
+}
+export interface BasicAuthData {
+    url: string;
+    username: string;
+    password: string;
+}
+export declare class AccessibilityAuthConfig {
+    private auth;
+    setAuth(auth: {
+        username: string;
+        password: string;
+    }): void;
+    private transformLocalUrl;
+    createFormAuthConfig(name: string, authData: FormAuthData): Promise<AuthConfigResponse>;
+    createBasicAuthConfig(name: string, authData: BasicAuthData): Promise<AuthConfigResponse>;
+    getAuthConfig(configId: number): Promise<AuthConfigResponse>;
+}

package/dist/tools/accessiblity-utils/auth-config.js

@@ -0,0 +1,125 @@
+import { apiClient } from "../../lib/apiClient.js";
+import logger from "../../logger.js";
+export class AccessibilityAuthConfig {
+    auth;
+    setAuth(auth) {
+        this.auth = auth;
+    }
+    transformLocalUrl(url) {
+        try {
+            const parsed = new URL(url);
+            const localHosts = new Set(["127.0.0.1", "localhost", "0.0.0.0"]);
+            const BS_LOCAL_DOMAIN = "bs-local.com";
+            if (localHosts.has(parsed.hostname)) {
+                parsed.hostname = BS_LOCAL_DOMAIN;
+                return parsed.toString();
+            }
+            return url;
+        }
+        catch {
+            return url;
+        }
+    }
+    async createFormAuthConfig(name, authData) {
+        if (!this.auth?.username || !this.auth?.password) {
+            throw new Error("BrowserStack credentials are not set for AccessibilityAuthConfig.");
+        }
+        const transformedAuthData = {
+            ...authData,
+            url: this.transformLocalUrl(authData.url),
+        };
+        const requestBody = {
+            name,
+            type: "form",
+            authData: transformedAuthData,
+        };
+        try {
+            const response = await apiClient.post({
+                url: "https://api-accessibility.browserstack.com/api/website-scanner/v1/auth_configs",
+                headers: {
+                    Authorization: "Basic " +
+                        Buffer.from(`${this.auth.username}:${this.auth.password}`).toString("base64"),
+                    "Content-Type": "application/json",
+                },
+                body: requestBody,
+            });
+            const data = response.data;
+            logger.info(`The data returned from the API is: ${JSON.stringify(data)}`);
+            if (!data.success) {
+                throw new Error(`Unable to create auth config: ${data.errors?.join(", ")}`);
+            }
+            return data;
+        }
+        catch (err) {
+            logger.error(`Error creating form auth config: ${JSON.stringify(err?.response?.data)}`);
+            const msg = err?.response?.data?.error ||
+                err?.response?.data?.message ||
+                err?.message ||
+                String(err);
+            throw new Error(`Failed to create form auth config: ${msg}`);
+        }
+    }
+    async createBasicAuthConfig(name, authData) {
+        if (!this.auth?.username || !this.auth?.password) {
+            throw new Error("BrowserStack credentials are not set for AccessibilityAuthConfig.");
+        }
+        const transformedAuthData = {
+            ...authData,
+            url: this.transformLocalUrl(authData.url),
+        };
+        const requestBody = {
+            name,
+            type: "basic",
+            authData: transformedAuthData,
+        };
+        try {
+            const response = await apiClient.post({
+                url: "https://api-accessibility.browserstack.com/api/website-scanner/v1/auth_configs",
+                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 create auth config: ${data.errors?.join(", ")}`);
+            }
+            return data;
+        }
+        catch (err) {
+            const msg = err?.response?.data?.error ||
+                err?.response?.data?.message ||
+                err?.message ||
+                String(err);
+            throw new Error(`Failed to create basic auth config: ${msg}`);
+        }
+    }
+    async getAuthConfig(configId) {
+        if (!this.auth?.username || !this.auth?.password) {
+            throw new Error("BrowserStack credentials are not set for AccessibilityAuthConfig.");
+        }
+        try {
+            const response = await apiClient.get({
+                url: `https://api-accessibility.browserstack.com/api/website-scanner/v1/auth_configs/${configId}`,
+                headers: {
+                    Authorization: "Basic " +
+                        Buffer.from(`${this.auth.username}:${this.auth.password}`).toString("base64"),
+                },
+            });
+            const data = response.data;
+            if (!data.success) {
+                throw new Error(`Unable to get auth config: ${data.errors?.join(", ")}`);
+            }
+            return data;
+        }
+        catch (err) {
+            const msg = err?.response?.data?.error ||
+                err?.response?.data?.message ||
+                err?.message ||
+                String(err);
+            throw new Error(`Failed to get auth config: ${msg}`);
+        }
+    }
+}

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

@@ -19,7 +19,7 @@ export declare class AccessibilityScanner {
         username: string;
         password: string;
     }): void;
-    startScan(name: string, urlList: string[]): Promise<AccessibilityScanResponse>;
+    startScan(name: string, urlList: string[], authConfigId?: number): 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

@@ -8,7 +8,7 @@ export class AccessibilityScanner {
     setAuth(auth) {
         this.auth = auth;
     }
-    async startScan(name, urlList) {
+    async startScan(name, urlList, authConfigId) {
         if (!this.auth?.username || !this.auth?.password) {
             throw new Error("BrowserStack credentials are not set for AccessibilityScanner.");
         }
@@ -47,6 +47,7 @@ export class AccessibilityScanner {
             name,
             urlList: transformedUrlList,
             recurring: false,
+            ...(authConfigId && { authConfigId }),
         };
         let requestBody = baseRequestBody;
         if (hasLocal) {

package/dist/tools/add-percy-snapshots.d.ts

@@ -0,0 +1,5 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare function updateTestsWithPercyCommands(args: {
+    uuid: string;
+    index: number;
+}): Promise<CallToolResult>;

package/dist/tools/add-percy-snapshots.js

@@ -0,0 +1,17 @@
+import { testFilePathsMap } from "../lib/inmemory-store.js";
+import { updateFileAndStep } from "./percy-snapshot-utils/utils.js";
+import { percyWebSetupInstructions } from "../tools/sdk-utils/percy-web/handler.js";
+export async function updateTestsWithPercyCommands(args) {
+    const { uuid, index } = args;
+    const filePaths = testFilePathsMap.get(uuid);
+    if (!filePaths) {
+        throw new Error(`No test files found in memory for UUID: ${uuid}`);
+    }
+    if (index < 0 || index >= filePaths.length) {
+        throw new Error(`Invalid index: ${index}. There are ${filePaths.length} files for UUID: ${uuid}`);
+    }
+    const result = await updateFileAndStep(filePaths[index], index, filePaths.length, percyWebSetupInstructions);
+    return {
+        content: result,
+    };
+}

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

@@ -26,8 +26,9 @@ export declare function resolveVersion(versions: string[], requestedVersion: str
 export declare function validateArgs(args: {
     desiredPlatform: string;
     desiredPlatformVersion: string;
-    appPath: string;
+    appPath?: string;
     desiredPhone: string;
+    browserstackAppUrl?: string;
 }): void;
 /**
  * Uploads an application file to AppAutomate and returns the app URL

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

@@ -49,21 +49,24 @@ export function resolveVersion(versions, requestedVersion) {
  * Checks for presence and correctness of platform, device, and file types.
  */
 export function validateArgs(args) {
-    const { desiredPlatform, desiredPlatformVersion, appPath, desiredPhone } = args;
+    const { desiredPlatform, desiredPlatformVersion, appPath, desiredPhone, browserstackAppUrl, } = args;
     if (!desiredPlatform || !desiredPhone) {
         throw new Error("Missing required arguments: desiredPlatform and desiredPhone are required");
     }
     if (!desiredPlatformVersion) {
         throw new Error("Missing required arguments: desiredPlatformVersion is required");
     }
-    if (!appPath) {
-        throw new Error("You must provide an appPath.");
-    }
-    if (desiredPlatform === "android" && !appPath.endsWith(".apk")) {
-        throw new Error("You must provide a valid Android app path (.apk).");
-    }
-    if (desiredPlatform === "ios" && !appPath.endsWith(".ipa")) {
-        throw new Error("You must provide a valid iOS app path (.ipa).");
+    if (!appPath && !browserstackAppUrl) {
+        throw new Error("Either appPath or browserstackAppUrl must be provided");
+    }
+    // Only validate app path format if appPath is provided
+    if (appPath) {
+        if (desiredPlatform === "android" && !appPath.endsWith(".apk")) {
+            throw new Error("You must provide a valid Android app path (.apk).");
+        }
+        if (desiredPlatform === "ios" && !appPath.endsWith(".ipa")) {
+            throw new Error("You must provide a valid iOS app path (.ipa).");
+        }
     }
 }
 /**