@browserstack/mcp-server 1.2.3 → 1.2.4

package/dist/tools/percy-snapshot-utils/utils.d.ts

@@ -0,0 +1,4 @@
+export declare function updateFileAndStep(file: string, idx: number, total: number, instruction: string): Promise<{
+    type: "text";
+    text: string;
+}[]>;

package/dist/tools/percy-snapshot-utils/utils.js

@@ -0,0 +1,30 @@
+const content = [];
+export async function updateFileAndStep(file, idx, total, instruction) {
+    content.length = 0;
+    const nextIndex = idx + 1;
+    content.push({
+        type: "text",
+        text: `Complete all steps in order. If a tool call is requested, update the file first, then call the tool. Follow instructions exactly— do not skip any steps to ensure all files are updated.`,
+    });
+    content.push({
+        type: "text",
+        text: `Step 1 : You need to add percy snapshot commands in some key test cases in the file ${file} use the following instructions: \n${instruction}`,
+    });
+    content.push({
+        type: "text",
+        text: `Step 2 : Confirm that Percy snapshot commands have been added at all key points of visual change in the file ${file}.`,
+    });
+    if (nextIndex < total) {
+        content.push({
+            type: "text",
+            text: `Step 3 : Call the tool updateTestFileWithInstructions with index as ${nextIndex} out of ${total}`,
+        });
+    }
+    if (nextIndex === total) {
+        content.push({
+            type: "text",
+            text: `Step 3: Percy snapshot commands have been added to all files. You can now run the tool runPercyScan to run the percy scan.`,
+        });
+    }
+    return content;
+}

package/dist/tools/rca-agent-utils/constants.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { TestStatus } from "./types.js";
+export declare const FETCH_RCA_PARAMS: {
+    testId: z.ZodArray<z.ZodString, "many">;
+};
+export declare const GET_BUILD_ID_PARAMS: {
+    browserStackProjectName: z.ZodString;
+    browserStackBuildName: z.ZodString;
+};
+export declare const LIST_TEST_IDS_PARAMS: {
+    buildId: z.ZodString;
+    status: z.ZodNativeEnum<typeof TestStatus>;
+};

package/dist/tools/rca-agent-utils/constants.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import { TestStatus } from "./types.js";
+export const FETCH_RCA_PARAMS = {
+    testId: z
+        .array(z.string())
+        .max(3)
+        .describe("Array of test IDs to fetch RCA data for (maximum 3 IDs). If not provided, use the listTestIds tool get all failed testcases. If more than 3 IDs are provided, only the first 3 will be processed."),
+};
+export const GET_BUILD_ID_PARAMS = {
+    browserStackProjectName: z
+        .string()
+        .describe("The BrowserStack project name used during test run creation. Action: First, check browserstack.yml or any equivalent project configuration files. If the project name is found, extract and return it. If it is not found or if there is any uncertainty, immediately prompt the user to provide the value. Do not infer, guess, or assume a default."),
+    browserStackBuildName: z
+        .string()
+        .describe("The BrowserStack build name used during test run creation. Action: First, check browserstack.yml or any equivalent project configuration files. If the build name is found, extract and return it. If it is not found or if there is any uncertainty, immediately prompt the user to provide the value. Do not infer, guess, or assume a default."),
+};
+export const LIST_TEST_IDS_PARAMS = {
+    buildId: z
+        .string()
+        .describe("The Browserstack Build ID of the test run. If not known, use the getBuildId tool to fetch it using project and build name"),
+    status: z
+        .nativeEnum(TestStatus)
+        .describe("Filter tests by status. If not provided, all tests are returned. Example for RCA usecase always use failed status"),
+};

package/dist/tools/rca-agent-utils/format-rca.d.ts

@@ -0,0 +1 @@
+export declare function formatRCAData(rcaData: any): string;

package/dist/tools/rca-agent-utils/format-rca.js

@@ -0,0 +1,37 @@
+// Utility function to format RCA data for better readability
+export function formatRCAData(rcaData) {
+    if (!rcaData || !rcaData.testCases || rcaData.testCases.length === 0) {
+        return "No RCA data available.";
+    }
+    let output = "## Root Cause Analysis Report\n\n";
+    rcaData.testCases.forEach((testCase, index) => {
+        // Show test case ID with smaller heading
+        output += `### Test Case ${index + 1}\n`;
+        output += `**Test ID:** ${testCase.id}\n`;
+        output += `**Status:** ${testCase.state}\n\n`;
+        // Access RCA data from the correct path
+        const rca = testCase.rcaData?.rcaData;
+        if (rca) {
+            if (rca.root_cause) {
+                output += `**Root Cause:** ${rca.root_cause}\n\n`;
+            }
+            if (rca.failure_type) {
+                output += `**Failure Type:** ${rca.failure_type}\n\n`;
+            }
+            if (rca.description) {
+                output += `**Detailed Analysis:**\n${rca.description}\n\n`;
+            }
+            if (rca.possible_fix) {
+                output += `**Recommended Fix:**\n${rca.possible_fix}\n\n`;
+            }
+        }
+        else if (testCase.rcaData?.error) {
+            output += `**Error:** ${testCase.rcaData.error}\n\n`;
+        }
+        else if (testCase.state === "failed") {
+            output += `**Note:** RCA analysis failed or is not available for this test case.\n\n`;
+        }
+        output += "---\n\n";
+    });
+    return output;
+}

package/dist/tools/rca-agent-utils/get-build-id.d.ts

@@ -0,0 +1 @@
+export declare function getBuildId(projectName: string, buildName: string, username: string, accessKey: string): Promise<string>;

package/dist/tools/rca-agent-utils/get-build-id.js

@@ -0,0 +1,18 @@
+export async function getBuildId(projectName, buildName, username, accessKey) {
+    const url = new URL("https://api-automation.browserstack.com/ext/v1/builds/latest");
+    url.searchParams.append("project_name", projectName);
+    url.searchParams.append("build_name", buildName);
+    url.searchParams.append("user_name", username);
+    const authHeader = "Basic " + Buffer.from(`${username}:${accessKey}`).toString("base64");
+    const response = await fetch(url.toString(), {
+        headers: {
+            Authorization: authHeader,
+            "Content-Type": "application/json",
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to fetch build ID: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    return data.build_id;
+}

package/dist/tools/rca-agent-utils/get-failed-test-id.d.ts

@@ -0,0 +1,2 @@
+import { TestStatus, FailedTestInfo } from "./types.js";
+export declare function getTestIds(buildId: string, authString: string, status?: TestStatus): Promise<FailedTestInfo[]>;

package/dist/tools/rca-agent-utils/get-failed-test-id.js

@@ -0,0 +1,69 @@
+import logger from "../../logger.js";
+export async function getTestIds(buildId, authString, status) {
+    const baseUrl = `https://api-automation.browserstack.com/ext/v1/builds/${buildId}/testRuns`;
+    let url = status ? `${baseUrl}?test_statuses=${status}` : baseUrl;
+    let allFailedTests = [];
+    let requestNumber = 0;
+    // Construct Basic auth header
+    const encodedCredentials = Buffer.from(authString).toString("base64");
+    const authHeader = `Basic ${encodedCredentials}`;
+    try {
+        while (true) {
+            requestNumber++;
+            const response = await fetch(url, {
+                headers: {
+                    Authorization: authHeader,
+                    "Content-Type": "application/json",
+                },
+            });
+            if (!response.ok) {
+                throw new Error(`Failed to fetch test runs: ${response.status} ${response.statusText}`);
+            }
+            const data = (await response.json());
+            // Extract failed IDs from current page
+            if (data.hierarchy && data.hierarchy.length > 0) {
+                const currentFailedTests = extractFailedTestIds(data.hierarchy, status);
+                allFailedTests = allFailedTests.concat(currentFailedTests);
+            }
+            // Check for pagination termination conditions
+            if (!data.pagination?.has_next ||
+                !data.pagination.next_page ||
+                requestNumber >= 5) {
+                break;
+            }
+            const params = {
+                next_page: data.pagination.next_page,
+            };
+            if (status)
+                params.test_statuses = status;
+            url = `${baseUrl}?${new URLSearchParams(params).toString()}`;
+        }
+        // Return unique failed test IDs
+        return allFailedTests;
+    }
+    catch (error) {
+        logger.error("Error fetching failed tests:", error);
+        throw error;
+    }
+}
+// Recursive function to extract failed test IDs from hierarchy
+function extractFailedTestIds(hierarchy, status) {
+    let failedTests = [];
+    for (const node of hierarchy) {
+        if (node.details?.status === status && node.details?.run_count) {
+            if (node.details?.observability_url) {
+                const idMatch = node.details.observability_url.match(/details=(\d+)/);
+                if (idMatch) {
+                    failedTests.push({
+                        test_id: idMatch[1],
+                        test_name: node.display_name || `Test ${idMatch[1]}`,
+                    });
+                }
+            }
+        }
+        if (node.children && node.children.length > 0) {
+            failedTests = failedTests.concat(extractFailedTestIds(node.children, status));
+        }
+    }
+    return failedTests;
+}

package/dist/tools/rca-agent-utils/rca-data.d.ts

@@ -0,0 +1,9 @@
+import { RCAResponse } from "./types.js";
+interface ScanProgressContext {
+    sendNotification: (notification: any) => Promise<void>;
+    _meta?: {
+        progressToken?: string | number;
+    };
+}
+export declare function getRCAData(testIds: string[], authString: string, context?: ScanProgressContext): Promise<RCAResponse>;
+export {};

package/dist/tools/rca-agent-utils/rca-data.js

@@ -0,0 +1,196 @@
+import { RCAState } from "./types.js";
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function isInProgressState(state) {
+    return [
+        RCAState.PENDING,
+        RCAState.FETCHING_LOGS,
+        RCAState.GENERATING_RCA,
+        RCAState.GENERATED_RCA,
+    ].includes(state);
+}
+function isFailedState(state) {
+    return [
+        RCAState.FAILED,
+        RCAState.LLM_SERVICE_ERROR,
+        RCAState.LOG_FETCH_ERROR,
+        RCAState.UNKNOWN_ERROR,
+        RCAState.TIMEOUT,
+    ].includes(state);
+}
+function calculateProgress(resolvedCount, totalCount, baseProgress = 10) {
+    if (totalCount === 0)
+        return 100; // ✅ fix divide by zero
+    const progressRange = 90 - baseProgress;
+    const completionProgress = (resolvedCount / totalCount) * progressRange;
+    return Math.min(100, baseProgress + completionProgress);
+}
+// ✅ centralized mapping function
+function mapApiState(apiState) {
+    const state = apiState?.toLowerCase();
+    switch (state) {
+        case "completed":
+            return RCAState.COMPLETED;
+        case "pending":
+            return RCAState.PENDING;
+        case "fetching_logs":
+            return RCAState.FETCHING_LOGS;
+        case "generating_rca":
+            return RCAState.GENERATING_RCA;
+        case "generated_rca":
+            return RCAState.GENERATED_RCA;
+        case "error":
+            return RCAState.UNKNOWN_ERROR;
+        default:
+            return RCAState.UNKNOWN_ERROR;
+    }
+}
+async function notifyProgress(context, message, progress) {
+    if (!context?.sendNotification)
+        return;
+    await context.sendNotification({
+        method: "notifications/progress",
+        params: {
+            progressToken: context._meta?.progressToken?.toString(),
+            message,
+            progress,
+            total: 100,
+        },
+    });
+}
+async function updateProgress(context, testCases, message) {
+    const inProgressCases = testCases.filter((tc) => isInProgressState(tc.state));
+    const resolvedCount = testCases.length - inProgressCases.length;
+    await notifyProgress(context, message ??
+        `RCA analysis in progress (${resolvedCount}/${testCases.length} resolved)`, inProgressCases.length === 0
+        ? 100
+        : calculateProgress(resolvedCount, testCases.length));
+}
+async function fetchInitialRCA(testId, headers, baseUrl) {
+    const url = baseUrl.replace("{testId}", testId);
+    try {
+        const response = await fetch(url, { headers });
+        if (!response.ok) {
+            return {
+                id: testId,
+                testRunId: testId,
+                state: RCAState.LOG_FETCH_ERROR,
+                rcaData: {
+                    error: `HTTP ${response.status}: Failed to start RCA analysis`,
+                },
+            };
+        }
+        const data = await response.json();
+        const resultState = mapApiState(data.state);
+        return {
+            id: testId,
+            testRunId: testId,
+            state: resultState,
+            ...(resultState === RCAState.COMPLETED && { rcaData: data }),
+            ...(isFailedState(resultState) &&
+                data.state && {
+                rcaData: {
+                    error: `API returned state: ${data.state}`,
+                    originalResponse: data,
+                },
+            }),
+        };
+    }
+    catch (error) {
+        return {
+            id: testId,
+            testRunId: testId,
+            state: RCAState.LLM_SERVICE_ERROR,
+            rcaData: {
+                error: error instanceof Error ? error.message : "Network or parsing error",
+            },
+        };
+    }
+}
+async function pollRCAResults(testCases, headers, baseUrl, context, pollInterval, timeout, initialDelay) {
+    const startTime = Date.now();
+    await delay(initialDelay);
+    try {
+        while (true) {
+            const inProgressCases = testCases.filter((tc) => isInProgressState(tc.state));
+            await updateProgress(context, testCases);
+            if (inProgressCases.length === 0)
+                break;
+            if (Date.now() - startTime >= timeout) {
+                inProgressCases.forEach((tc) => {
+                    tc.state = RCAState.TIMEOUT;
+                    tc.rcaData = { error: `Timeout after ${timeout}ms` };
+                });
+                await updateProgress(context, testCases, "RCA analysis timed out");
+                break;
+            }
+            await Promise.allSettled(inProgressCases.map(async (tc) => {
+                try {
+                    const pollUrl = baseUrl.replace("{testId}", tc.id);
+                    const response = await fetch(pollUrl, { headers });
+                    if (!response.ok) {
+                        const errorText = await response.text();
+                        tc.state = RCAState.LOG_FETCH_ERROR;
+                        tc.rcaData = {
+                            error: `HTTP ${response.status}: Polling failed - ${errorText}`,
+                        };
+                        return;
+                    }
+                    const data = await response.json();
+                    if (!isFailedState(tc.state)) {
+                        const mappedState = mapApiState(data.state);
+                        tc.state = mappedState;
+                        if (mappedState === RCAState.COMPLETED) {
+                            tc.rcaData = data;
+                        }
+                        else if (mappedState === RCAState.UNKNOWN_ERROR) {
+                            tc.rcaData = {
+                                error: `API returned state: ${data.state}`,
+                                originalResponse: data,
+                            };
+                        }
+                    }
+                }
+                catch (err) {
+                    if (!isFailedState(tc.state)) {
+                        tc.state = RCAState.LLM_SERVICE_ERROR;
+                        tc.rcaData = {
+                            error: err instanceof Error
+                                ? err.message
+                                : "Network or parsing error",
+                        };
+                    }
+                }
+            }));
+            await delay(pollInterval);
+        }
+    }
+    catch (err) {
+        testCases
+            .filter((tc) => isInProgressState(tc.state))
+            .forEach((tc) => {
+            tc.state = RCAState.UNKNOWN_ERROR;
+            tc.rcaData = {
+                error: err instanceof Error ? err.message : "Unexpected error",
+            };
+        });
+        await updateProgress(context, testCases, "RCA analysis failed due to unexpected error");
+    }
+    return { testCases };
+}
+export async function getRCAData(testIds, authString, context) {
+    const pollInterval = 5000;
+    const timeout = 40000;
+    const initialDelay = 20000;
+    const baseUrl = "https://api-observability.browserstack.com/ext/v1/testRun/{testId}/testRca";
+    const headers = {
+        Authorization: `Basic ${Buffer.from(authString).toString("base64")}`,
+        "Content-Type": "application/json",
+    };
+    await notifyProgress(context, "Starting RCA analysis for test cases...", 0);
+    const testCases = await Promise.all(testIds.map((testId) => fetchInitialRCA(testId, headers, baseUrl)));
+    const inProgressCount = testCases.filter((tc) => isInProgressState(tc.state)).length;
+    await notifyProgress(context, `Initial RCA requests completed. ${inProgressCount} cases pending analysis...`, 10);
+    if (inProgressCount === 0)
+        return { testCases };
+    return await pollRCAResults(testCases, headers, baseUrl, context, pollInterval, timeout, initialDelay);
+}

package/dist/tools/rca-agent-utils/types.d.ts

@@ -0,0 +1,48 @@
+export declare enum TestStatus {
+    PASSED = "passed",
+    FAILED = "failed",
+    PENDING = "pending",
+    SKIPPED = "skipped"
+}
+export interface TestDetails {
+    status: TestStatus;
+    details: any;
+    children?: TestDetails[];
+    display_name?: string;
+}
+export interface TestRun {
+    hierarchy: TestDetails[];
+    pagination?: {
+        has_next: boolean;
+        next_page: string | null;
+    };
+}
+export interface FailedTestInfo {
+    test_id: string;
+    test_name: string;
+}
+export declare enum RCAState {
+    PENDING = "pending",
+    FETCHING_LOGS = "fetching_logs",
+    GENERATING_RCA = "generating_rca",
+    GENERATED_RCA = "generated_rca",
+    COMPLETED = "completed",
+    FAILED = "failed",
+    LLM_SERVICE_ERROR = "LLM_SERVICE_ERROR",
+    LOG_FETCH_ERROR = "LOG_FETCH_ERROR",
+    UNKNOWN_ERROR = "UNKNOWN_ERROR",
+    TIMEOUT = "TIMEOUT"
+}
+export interface RCATestCase {
+    id: string;
+    testRunId: string;
+    state: RCAState;
+    rcaData?: any;
+}
+export interface RCAResponse {
+    testCases: RCATestCase[];
+}
+export interface BuildIdArgs {
+    browserStackProjectName: string;
+    browserStackBuildName: string;
+}

package/dist/tools/rca-agent-utils/types.js

@@ -0,0 +1,20 @@
+export var TestStatus;
+(function (TestStatus) {
+    TestStatus["PASSED"] = "passed";
+    TestStatus["FAILED"] = "failed";
+    TestStatus["PENDING"] = "pending";
+    TestStatus["SKIPPED"] = "skipped";
+})(TestStatus || (TestStatus = {}));
+export var RCAState;
+(function (RCAState) {
+    RCAState["PENDING"] = "pending";
+    RCAState["FETCHING_LOGS"] = "fetching_logs";
+    RCAState["GENERATING_RCA"] = "generating_rca";
+    RCAState["GENERATED_RCA"] = "generated_rca";
+    RCAState["COMPLETED"] = "completed";
+    RCAState["FAILED"] = "failed";
+    RCAState["LLM_SERVICE_ERROR"] = "LLM_SERVICE_ERROR";
+    RCAState["LOG_FETCH_ERROR"] = "LOG_FETCH_ERROR";
+    RCAState["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
+    RCAState["TIMEOUT"] = "TIMEOUT";
+})(RCAState || (RCAState = {}));

package/dist/tools/rca-agent.d.ts

@@ -0,0 +1,14 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { BrowserStackConfig } from "../lib/types.js";
+import { TestStatus } from "./rca-agent-utils/types.js";
+import { BuildIdArgs } from "./rca-agent-utils/types.js";
+export declare function getBuildIdTool(args: BuildIdArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+export declare function fetchRCADataTool(args: {
+    testId: string[];
+}, config: BrowserStackConfig): Promise<CallToolResult>;
+export declare function listTestIdsTool(args: {
+    buildId: string;
+    status?: TestStatus;
+}, config: BrowserStackConfig): Promise<CallToolResult>;
+export default function addRCATools(server: McpServer, config: BrowserStackConfig): Record<string, any>;

package/dist/tools/rca-agent.js

@@ -0,0 +1,119 @@
+import logger from "../logger.js";
+import { getBrowserStackAuth } from "../lib/get-auth.js";
+import { getBuildId } from "./rca-agent-utils/get-build-id.js";
+import { getTestIds } from "./rca-agent-utils/get-failed-test-id.js";
+import { getRCAData } from "./rca-agent-utils/rca-data.js";
+import { formatRCAData } from "./rca-agent-utils/format-rca.js";
+import { handleMCPError } from "../lib/utils.js";
+import { trackMCP } from "../index.js";
+import { FETCH_RCA_PARAMS, GET_BUILD_ID_PARAMS, LIST_TEST_IDS_PARAMS, } from "./rca-agent-utils/constants.js";
+// Tool function to fetch build ID
+export async function getBuildIdTool(args, config) {
+    try {
+        const { browserStackProjectName, browserStackBuildName } = args;
+        const authString = getBrowserStackAuth(config);
+        const [username, accessKey] = authString.split(":");
+        const buildId = await getBuildId(browserStackProjectName, browserStackBuildName, username, accessKey);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: buildId,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        logger.error("Error fetching build ID", error);
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error fetching build ID: ${errorMessage}`,
+                },
+            ],
+        };
+    }
+}
+// Tool function that fetches RCA data
+export async function fetchRCADataTool(args, config) {
+    try {
+        const authString = getBrowserStackAuth(config);
+        // Limit to first 3 test IDs for performance
+        const testIds = args.testId;
+        const rcaData = await getRCAData(testIds, authString);
+        const formattedData = formatRCAData(rcaData);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: formattedData,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        logger.error("Error fetching RCA data", error);
+        throw error;
+    }
+}
+export async function listTestIdsTool(args, config) {
+    try {
+        const { buildId, status } = args;
+        const authString = getBrowserStackAuth(config);
+        // Get test IDs
+        const testIds = await getTestIds(buildId, authString, status);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(testIds, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        logger.error("Error listing test IDs", error);
+        const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error listing test IDs: ${errorMessage}`,
+                },
+            ],
+        };
+    }
+}
+export default function addRCATools(server, config) {
+    const tools = {};
+    tools.fetchRCA = server.tool("fetchRCA", "Retrieves AI-RCA (Root Cause Analysis) data for a BrowserStack Automate and App-Automate session and provides insights into test failures.", FETCH_RCA_PARAMS, async (args) => {
+        try {
+            trackMCP("fetchRCA", server.server.getClientVersion(), config);
+            return await fetchRCADataTool(args, config);
+        }
+        catch (error) {
+            return handleMCPError("fetchRCA", server, config, error);
+        }
+    });
+    tools.getBuildId = server.tool("getBuildId", "Get the BrowserStack build ID for a given project and build name.", GET_BUILD_ID_PARAMS, async (args) => {
+        try {
+            trackMCP("getBuildId", server.server.getClientVersion(), config);
+            return await getBuildIdTool(args, config);
+        }
+        catch (error) {
+            return handleMCPError("getBuildId", server, config, error);
+        }
+    });
+    tools.listTestIds = server.tool("listTestIds", "List test IDs from a BrowserStack Automate build, optionally filtered by status", LIST_TEST_IDS_PARAMS, async (args) => {
+        try {
+            trackMCP("listTestIds", server.server.getClientVersion(), config);
+            return await listTestIdsTool(args, config);
+        }
+        catch (error) {
+            return handleMCPError("listTestIds", server, config, error);
+        }
+    });
+    return tools;
+}

package/dist/tools/review-agent-utils/build-counts.d.ts

@@ -0,0 +1,7 @@
+export declare function getPercyBuildCount(percyToken: string): Promise<{
+    noBuilds: boolean;
+    isFirstBuild: boolean;
+    lastBuildId: string | undefined;
+    orgId: string | undefined;
+    browserIds: string[];
+}>;