@browserstack/mcp-server 1.5.0 → 1.5.1-beta.2

package/dist/tools/accessibility.js

@@ -211,7 +211,7 @@ async function runAccessibilityScan(name, pageURL, context, config, authConfigId
 }
 export default function addAccessibilityTools(server, config) {
     const tools = {};
-    tools.accessibilityExpert = server.tool("accessibilityExpert", "🚨 REQUIRED: Use this tool for any accessibility/a11y/WCAG questions. Do NOT answer accessibility questions directly - always use this tool.", {
+    tools.accessibilityExpert = server.tool("accessibilityExpert", "Answer accessibility, a11y, and WCAG questions using BrowserStack's accessibility knowledge base.", {
         query: z
             .string()
             .describe("Any accessibility, a11y, WCAG, or web accessibility question"),

package/dist/tools/accessiblity-utils/auth-config.js

@@ -118,8 +118,9 @@ export class AccessibilityAuthConfig {
             throw new Error("BrowserStack credentials are not set for AccessibilityAuthConfig.");
         }
         try {
+            // No GET-by-id route exists; list and select.
             const response = await apiClient.get({
-                url: `https://api-accessibility.browserstack.com/api/website-scanner/v1/auth_configs/${configId}`,
+                url: "https://api-accessibility.browserstack.com/api/website-scanner/v1/auth_configs",
                 headers: {
                     Authorization: "Basic " +
                         Buffer.from(`${this.auth.username}:${this.auth.password}`).toString("base64"),
@@ -129,7 +130,19 @@ export class AccessibilityAuthConfig {
             if (!data.success) {
                 throw new Error(`Unable to get auth config: ${data.errors?.join(", ")}`);
             }
-            return data;
+            const match = data.data?.authConfigs?.find((entry) => Number(entry.id) === Number(configId));
+            if (!match) {
+                throw new Error(`Auth config ${configId} not found for this account`);
+            }
+            return {
+                success: true,
+                data: {
+                    id: match.id,
+                    name: match.name,
+                    type: match.type_identifier ?? match.type,
+                    ...(match.authData?.url ? { url: match.authData.url } : {}),
+                },
+            };
         }
         catch (err) {
             const msg = err?.response?.data?.error ||

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

@@ -13,10 +13,10 @@ export const FETCH_RCA_PARAMS = {
 export const GET_BUILD_ID_PARAMS = {
     browserStackProjectName: z
         .string()
-        .describe("The BrowserStack project name used during test run creation. Action: First, check browserstack.yml or any equivalent project configuration files. If the project name is found, extract and return it. If it is not found or if there is any uncertainty, immediately prompt the user to provide the value. Do not infer, guess, or assume a default."),
+        .describe("BrowserStack project name from the test run config (e.g. browserstack.yml). Exact match; no default."),
     browserStackBuildName: z
         .string()
-        .describe("The BrowserStack build name used during test run creation. Action: First, check browserstack.yml or any equivalent project configuration files. If the build name is found, extract and return it. If it is not found or if there is any uncertainty, immediately prompt the user to provide the value. Do not infer, guess, or assume a default."),
+        .describe("BrowserStack build name from the test run config (e.g. browserstack.yml). Exact match; no default."),
 };
 export const LIST_TEST_IDS_PARAMS = {
     buildId: z

package/dist/tools/rca-agent.js

@@ -26,8 +26,8 @@ export async function getBuildIdTool(args, config) {
         };
     }
     catch (error) {
-        logger.error("Error fetching build ID", error);
         const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        logger.error("Error fetching build ID: %s", errorMessage);
         return {
             content: [
                 {
@@ -56,8 +56,8 @@ export async function listBuildIdTool(args, config) {
         };
     }
     catch (error) {
-        logger.error("Error fetching build ID", error);
         const errorMessage = error instanceof Error ? error.message : "Unknown error";
+        logger.error("Error fetching build ID: %s", errorMessage);
         return {
             content: [
                 {

package/dist/tools/sdk-utils/common/utils.js

@@ -51,7 +51,7 @@ export async function formatToolResult(resultPromise, runType) {
     if (runType != "percy-web") {
         finalContent.push({
             type: "text",
-            text: "CRITICAL: After the build is run, you MUST explicitly ask the user if they want to perform RCA (Root Cause Analysis) for any failed tests using the RCA tool. This step is mandatory and should not be skipped.",
+            text: "After the build has run, root cause analysis (RCA) is available for any failed tests: getBuildId, then listTestIds, then fetchRCA.",
         });
     }
     return {

package/dist/tools/selfheal-utils/fetch-test-code.d.ts

@@ -39,11 +39,10 @@ export interface SessionTestCode {
  */
 export declare function fetchTestCodeBySession(sessionId: string, config: BrowserStackConfig): Promise<SessionTestCode>;
 /**
- * Builds a directive guidance block for the calling LLM when one or more
- * sessions did not return usable test code. Each status block contains:
+ * Builds per-status notes when one or more sessions did not return usable
+ * test code. Each status block contains:
  *   - A diagnosis (what happened, per BrowserStack)
- *   - An explicit "do NOT paraphrase this as X" constraint
- *   - A ready-to-say phrasing the LLM can quote when replying to the user
+ *   - The next step
  *
  * Returns empty string when every session returned `status: ok`.
  */

package/dist/tools/selfheal-utils/fetch-test-code.js

@@ -82,11 +82,10 @@ export async function fetchTestCodeBySession(sessionId, config) {
     }
 }
 /**
- * Builds a directive guidance block for the calling LLM when one or more
- * sessions did not return usable test code. Each status block contains:
+ * Builds per-status notes when one or more sessions did not return usable
+ * test code. Each status block contains:
  *   - A diagnosis (what happened, per BrowserStack)
- *   - An explicit "do NOT paraphrase this as X" constraint
- *   - A ready-to-say phrasing the LLM can quote when replying to the user
+ *   - The next step
  *
  * Returns empty string when every session returned `status: ok`.
  */
@@ -107,21 +106,14 @@ export function describeTestCodeFetchIssues(sessionTestCodes) {
             `### Non-SDK build — session(s): ${ids}`,
             "",
             "Diagnosis: BrowserStack's test-code API returned HTTP 200 with rows " +
-                "where `code` and `filename` are null. This is the KNOWN signature " +
-                "of a BrowserStack run that was NOT instrumented with the " +
-                "BrowserStack SDK / Observability. The API literally has no source " +
-                "code to return for these sessions — this is by design.",
-            "",
-            "DO NOT tell the user any of the following (all are wrong for this " +
-                "status): 'credentials issue', 'credentials or session issue', " +
-                "'could not fetch from the API due to auth', '401', 'unauthorized'. " +
-                "The credentials are fine; the build just isn't SDK-enabled.",
-            "",
-            "Say this (or very close to it) to the user, then wait for their reply:",
-            '  "This is a non-SDK BrowserStack build, so the test-code API has ' +
-                "no source to return for it (this is expected, not a credentials " +
-                "problem). Can you tell me the local file path where these tests live? " +
-                "Once I have the file, I'll apply the healed locators listed in the plan.\"",
+                "where `code` and `filename` are null. This is the signature of a " +
+                "BrowserStack run that was not instrumented with the BrowserStack " +
+                "SDK / Observability, so the API has no source code to return for " +
+                "these sessions. Credentials are not involved; this is not an auth " +
+                "failure or a session problem.",
+            "",
+            "Next step: the healed locators can be applied once the user shares " +
+                "the local file path where these tests live.",
         ].join("\n"));
     }
     const unauthorized = byStatus.get("unauthorized");
@@ -131,23 +123,16 @@ export function describeTestCodeFetchIssues(sessionTestCodes) {
             `### Unauthorized (HTTP 401) — session(s): ${ids}`,
             "",
             "Diagnosis: BrowserStack's test-code API rejected the credentials " +
-                "(HTTP 401). This IS an authentication problem for this specific " +
-                "API — the healing report endpoint and test-code endpoint use the " +
+                "(HTTP 401). This is an authentication problem for this specific " +
+                "API. The healing report endpoint and test-code endpoint use the " +
                 "same BrowserStack auth, so if the report fetch above succeeded " +
-                "with the same creds, suspect that the access key configured on " +
-                "the MCP server was rotated.",
-            "",
-            "DO NOT say 'credentials or session issue' (that hides the real cause). " +
-                "Name the 401 explicitly and offer the user a choice. Do NOT ask " +
-                "the user to paste a BrowserStack username or access key in chat — " +
-                "the MCP server reads credentials from its own environment.",
+                "with the same creds, the access key configured on the MCP server " +
+                "was likely rotated.",
             "",
-            "Say this (or very close to it) to the user, then wait for their reply:",
-            '  "The BrowserStack test-code API returned 401 Unauthorized for ' +
-                `session(s) ${ids}. Would you like to: (a) update the BrowserStack ` +
-                "username and access key on the MCP server (BROWSERSTACK_USERNAME / " +
-                "BROWSERSTACK_ACCESS_KEY) and restart it, or (b) skip the API and " +
-                'point me at the local test file so I can apply the healed locators there?"',
+            "Next step: either update BROWSERSTACK_USERNAME / " +
+                "BROWSERSTACK_ACCESS_KEY on the MCP server and restart it, or apply " +
+                "the healed locators to the local test file if the user shares its " +
+                "path. Credentials are read from the server environment, not from chat.",
         ].join("\n"));
     }
     const forbidden = byStatus.get("forbidden");
@@ -159,16 +144,10 @@ export function describeTestCodeFetchIssues(sessionTestCodes) {
             "Diagnosis: BrowserStack's test-code API accepted the credentials " +
                 "but denied access to the session's source (HTTP 403). Typically " +
                 "the user does not own this session, or the account does not have " +
-                "Observability enabled.",
+                "Observability enabled. The credentials themselves were accepted.",
             "",
-            "Do NOT blame the credentials broadly — say 'access denied for this " +
-                "session' and move on.",
-            "",
-            "Say this (or very close to it) to the user:",
-            `  "BrowserStack denied access (HTTP 403) to session(s) ${ids}. ` +
-                "This usually means the account does not own these sessions or " +
-                "does not have Observability enabled. Can you either share the " +
-                'local test file path, or confirm which account these sessions belong to?"',
+            "Next step: confirm which account owns these sessions, or apply the " +
+                "healed locators to the local test file if the user shares its path.",
         ].join("\n"));
     }
     const notFound = byStatus.get("not_found");
@@ -178,14 +157,11 @@ export function describeTestCodeFetchIssues(sessionTestCodes) {
             `### Not found (HTTP 404) — session(s): ${ids}`,
             "",
             "Diagnosis: BrowserStack returned HTTP 404 — the session id is most " +
-                "likely wrong, or the session has been purged.",
-            "",
-            "Do NOT say 'credentials'. Ask the user to verify the id.",
+                "likely wrong, or the session has been purged. Credentials are not " +
+                "involved.",
             "",
-            "Say this (or very close to it) to the user:",
-            `  "I couldn't find session(s) ${ids} on BrowserStack (HTTP 404). ` +
-                "Can you double-check the session id(s), or share the local test " +
-                'file directly so I can apply the healed locators?"',
+            "Next step: verify the session id(s), or apply the healed locators to " +
+                "the local test file if the user shares its path.",
         ].join("\n"));
     }
     const empty = byStatus.get("empty");
@@ -198,9 +174,8 @@ export function describeTestCodeFetchIssues(sessionTestCodes) {
                 "no test code was captured (e.g. a raw Selenium session not linked " +
                 "to a test framework).",
             "",
-            "Say this (or very close to it) to the user:",
-            `  "BrowserStack has no test code recorded for session(s) ${ids}. ` +
-                'Can you point me at the local test file where these locators live?"',
+            "Next step: the healed locators can be applied once the user shares " +
+                "the local test file where these locators live.",
         ].join("\n"));
     }
     const errored = byStatus.get("error");
@@ -215,10 +190,8 @@ export function describeTestCodeFetchIssues(sessionTestCodes) {
             `Diagnosis: network/transport failure — ${details}. This is not an ` +
                 "auth issue.",
             "",
-            "Say this (or very close to it) to the user:",
-            `  "I hit a transport error fetching test code from BrowserStack ` +
-                `(${details}). Want me to retry, or would you prefer to share the ` +
-                'local test file directly?"',
+            "Next step: retry the fetch, or apply the healed locators to the " +
+                "local test file if the user shares its path.",
         ].join("\n"));
     }
     return notes.join("\n\n");

package/dist/tools/selfheal.js

@@ -18,9 +18,10 @@ function resolveBrowserStackAuth(config) {
     return { config };
 }
 const CREDS_PROMPT_TEXT = "BrowserStack credentials are not configured on the MCP server. " +
-    "Ask the user to set BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY " +
-    "in the server environment (https://www.browserstack.com/accounts/profile/details), " +
-    "restart the MCP server, and retry. Do NOT ask the user to paste credentials in chat.";
+    "Set BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY in the server " +
+    "environment (https://www.browserstack.com/accounts/profile/details), " +
+    "restart the MCP server, and retry. Credentials are read from the server " +
+    "environment, not from chat.";
 function credsMissingResult() {
     return {
         content: [{ type: "text", text: CREDS_PROMPT_TEXT }],
@@ -45,20 +46,13 @@ function trimOrUndefined(value) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : undefined;
 }
-/**
- * Wraps per-status guidance in a HEAD-OF-RESPONSE banner the LLM is unlikely
- * to paraphrase away. The banner must come BEFORE the plan JSON so the model
- * anchors on it when composing its user-facing reply.
- */
+/** Per-status notes, placed ahead of the plan JSON. */
 function buildWarningBanner(body) {
     return [
-        "## ATTENTION — test code fetch did not return usable source",
+        "## Test code fetch did not return usable source",
         "",
-        "Read this block BEFORE composing your reply to the user. When relaying " +
-            "this to the user, quote the provided phrasings below as closely as " +
-            "possible — do NOT compress multiple statuses into a generic " +
-            "'credentials or session issue' message. If the status below is " +
-            "`non_sdk_build`, it is definitely NOT a credentials problem.",
+        "Each status below has a different cause and is reported separately; " +
+            "a `non_sdk_build` status is not a credentials problem.",
         "",
         body,
         "",
@@ -236,7 +230,7 @@ export async function fetchSelfHealSelectorTool(args, config) {
                         "Self-healing report fetched successfully (buildUuid mode). " +
                         "Work session-by-session: for each entry in `healing_logs[]`, " +
                         "pass `healed_selectors[]` to `prepareSelfHealingPlan` so the " +
-                        "calling LLM can apply the edits with its own file-editing " +
+                        "caller can apply the edits with its own file-editing " +
                         "tools (this server never writes files).\n" +
                         JSON.stringify(report, null, 2) +
                         (testCodeContext
@@ -263,9 +257,9 @@ export async function fetchSelfHealSelectorTool(args, config) {
 const PLAN_INSTRUCTIONS = [
     "## How to use this plan",
     "",
-    "This tool does NOT modify any files. It returns the healed-locator plan",
-    "and per-session test source code so that YOU (the calling LLM) can make",
-    "surgical edits with your own file-editing tools.",
+    "This tool does not modify any files. It returns the healed-locator plan",
+    "and per-session test source code so the caller can make targeted edits",
+    "with its own file-editing tools.",
     "",
     "For each session in the plan:",
     "  1. Read each `tests[].code` to understand the test intent — especially",
@@ -273,10 +267,10 @@ const PLAN_INSTRUCTIONS = [
     "  2. Locate the exact call site(s) in the user's local project that",
     "     correspond to the original locator. Use `tests[].filename` as the",
     "     first place to look.",
-    "  3. Edit ONLY the call sites that belong to this session's failing step.",
-    "     A single id / class value may appear in many places; do NOT blindly",
-    "     find/replace across the repo (e.g. two different elements both using",
-    '     id="foo" must be resolved individually).',
+    "  3. Edit only the call sites that belong to this session's failing step.",
+    "     A single id / class value may appear in many places, so a blanket",
+    "     find/replace across the repo is unsafe (e.g. two different elements",
+    '     both using id="foo" must be resolved individually).',
     "  4. The healing report speaks in CSS/xpath, but the source often uses",
     "     `By.id(...)`, `By.name(...)`, `By.css(...)` wrappers. Translate as",
     "     needed — e.g. `*[id=\"email-field\"]` → `By.id('email-field')`, or",
@@ -285,7 +279,7 @@ const PLAN_INSTRUCTIONS = [
     "",
     "If `tests[]` is empty for a session, the BrowserStack API did not return",
     "test code (credentials missing, or the session has no associated test",
-    "runs). Ask the user to point you at the right file before editing.",
+    "runs). The local file path is needed before editing.",
 ].join("\n");
 export async function prepareSelfHealingPlanTool(args, config) {
     const rawArgs = args;
@@ -389,7 +383,7 @@ export async function prepareSelfHealingPlanTool(args, config) {
         }
         catch (error) {
             logger.warn("Failed to fetch test code during plan preparation", error);
-            warningBanner = buildWarningBanner(`### Transport error while fetching test code\n\nDiagnosis: ${error instanceof Error ? error.message : String(error)}. This is not an auth issue.\n\nSay this to the user: "I hit a transport error fetching test code from BrowserStack. Want me to retry, or would you rather share the local test file directly so I can apply the healed locators?"`);
+            warningBanner = buildWarningBanner(`### Transport error while fetching test code\n\nDiagnosis: ${error instanceof Error ? error.message : String(error)}. This is not an auth issue.\n\nNext step: retry the fetch, or apply the healed locators to the local test file if the user shares its path.`);
         }
     }
     else if (!resolved && sessionIds.length > 0) {
@@ -400,14 +394,10 @@ export async function prepareSelfHealingPlanTool(args, config) {
                 "configured on the MCP server, so test code could not be fetched. " +
                 "The plan was still generated from the locator pairs you sent.",
             "",
-            "Say this to the user: \"I couldn't pull the test source " +
-                "automatically because BrowserStack credentials aren't configured " +
-                "on the MCP server. Please set BROWSERSTACK_USERNAME and " +
-                "BROWSERSTACK_ACCESS_KEY in the server environment and restart " +
-                "the MCP server, or point me at the local test file directly so " +
-                'I can apply the healed locators."',
-            "",
-            "Do NOT ask the user to paste credentials in chat.",
+            "Next step: set BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY in " +
+                "the server environment and restart the MCP server, or apply the " +
+                "healed locators to the local test file if the user shares its path. " +
+                "Credentials are read from the server environment, not from chat.",
         ].join("\n"));
     }
     const skippedNote = skipped.length > 0

package/dist/tools/testmanagement-utils/get-sub-testplan.js

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { formatAxiosError } from "../../lib/error.js";
 import { getBrowserStackAuth } from "../../lib/get-auth.js";
 import { getTMBaseURL } from "../../lib/tm-base-url.js";
+import { wrapUntrusted } from "../../lib/untrusted-content.js";
 /**
  * Schema for fetching a single sub-test-plan by identifier under a parent test
  * plan, including its linked test runs.
@@ -106,7 +107,9 @@ export async function getSubTestPlan(args, config) {
             `Sub-Test-Plan ${plan.identifier}: ${plan.name}`,
             `Parent plan: ${plan.parent_plan_id}`,
             `Status: ${plan.active_state}`,
-            plan.description ? `Description: ${plan.description}` : null,
+            plan.description
+                ? `Description:\n${wrapUntrusted("sub-test-plan description", plan.description)}`
+                : null,
             tagsLine,
             issuesLine,
             plan.start_date || plan.end_date
@@ -133,12 +136,12 @@ export async function getSubTestPlan(args, config) {
                 { type: "text", text: header + runsBlock },
                 {
                     type: "text",
-                    text: JSON.stringify({
+                    text: wrapUntrusted("sub-test-plan (structured data)", JSON.stringify({
                         sub_test_plan: plan,
                         linked_test_runs: runs,
                         status_summary: statusSummary,
                         total_test_cases: totalCases,
-                    }, null, 2),
+                    }, null, 2)),
                 },
             ],
         };

package/dist/tools/testmanagement-utils/get-testplan.js

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { formatAxiosError } from "../../lib/error.js";
 import { getBrowserStackAuth } from "../../lib/get-auth.js";
 import { getTMBaseURL } from "../../lib/tm-base-url.js";
+import { wrapUntrusted } from "../../lib/untrusted-content.js";
 /**
  * Schema for fetching a single test plan by identifier, including its linked test runs.
  */
@@ -58,7 +59,9 @@ export async function getTestPlan(args, config) {
         const header = [
             `Test Plan ${plan.identifier}: ${plan.name}`,
             `Status: ${plan.active_state}`,
-            plan.description ? `Description: ${plan.description}` : null,
+            plan.description
+                ? `Description:\n${wrapUntrusted("test plan description", plan.description)}`
+                : null,
             plan.start_date || plan.end_date
                 ? `Dates: ${plan.start_date ?? "—"} → ${plan.end_date ?? "—"}`
                 : null,
@@ -83,12 +86,12 @@ export async function getTestPlan(args, config) {
                 { type: "text", text: header + runsBlock },
                 {
                     type: "text",
-                    text: JSON.stringify({
+                    text: wrapUntrusted("test plan (structured data)", JSON.stringify({
                         test_plan: plan,
                         linked_test_runs: runs,
                         status_summary: statusSummary,
                         total_test_cases: totalCases,
-                    }, null, 2),
+                    }, null, 2)),
                 },
             ],
         };

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

@@ -83,7 +83,7 @@ export async function listTestsInFailureThemeTool(args, config) {
 }
 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) => {
+    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 passes back the threadId from the previous response, since a test run has 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; calling tfaRcaTurn again for the same turn 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);

package/package.json

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