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

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: [
                 {
@@ -130,7 +130,13 @@ export async function listTestIdsTool(args, config) {
 }
 export default function addRCATools(server, config) {
     const tools = {};
-    tools.fetchRCA = server.tool("fetchRCA", "Fetch AI Root Cause Analysis for the current user's failed BrowserStack Automate/App-Automate tests. Suggests fixes only; never auto-apply, require explicit user approval.", FETCH_RCA_PARAMS, async (args) => {
+    tools.fetchRCA = server.tool("fetchRCA", "Fetch AI Root Cause Analysis for the current user's failed BrowserStack Automate/App-Automate tests. Suggests fixes only; never auto-apply, require explicit user approval.", FETCH_RCA_PARAMS, {
+        title: "Fetch Root Cause Analysis",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    }, async (args) => {
         try {
             trackMCP("fetchRCA", server.server.getClientVersion(), undefined, config);
             return await fetchRCADataTool(args, config);
@@ -139,7 +145,13 @@ export default function addRCATools(server, config) {
             return handleMCPError("fetchRCA", server, config, error);
         }
     });
-    tools.getBuildId = server.tool("getBuildId", "Get the BrowserStack build ID for a given project and build name, scoped to the current user's builds.", GET_BUILD_ID_PARAMS, async (args) => {
+    tools.getBuildId = server.tool("getBuildId", "Get the BrowserStack build ID for a given project and build name, scoped to the current user's builds.", GET_BUILD_ID_PARAMS, {
+        title: "Get Build ID",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    }, async (args) => {
         try {
             trackMCP("getBuildId", server.server.getClientVersion(), undefined, config);
             return await getBuildIdTool(args, config);
@@ -148,7 +160,13 @@ export default function addRCATools(server, config) {
             return handleMCPError("getBuildId", server, config, error);
         }
     });
-    tools.listBuildId = server.tool("listBuildId", "Get the latest build ID for a project and build name, across all users (no user filter).", GET_BUILD_ID_PARAMS, async (args) => {
+    tools.listBuildId = server.tool("listBuildId", "Get the latest build ID for a project and build name, across all users (no user filter).", GET_BUILD_ID_PARAMS, {
+        title: "List Build IDs",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    }, async (args) => {
         try {
             trackMCP("listBuildId", server.server.getClientVersion(), undefined, config);
             return await listBuildIdTool(args, config);
@@ -157,7 +175,13 @@ 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, async (args) => {
+    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,
+        destructiveHint: false,
+        idempotentHint: true,
+    }, async (args) => {
         try {
             trackMCP("listTestIds", server.server.getClientVersion(), undefined, config);
             return await listTestIdsTool(args, config);

package/dist/tools/selfheal.js

@@ -443,6 +443,12 @@ export default function addSelfHealTools(server, config) {
             .string()
             .describe("Build UUID. Fetches the build's self-healing report.")
             .optional(),
+    }, {
+        title: "Fetch Self-Healed Selectors",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
     }, async (args) => {
         try {
             trackMCP("fetchSelfHealedSelectors", server.server.getClientVersion(), undefined, config);
@@ -495,6 +501,12 @@ export default function addSelfHealTools(server, config) {
         "(`session_id`, `original_locator`, `healed_locator`, " +
         "`healing_thought`).", {
         sessions: sessionsFieldSchema.describe("Sessions to plan edits for. See tool description for accepted shapes."),
+    }, {
+        title: "Prepare Self-Healing Plan",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
     }, async (args) => {
         try {
             trackMCP("prepareSelfHealingPlan", server.server.getClientVersion(), undefined, config);

package/dist/tools/testmanagement.js

@@ -432,22 +432,124 @@ export async function getSubTestPlanTool(args, config, server) {
  */
 export default function addTestManagementTools(server, config) {
     const tools = {};
-    tools.createProjectOrFolder = server.tool("createProjectOrFolder", "Create a project and/or folder in BrowserStack Test Management.", CreateProjFoldSchema.shape, (args) => createProjectOrFolderTool(args, config, server));
-    tools.createTestCase = server.tool("createTestCase", "Use this tool to create a test case in BrowserStack Test Management.", CreateTestCaseSchema.shape, (args) => createTestCaseTool(args, config, server));
-    tools.updateTestCase = server.tool("updateTestCase", "Update an existing test case in BrowserStack Test Management. Any subset of the following fields may be changed: name, description, preconditions, test_case_steps, owner, priority, case_type, automation_status, status, tags, issues, custom_fields. Only the supplied fields are modified.", UpdateTestCaseSchema.shape, (args) => updateTestCaseTool(args, config, server));
-    tools.listTestCases = server.tool("listTestCases", "List test cases in a project, optionally scoped to a specific folder. Omit folder_id to list all test cases in the project; provide folder_id (discoverable via listFolders) to list only that folder's cases. Supports filters: case_type, priority, pagination.", ListTestCasesSchema.shape, (args) => listTestCasesTool(args, config, server));
-    tools.listFolders = server.tool("listFolders", "List folders in a BrowserStack Test Management project, returning each folder's id and name (plus case counts and sub-folder counts). Pass parent_id to list sub-folders under a specific folder instead of top-level folders.", ListFoldersSchema.shape, (args) => listFoldersTool(args, config, server));
-    tools.listTestCaseTemplates = server.tool("listTestCaseTemplates", "List test-case templates with their numeric template_id. Use the id with createTestCase to apply a custom template (the 'template' slug only selects system templates).", ListTemplatesSchema.shape, (args) => listTemplatesTool(args, config, server));
-    tools.createTestRun = server.tool("createTestRun", "Create a test run in BrowserStack Test Management.", CreateTestRunSchema.shape, (args) => createTestRunTool(args, config, server));
-    tools.listTestRuns = server.tool("listTestRuns", "List test runs in a project with optional filters (date ranges, assignee, state, etc.)", ListTestRunsSchema.shape, (args) => listTestRunsTool(args, config, server));
-    tools.updateTestRun = server.tool("updateTestRun", "Update a test run's metadata and/or add test cases to it.", UpdateTestRunSchema.shape, (args) => updateTestRunTool(args, config, server));
-    tools.addTestResult = server.tool("addTestResult", "Add a test result to a specific test run via BrowserStack Test Management API.", AddTestResultSchema.shape, (args) => addTestResultTool(args, config, server));
-    tools.uploadProductRequirementFile = server.tool("uploadProductRequirementFile", "Upload files (e.g., PDRs, PDFs) to BrowserStack Test Management and retrieve a file mapping ID. This is utilized for generating test cases from files and is part of the Test Case Generator AI Agent in BrowserStack.", UploadFileSchema.shape, (args) => uploadProductRequirementFileTool(args, config, server));
-    tools.createTestCasesFromFile = server.tool("createTestCasesFromFile", "Generate test cases from a file in BrowserStack Test Management using the Test Case Generator AI Agent.", CreateTestCasesFromFileSchema.shape, (args, context) => createTestCasesFromFileTool(args, context, config, server));
-    tools.createLCASteps = server.tool("createLCASteps", "Generate Low Code Automation (LCA) steps for a test case in BrowserStack Test Management using the Low Code Automation Agent.", CreateLCAStepsSchema.shape, (args, context) => createLCAStepsTool(args, context, config, server));
-    tools.listTestPlans = server.tool("listTestPlans", "List test plans in a BrowserStack Test Management project. Returns each plan's identifier (TP-*), name, status, description, dates, and active/closed test-run counts. Supports pagination.", ListTestPlansSchema.shape, (args) => listTestPlansTool(args, config, server));
-    tools.getTestPlan = server.tool("getTestPlan", "Fetch a test plan by identifier (TP-*) from BrowserStack Test Management. Returns plan metadata, the full list of linked test runs, total test-case count across runs, and a status summary — suitable for generating test documentation or QA status reports.", GetTestPlanSchema.shape, (args) => getTestPlanTool(args, config, server));
-    tools.listSubTestPlans = server.tool("listSubTestPlans", "List sub-test-plans under a parent test plan (TP-*) in a Test Management project. Supports pagination.", ListSubTestPlansSchema.shape, (args) => listSubTestPlansTool(args, config, server));
-    tools.getSubTestPlan = server.tool("getSubTestPlan", "Fetch a sub-test-plan (STP-*) under a parent plan (TP-*). Returns metadata and linked test runs.", GetSubTestPlanSchema.shape, (args) => getSubTestPlanTool(args, config, server));
+    tools.createProjectOrFolder = server.tool("createProjectOrFolder", "Create a project and/or folder in BrowserStack Test Management.", CreateProjFoldSchema.shape, {
+        title: "Create Project or Folder",
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+    }, (args) => createProjectOrFolderTool(args, config, server));
+    tools.createTestCase = server.tool("createTestCase", "Use this tool to create a test case in BrowserStack Test Management.", CreateTestCaseSchema.shape, {
+        title: "Create Test Case",
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+    }, (args) => createTestCaseTool(args, config, server));
+    tools.updateTestCase = server.tool("updateTestCase", "Update an existing test case in BrowserStack Test Management. Any subset of the following fields may be changed: name, description, preconditions, test_case_steps, owner, priority, case_type, automation_status, status, tags, issues, custom_fields. Only the supplied fields are modified.", UpdateTestCaseSchema.shape, {
+        title: "Update Test Case",
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+    }, (args) => updateTestCaseTool(args, config, server));
+    tools.listTestCases = server.tool("listTestCases", "List test cases in a project, optionally scoped to a specific folder. Omit folder_id to list all test cases in the project; provide folder_id (discoverable via listFolders) to list only that folder's cases. Supports filters: case_type, priority, pagination.", ListTestCasesSchema.shape, {
+        title: "List Test Cases",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    }, (args) => listTestCasesTool(args, config, server));
+    tools.listFolders = server.tool("listFolders", "List folders in a BrowserStack Test Management project, returning each folder's id and name (plus case counts and sub-folder counts). Pass parent_id to list sub-folders under a specific folder instead of top-level folders.", ListFoldersSchema.shape, {
+        title: "List Folders",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    }, (args) => listFoldersTool(args, config, server));
+    tools.listTestCaseTemplates = server.tool("listTestCaseTemplates", "List test-case templates with their numeric template_id. Use the id with createTestCase to apply a custom template (the 'template' slug only selects system templates).", ListTemplatesSchema.shape, {
+        title: "List Test Case Templates",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    }, (args) => listTemplatesTool(args, config, server));
+    tools.createTestRun = server.tool("createTestRun", "Create a test run in BrowserStack Test Management.", CreateTestRunSchema.shape, {
+        title: "Create Test Run",
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+    }, (args) => createTestRunTool(args, config, server));
+    tools.listTestRuns = server.tool("listTestRuns", "List test runs in a project with optional filters (date ranges, assignee, state, etc.)", ListTestRunsSchema.shape, {
+        title: "List Test Runs",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    }, (args) => listTestRunsTool(args, config, server));
+    tools.updateTestRun = server.tool("updateTestRun", "Update a test run's metadata and/or add test cases to it.", UpdateTestRunSchema.shape, {
+        title: "Update Test Run",
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+    }, (args) => updateTestRunTool(args, config, server));
+    tools.addTestResult = server.tool("addTestResult", "Add a test result to a specific test run via BrowserStack Test Management API.", AddTestResultSchema.shape, {
+        title: "Add Test Result",
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+    }, (args) => addTestResultTool(args, config, server));
+    tools.uploadProductRequirementFile = server.tool("uploadProductRequirementFile", "Upload files (e.g., PDRs, PDFs) to BrowserStack Test Management and retrieve a file mapping ID. This is utilized for generating test cases from files and is part of the Test Case Generator AI Agent in BrowserStack.", UploadFileSchema.shape, {
+        title: "Upload Product Requirement File",
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+    }, (args) => uploadProductRequirementFileTool(args, config, server));
+    tools.createTestCasesFromFile = server.tool("createTestCasesFromFile", "Generate test cases from a file in BrowserStack Test Management using the Test Case Generator AI Agent.", CreateTestCasesFromFileSchema.shape, {
+        title: "Create Test Cases from File",
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+    }, (args, context) => createTestCasesFromFileTool(args, context, config, server));
+    tools.createLCASteps = server.tool("createLCASteps", "Generate Low Code Automation (LCA) steps for a test case in BrowserStack Test Management using the Low Code Automation Agent.", CreateLCAStepsSchema.shape, {
+        title: "Create LCA Steps",
+        readOnlyHint: false,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+    }, (args, context) => createLCAStepsTool(args, context, config, server));
+    tools.listTestPlans = server.tool("listTestPlans", "List test plans in a BrowserStack Test Management project. Returns each plan's identifier (TP-*), name, status, description, dates, and active/closed test-run counts. Supports pagination.", ListTestPlansSchema.shape, {
+        title: "List Test Plans",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    }, (args) => listTestPlansTool(args, config, server));
+    tools.getTestPlan = server.tool("getTestPlan", "Fetch a test plan by identifier (TP-*) from BrowserStack Test Management. Returns plan metadata, the full list of linked test runs, total test-case count across runs, and a status summary — suitable for generating test documentation or QA status reports.", GetTestPlanSchema.shape, {
+        title: "Get Test Plan",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    }, (args) => getTestPlanTool(args, config, server));
+    tools.listSubTestPlans = server.tool("listSubTestPlans", "List sub-test-plans under a parent test plan (TP-*) in a Test Management project. Supports pagination.", ListSubTestPlansSchema.shape, {
+        title: "List Sub Test Plans",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    }, (args) => listSubTestPlansTool(args, config, server));
+    tools.getSubTestPlan = server.tool("getSubTestPlan", "Fetch a sub-test-plan (STP-*) under a parent plan (TP-*). Returns metadata and linked test runs.", GetSubTestPlanSchema.shape, {
+        title: "Get Sub Test Plan",
+        readOnlyHint: true,
+        openWorldHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+    }, (args) => getSubTestPlanTool(args, config, server));
     return tools;
 }

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

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

@@ -0,0 +1,133 @@
+import { apiClient } from "../../lib/apiClient.js";
+import { AI_FAILURES_FLAT_PATH, AI_FAILURES_PATH, BUILD_THEMES_FAILURE_STATUSES, BUILD_THEMES_POLL_INTERVAL_MS, BUILD_THEMES_POLL_MAX_WAIT_MS, BUILD_THEMES_SUCCESS_STATUS, getO11yBaseUrl, } from "./constants.js";
+import { buildAuthHeader } from "./turn-result.js";
+export class BuildFailureThemesError extends Error {
+}
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function authHeaders(config) {
+    return {
+        "Content-Type": "application/json",
+        Authorization: buildAuthHeader(config),
+    };
+}
+// Normalize a response body to a plain object — a malformed 200 is treated as "no data".
+function asObject(data) {
+    return typeof data === "object" && data !== null && !Array.isArray(data)
+        ? data
+        : {};
+}
+function failuresUrl(buildUuid) {
+    return (getO11yBaseUrl() +
+        AI_FAILURES_PATH.replace("{buildUuid}", encodeURIComponent(buildUuid)));
+}
+async function fetchFailuresOnce(buildUuid, config) {
+    return apiClient.get({
+        url: failuresUrl(buildUuid),
+        headers: authHeaders(config),
+        raise_error: false,
+    });
+}
+// Same URL as the GET read, different verb — kicks off build-level theme computation.
+async function triggerFailuresOnce(buildUuid, config) {
+    return apiClient.post({
+        url: failuresUrl(buildUuid),
+        headers: authHeaders(config),
+        body: {},
+        raise_error: false,
+    });
+}
+// Fetch a build's server-computed failure-theme clusters, triggering computation
+// if nothing has run yet. Triggers at most once per call, then polls until
+// SUCCESS or BUILD_THEMES_POLL_MAX_WAIT_MS is spent — never blocks past that.
+export async function fetchBuildFailureThemes(buildUuid, config) {
+    const startTime = Date.now();
+    let lastStatus;
+    let triggered = false;
+    /** Attempts the one-time trigger POST; returns whether it succeeded. */
+    const triggerOnce = async () => {
+        triggered = true;
+        const triggerResponse = await triggerFailuresOnce(buildUuid, config);
+        return triggerResponse.ok;
+    };
+    while (true) {
+        const response = await fetchFailuresOnce(buildUuid, config);
+        if (response.ok) {
+            const data = asObject(response.data);
+            const status = data.buildThemeWorkflow?.status;
+            if (status === BUILD_THEMES_SUCCESS_STATUS) {
+                return {
+                    ready: true,
+                    status,
+                    buildId: data.buildId,
+                    buildThemes: data.buildThemes ?? [],
+                    buildWorkflows: data.buildWorkflows ?? [],
+                    stats: data.stats,
+                };
+            }
+            if (status && BUILD_THEMES_FAILURE_STATUSES.includes(status)) {
+                if (triggered) {
+                    // Already retried once and it failed again — a real failure, not
+                    // async lag. Nothing left to do but report it.
+                    return { ready: false, status };
+                }
+                if (!(await triggerOnce())) {
+                    return { ready: false, status: "trigger-unavailable" };
+                }
+            }
+            else {
+                // status undefined (never computed) — trigger once. An in-progress
+                // value (PENDING/PROCESSING) just keeps polling either way.
+                if (!status && !triggered && !(await triggerOnce())) {
+                    return { ready: false, status: "trigger-unavailable" };
+                }
+                lastStatus = status ?? lastStatus;
+            }
+        }
+        else if (response.status === 404) {
+            if (!triggered && !(await triggerOnce())) {
+                return { ready: false, status: "trigger-unavailable" };
+            }
+        }
+        else {
+            throw new BuildFailureThemesError(`failed to fetch build failure themes (status ${response.status})`);
+        }
+        if (Date.now() - startTime >= BUILD_THEMES_POLL_MAX_WAIT_MS) {
+            return { ready: false, status: lastStatus ?? "PENDING" };
+        }
+        await delay(BUILD_THEMES_POLL_INTERVAL_MS);
+    }
+}
+/** Paginated test-run membership for one failure theme or workflow. */
+export async function fetchTestsInFailureTheme(args, config) {
+    const params = {
+        limit: args.limit ?? 50,
+    };
+    if (args.themeId !== undefined)
+        params.buildFailureThemeId = args.themeId;
+    if (args.workflowId !== undefined)
+        params.buildFailureWorkflowId = args.workflowId;
+    if (args.cursor)
+        params.searchAfter = args.cursor;
+    const url = getO11yBaseUrl() +
+        AI_FAILURES_FLAT_PATH.replace("{buildUuid}", encodeURIComponent(args.buildUuid));
+    const response = await apiClient.get({
+        url,
+        headers: authHeaders(config),
+        params,
+        raise_error: false,
+    });
+    if (!response.ok) {
+        throw new BuildFailureThemesError(`failed to list tests in failure theme (status ${response.status})`);
+    }
+    const data = asObject(response.data);
+    const testRuns = data.testRuns ?? [];
+    return {
+        tests: testRuns.map((t) => ({
+            testRunId: t?.details?.id ?? t?.id,
+            title: t?.title,
+            status: t?.details?.status,
+            raw: t,
+        })),
+        nextCursor: data.nextCursor ?? data.searchAfter ?? data.next_search_after,
+    };
+}