@browserstack/mcp-server 1.2.36 → 1.3.1-beta.1

package/README.md

@@ -41,6 +41,8 @@ Click on the buttons below to install MCP in your respective IDE:
 
 <a href="http://mcp.browserstack.com/one-click-setup?client=vscode"><img src="assets/one-click-vs-code.png" alt="Install in VS Code" width="160" height="80"></a>&nbsp;&nbsp;&nbsp;<a href="http://mcp.browserstack.com/one-click-setup?client=cursor"><img src="assets/one-click-cursor.png" alt="Install in Cursor" width="150" height="70"></a>
 
+> **Note:** The hosted Remote MCP server (`mcp.browserstack.com`) is now fully stateless over Streamable HTTP — any Streamable-HTTP client (Claude, Cursor, VS Code, ChatGPT) connects with no configuration change.
+
 #### Note : Ensure you are using Node version >= `18.0` 
 - Check your node version using `node --version`. Recommended version: `v22.15.0` (LTS)
 - To Upgrade Node :

package/dist/config.d.ts

@@ -8,7 +8,10 @@ export declare class Config {
     readonly USE_OWN_LOCAL_BINARY_PROCESS: boolean;
     readonly REMOTE_MCP: boolean;
     readonly UPLOAD_BASE_DIR: string | undefined;
-    constructor(DEV_MODE: boolean, browserstackLocalOptions: Record<string, any>, USE_OWN_LOCAL_BINARY_PROCESS: boolean, REMOTE_MCP: boolean, UPLOAD_BASE_DIR: string | undefined);
+    readonly O11Y_TFA_RCA_BASE_URL: string;
+    readonly BROWSERSTACK_AUTOMATION_BASE_URL: string;
+    readonly BROWSERSTACK_O11Y_UI_BASE_URL: string;
+    constructor(DEV_MODE: boolean, browserstackLocalOptions: Record<string, any>, USE_OWN_LOCAL_BINARY_PROCESS: boolean, REMOTE_MCP: boolean, UPLOAD_BASE_DIR: string | undefined, O11Y_TFA_RCA_BASE_URL: string, BROWSERSTACK_AUTOMATION_BASE_URL: string, BROWSERSTACK_O11Y_UI_BASE_URL: string);
 }
 declare const config: Config;
 export default config;

package/dist/config.js

@@ -28,6 +28,12 @@ for (const key of BROWSERSTACK_LOCAL_OPTION_KEYS) {
         browserstackLocalOptions[key] = envVar;
     }
 }
+// Overridable via O11Y_TFA_RCA_BASE_URL to target a staging tenant.
+const DEFAULT_O11Y_TFA_RCA_BASE_URL = "https://api-automation.browserstack.com";
+// Overridable via BROWSERSTACK_AUTOMATION_BASE_URL to target a non-prod env.
+const DEFAULT_BROWSERSTACK_AUTOMATION_BASE_URL = "https://api-automation.browserstack.com";
+// Overridable via BROWSERSTACK_O11Y_UI_BASE_URL to point at a staging UI.
+const DEFAULT_BROWSERSTACK_O11Y_UI_BASE_URL = "https://automation.browserstack.com";
 /**
  * USE_OWN_LOCAL_BINARY_PROCESS:
  *   If true, the system will not start a new local binary process, but will use the user's own process.
@@ -38,15 +44,30 @@ export class Config {
     USE_OWN_LOCAL_BINARY_PROCESS;
     REMOTE_MCP;
     UPLOAD_BASE_DIR;
-    constructor(DEV_MODE, browserstackLocalOptions, USE_OWN_LOCAL_BINARY_PROCESS, REMOTE_MCP, UPLOAD_BASE_DIR) {
+    O11Y_TFA_RCA_BASE_URL;
+    BROWSERSTACK_AUTOMATION_BASE_URL;
+    BROWSERSTACK_O11Y_UI_BASE_URL;
+    constructor(DEV_MODE, browserstackLocalOptions, USE_OWN_LOCAL_BINARY_PROCESS, REMOTE_MCP, UPLOAD_BASE_DIR, O11Y_TFA_RCA_BASE_URL, BROWSERSTACK_AUTOMATION_BASE_URL, BROWSERSTACK_O11Y_UI_BASE_URL) {
         this.DEV_MODE = DEV_MODE;
         this.browserstackLocalOptions = browserstackLocalOptions;
         this.USE_OWN_LOCAL_BINARY_PROCESS = USE_OWN_LOCAL_BINARY_PROCESS;
         this.REMOTE_MCP = REMOTE_MCP;
         this.UPLOAD_BASE_DIR = UPLOAD_BASE_DIR;
+        this.O11Y_TFA_RCA_BASE_URL = O11Y_TFA_RCA_BASE_URL;
+        this.BROWSERSTACK_AUTOMATION_BASE_URL = BROWSERSTACK_AUTOMATION_BASE_URL;
+        this.BROWSERSTACK_O11Y_UI_BASE_URL = BROWSERSTACK_O11Y_UI_BASE_URL;
     }
 }
 const config = new Config(process.env.DEV_MODE === "true", browserstackLocalOptions, process.env.USE_OWN_LOCAL_BINARY_PROCESS === "true", process.env.REMOTE_MCP === "true", process.env.MCP_UPLOAD_BASE_DIR && process.env.MCP_UPLOAD_BASE_DIR.length > 0
     ? process.env.MCP_UPLOAD_BASE_DIR
-    : undefined);
+    : undefined, process.env.O11Y_TFA_RCA_BASE_URL &&
+    process.env.O11Y_TFA_RCA_BASE_URL.length > 0
+    ? process.env.O11Y_TFA_RCA_BASE_URL
+    : DEFAULT_O11Y_TFA_RCA_BASE_URL, process.env.BROWSERSTACK_AUTOMATION_BASE_URL &&
+    process.env.BROWSERSTACK_AUTOMATION_BASE_URL.length > 0
+    ? process.env.BROWSERSTACK_AUTOMATION_BASE_URL
+    : DEFAULT_BROWSERSTACK_AUTOMATION_BASE_URL, process.env.BROWSERSTACK_O11Y_UI_BASE_URL &&
+    process.env.BROWSERSTACK_O11Y_UI_BASE_URL.length > 0
+    ? process.env.BROWSERSTACK_O11Y_UI_BASE_URL
+    : DEFAULT_BROWSERSTACK_O11Y_UI_BASE_URL);
 export default config;

package/dist/index.d.ts

@@ -3,4 +3,5 @@ import "dotenv/config";
 export { setLogger } from "./logger.js";
 export { BrowserStackMcpServer } from "./server-factory.js";
 export { trackMCP } from "./lib/instrumentation.js";
+export { default as addTfaRcaCollaborationTools } from "./tools/tfa-rca-collaboration.js";
 export declare const PackageJsonVersion: any;

package/dist/index.js

@@ -36,4 +36,5 @@ process.on("exit", () => {
 export { setLogger } from "./logger.js";
 export { BrowserStackMcpServer } from "./server-factory.js";
 export { trackMCP } from "./lib/instrumentation.js";
+export { default as addTfaRcaCollaborationTools } from "./tools/tfa-rca-collaboration.js";
 export const PackageJsonVersion = packageJson.version;

package/dist/lib/tm-base-url.js

@@ -20,6 +20,7 @@ export async function getTMBaseURL(config) {
     const authString = getBrowserStackAuth(config);
     const [username, password] = authString.split(":");
     const authHeader = "Basic " + Buffer.from(`${username}:${password}`).toString("base64");
+    const failures = [];
     for (const baseUrl of TM_BASE_URLS) {
         try {
             const res = await apiClient.get({
@@ -27,6 +28,9 @@ export async function getTMBaseURL(config) {
                 headers: { Authorization: authHeader },
                 raise_error: false,
             });
+            if (!res.ok) {
+                failures.push(`${baseUrl}: HTTP ${res.status}`);
+            }
             if (res.ok) {
                 // Only populate the cache in single-tenant (stdio) mode; in remote mode
                 // the cache must stay empty so each user discovers their own region.
@@ -38,8 +42,10 @@ export async function getTMBaseURL(config) {
             }
         }
         catch (err) {
+            const code = err?.code ?? err?.message;
+            failures.push(`${baseUrl}: ${code}`);
             logger.debug(`Failed TM base URL: ${baseUrl} (${err})`);
         }
     }
-    throw new Error("Unable to connect to BrowserStack Test Management. Please check your credentials and network connection.Please open an issue on GitHub if the problem persists");
+    throw new Error(`Unable to connect to BrowserStack Test Management. Please check your credentials and network connection.Please open an issue on GitHub if the problem persists. Details: ${failures.join("; ")}`);
 }

package/dist/tools/accessibility.js

@@ -213,6 +213,12 @@ export default function addAccessibilityTools(server, config) {
         query: z
             .string()
             .describe("Any accessibility, a11y, WCAG, or web accessibility question"),
+    }, {
+        title: "Accessibility Expert",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
     }, async (args) => {
         return await executeAccessibilityRAG(args, server, config);
     });
@@ -227,6 +233,12 @@ export default function addAccessibilityTools(server, config) {
             .boolean()
             .optional()
             .describe("Enable advanced accessibility rules in the scan settings"),
+    }, {
+        title: "Start Accessibility Scan",
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
     }, async (args, context) => {
         return await executeAccessibilityScan(args, context, server, config);
     });
@@ -256,6 +268,12 @@ export default function addAccessibilityTools(server, config) {
             .string()
             .optional()
             .describe("CSS selector for submit button (required for form auth)"),
+    }, {
+        title: "Create Accessibility Auth Config",
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
     }, async (args) => {
         try {
             const creds = await elicitCredentialsIfSupported(server, { username: args.username, password: args.password }, [
@@ -287,6 +305,12 @@ export default function addAccessibilityTools(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"),
+    }, {
+        title: "Get Accessibility Auth Config",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
     }, async (args) => {
         return await executeGetAuthConfig(args, server, config);
     });
@@ -301,6 +325,12 @@ export default function addAccessibilityTools(server, config) {
             .number()
             .optional()
             .describe("Character offset for pagination (default: 0)"),
+    }, {
+        title: "Fetch Accessibility Issues",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
     }, async (args) => {
         return await executeFetchAccessibilityIssues(args, server, config);
     });

package/dist/tools/appautomate.js

@@ -207,6 +207,12 @@ export default function addAppAutomationTools(server, config) {
         appPath: z
             .string()
             .describe("The path to the .apk or .ipa file. Required for app installation."),
+    }, {
+        title: "Take App Screenshot",
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
     }, async (args) => {
         try {
             trackMCP("takeAppScreenshot", server.server.getClientVersion(), undefined, config);
@@ -226,7 +232,13 @@ export default function addAppAutomationTools(server, config) {
             };
         }
     });
-    tools.runAppTestsOnBrowserStack = server.tool("runAppTestsOnBrowserStack", RUN_APP_AUTOMATE_DESCRIPTION, RUN_APP_AUTOMATE_SCHEMA, async (args) => {
+    tools.runAppTestsOnBrowserStack = server.tool("runAppTestsOnBrowserStack", RUN_APP_AUTOMATE_DESCRIPTION, RUN_APP_AUTOMATE_SCHEMA, {
+        title: "Run App Tests on BrowserStack",
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+    }, async (args) => {
         try {
             trackMCP("runAppTestsOnBrowserStack", server.server.getClientVersion(), undefined, config);
             const devicesAsArrays = args.devices.map((device) => [device.platform, device.deviceName, device.osVersion]);
@@ -246,7 +258,13 @@ export default function addAppAutomationTools(server, config) {
             };
         }
     });
-    tools.setupBrowserStackAppAutomateTests = server.tool("setupBrowserStackAppAutomateTests", SETUP_APP_AUTOMATE_DESCRIPTION, SETUP_APP_AUTOMATE_SCHEMA, async (args) => {
+    tools.setupBrowserStackAppAutomateTests = server.tool("setupBrowserStackAppAutomateTests", SETUP_APP_AUTOMATE_DESCRIPTION, SETUP_APP_AUTOMATE_SCHEMA, {
+        title: "Set Up App Automate Tests",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    }, async (args) => {
         try {
             return await setupAppAutomateHandler(args, config);
         }

package/dist/tools/applive.js

@@ -67,6 +67,12 @@ export default function addAppLiveTools(server, config) {
         appPath: z
             .string()
             .describe("The path to the .ipa or .apk file to install on the device. Always ask the user for the app path, do not assume it."),
+    }, {
+        title: "Run App Live Session",
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
     }, async (args) => {
         try {
             trackMCP("runAppLiveSession", server.server.getClientVersion(), undefined, config);

package/dist/tools/automate.js

@@ -58,6 +58,12 @@ export default function addAutomationTools(server, config) {
         sessionType: z
             .enum([SessionType.Automate, SessionType.AppAutomate])
             .describe("Type of BrowserStack session"),
+    }, {
+        title: "Fetch Automation Screenshots",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
     }, async (args) => {
         try {
             trackMCP("fetchAutomationScreenshots", server.server.getClientVersion(), undefined, config);

package/dist/tools/bstack-sdk.js

@@ -5,7 +5,13 @@ import { handleMCPError } from "../lib/utils.js";
 import { trackMCP } from "../lib/instrumentation.js";
 export function registerRunBrowserStackTestsTool(server, config) {
     const tools = {};
-    tools.setupBrowserStackAutomateTests = server.tool("setupBrowserStackAutomateTests", RUN_ON_BROWSERSTACK_DESCRIPTION, RunTestsOnBrowserStackParamsShape, async (args) => {
+    tools.setupBrowserStackAutomateTests = server.tool("setupBrowserStackAutomateTests", RUN_ON_BROWSERSTACK_DESCRIPTION, RunTestsOnBrowserStackParamsShape, {
+        title: "Set Up Automate Tests",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    }, async (args) => {
         try {
             trackMCP("runTestsOnBrowserStack", server.server.getClientVersion(), config);
             return await runTestsOnBrowserStackHandler(args, config);

package/dist/tools/build-insights.js

@@ -7,9 +7,13 @@ export async function fetchBuildInsightsTool(args, config) {
     try {
         const buildUrl = `https://api-automation.browserstack.com/ext/v1/builds/${args.buildId}`;
         const qualityGateUrl = `https://api-automation.browserstack.com/ext/v1/quality-gates/${args.buildId}`;
+        // Quality gate data is optional — a failure there should not block build insights
         const [buildData, qualityData] = await Promise.all([
             fetchFromBrowserStackAPI(buildUrl, config),
-            fetchFromBrowserStackAPI(qualityGateUrl, config),
+            fetchFromBrowserStackAPI(qualityGateUrl, config).catch((error) => {
+                logger.warn("Failed to fetch quality gate data", error);
+                return null;
+            }),
         ]);
         // Select useful fields for users
         const insights = {
@@ -25,9 +29,12 @@ export async function fetchBuildInsightsTool(args, config) {
             unique_errors: buildData.unique_errors?.overview,
             observability_url: buildData?.observability_url,
             ci_build_url: buildData.ci_info?.build_url,
-            quality_gate_result: qualityData.quality_gate_result,
+            branch: buildData.vcs_info?.branch,
+            commit_sha: buildData.vcs_info?.sha,
+            vcs_name: buildData.vcs_info?.name,
+            quality_gate_result: qualityData?.quality_gate_result,
         };
-        const qualityProfiles = qualityData.quality_profiles?.map((profile) => ({
+        const qualityProfiles = qualityData?.quality_profiles?.map((profile) => ({
             name: profile.name,
             result: profile.result,
         }));
@@ -54,6 +61,12 @@ export default function addBuildInsightsTools(server, config) {
     const tools = {};
     tools.fetchBuildInsights = server.tool("fetchBuildInsights", "Fetches insights about a BrowserStack build by combining build details and quality gate results.", {
         buildId: z.string().describe("The build UUID of the BrowserStack build"),
+    }, {
+        title: "Fetch Build Insights",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
     }, async (args) => {
         try {
             trackMCP("fetchBuildInsights", server.server.getClientVersion(), config);

package/dist/tools/get-failure-logs.js

@@ -119,6 +119,12 @@ export default function registerGetFailureLogs(server, config) {
             AppAutomateLogType.CrashLogs,
         ]))
             .describe("The types of logs to fetch."),
+    }, {
+        title: "Get Failure Logs",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
     }, async (args) => {
         try {
             trackMCP("getFailureLogs", server.server.getClientVersion(), undefined, config);

package/dist/tools/live.js

@@ -88,7 +88,13 @@ async function runBrowserSession(rawArgs, config) {
 }
 export default function addBrowserLiveTools(server, config) {
     const tools = {};
-    tools.runBrowserLiveSession = server.tool("runBrowserLiveSession", "Launch a BrowserStack Live session (desktop or mobile).", LiveArgsShape, async (args) => {
+    tools.runBrowserLiveSession = server.tool("runBrowserLiveSession", "Launch a BrowserStack Live session (desktop or mobile).", LiveArgsShape, {
+        title: "Run Browser Live Session",
+        readOnlyHint: false,
+        openWorldHint: true,
+        destructiveHint: false,
+        idempotentHint: false,
+    }, async (args) => {
         try {
             trackMCP("runBrowserLiveSession", server.server.getClientVersion(), undefined, config);
             return await runBrowserSession(args, config);

package/dist/tools/observability.js

@@ -39,6 +39,12 @@ export default function addObservabilityTools(server, config) {
         projectName: z
             .string()
             .describe("Name of the project to get failures for. This is the 'projectName' key in the browserstack.yml file. If not sure, ask the user for the project name."),
+    }, {
+        title: "Get Failures in Last Run",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
     }, async (args) => {
         try {
             trackMCP("getFailuresInLastRun", server.server.getClientVersion(), undefined, config);

package/dist/tools/percy-sdk.js

@@ -30,7 +30,13 @@ export function registerPercyTools(server, config) {
             ],
         };
     });
-    tools.percyVisualTestIntegrationAgent = server.tool("percyVisualTestIntegrationAgent", SIMULATE_PERCY_CHANGE_DESCRIPTION, SetUpPercyParamsShape, async (args) => {
+    tools.percyVisualTestIntegrationAgent = server.tool("percyVisualTestIntegrationAgent", SIMULATE_PERCY_CHANGE_DESCRIPTION, SetUpPercyParamsShape, {
+        title: "Percy Visual Test Integration Agent",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    }, async (args) => {
         try {
             trackMCP("VisualTestIntegrationAgent", server.server.getClientVersion(), config);
             return simulatePercyChangeHandler(args, config);
@@ -39,7 +45,13 @@ export function registerPercyTools(server, config) {
             return handleMCPError("VisualTestIntegrationAgent", server, config, error);
         }
     });
-    tools.setupPercyVisualTesting = server.tool("expandPercyVisualTesting", SETUP_PERCY_DESCRIPTION, SetUpPercyParamsShape, async (args) => {
+    tools.setupPercyVisualTesting = server.tool("expandPercyVisualTesting", SETUP_PERCY_DESCRIPTION, SetUpPercyParamsShape, {
+        title: "Expand Percy Visual Testing",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    }, async (args) => {
         try {
             trackMCP("setupPercyVisualTesting", server.server.getClientVersion(), config);
             return setUpPercyHandler(args, config);
@@ -48,7 +60,13 @@ export function registerPercyTools(server, config) {
             return handleMCPError("setupPercyVisualTesting", server, config, error);
         }
     });
-    tools.addPercySnapshotCommands = server.tool("addPercySnapshotCommands", PERCY_SNAPSHOT_COMMANDS_DESCRIPTION, UpdateTestFileWithInstructionsParams, async (args) => {
+    tools.addPercySnapshotCommands = server.tool("addPercySnapshotCommands", PERCY_SNAPSHOT_COMMANDS_DESCRIPTION, UpdateTestFileWithInstructionsParams, {
+        title: "Add Percy Snapshot Commands",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    }, async (args) => {
         try {
             trackMCP("addPercySnapshotCommands", server.server.getClientVersion(), config);
             return await updateTestsWithPercyCommands(args);
@@ -57,7 +75,13 @@ export function registerPercyTools(server, config) {
             return handleMCPError("addPercySnapshotCommands", server, config, error);
         }
     });
-    tools.listTestFiles = server.tool("listTestFiles", LIST_TEST_FILES_DESCRIPTION, {}, async () => {
+    tools.listTestFiles = server.tool("listTestFiles", LIST_TEST_FILES_DESCRIPTION, {}, {
+        title: "List Test Files",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    }, async () => {
         try {
             trackMCP("listTestFiles", server.server.getClientVersion(), config);
             return addListTestFiles();
@@ -66,7 +90,13 @@ export function registerPercyTools(server, config) {
             return handleMCPError("listTestFiles", server, config, error);
         }
     });
-    tools.runPercyScan = server.tool("runPercyScan", "Run a Percy visual test scan. Example prompts : Run this Percy build/scan. Never run percy scan/build without this tool", RunPercyScanParamsShape, async (args) => {
+    tools.runPercyScan = server.tool("runPercyScan", "Run a Percy visual test scan. Example prompts : Run this Percy build/scan. Never run percy scan/build without this tool", RunPercyScanParamsShape, {
+        title: "Run Percy Scan",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    }, async (args) => {
         try {
             trackMCP("runPercyScan", server.server.getClientVersion(), config);
             return runPercyScan(args);
@@ -75,7 +105,13 @@ export function registerPercyTools(server, config) {
             return handleMCPError("runPercyScan", server, config, error);
         }
     });
-    tools.fetchPercyChanges = server.tool("fetchPercyChanges", "Retrieves and summarizes all visual changes detected by Percy AI between the latest and previous builds, helping quickly review what has changed in your project.", FetchPercyChangesParamsShape, async (args) => {
+    tools.fetchPercyChanges = server.tool("fetchPercyChanges", "Retrieves and summarizes all visual changes detected by Percy AI between the latest and previous builds, helping quickly review what has changed in your project.", FetchPercyChangesParamsShape, {
+        title: "Fetch Percy Changes",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    }, async (args) => {
         try {
             trackMCP("fetchPercyChanges", server.server.getClientVersion(), config);
             return await fetchPercyChanges(args, config);
@@ -84,7 +120,13 @@ export function registerPercyTools(server, config) {
             return handleMCPError("fetchPercyChanges", server, config, error);
         }
     });
-    tools.managePercyBuildApproval = server.tool("managePercyBuildApproval", "Approve or reject a Percy build", ManagePercyBuildApprovalParamsShape, async (args) => {
+    tools.managePercyBuildApproval = server.tool("managePercyBuildApproval", "Approve or reject a Percy build", ManagePercyBuildApprovalParamsShape, {
+        title: "Manage Percy Build Approval",
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+    }, async (args) => {
         try {
             trackMCP("managePercyBuildApproval", server.server.getClientVersion(), config);
             return await approveOrDeclinePercyBuild(args, config);

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

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { TestStatus } from "./types.js";
+export declare function getAutomationBaseUrl(): string;
 export declare const FETCH_RCA_PARAMS: {
     testId: z.ZodArray<z.ZodNumber>;
 };
@@ -10,4 +11,5 @@ export declare const GET_BUILD_ID_PARAMS: {
 export declare const LIST_TEST_IDS_PARAMS: {
     buildId: z.ZodString;
     status: z.ZodEnum<typeof TestStatus>;
+    includeFailureDetail: z.ZodOptional<z.ZodBoolean>;
 };

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

@@ -1,5 +1,9 @@
 import { z } from "zod";
+import appConfig from "../../config.js";
 import { TestStatus } from "./types.js";
+export function getAutomationBaseUrl() {
+    return appConfig.BROWSERSTACK_AUTOMATION_BASE_URL;
+}
 export const FETCH_RCA_PARAMS = {
     testId: z
         .array(z.number().int())
@@ -21,4 +25,8 @@ export const LIST_TEST_IDS_PARAMS = {
     status: z
         .nativeEnum(TestStatus)
         .describe("Filter tests by status. If not provided, all tests are returned. Example for RCA usecase always use failed status"),
+    includeFailureDetail: z
+        .boolean()
+        .optional()
+        .describe("Add per-test failure signature for clustering. Default false."),
 };

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

@@ -1,3 +1,4 @@
 import { TestStatus, FailedTestInfo, TestDetails } from "./types.js";
-export declare function getTestIds(buildId: string, authString: string, status?: TestStatus): Promise<FailedTestInfo[]>;
-export declare function extractFailedTestIds(hierarchy: TestDetails[], status?: TestStatus): FailedTestInfo[];
+export declare function getTestIds(buildId: string, authString: string, status?: TestStatus, includeFailureDetail?: boolean): Promise<FailedTestInfo[]>;
+export declare function extractTestIds(hierarchy: TestDetails[], status?: TestStatus, includeFailureDetail?: boolean): FailedTestInfo[];
+export declare const extractFailedTestIds: typeof extractTestIds;

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

@@ -1,8 +1,15 @@
 import logger from "../../logger.js";
-export async function getTestIds(buildId, authString, status) {
-    const baseUrl = `https://api-automation.browserstack.com/ext/v1/builds/${buildId}/testRuns`;
+import { getAutomationBaseUrl } from "./constants.js";
+import { TestStatus, } from "./types.js";
+// Keeps the response payload lean — never full stack traces.
+const ERROR_SUMMARY_MAX = 200;
+// Safety bound on pagination; hitting it is logged, never silent.
+const MAX_PAGES = 100;
+export async function getTestIds(buildId, authString, status, includeFailureDetail = false) {
+    // No `status` → returns ALL tests; a `status` narrows the query.
+    const baseUrl = `${getAutomationBaseUrl()}/ext/v1/builds/${buildId}/testRuns`;
     let url = status ? `${baseUrl}?test_statuses=${status}` : baseUrl;
-    let allFailedTests = [];
+    let allTests = [];
     let requestNumber = 0;
     // Construct Basic auth header
     const encodedCredentials = Buffer.from(authString).toString("base64");
@@ -20,15 +27,16 @@ export async function getTestIds(buildId, authString, status) {
                 throw new Error(`Failed to fetch test runs: ${response.status} ${response.statusText}`);
             }
             const data = (await response.json());
-            // Extract failed IDs from current page
+            // Extract test IDs from the current page (all tests unless narrowed).
             if (data.hierarchy && data.hierarchy.length > 0) {
-                const currentFailedTests = extractFailedTestIds(data.hierarchy, status);
-                allFailedTests = allFailedTests.concat(currentFailedTests);
+                const currentTests = extractTestIds(data.hierarchy, status, includeFailureDetail);
+                allTests = allTests.concat(currentTests);
             }
-            // Check for pagination termination conditions
-            if (!data.pagination?.has_next ||
-                !data.pagination.next_page ||
-                requestNumber >= 5) {
+            if (!data.pagination?.has_next || !data.pagination.next_page) {
+                break;
+            }
+            if (requestNumber >= MAX_PAGES) {
+                logger.warn(`listTestIds: hit MAX_PAGES (${MAX_PAGES}) for build ${buildId}; result may be partial`);
                 break;
             }
             const params = {
@@ -38,31 +46,92 @@ export async function getTestIds(buildId, authString, status) {
                 params.test_statuses = status;
             url = `${baseUrl}?${new URLSearchParams(params).toString()}`;
         }
-        // Return unique failed test IDs
-        return allFailedTests;
+        return allTests;
     }
     catch (error) {
-        logger.error("Error fetching failed tests:", error);
+        logger.error("Error fetching test runs:", error);
         throw error;
     }
 }
-export function extractFailedTestIds(hierarchy, status) {
-    let failedTests = [];
+export function extractTestIds(hierarchy, status, includeFailureDetail = false) {
+    let tests = [];
     for (const node of hierarchy) {
-        if (node.details?.status === status) {
-            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]}`,
-                    });
+        // observability_url `details=<id>` filters out suite/hook nodes. run_count
+        // is not required — JUnit-uploaded builds report run_count=0 for real tests too.
+        const nodeStatus = node.details?.status;
+        const statusMatches = status === undefined || nodeStatus === status;
+        if (statusMatches && node.details?.observability_url) {
+            const idMatch = node.details.observability_url.match(/details=(\d+)/);
+            if (idMatch) {
+                const entry = {
+                    test_id: idMatch[1],
+                    test_name: node.display_name || `Test ${idMatch[1]}`,
+                    status: nodeStatus,
+                };
+                // Failure signatures only exist for failed tests; include when asked.
+                if (includeFailureDetail && nodeStatus === TestStatus.FAILED) {
+                    const signature = buildFailureSignature(node.details);
+                    if (signature)
+                        entry.failure = signature;
                 }
+                tests.push(entry);
             }
         }
         if (node.children && node.children.length > 0) {
-            failedTests = failedTests.concat(extractFailedTestIds(node.children, status));
+            tests = tests.concat(extractTestIds(node.children, status, includeFailureDetail));
+        }
+    }
+    return tests;
+}
+// Back-compat alias — prefer extractTestIds. Kept so existing imports/tests
+// referencing the old name continue to resolve.
+export const extractFailedTestIds = extractTestIds;
+// Build a trimmed failure signature from a test node's `details`. Returns
+// undefined when no signal is available so the field is simply omitted.
+function buildFailureSignature(details) {
+    if (!details)
+        return undefined;
+    const signature = {};
+    if (details.failure_categories != null) {
+        signature.category = Array.isArray(details.failure_categories)
+            ? details.failure_categories.filter(Boolean).join(", ")
+            : String(details.failure_categories);
+    }
+    const errorSummary = extractFirstFailureLine(details);
+    if (errorSummary)
+        signature.error_summary = errorSummary;
+    if (details.file_path)
+        signature.file_path = String(details.file_path);
+    if (typeof details.is_flaky === "boolean")
+        signature.is_flaky = details.is_flaky;
+    if (typeof details.is_always_failing === "boolean")
+        signature.is_always_failing = details.is_always_failing;
+    if (typeof details.is_new_failure === "boolean")
+        signature.is_new_failure = details.is_new_failure;
+    return Object.keys(signature).length > 0 ? signature : undefined;
+}
+// First non-empty line of the first retry's TEST_FAILURE log, capped. Handles
+// both string entries and object entries ({ message } / { text }).
+function extractFirstFailureLine(details) {
+    const retries = details?.retries;
+    if (!Array.isArray(retries))
+        return undefined;
+    for (const retry of retries) {
+        const failures = retry?.logs?.TEST_FAILURE;
+        if (!failures)
+            continue;
+        const entries = Array.isArray(failures) ? failures : [failures];
+        for (const failure of entries) {
+            const text = typeof failure === "string"
+                ? failure
+                : (failure?.message ?? failure?.text ?? "");
+            const firstLine = String(text)
+                .split("\n")
+                .map((line) => line.trim())
+                .find((line) => line.length > 0);
+            if (firstLine)
+                return firstLine.slice(0, ERROR_SUMMARY_MAX);
         }
     }
-    return failedTests;
+    return undefined;
 }