@browserstack/mcp-server 1.2.25-beta.1 → 1.2.27-beta.1

package/README.md

@@ -334,7 +334,7 @@ As of now we support 20 tools.
   List all test runs from the 'Shopping App' project that were executed last week and are currently marked in-progress
   ```
 
- 6. `updateTestRun` — Partially update a test run (status, tags, notes, associated test cases).
+ 6. `updateTestRun` — Update a test run's name/state and/or add test cases to it.
   **Prompt example**
 
   ```text

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,31 @@ for (const key of BROWSERSTACK_LOCAL_OPTION_KEYS) {
         browserstackLocalOptions[key] = envVar;
     }
 }
+/**
+ * Default o11y base URL for the `tfaRcaTurn` collaborative-RCA tool —
+ * PRODUCTION (verified: api-automation.browserstack.com routes the
+ * /ext/v1 testRca + rcaChat endpoints). Same value for every user served by
+ * the process; overridable at startup via `O11Y_TFA_RCA_BASE_URL` to target a
+ * staging tenant (e.g. api-observability-<tenant>.bsstag.com) where a build's
+ * representatives actually live. Per-process config, never a per-call arg.
+ */
+const DEFAULT_O11Y_TFA_RCA_BASE_URL = "https://api-automation.browserstack.com";
+/**
+ * Base URL for the Automate test-runs API (`/ext/v1/builds/{id}/testRuns`) that
+ * `listTestIds` calls. Overridable at startup via `BROWSERSTACK_AUTOMATION_BASE_URL`
+ * so the tool can target a non-prod env (e.g. rengg-tfa staging) where a build
+ * actually lives, instead of the prod default. Per-process config, never a
+ * per-call arg.
+ */
+const DEFAULT_BROWSERSTACK_AUTOMATION_BASE_URL = "https://api-automation.browserstack.com";
+/**
+ * Base URL of the Test Observability (TRA) web UI used to build the
+ * human-facing "view the full report" links returned by the RCA tools.
+ * Same value for every user served by the process; overridable at startup via
+ * `BROWSERSTACK_O11Y_UI_BASE_URL` (e.g. to point at a staging UI). Per-process
+ * config, never a per-call arg.
+ */
+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 +63,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/server-factory.js

@@ -16,6 +16,7 @@ import addAppLiveTools from "./tools/applive.js";
 import addBuildInsightsTools from "./tools/build-insights.js";
 import { setupOnInitialized } from "./oninitialized.js";
 import addRCATools from "./tools/rca-agent.js";
+import addTfaRcaCollaborationTools from "./tools/tfa-rca-collaboration.js";
 /**
  * Wrapper class for BrowserStack MCP Server
  * Stores a map of registered tools by name
@@ -51,6 +52,7 @@ export class BrowserStackMcpServer {
             addSelfHealTools,
             addBuildInsightsTools,
             addRCATools,
+            addTfaRcaCollaborationTools,
         ];
         toolAdders.forEach((adder) => {
             // Each adder now returns a Record<string, Tool>

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

@@ -1,5 +1,13 @@
 import { z } from "zod";
 import { TestStatus } from "./types.js";
+/**
+ * Base URL for the Automate test-runs API used by `listTestIds`. Process-startup
+ * config resolved in `src/config.ts` from `BROWSERSTACK_AUTOMATION_BASE_URL`
+ * (default prod). Set it to a rengg/staging host to list a build that lives
+ * there. Read per call so a per-server-instance config is honored; never read
+ * `process.env` here.
+ */
+export declare function getAutomationBaseUrl(): string;
 export declare const FETCH_RCA_PARAMS: {
     testId: z.ZodArray<z.ZodNumber>;
 };
@@ -10,4 +18,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,16 @@
 import { z } from "zod";
+import appConfig from "../../config.js";
 import { TestStatus } from "./types.js";
+/**
+ * Base URL for the Automate test-runs API used by `listTestIds`. Process-startup
+ * config resolved in `src/config.ts` from `BROWSERSTACK_AUTOMATION_BASE_URL`
+ * (default prod). Set it to a rengg/staging host to list a build that lives
+ * there. Read per call so a per-server-instance config is honored; never read
+ * `process.env` here.
+ */
+export function getAutomationBaseUrl() {
+    return appConfig.BROWSERSTACK_AUTOMATION_BASE_URL;
+}
 export const FETCH_RCA_PARAMS = {
     testId: z
         .array(z.number().int())
@@ -21,4 +32,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,3 @@
 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 extractFailedTestIds(hierarchy: TestDetails[], status?: TestStatus, includeFailureDetail?: boolean): FailedTestInfo[];

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

@@ -1,6 +1,10 @@
 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";
+// Cap on the failure summary line — keep the response payload lean (we never
+// return full stack traces into the MCP client's context window).
+const ERROR_SUMMARY_MAX = 200;
+export async function getTestIds(buildId, authString, status, includeFailureDetail = false) {
+    const baseUrl = `${getAutomationBaseUrl()}/ext/v1/builds/${buildId}/testRuns`;
     let url = status ? `${baseUrl}?test_statuses=${status}` : baseUrl;
     let allFailedTests = [];
     let requestNumber = 0;
@@ -22,7 +26,7 @@ export async function getTestIds(buildId, authString, status) {
             const data = (await response.json());
             // Extract failed IDs from current page
             if (data.hierarchy && data.hierarchy.length > 0) {
-                const currentFailedTests = extractFailedTestIds(data.hierarchy, status);
+                const currentFailedTests = extractFailedTestIds(data.hierarchy, status, includeFailureDetail);
                 allFailedTests = allFailedTests.concat(currentFailedTests);
             }
             // Check for pagination termination conditions
@@ -46,23 +50,82 @@ export async function getTestIds(buildId, authString, status) {
         throw error;
     }
 }
-export function extractFailedTestIds(hierarchy, status) {
+export function extractFailedTestIds(hierarchy, status, includeFailureDetail = false) {
     let failedTests = [];
     for (const node of hierarchy) {
+        // Match on status alone — the observability_url `details=<id>` check below
+        // already filters to real test nodes (suite/hook nodes carry no status and
+        // no such URL). Do NOT also require run_count: JUnit-uploaded builds report
+        // run_count=0 even for genuinely failed tests, which would drop them all.
         if (node.details?.status === status) {
             if (node.details?.observability_url) {
                 const idMatch = node.details.observability_url.match(/details=(\d+)/);
                 if (idMatch) {
-                    failedTests.push({
+                    const entry = {
                         test_id: idMatch[1],
                         test_name: node.display_name || `Test ${idMatch[1]}`,
-                    });
+                    };
+                    if (includeFailureDetail) {
+                        const signature = buildFailureSignature(node.details);
+                        if (signature)
+                            entry.failure = signature;
+                    }
+                    failedTests.push(entry);
                 }
             }
         }
         if (node.children && node.children.length > 0) {
-            failedTests = failedTests.concat(extractFailedTestIds(node.children, status));
+            failedTests = failedTests.concat(extractFailedTestIds(node.children, status, includeFailureDetail));
         }
     }
     return failedTests;
 }
+// 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 undefined;
+}

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

@@ -17,9 +17,18 @@ 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;
+    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: [
                 {

package/dist/tools/testmanagement-utils/list-testcases.js

@@ -65,7 +65,13 @@ export async function listTestCases(args, config) {
         const count = info?.count ?? test_cases.length;
         // Summary for more focused output
         const summary = test_cases
-            .map((tc) => `• ${tc.identifier}: ${tc.title} [${tc.case_type} | ${tc.priority}]`)
+            .map((tc) => {
+            const links = (tc.issues ?? [])
+                .filter((i) => i?.issue_type && i?.jira_id)
+                .map((i) => `${i.issue_type}:${i.jira_id}`)
+                .join(", ");
+            return `• ${tc.identifier}: ${tc.title} [${tc.case_type} | ${tc.priority}]${links ? ` {linked: ${links}}` : ""}`;
+        })
             .join("\n");
         return {
             content: [

package/dist/tools/testmanagement-utils/update-testrun.d.ts

@@ -17,11 +17,26 @@ export declare const UpdateTestRunSchema: z.ZodObject<{
             rejected: "rejected";
             closed: "closed";
         }>>;
+        add_test_cases: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            test_case_ids: z.ZodArray<z.ZodString>;
+            configuration_ids: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        }, z.core.$strip>>>;
+        preserve_existing_results: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 type UpdateTestRunArgs = z.infer<typeof UpdateTestRunSchema>;
 /**
  * Partially updates an existing test run.
+ *
+ * Dispatches to one of two BrowserStack endpoints based on the fields provided,
+ * mirroring how the platform splits these concerns across two endpoints:
+ *  - metadata (name / run_state) -> PATCH .../test-runs/{id}/update
+ *  - adding test cases -> PATCH .../test-runs/{id}/test-cases
+ *
+ * Either or both may be supplied in one call; each provided concern hits its
+ * own endpoint and both outcomes are reported. At least one must be provided.
+ * Removing test cases is intentionally not exposed — this tool is
+ * non-destructive.
  */
 export declare function updateTestRun(args: UpdateTestRunArgs, config: BrowserStackConfig): Promise<CallToolResult>;
 export {};

package/dist/tools/testmanagement-utils/update-testrun.js

@@ -3,6 +3,19 @@ import { getBrowserStackAuth } from "../../lib/get-auth.js";
 import { z } from "zod";
 import { formatAxiosError } from "../../lib/error.js";
 import { getTMBaseURL } from "../../lib/tm-base-url.js";
+/**
+ * Selection of test cases (with optional configurations) to add.
+ */
+const TestCaseSelectionSchema = z.object({
+    test_case_ids: z
+        .array(z.string())
+        .min(1)
+        .describe("Test case IDs, e.g. TC-123"),
+    configuration_ids: z
+        .array(z.number())
+        .optional()
+        .describe("Configuration IDs to apply"),
+});
 /**
  * Schema for updating a test run with partial fields.
  */
@@ -24,22 +37,82 @@ export const UpdateTestRunSchema = z.object({
         ])
             .optional()
             .describe("Updated state of the test run"),
+        add_test_cases: z
+            .array(TestCaseSelectionSchema)
+            .optional()
+            .describe("Test cases to add to the run"),
+        preserve_existing_results: z
+            .boolean()
+            .optional()
+            .describe("Keep existing results when adding cases (default true)"),
     }),
 });
+/**
+ * Builds the HTTP Basic auth header from per-request config credentials.
+ */
+function buildAuthHeader(config) {
+    return "Basic " + Buffer.from(getBrowserStackAuth(config)).toString("base64");
+}
 /**
  * Partially updates an existing test run.
+ *
+ * Dispatches to one of two BrowserStack endpoints based on the fields provided,
+ * mirroring how the platform splits these concerns across two endpoints:
+ *  - metadata (name / run_state) -> PATCH .../test-runs/{id}/update
+ *  - adding test cases -> PATCH .../test-runs/{id}/test-cases
+ *
+ * Either or both may be supplied in one call; each provided concern hits its
+ * own endpoint and both outcomes are reported. At least one must be provided.
+ * Removing test cases is intentionally not exposed — this tool is
+ * non-destructive.
  */
 export async function updateTestRun(args, config) {
+    const { name, run_state, add_test_cases } = args.test_run;
+    const addIds = add_test_cases?.flatMap((s) => s.test_case_ids) ?? [];
+    const hasTestCases = addIds.length > 0;
+    const hasMetadata = name !== undefined || run_state !== undefined;
+    if (!hasTestCases && !hasMetadata) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "Nothing to update: provide name/run_state and/or add_test_cases.",
+                },
+            ],
+            isError: true,
+        };
+    }
+    const tmBaseUrl = await getTMBaseURL(config);
+    const authHeader = buildAuthHeader(config);
+    const tasks = [];
+    if (hasMetadata) {
+        tasks.push(updateTestRunMetadata(args, tmBaseUrl, authHeader));
+    }
+    if (hasTestCases) {
+        tasks.push(updateTestRunTestCases(args, tmBaseUrl, authHeader));
+    }
+    const results = await Promise.all(tasks);
+    if (results.length === 1) {
+        return results[0];
+    }
+    // Both concerns updated: aggregate outcomes; surface an error if either failed.
+    return {
+        content: results.flatMap((r) => r.content),
+        isError: results.some((r) => r.isError),
+    };
+}
+/**
+ * Updates test run metadata (name / run_state) via the /update endpoint.
+ */
+async function updateTestRunMetadata(args, baseUrl, authHeader) {
     try {
-        const body = { test_run: args.test_run };
-        const tmBaseUrl = await getTMBaseURL(config);
-        const url = `${tmBaseUrl}/api/v2/projects/${encodeURIComponent(args.project_identifier)}/test-runs/${encodeURIComponent(args.test_run_id)}/update`;
-        const authString = getBrowserStackAuth(config);
-        const [username, password] = authString.split(":");
+        const { name, run_state } = args.test_run;
+        const body = { test_run: { name, run_state } };
+        const url = `${baseUrl}/api/v2/projects/${encodeURIComponent(args.project_identifier)}/test-runs/${encodeURIComponent(args.test_run_id)}/update`;
         const resp = await apiClient.patch({
             url,
             headers: {
-                Authorization: "Basic " + Buffer.from(`${username}:${password}`).toString("base64"),
+                Authorization: authHeader,
                 "Content-Type": "application/json",
             },
             body,
@@ -70,3 +143,52 @@ export async function updateTestRun(args, config) {
         return formatAxiosError(err, "Failed to update test run");
     }
 }
+/**
+ * Adds test cases to a run via the /test-cases endpoint.
+ * This call is applied asynchronously by the backend.
+ */
+async function updateTestRunTestCases(args, baseUrl, authHeader) {
+    try {
+        const { add_test_cases, preserve_existing_results } = args.test_run;
+        const body = {
+            test_run: {
+                add_test_cases,
+                preserve_existing_results: preserve_existing_results ?? true,
+            },
+        };
+        const url = `${baseUrl}/api/v2/projects/${encodeURIComponent(args.project_identifier)}/test-runs/${encodeURIComponent(args.test_run_id)}/test-cases`;
+        const resp = await apiClient.patch({
+            url,
+            headers: {
+                Authorization: authHeader,
+                "Content-Type": "application/json",
+            },
+            body,
+        });
+        const data = resp.data;
+        if (!data.success) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to update test run test cases: ${JSON.stringify(data)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const added = add_test_cases?.flatMap((s) => s.test_case_ids) ?? [];
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Queued test-case update for ${args.test_run_id} (added ${added.length}); changes apply asynchronously.`,
+                },
+                { type: "text", text: JSON.stringify(data, null, 2) },
+            ],
+        };
+    }
+    catch (err) {
+        return formatAxiosError(err, "Failed to update test run test cases");
+    }
+}

package/dist/tools/testmanagement.js

@@ -400,7 +400,7 @@ export default function addTestManagementTools(server, config) {
     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 in BrowserStack Test Management.", UpdateTestRunSchema.shape, (args) => updateTestRunTool(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));

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

@@ -0,0 +1,8 @@
+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 { TriggerRcaReportArgs } from "./tfa-rca-utils/trigger-report.js";
+export declare function tfaRcaTurnTool(args: TfaRcaTurnArgs, config: BrowserStackConfig, context?: any): Promise<CallToolResult>;
+export declare function triggerRcaReportTool(args: TriggerRcaReportArgs, 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,78 @@
+import { trackMCP } from "../lib/instrumentation.js";
+import { handleMCPError } from "../lib/utils.js";
+import { TFA_RCA_TURN_PARAMS, TRIGGER_RCA_REPORT_PARAMS, } from "./tfa-rca-utils/constants.js";
+import { submitTfaRcaTurn, TfaRcaTurnError, } from "./tfa-rca-utils/submit-turn.js";
+import { triggerRcaReport, TriggerRcaReportError, } from "./tfa-rca-utils/trigger-report.js";
+const TOOL_NAME = "tfaRcaTurn";
+const TRIGGER_TOOL_NAME = "triggerRcaReport";
+/** 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 triggerRcaReportTool(args, config) {
+    const glimpse = await triggerRcaReport(args, config);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(glimpse, 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; returns status, asks, and RCA.", 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.triggerRcaReport = server.tool(TRIGGER_TOOL_NAME, "Trigger or read a build's Release Readiness report; returns a verdict glimpse and a UI link.", 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);
+        }
+    });
+    return tools;
+}

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

@@ -0,0 +1,65 @@
+import { z } from "zod";
+/**
+ * O11y base for the `rcaChat` proxy. The MCP server talks ONLY to o11y-api
+ * (boundary discipline, R9). The value is process-startup config resolved in
+ * `src/config.ts` from `O11Y_TFA_RCA_BASE_URL` (default: production) — never read
+ * `process.env` here. Resolved per call so a config built per server instance
+ * (multi-tenant) is honored.
+ */
+export declare function getO11yBaseUrl(): string;
+/**
+ * Test Observability (TRA) web UI base for human-facing "view report" links.
+ * Startup config (`BROWSERSTACK_O11Y_UI_BASE_URL` in `src/config.ts`, default
+ * observability.browserstack.com) — never read `process.env` here.
+ */
+export declare function getO11yUiBaseUrl(): string;
+/**
+ * TRA UI deep-link for a build's AI report (confirmed shape, 2026-07-13):
+ * `<UI_BASE>/builds/<buildUuid>?tab=ai_report&subTab=aitfa` — the AI-TFA
+ * sub-tab of the build's AI report. `{buildUuid}` is replaced with the
+ * caller-supplied build id.
+ */
+export declare const O11Y_UI_BUILD_PATH = "/builds/{buildUuid}?tab=ai_report&subTab=aitfa";
+/** Human-facing TRA UI link for one build's full report. */
+export declare function getO11yUiBuildUrl(buildUuid: string): string;
+/**
+ * Generic TRA UI pointer used on RESOLVED turns where only a testRunId is
+ * known (no buildUuid to deep-link). The full RCA lives on the dashboard
+ * (build page → AI report → AI TFA sub-tab).
+ */
+export declare function getRcaViewGuidance(): string;
+/** Trigger (or read, when already complete) a build's Release Readiness report. */
+export declare const RELEASE_READINESS_TRIGGER_PATH = "/ext/v1/ai/builds/{buildUuid}/releaseReadiness/trigger";
+/** Submit one collaborative turn for a test run. */
+export declare const RCA_CHAT_SUBMIT_PATH = "/ext/v1/testRuns/{testRunId}/rcaChat";
+/** Poll a submitted turn to completion. */
+export declare const RCA_CHAT_POLL_PATH = "/ext/v1/testRuns/{testRunId}/rcaChat/{turnId}";
+/** Initial wait before the first poll GET. */
+export declare const POLL_INITIAL_DELAY_MS = 2000;
+/** Interval between poll GETs. */
+export declare const POLL_INTERVAL_MS = 3000;
+/** Wall-clock cap for the in-call poll; exceeding it yields a soft PENDING. */
+export declare const POLL_MAX_WAIT_MS: number;
+/** Max length of the digest message, matching o11y's request `@Size`. */
+export declare const MESSAGE_MAX_LENGTH = 5000;
+/** Max chars of `root_cause` surfaced in the RESOLVED glimpse. */
+export declare const RCA_GLIMPSE_ROOT_CAUSE_MAX = 220;
+/**
+ * Zod param shapes for the `tfaRcaTurn` tool, exported as a
+ * `Record<string, ZodType>` mirroring `rca-agent-utils/constants.ts`.
+ * No credential fields (security rule). Each `.describe()` ≤ 60 chars.
+ */
+export declare const TFA_RCA_TURN_PARAMS: {
+    testRunId: z.ZodString;
+    message: z.ZodString;
+    threadId: z.ZodOptional<z.ZodString>;
+    turnId: z.ZodOptional<z.ZodString>;
+};
+/**
+ * Zod param shapes for the `triggerRcaReport` tool. No credential fields
+ * (security rule). Each `.describe()` ≤ 60 chars.
+ */
+export declare const TRIGGER_RCA_REPORT_PARAMS: {
+    buildUuid: z.ZodString;
+    force: z.ZodOptional<z.ZodBoolean>;
+};

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

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import appConfig from "../../config.js";
+/**
+ * O11y base for the `rcaChat` proxy. The MCP server talks ONLY to o11y-api
+ * (boundary discipline, R9). The value is process-startup config resolved in
+ * `src/config.ts` from `O11Y_TFA_RCA_BASE_URL` (default: production) — never read
+ * `process.env` here. Resolved per call so a config built per server instance
+ * (multi-tenant) is honored.
+ */
+export function getO11yBaseUrl() {
+    return appConfig.O11Y_TFA_RCA_BASE_URL;
+}
+/**
+ * Test Observability (TRA) web UI base for human-facing "view report" links.
+ * Startup config (`BROWSERSTACK_O11Y_UI_BASE_URL` in `src/config.ts`, default
+ * observability.browserstack.com) — never read `process.env` here.
+ */
+export function getO11yUiBaseUrl() {
+    return appConfig.BROWSERSTACK_O11Y_UI_BASE_URL;
+}
+/**
+ * TRA UI deep-link for a build's AI report (confirmed shape, 2026-07-13):
+ * `<UI_BASE>/builds/<buildUuid>?tab=ai_report&subTab=aitfa` — the AI-TFA
+ * sub-tab of the build's AI report. `{buildUuid}` is replaced with the
+ * caller-supplied build id.
+ */
+export const O11Y_UI_BUILD_PATH = "/builds/{buildUuid}?tab=ai_report&subTab=aitfa";
+/** Human-facing TRA UI link for one build's full report. */
+export function getO11yUiBuildUrl(buildUuid) {
+    return (getO11yUiBaseUrl() +
+        O11Y_UI_BUILD_PATH.replace("{buildUuid}", encodeURIComponent(buildUuid)));
+}
+/**
+ * Generic TRA UI pointer used on RESOLVED turns where only a testRunId is
+ * known (no buildUuid to deep-link). The full RCA lives on the dashboard
+ * (build page → AI report → AI TFA sub-tab).
+ */
+export function getRcaViewGuidance() {
+    return `${getO11yUiBaseUrl()} — open the build's AI report (tab=ai_report, subTab=aitfa) to view the full RCA`;
+}
+/** Trigger (or read, when already complete) a build's Release Readiness report. */
+export const RELEASE_READINESS_TRIGGER_PATH = "/ext/v1/ai/builds/{buildUuid}/releaseReadiness/trigger";
+/** Submit one collaborative turn for a test run. */
+export const RCA_CHAT_SUBMIT_PATH = "/ext/v1/testRuns/{testRunId}/rcaChat";
+/** Poll a submitted turn to completion. */
+export const RCA_CHAT_POLL_PATH = "/ext/v1/testRuns/{testRunId}/rcaChat/{turnId}";
+/** Initial wait before the first poll GET. */
+export const POLL_INITIAL_DELAY_MS = 2000;
+/** Interval between poll GETs. */
+export const POLL_INTERVAL_MS = 3000;
+/** Wall-clock cap for the in-call poll; exceeding it yields a soft PENDING. */
+export const POLL_MAX_WAIT_MS = 90 * 1000;
+/** Max length of the digest message, matching o11y's request `@Size`. */
+export const MESSAGE_MAX_LENGTH = 5000;
+/** Max chars of `root_cause` surfaced in the RESOLVED glimpse. */
+export const RCA_GLIMPSE_ROOT_CAUSE_MAX = 220;
+/**
+ * Zod param shapes for the `tfaRcaTurn` tool, exported as a
+ * `Record<string, ZodType>` mirroring `rca-agent-utils/constants.ts`.
+ * No credential fields (security rule). Each `.describe()` ≤ 60 chars.
+ */
+export const TFA_RCA_TURN_PARAMS = {
+    testRunId: z.string().describe("Test run id to run RCA collaboration on."),
+    message: z
+        .string()
+        .max(MESSAGE_MAX_LENGTH)
+        .describe("Digested analysis to send this turn; no raw logs."),
+    threadId: z
+        .string()
+        .optional()
+        .describe("Thread id from prior turn; omit on first turn."),
+    turnId: z
+        .string()
+        .optional()
+        .describe("Turn id to resume a pending poll; usually omit."),
+};
+/**
+ * Zod param shapes for the `triggerRcaReport` tool. No credential fields
+ * (security rule). Each `.describe()` ≤ 60 chars.
+ */
+export const TRIGGER_RCA_REPORT_PARAMS = {
+    buildUuid: z.string().describe("Automate build UUID to analyze."),
+    force: z
+        .boolean()
+        .optional()
+        .describe("Re-run even if a completed report exists."),
+};

package/dist/tools/tfa-rca-utils/submit-turn.d.ts

@@ -0,0 +1,28 @@
+import { BrowserStackConfig } from "../../lib/types.js";
+import { TfaRcaTurnResult } from "./types.js";
+interface TurnContext {
+    sendNotification?: (notification: any) => Promise<void>;
+    _meta?: {
+        progressToken?: string | number;
+    };
+}
+export interface TfaRcaTurnArgs {
+    testRunId: string;
+    message: string;
+    threadId?: string;
+    /** Resume polling an already-submitted turn without re-submitting. */
+    turnId?: string;
+}
+/**
+ * Domain error carrying a client-safe message. The tool maps these to a
+ * `{ isError: true }` envelope; the message never contains credentials.
+ */
+export declare class TfaRcaTurnError extends Error {
+}
+/**
+ * Submit one collaborative RCA turn to the o11y `rcaChat` proxy and poll to
+ * completion, returning a trimmed structured result. Stateless: all identifiers
+ * are function-scoped; nothing persists between calls.
+ */
+export declare function submitTfaRcaTurn(args: TfaRcaTurnArgs, config: BrowserStackConfig, context?: TurnContext): Promise<TfaRcaTurnResult>;
+export {};

package/dist/tools/tfa-rca-utils/submit-turn.js

@@ -0,0 +1,222 @@
+import { apiClient } from "../../lib/apiClient.js";
+import { getBrowserStackAuth } from "../../lib/get-auth.js";
+import { getO11yBaseUrl, getRcaViewGuidance, POLL_INITIAL_DELAY_MS, POLL_INTERVAL_MS, POLL_MAX_WAIT_MS, RCA_CHAT_POLL_PATH, RCA_CHAT_SUBMIT_PATH, RCA_GLIMPSE_ROOT_CAUSE_MAX, } from "./constants.js";
+import { PENDING_STATUS, TfaStatus, } from "./types.js";
+/**
+ * Domain error carrying a client-safe message. The tool maps these to a
+ * `{ isError: true }` envelope; the message never contains credentials.
+ */
+export class TfaRcaTurnError extends Error {
+}
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function buildAuthHeader(config) {
+    const authString = getBrowserStackAuth(config);
+    return `Basic ${Buffer.from(authString).toString("base64")}`;
+}
+async function notify(context, message, progress) {
+    if (!context?.sendNotification)
+        return;
+    await context.sendNotification({
+        method: "notifications/progress",
+        params: {
+            progressToken: context._meta?.progressToken?.toString() ?? "tfa-rca-turn",
+            message,
+            progress,
+            total: 100,
+        },
+    });
+}
+/** Map a raw status string from the wire onto the `TfaStatus` enum. */
+function toTfaStatus(raw) {
+    switch (raw) {
+        case "RESOLVED":
+            return TfaStatus.RESOLVED;
+        case "BLOCKED":
+            return TfaStatus.BLOCKED;
+        default:
+            return TfaStatus.NEEDS_INFO;
+    }
+}
+/** Map one wire ask (snake_case) to the client `TfaAsk` (camelCase). */
+function toAsk(raw) {
+    return {
+        what: raw?.what ?? "",
+        why: raw?.why ?? "",
+        evidenceType: raw?.evidence_type ?? "other",
+        priority: raw?.priority ?? "medium",
+    };
+}
+/**
+ * Read the LLM-enforced structured turn from the completed `rcaChat` poll body.
+ *
+ * The poll envelope's own `status` field is the lifecycle state
+ * (`working`/`completed`/`failed`); the agent's `TurnResponse` is passed
+ * through under `turn` so its `status` (NEEDS_INFO/RESOLVED/BLOCKED) never
+ * collides with the lifecycle one. The agent's model validator guarantees the
+ * sub-object matching the turn status is present; we still default-fill the
+ * lists so the skill never sees `undefined`.
+ */
+function readStructuredTurn(data) {
+    const turn = data.turn ?? {};
+    const status = toTfaStatus(turn.status);
+    const needsInfo = turn.needs_info ?? {};
+    const blocked = turn.blocked ?? {};
+    return {
+        status,
+        confidence: turn.confidence ?? "unknown",
+        questions: Array.isArray(needsInfo.questions) ? needsInfo.questions : [],
+        asks: Array.isArray(needsInfo.asks) ? needsInfo.asks.map(toAsk) : [],
+        suggestions: Array.isArray(needsInfo.suggestions)
+            ? needsInfo.suggestions
+            : [],
+        hypotheses: Array.isArray(needsInfo.hypotheses) ? needsInfo.hypotheses : [],
+        rca: status === TfaStatus.RESOLVED ? (turn.rca ?? undefined) : undefined,
+        reason: status === TfaStatus.BLOCKED ? blocked.reason : undefined,
+        unmetAsks: status === TfaStatus.BLOCKED && Array.isArray(blocked.unmet_asks)
+            ? blocked.unmet_asks
+            : undefined,
+    };
+}
+/** Truncate to `max` chars total (ellipsis included when cut). */
+function truncate(text, max) {
+    if (text === undefined)
+        return undefined;
+    return text.length > max ? text.slice(0, max - 1) + "…" : text;
+}
+/**
+ * Trim a completed turn to the status-discriminated contract:
+ * - NEEDS_INFO: questions/asks/suggestions/hypotheses VERBATIM (the client
+ *   loop consumes them).
+ * - RESOLVED: glimpse only (root_cause truncated, failure_type, related_prs)
+ *   + a `viewRca` pointer — the full RCA lives on the TRA dashboard.
+ * - BLOCKED: reason + unmetAsks.
+ */
+function toTrimmedResult(turn, threadId) {
+    switch (turn.status) {
+        case TfaStatus.RESOLVED: {
+            const rca = turn.rca ?? {};
+            return {
+                status: turn.status,
+                confidence: turn.confidence,
+                threadId,
+                glimpse: {
+                    root_cause: truncate(rca.root_cause, RCA_GLIMPSE_ROOT_CAUSE_MAX),
+                    failure_type: rca.failure_type,
+                    related_prs: rca.related_prs,
+                },
+                viewRca: getRcaViewGuidance(),
+            };
+        }
+        case TfaStatus.BLOCKED:
+            return {
+                status: turn.status,
+                confidence: turn.confidence,
+                threadId,
+                reason: turn.reason,
+                unmetAsks: turn.unmetAsks,
+            };
+        default:
+            return {
+                status: turn.status,
+                confidence: turn.confidence,
+                threadId,
+                questions: turn.questions,
+                asks: turn.asks,
+                suggestions: turn.suggestions,
+                hypotheses: turn.hypotheses,
+            };
+    }
+}
+/** Map a submit (POST) non-2xx into a clean, group-scope-safe domain error. */
+function mapSubmitError(status) {
+    if (status === 403) {
+        return new TfaRcaTurnError("AI consent not enabled for this group");
+    }
+    if (status === 404) {
+        return new TfaRcaTurnError("test run not found for your group");
+    }
+    return new TfaRcaTurnError(`failed to submit RCA turn (status ${status})`);
+}
+/**
+ * Submit one collaborative RCA turn to the o11y `rcaChat` proxy and poll to
+ * completion, returning a trimmed structured result. Stateless: all identifiers
+ * are function-scoped; nothing persists between calls.
+ */
+export async function submitTfaRcaTurn(args, config, context) {
+    const authHeader = buildAuthHeader(config);
+    const headers = {
+        "Content-Type": "application/json",
+        Authorization: authHeader,
+    };
+    const baseUrl = getO11yBaseUrl();
+    let turnId = args.turnId;
+    let threadId = args.threadId;
+    // Submit only when we are not resuming an existing turn.
+    if (!turnId) {
+        const submitUrl = baseUrl + RCA_CHAT_SUBMIT_PATH.replace("{testRunId}", args.testRunId);
+        await notify(context, "Submitting RCA turn to TFA agent...", 5);
+        const body = {
+            message: args.message,
+            client_context: args.message,
+        };
+        if (args.threadId) {
+            body.thread_id = args.threadId;
+        }
+        const submitResponse = await apiClient.post({
+            url: submitUrl,
+            headers,
+            body,
+            raise_error: false,
+        });
+        if (!submitResponse.ok) {
+            throw mapSubmitError(submitResponse.status);
+        }
+        const data = submitResponse.data ?? {};
+        turnId = data.turnId;
+        threadId = data.threadId ?? threadId;
+        if (!turnId) {
+            throw new TfaRcaTurnError("turn expired or not found");
+        }
+    }
+    // Poll to completion, soft-PENDING on wall-clock cap.
+    const pollUrl = baseUrl +
+        RCA_CHAT_POLL_PATH.replace("{testRunId}", args.testRunId).replace("{turnId}", turnId);
+    await delay(POLL_INITIAL_DELAY_MS);
+    const startTime = Date.now();
+    while (true) {
+        const pollResponse = await apiClient.get({
+            url: pollUrl,
+            headers,
+            raise_error: false,
+        });
+        if (pollResponse.status === 404) {
+            throw new TfaRcaTurnError("turn expired or not found");
+        }
+        if (pollResponse.ok) {
+            const data = pollResponse.data ?? {};
+            const status = data.status;
+            threadId = data.threadId ?? threadId;
+            if (status === "failed") {
+                throw new TfaRcaTurnError(data.error || "TFA agent run failed");
+            }
+            if (status === "completed") {
+                const turn = readStructuredTurn(data);
+                await notify(context, "TFA agent turn complete.", 100);
+                return toTrimmedResult(turn, threadId);
+            }
+            // status === "working" (or any other in-progress value) → keep polling.
+        }
+        // Transient non-2xx (other than 404) during polling: classify and continue.
+        if (Date.now() - startTime >= POLL_MAX_WAIT_MS) {
+            await notify(context, "TFA agent still working; will resume later.", 90);
+            // PENDING keeps only what the skill needs to resume polling.
+            return {
+                status: PENDING_STATUS,
+                threadId,
+                turnId,
+            };
+        }
+        await notify(context, "Waiting for TFA agent reply...", 50);
+        await delay(POLL_INTERVAL_MS);
+    }
+}

package/dist/tools/tfa-rca-utils/trigger-report.d.ts

@@ -0,0 +1,36 @@
+import { BrowserStackConfig } from "../../lib/types.js";
+export interface TriggerRcaReportArgs {
+    buildUuid: string;
+    /** Re-run even if a completed report already exists. */
+    force?: boolean;
+}
+/**
+ * Domain error carrying a client-safe message. The tool maps these to a
+ * `{ isError: true }` envelope; the message never contains credentials.
+ */
+export declare class TriggerRcaReportError extends Error {
+}
+/**
+ * Trimmed glimpse of the Release Readiness report. The raw o11y response —
+ * including the `prs[]` and `workflows[]` arrays — is NEVER echoed; the full
+ * report lives on the Test Observability dashboard (`viewReport`).
+ */
+export interface RcaReportGlimpse {
+    state?: string;
+    verdict?: string;
+    verdictProvisional?: boolean;
+    partial?: boolean;
+    analyzedCount?: number;
+    totalFailedCount?: number;
+    totalPrs?: number;
+    faultyPrNumbers?: unknown[];
+    failureReason?: string;
+    /** TRA UI link where the full report lives. */
+    viewReport: string;
+}
+/**
+ * Trigger (or read, when one already exists) the Release Readiness report for
+ * a build via the o11y external API, returning a trimmed glimpse. Stateless:
+ * nothing persists between calls.
+ */
+export declare function triggerRcaReport(args: TriggerRcaReportArgs, config: BrowserStackConfig): Promise<RcaReportGlimpse>;

package/dist/tools/tfa-rca-utils/trigger-report.js

@@ -0,0 +1,70 @@
+import { apiClient } from "../../lib/apiClient.js";
+import { getBrowserStackAuth } from "../../lib/get-auth.js";
+import { getO11yBaseUrl, getO11yUiBuildUrl, RELEASE_READINESS_TRIGGER_PATH, } from "./constants.js";
+/**
+ * Domain error carrying a client-safe message. The tool maps these to a
+ * `{ isError: true }` envelope; the message never contains credentials.
+ */
+export class TriggerRcaReportError extends Error {
+}
+/** Pull a machine error code out of a non-2xx body, wherever it rides. */
+function extractErrorCode(data) {
+    const candidate = data?.code ?? data?.error ?? data?.errorCode ?? data?.message;
+    return typeof candidate === "string" ? candidate : "";
+}
+/** Map a trigger (POST) non-2xx into a clean, group-scope-safe domain error. */
+function mapTriggerError(status, data) {
+    const code = extractErrorCode(data);
+    if (code.includes("REPO_NOT_CONFIGURED")) {
+        return new TriggerRcaReportError("repository not configured for Release Readiness; connect the repo in Test Observability settings");
+    }
+    if (code.includes("RELEASE_READINESS_NOT_FOUND")) {
+        return new TriggerRcaReportError("no Release Readiness report found for this build");
+    }
+    if (status === 403) {
+        return new TriggerRcaReportError("Release Readiness AI is not enabled for this group (plan or feature flag)");
+    }
+    if (status === 404) {
+        return new TriggerRcaReportError("build not found for your group");
+    }
+    return new TriggerRcaReportError(`failed to trigger Release Readiness report (status ${status})`);
+}
+/**
+ * Trigger (or read, when one already exists) the Release Readiness report for
+ * a build via the o11y external API, returning a trimmed glimpse. Stateless:
+ * nothing persists between calls.
+ */
+export async function triggerRcaReport(args, config) {
+    const authString = getBrowserStackAuth(config);
+    const headers = {
+        "Content-Type": "application/json",
+        Authorization: `Basic ${Buffer.from(authString).toString("base64")}`,
+    };
+    const url = getO11yBaseUrl() +
+        RELEASE_READINESS_TRIGGER_PATH.replace("{buildUuid}", encodeURIComponent(args.buildUuid)) +
+        `?force=${args.force === true}`;
+    const response = await apiClient.post({
+        url,
+        headers,
+        body: {},
+        raise_error: false,
+    });
+    if (!response.ok) {
+        throw mapTriggerError(response.status, response.data);
+    }
+    const data = response.data ?? {};
+    const summary = data.summary ?? {};
+    // Trimmed glimpse only — never the raw response, never prs[]/workflows[].
+    return {
+        state: summary.state ?? data.state,
+        verdict: summary.verdict,
+        verdictProvisional: summary.verdictProvisional,
+        partial: summary.partial,
+        analyzedCount: summary.analyzedCount,
+        totalFailedCount: summary.totalFailedCount,
+        totalPrs: summary.totalPrs,
+        faultyPrNumbers: summary.faultyPrNumbers,
+        failureReason: summary.failureReason,
+        viewReport: getO11yUiBuildUrl(args.buildUuid),
+    };
+}

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

@@ -0,0 +1,104 @@
+/**
+ * Collaboration status emitted by the TFA agent for one RCA turn.
+ * - NEEDS_INFO: TFA needs more digested input; the skill should execute the
+ *   returned asks/questions and submit another turn on the same thread.
+ * - RESOLVED: an agreed root cause was reached (carries `rca`); the loop stops.
+ * - BLOCKED: TFA cannot proceed; the loop stops with a best-effort result.
+ */
+export declare enum TfaStatus {
+    NEEDS_INFO = "NEEDS_INFO",
+    RESOLVED = "RESOLVED",
+    BLOCKED = "BLOCKED"
+}
+/**
+ * Soft, tool-emitted status used when an in-call poll exceeds its wall-clock
+ * cap. Not produced by the agent — produced by the turn util so the skill can
+ * resume polling on a later turn via the optional `turnId` arg.
+ */
+export declare const PENDING_STATUS: "PENDING";
+/**
+ * Confidence the agent attaches to a turn. Mirrors the misc-services
+ * `TurnResponse.confidence` Literal; PENDING turns carry `unknown`.
+ */
+export type Confidence = "low" | "medium" | "high" | "unknown";
+/**
+ * Evidence category the skill routes an ask to. Mirrors the misc-services
+ * `Ask.evidence_type` Literal.
+ */
+export type EvidenceType = "test_logs" | "product_code" | "k8s" | "kibana" | "metrics" | "deploy" | "ci" | "other";
+/** A typed request for evidence; the skill routes it by `evidenceType`. */
+export interface TfaAsk {
+    what: string;
+    why: string;
+    evidenceType: EvidenceType;
+    priority: "high" | "medium" | "low";
+}
+/**
+ * The agreed root-cause analysis carried on a RESOLVED turn. Mirrors the
+ * misc-services `TestFailureAnalysis` schema; passed through verbatim from the
+ * o11y `rcaChat` response and never reshaped client-side.
+ */
+export interface TfaRca {
+    root_cause?: string;
+    description?: string;
+    possible_fix?: string;
+    failure_type?: string;
+    alternatives_considered?: string[];
+    related_prs?: unknown[];
+    [key: string]: unknown;
+}
+/**
+ * Structured turn the o11y `rcaChat` poll returns once `status === "completed"`.
+ * Mirrors the misc-services `TurnResponse`; sub-objects are status-discriminated
+ * (the agent's model validator guarantees the matching one is present).
+ */
+export interface TurnResponse {
+    status: TfaStatus;
+    confidence: Confidence;
+    questions: string[];
+    asks: TfaAsk[];
+    suggestions: string[];
+    hypotheses: string[];
+    rca?: TfaRca;
+    /** Present on BLOCKED turns: why TFA cannot proceed. */
+    reason?: string;
+    /** Present on BLOCKED turns: the asks that went unmet. */
+    unmetAsks?: string[];
+}
+/**
+ * Trimmed glimpse of a RESOLVED turn's RCA. The full `TfaRca` payload
+ * (analysis, log_evidence, alternatives, ...) is intentionally dropped — the
+ * complete report lives on the Test Observability dashboard (`viewRca`).
+ */
+export interface TfaRcaGlimpse {
+    /** Truncated to `RCA_GLIMPSE_ROOT_CAUSE_MAX` chars. */
+    root_cause?: string;
+    failure_type?: string;
+    related_prs?: unknown[];
+}
+/**
+ * Trimmed, status-discriminated result returned by the turn util / tool. The
+ * raw o11y envelope, `meta` blob, and full RCA payload are never echoed:
+ * - NEEDS_INFO carries questions/asks/suggestions/hypotheses VERBATIM (the
+ *   client loop executes them).
+ * - RESOLVED carries only a `glimpse` + a `viewRca` UI pointer.
+ * - BLOCKED carries reason/unmetAsks.
+ * - PENDING carries only turnId/threadId to resume polling.
+ */
+export interface TfaRcaTurnResult {
+    status: TfaStatus | typeof PENDING_STATUS;
+    confidence?: Confidence;
+    threadId?: string;
+    /** Present on PENDING turns: resume via the tool's `turnId` arg. */
+    turnId?: string;
+    questions?: string[];
+    asks?: TfaAsk[];
+    suggestions?: string[];
+    hypotheses?: string[];
+    /** Present on RESOLVED turns: trimmed root-cause glimpse. */
+    glimpse?: TfaRcaGlimpse;
+    /** Present on RESOLVED turns: where the full RCA report lives. */
+    viewRca?: string;
+    reason?: string;
+    unmetAsks?: string[];
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Collaboration status emitted by the TFA agent for one RCA turn.
+ * - NEEDS_INFO: TFA needs more digested input; the skill should execute the
+ *   returned asks/questions and submit another turn on the same thread.
+ * - RESOLVED: an agreed root cause was reached (carries `rca`); the loop stops.
+ * - BLOCKED: TFA cannot proceed; the loop stops with a best-effort result.
+ */
+export var TfaStatus;
+(function (TfaStatus) {
+    TfaStatus["NEEDS_INFO"] = "NEEDS_INFO";
+    TfaStatus["RESOLVED"] = "RESOLVED";
+    TfaStatus["BLOCKED"] = "BLOCKED";
+})(TfaStatus || (TfaStatus = {}));
+/**
+ * Soft, tool-emitted status used when an in-call poll exceeds its wall-clock
+ * cap. Not produced by the agent — produced by the turn util so the skill can
+ * resume polling on a later turn via the optional `turnId` arg.
+ */
+export const PENDING_STATUS = "PENDING";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserstack/mcp-server",
-  "version": "1.2.25-beta.1",
+  "version": "1.2.27-beta.1",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",