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

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/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,
         }));

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;
 }

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

@@ -17,9 +17,19 @@ export interface TestRun {
         next_page: string | null;
     };
 }
+export interface TestFailureSignature {
+    category?: string;
+    error_summary?: string;
+    file_path?: string;
+    is_flaky?: boolean;
+    is_always_failing?: boolean;
+    is_new_failure?: boolean;
+}
 export interface FailedTestInfo {
     test_id: number;
     test_name: string;
+    status?: TestStatus;
+    failure?: TestFailureSignature;
 }
 export declare enum RCAState {
     PENDING = "pending",

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

@@ -11,5 +11,6 @@ export declare function fetchRCADataTool(args: {
 export declare function listTestIdsTool(args: {
     buildId: string;
     status?: TestStatus;
+    includeFailureDetail?: boolean;
 }, config: BrowserStackConfig): Promise<CallToolResult>;
 export default function addRCATools(server: McpServer, config: BrowserStackConfig): Record<string, any>;

package/dist/tools/rca-agent.js

@@ -101,10 +101,10 @@ export async function fetchRCADataTool(args, config) {
 }
 export async function listTestIdsTool(args, config) {
     try {
-        const { buildId, status } = args;
+        const { buildId, status, includeFailureDetail } = args;
         const authString = getBrowserStackAuth(config);
         // Get test IDs
-        const testIds = await getTestIds(buildId, authString, status);
+        const testIds = await getTestIds(buildId, authString, status, includeFailureDetail);
         return {
             content: [
                 {
@@ -175,7 +175,7 @@ export default function addRCATools(server, config) {
             return handleMCPError("listBuildId", server, config, error);
         }
     });
-    tools.listTestIds = server.tool("listTestIds", "List test IDs from a BrowserStack Automate build, optionally filtered by status", LIST_TEST_IDS_PARAMS, {
+    tools.listTestIds = server.tool("listTestIds", "List all tests of a BrowserStack build (each with its status); optional status filter.", LIST_TEST_IDS_PARAMS, {
         title: "List Test IDs",
         readOnlyHint: true,
         openWorldHint: false,

package/dist/tools/tfa-rca-collaboration.d.ts

@@ -0,0 +1,15 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { BrowserStackConfig } from "../lib/types.js";
+import { TfaRcaTurnArgs } from "./tfa-rca-utils/submit-turn.js";
+import { GetTfaTurnResultArgs } from "./tfa-rca-utils/turn-result.js";
+import { TriggerRcaReportArgs } from "./tfa-rca-utils/trigger-report.js";
+import { ListTestsInFailureThemeArgs } from "./tfa-rca-utils/build-failure-themes.js";
+export declare function tfaRcaTurnTool(args: TfaRcaTurnArgs, config: BrowserStackConfig, context?: any): Promise<CallToolResult>;
+export declare function getTfaTurnResultTool(args: GetTfaTurnResultArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+export declare function triggerRcaReportTool(args: TriggerRcaReportArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+export declare function getBuildFailureThemesTool(args: {
+    buildUuid: string;
+}, config: BrowserStackConfig): Promise<CallToolResult>;
+export declare function listTestsInFailureThemeTool(args: ListTestsInFailureThemeArgs, config: BrowserStackConfig): Promise<CallToolResult>;
+export default function addTfaRcaCollaborationTools(server: McpServer, config: BrowserStackConfig): Record<string, any>;

package/dist/tools/tfa-rca-collaboration.js

@@ -0,0 +1,162 @@
+import { trackMCP } from "../lib/instrumentation.js";
+import { handleMCPError } from "../lib/utils.js";
+import { GET_BUILD_FAILURE_THEMES_PARAMS, GET_TFA_TURN_RESULT_PARAMS, LIST_TESTS_IN_FAILURE_THEME_PARAMS, TFA_RCA_TURN_PARAMS, TRIGGER_RCA_REPORT_PARAMS, } from "./tfa-rca-utils/constants.js";
+import { submitTfaRcaTurn, } from "./tfa-rca-utils/submit-turn.js";
+import { getTfaTurnResult, TfaRcaTurnError, } from "./tfa-rca-utils/turn-result.js";
+import { triggerRcaReport, TriggerRcaReportError, } from "./tfa-rca-utils/trigger-report.js";
+import { BuildFailureThemesError, fetchBuildFailureThemes, fetchTestsInFailureTheme, } from "./tfa-rca-utils/build-failure-themes.js";
+const TOOL_NAME = "tfaRcaTurn";
+const GET_RESULT_TOOL_NAME = "getTfaTurnResult";
+const TRIGGER_TOOL_NAME = "triggerRcaReport";
+const GET_BUILD_FAILURE_THEMES_TOOL_NAME = "getBuildFailureThemes";
+const LIST_TESTS_IN_FAILURE_THEME_TOOL_NAME = "listTestsInFailureTheme";
+/** Wrap a domain error into the standard `{ isError: true }` envelope. */
+function domainErrorResult(toolName, error) {
+    const readable = toolName.replace(/([A-Z])/g, " $1").toLowerCase();
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Failed to ${readable}: ${error.message}`,
+            },
+        ],
+        isError: true,
+    };
+}
+export async function tfaRcaTurnTool(args, config, context) {
+    // The util returns the trimmed, status-discriminated contract; JSON.stringify
+    // drops the undefined slots, so the wrapper stays a plain serializer.
+    const result = await submitTfaRcaTurn(args, config, context);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+}
+export async function getTfaTurnResultTool(args, config) {
+    // Same trimmed contract as `tfaRcaTurn`, read once without submitting.
+    const result = await getTfaTurnResult(args, config);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+}
+export async function triggerRcaReportTool(args, config) {
+    const glimpse = await triggerRcaReport(args, config);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(glimpse, null, 2),
+            },
+        ],
+    };
+}
+export async function getBuildFailureThemesTool(args, config) {
+    const result = await fetchBuildFailureThemes(args.buildUuid, config);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+}
+export async function listTestsInFailureThemeTool(args, config) {
+    const result = await fetchTestsInFailureTheme(args, config);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+}
+export default function addTfaRcaCollaborationTools(server, config) {
+    const tools = {};
+    tools.tfaRcaTurn = server.tool(TOOL_NAME, "Submit one collaborative RCA turn for a test run to the TFA agent, then poll in-call for a result. Omit threadId on the first turn for a test run — this starts a new investigation thread; every following turn on that same test MUST pass back the threadId from the previous response, since a test run should have only one active thread at a time. Returns status RESOLVED (terminal, includes root_cause/related_prs), NEEDS_INFO (fulfill the asks and submit the next turn with the same threadId), or PENDING (still working — poll it with getTfaTurnResult using the returned turnId; do NOT call tfaRcaTurn again for the same turn, that submits a duplicate).", TFA_RCA_TURN_PARAMS, async (args, context) => {
+        try {
+            const result = await tfaRcaTurnTool(args, config, context);
+            trackMCP(TOOL_NAME, server.server.getClientVersion(), undefined, config);
+            return result;
+        }
+        catch (error) {
+            // Domain failures carry a client-safe, group-scope-safe message.
+            if (error instanceof TfaRcaTurnError) {
+                trackMCP(TOOL_NAME, server.server.getClientVersion(), error, config);
+                return domainErrorResult(TOOL_NAME, error);
+            }
+            return handleMCPError(TOOL_NAME, server, config, error);
+        }
+    });
+    tools.getTfaTurnResult = server.tool(GET_RESULT_TOOL_NAME, "Read a previously submitted RCA turn's status once, given the testRunId and the turnId a PENDING tfaRcaTurn response returned — this never resubmits or duplicates the turn. Returns PENDING again if the TFA agent is still working, or the same RESOLVED/NEEDS_INFO contract as tfaRcaTurn once it finishes. On NEEDS_INFO, gather the requested evidence and continue via tfaRcaTurn with the same threadId; RESOLVED is terminal for this test — do not call this tool or tfaRcaTurn again for it.", GET_TFA_TURN_RESULT_PARAMS, async (args) => {
+        try {
+            const result = await getTfaTurnResultTool(args, config);
+            trackMCP(GET_RESULT_TOOL_NAME, server.server.getClientVersion(), undefined, config);
+            return result;
+        }
+        catch (error) {
+            // Domain failures carry a client-safe, group-scope-safe message.
+            if (error instanceof TfaRcaTurnError) {
+                trackMCP(GET_RESULT_TOOL_NAME, server.server.getClientVersion(), error, config);
+                return domainErrorResult(GET_RESULT_TOOL_NAME, error);
+            }
+            return handleMCPError(GET_RESULT_TOOL_NAME, server, config, error);
+        }
+    });
+    tools.triggerRcaReport = server.tool(TRIGGER_TOOL_NAME, "Trigger (or read, if one already exists) a build's Release Readiness report, returning a trimmed verdict glimpse and a Test Observability UI link — never the raw report body. Without force, a completed report is read as-is at no extra analysis cost, so it's safe to call this repeatedly just to check status. Pass force:true only to force a fresh re-analysis of an already-completed report (e.g. after new evidence changed the picture) — do NOT set force on every call, since that discards the cached report and always pays the full re-analysis cost.", TRIGGER_RCA_REPORT_PARAMS, async (args) => {
+        try {
+            const result = await triggerRcaReportTool(args, config);
+            trackMCP(TRIGGER_TOOL_NAME, server.server.getClientVersion(), undefined, config);
+            return result;
+        }
+        catch (error) {
+            // Domain failures carry a client-safe, group-scope-safe message.
+            if (error instanceof TriggerRcaReportError) {
+                trackMCP(TRIGGER_TOOL_NAME, server.server.getClientVersion(), error, config);
+                return domainErrorResult(TRIGGER_TOOL_NAME, error);
+            }
+            return handleMCPError(TRIGGER_TOOL_NAME, server, config, error);
+        }
+    });
+    tools.getBuildFailureThemes = server.tool(GET_BUILD_FAILURE_THEMES_TOOL_NAME, "Get a build's server-computed failure-theme clusters (buildThemes + buildWorkflows), the preferred grouping source for representative/sibling fan-out — call this once per build, not per test. Triggers server-side computation if nothing has ever run for this build, and polls in-call up to its own budget for the result to finish; never blocks indefinitely. ready:false means either the computation is still running past the poll budget or the trigger itself failed (status:'trigger-unavailable') — either way, fall back to client-side clustering rather than waiting longer or retrying this call.", GET_BUILD_FAILURE_THEMES_PARAMS, async (args) => {
+        try {
+            const result = await getBuildFailureThemesTool(args, config);
+            trackMCP(GET_BUILD_FAILURE_THEMES_TOOL_NAME, server.server.getClientVersion(), undefined, config);
+            return result;
+        }
+        catch (error) {
+            // Domain failures carry a client-safe, group-scope-safe message.
+            if (error instanceof BuildFailureThemesError) {
+                trackMCP(GET_BUILD_FAILURE_THEMES_TOOL_NAME, server.server.getClientVersion(), error, config);
+                return domainErrorResult(GET_BUILD_FAILURE_THEMES_TOOL_NAME, error);
+            }
+            return handleMCPError(GET_BUILD_FAILURE_THEMES_TOOL_NAME, server, config, error);
+        }
+    });
+    tools.listTestsInFailureTheme = server.tool(LIST_TESTS_IN_FAILURE_THEME_TOOL_NAME, "List the test runs belonging to one failure theme or workflow from a prior getBuildFailureThemes call, filtered by themeId or workflowId. Results are paginated — pass the previous response's nextCursor back as cursor and keep calling until no nextCursor is returned; do not assume a single page covers all members. This is the representative/sibling grouping source: every test in a theme's list becomes either the cluster's representative or a pre-seeded sibling confirm.", LIST_TESTS_IN_FAILURE_THEME_PARAMS, async (args) => {
+        try {
+            const result = await listTestsInFailureThemeTool(args, config);
+            trackMCP(LIST_TESTS_IN_FAILURE_THEME_TOOL_NAME, server.server.getClientVersion(), undefined, config);
+            return result;
+        }
+        catch (error) {
+            // Domain failures carry a client-safe, group-scope-safe message.
+            if (error instanceof BuildFailureThemesError) {
+                trackMCP(LIST_TESTS_IN_FAILURE_THEME_TOOL_NAME, server.server.getClientVersion(), error, config);
+                return domainErrorResult(LIST_TESTS_IN_FAILURE_THEME_TOOL_NAME, error);
+            }
+            return handleMCPError(LIST_TESTS_IN_FAILURE_THEME_TOOL_NAME, server, config, error);
+        }
+    });
+    return tools;
+}

package/dist/tools/tfa-rca-utils/build-failure-themes.d.ts

@@ -0,0 +1,61 @@
+import { BrowserStackConfig } from "../../lib/types.js";
+export declare class BuildFailureThemesError extends Error {
+}
+export interface BuildFailureTheme {
+    themeId: string;
+    buildFailureThemeId: number;
+    themeData: {
+        name: string;
+        description: string;
+    };
+    affectedWorkflows: unknown[];
+    affectedWorkflowCount?: number;
+    testRunCount?: number;
+    testPercentage?: number;
+}
+export interface BuildFailureWorkflow {
+    workflowIdentifier: string;
+    buildFailureWorkflowId: number;
+    workflowData: {
+        name: string;
+        description: string;
+    };
+    testRunCount?: number;
+    testPercentage?: number;
+    themesIdentified?: unknown[];
+    themeIdentifiedCount?: number;
+}
+export interface BuildFailureThemesResult {
+    ready: boolean;
+    /** Last observed `buildThemeWorkflow.status`, or "PENDING" if budget spent with no status yet. */
+    status: string;
+    buildId?: string;
+    buildThemes?: BuildFailureTheme[];
+    buildWorkflows?: BuildFailureWorkflow[];
+    stats?: {
+        totalThemes: number;
+        newThemes: number;
+        existingThemes: number;
+    };
+}
+export interface TestInFailureTheme {
+    testRunId: string | number | undefined;
+    title?: string;
+    status?: string;
+    raw: unknown;
+}
+export interface ListTestsInFailureThemeArgs {
+    buildUuid: string;
+    themeId?: number;
+    workflowId?: number;
+    limit?: number;
+    cursor?: string;
+}
+export interface ListTestsInFailureThemeResult {
+    tests: TestInFailureTheme[];
+    /** Cursor for the next page, if any. */
+    nextCursor?: string;
+}
+export declare function fetchBuildFailureThemes(buildUuid: string, config: BrowserStackConfig): Promise<BuildFailureThemesResult>;
+/** Paginated test-run membership for one failure theme or workflow. */
+export declare function fetchTestsInFailureTheme(args: ListTestsInFailureThemeArgs, config: BrowserStackConfig): Promise<ListTestsInFailureThemeResult>;