@browserstack/mcp-server 1.4.0-beta.2 → 1.4.0

package/dist/tools/failurelogs-utils/automate.js

@@ -1,4 +1,5 @@
 import { getBrowserStackAuth } from "../../lib/get-auth.js";
+import { wrapUntrusted } from "../../lib/untrusted-content.js";
 import { filterLinesByKeywords, validateLogResponse, } from "./utils.js";
 import { apiClient } from "../../lib/apiClient.js";
 // NETWORK LOGS
@@ -22,7 +23,7 @@ export async function retrieveNetworkFailures(sessionId, config) {
         entry.response.status >= 400 ||
         entry.response._error !== undefined);
     return failureEntries.length > 0
-        ? `Network Failures (${failureEntries.length} found):\n${JSON.stringify(failureEntries.map((entry) => ({
+        ? `Network Failures (${failureEntries.length} found):\n${wrapUntrusted("network logs", JSON.stringify(failureEntries.map((entry) => ({
             startedDateTime: entry.startedDateTime,
             request: {
                 method: entry.request?.method,
@@ -36,7 +37,7 @@ export async function retrieveNetworkFailures(sessionId, config) {
             },
             serverIPAddress: entry.serverIPAddress,
             time: entry.time,
-        })), null, 2)}`
+        })), null, 2))}`
         : "No network failures found";
 }
 // SESSION LOGS
@@ -60,7 +61,7 @@ export async function retrieveSessionFailures(sessionId, config) {
         : JSON.stringify(response.data);
     const logs = filterSessionFailures(logText);
     return logs.length > 0
-        ? `Session Failures (${logs.length} found):\n${JSON.stringify(logs, null, 2)}`
+        ? `Session Failures (${logs.length} found):\n${wrapUntrusted("session logs", JSON.stringify(logs, null, 2))}`
         : "No session failures found";
 }
 // CONSOLE LOGS
@@ -84,7 +85,7 @@ export async function retrieveConsoleFailures(sessionId, config) {
         : JSON.stringify(response.data);
     const logs = filterConsoleFailures(logText);
     return logs.length > 0
-        ? `Console Failures (${logs.length} found):\n${JSON.stringify(logs, null, 2)}`
+        ? `Console Failures (${logs.length} found):\n${wrapUntrusted("console logs", JSON.stringify(logs, null, 2))}`
         : "No console failures found";
 }
 // FILTER: session logs

package/dist/tools/failurelogs-utils/resolve-app-build-id.d.ts

@@ -0,0 +1,2 @@
+import { BrowserStackConfig } from "../../lib/types.js";
+export declare function resolveAppAutomateBuildId(sessionId: string, config: BrowserStackConfig): Promise<string | undefined>;

package/dist/tools/failurelogs-utils/resolve-app-build-id.js

@@ -0,0 +1,5 @@
+import { SessionType } from "../../lib/constants.js";
+import { resolveBuildIdFromSession } from "../automate-utils/resolve-hashed-build-id.js";
+export async function resolveAppAutomateBuildId(sessionId, config) {
+    return resolveBuildIdFromSession(sessionId, SessionType.AppAutomate, config);
+}

package/dist/tools/failurelogs-utils/video.d.ts

@@ -0,0 +1,3 @@
+import { BrowserStackConfig } from "../../lib/types.js";
+import { SessionType } from "../../lib/constants.js";
+export declare function retrieveSessionVideo(sessionId: string, sessionType: SessionType, config: BrowserStackConfig): Promise<string>;

package/dist/tools/failurelogs-utils/video.js

@@ -0,0 +1,25 @@
+import { getBrowserStackAuth } from "../../lib/get-auth.js";
+import { apiClient } from "../../lib/apiClient.js";
+import { SessionType } from "../../lib/constants.js";
+import { validateLogResponse } from "./utils.js";
+export async function retrieveSessionVideo(sessionId, sessionType, config) {
+    const product = sessionType === SessionType.AppAutomate ? "app-automate" : "automate";
+    const url = `https://api.browserstack.com/${product}/sessions/${encodeURIComponent(sessionId)}.json`;
+    const authString = getBrowserStackAuth(config);
+    const auth = Buffer.from(authString).toString("base64");
+    const response = await apiClient.get({
+        url,
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Basic ${auth}`,
+        },
+        raise_error: false,
+    });
+    const validationError = validateLogResponse(response, "session video");
+    if (validationError)
+        return validationError.message;
+    const videoUrl = response.data?.automation_session?.video_url;
+    return typeof videoUrl === "string" && videoUrl.trim()
+        ? `Session video: ${videoUrl.trim()}`
+        : "No session video available for this session";
+}

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

@@ -3,7 +3,9 @@ import { trackMCP } from "../lib/instrumentation.js";
 import { NEEDS_SESSION_ID } from "./tool-handoff.js";
 import { retrieveNetworkFailures, retrieveSessionFailures, retrieveConsoleFailures, } from "./failurelogs-utils/automate.js";
 import { retrieveDeviceLogs, retrieveAppiumLogs, retrieveCrashLogs, } from "./failurelogs-utils/app-automate.js";
-import { AppAutomateLogType, AutomateLogType, SessionType, } from "../lib/constants.js";
+import { resolveAppAutomateBuildId } from "./failurelogs-utils/resolve-app-build-id.js";
+import { retrieveSessionVideo } from "./failurelogs-utils/video.js";
+import { AppAutomateLogType, AutomateLogType, SessionType, SessionVideoLogType, } from "../lib/constants.js";
 // Main log fetcher function
 export async function getFailureLogs(args, config) {
     const results = [];
@@ -12,17 +14,16 @@ export async function getFailureLogs(args, config) {
     if (!args.sessionId) {
         throw new Error("Session ID is required");
     }
-    if (args.sessionType === SessionType.AppAutomate && !args.buildId) {
-        throw new Error("Build ID is required for app-automate sessions");
-    }
     // Validate log types and collect errors
     validLogTypes = args.logTypes.filter((logType) => {
         const isAutomate = Object.values(AutomateLogType).includes(logType);
         const isAppAutomate = Object.values(AppAutomateLogType).includes(logType);
         if (!isAutomate && !isAppAutomate) {
             errors.push(`Invalid log type '${logType}'. Valid log types are: ${[
-                ...Object.values(AutomateLogType),
-                ...Object.values(AppAutomateLogType),
+                ...new Set([
+                    ...Object.values(AutomateLogType),
+                    ...Object.values(AppAutomateLogType),
+                ]),
             ].join(", ")}`);
             return false;
         }
@@ -47,11 +48,26 @@ export async function getFailureLogs(args, config) {
             isError: true,
         };
     }
+    let buildId = args.buildId;
+    const needsBuildId = validLogTypes.some((logType) => logType !== SessionVideoLogType);
+    if (args.sessionType === SessionType.AppAutomate &&
+        needsBuildId &&
+        !buildId) {
+        buildId = await resolveAppAutomateBuildId(args.sessionId, config);
+        if (!buildId) {
+            throw new Error("Build ID is required for app-automate sessions");
+        }
+    }
     let response;
     // eslint-disable-next-line no-useless-catch
     try {
         for (const logType of validLogTypes) {
             switch (logType) {
+                case SessionVideoLogType: {
+                    response = await retrieveSessionVideo(args.sessionId, args.sessionType, config);
+                    results.push({ type: "text", text: response });
+                    break;
+                }
                 case AutomateLogType.NetworkLogs: {
                     response = await retrieveNetworkFailures(args.sessionId, config);
                     results.push({ type: "text", text: response });
@@ -68,17 +84,17 @@ export async function getFailureLogs(args, config) {
                     break;
                 }
                 case AppAutomateLogType.DeviceLogs: {
-                    response = await retrieveDeviceLogs(args.sessionId, args.buildId, config);
+                    response = await retrieveDeviceLogs(args.sessionId, buildId, config);
                     results.push({ type: "text", text: response });
                     break;
                 }
                 case AppAutomateLogType.AppiumLogs: {
-                    response = await retrieveAppiumLogs(args.sessionId, args.buildId, config);
+                    response = await retrieveAppiumLogs(args.sessionId, buildId, config);
                     results.push({ type: "text", text: response });
                     break;
                 }
                 case AppAutomateLogType.CrashLogs: {
-                    response = await retrieveCrashLogs(args.sessionId, args.buildId, config);
+                    response = await retrieveCrashLogs(args.sessionId, buildId, config);
                     results.push({ type: "text", text: response });
                     break;
                 }
@@ -99,7 +115,7 @@ export async function getFailureLogs(args, config) {
 // Register tool with the MCP server
 export default function registerGetFailureLogs(server, config) {
     const tools = {};
-    tools.getFailureLogs = server.tool("getFailureLogs", "Fetch various types of logs from a BrowserStack session. Supports both automate and app-automate sessions." +
+    tools.getFailureLogs = server.tool("getFailureLogs", "Fetch logs, or the session video URL, for an Automate/App Automate session." +
         NEEDS_SESSION_ID, {
         sessionType: z
             .enum([SessionType.Automate, SessionType.AppAutomate])
@@ -110,7 +126,7 @@ export default function registerGetFailureLogs(server, config) {
         buildId: z
             .string()
             .optional()
-            .describe("Required only when sessionType is 'app-automate'. If sessionType is 'app-automate', always ask the user to provide the build ID before proceeding."),
+            .describe("App Automate build ID. Optional — resolved from the session if omitted."),
         logTypes: z
             .array(z.enum([
             AutomateLogType.NetworkLogs,
@@ -119,6 +135,7 @@ export default function registerGetFailureLogs(server, config) {
             AppAutomateLogType.DeviceLogs,
             AppAutomateLogType.AppiumLogs,
             AppAutomateLogType.CrashLogs,
+            SessionVideoLogType,
         ]))
             .describe("The types of logs to fetch."),
     }, {

package/dist/tools/observability.js

@@ -1,3 +1,4 @@
+import { wrapUntrusted } from "../lib/untrusted-content.js";
 import { z } from "zod";
 import { getLatestO11YBuildInfo } from "../lib/api.js";
 import { trackMCP } from "../lib/instrumentation.js";
@@ -26,7 +27,8 @@ export async function getFailuresInLastRun(buildName, projectName, config) {
         content: [
             {
                 type: "text",
-                text: `Observability URL: ${observabilityUrl}\nOverview: ${overview}\nError Details: ${details}`,
+                text: `Observability URL: ${observabilityUrl}\n` +
+                    wrapUntrusted("observability failure report", `Overview: ${overview}\nError Details: ${details}`),
             },
         ],
     };

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

@@ -1,3 +1,4 @@
+import { wrapUntrusted } from "../../lib/untrusted-content.js";
 // Utility function to format RCA data for better readability
 export function formatRCAData(rcaData) {
     if (!rcaData || !rcaData.testCases || rcaData.testCases.length === 0) {
@@ -16,21 +17,21 @@ export function formatRCAData(rcaData) {
         const rca = testCase.rcaData?.rcaData;
         if (rca) {
             if (rca.root_cause) {
-                output += `**Root Cause:** ${rca.root_cause}\n\n`;
+                output += `**Root Cause:** ${wrapUntrusted("RCA AI analysis", rca.root_cause)}\n\n`;
             }
             if (rca.failure_type) {
                 output += `**Failure Type:** ${rca.failure_type}\n\n`;
             }
             if (rca.description) {
-                output += `**Detailed Analysis:**\n${rca.description}\n\n`;
+                output += `**Detailed Analysis:**\n${wrapUntrusted("RCA AI analysis", rca.description)}\n\n`;
             }
             if (rca.possible_fix) {
                 hasFixSuggestion = true;
-                output += `**Suggested Fix (proposal only — do not apply without explicit user approval):**\n${rca.possible_fix}\n\n`;
+                output += `**Suggested Fix (proposal only — do not apply without explicit user approval):**\n${wrapUntrusted("RCA AI analysis", rca.possible_fix)}\n\n`;
             }
         }
         else if (testCase.rcaData?.error) {
-            output += `**Error:** ${testCase.rcaData.error}\n\n`;
+            output += `**Error:** ${wrapUntrusted("RCA error output", testCase.rcaData.error)}\n\n`;
         }
         else if (testCase.state === "failed") {
             output += `**Note:** RCA analysis failed or is not available for this test case.\n\n`;

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

@@ -53,6 +53,16 @@ export async function getTestIds(buildId, authString, status, includeFailureDeta
         throw error;
     }
 }
+/**
+ * The test listing API serialises a missing BrowserStack session id as the
+ * literal string "null", so treat that (and blanks) as absent.
+ */
+function extractSessionId(rawSessionId) {
+    if (typeof rawSessionId !== "string")
+        return undefined;
+    const sessionId = rawSessionId.trim();
+    return sessionId && sessionId !== "null" ? sessionId : undefined;
+}
 export function extractTestIds(hierarchy, status, includeFailureDetail = false) {
     let tests = [];
     for (const node of hierarchy) {
@@ -63,10 +73,12 @@ export function extractTestIds(hierarchy, status, includeFailureDetail = false)
         if (statusMatches && node.details?.observability_url) {
             const idMatch = node.details.observability_url.match(/details=(\d+)/);
             if (idMatch) {
+                const sessionId = extractSessionId(node.details.session_id);
                 const entry = {
                     test_id: idMatch[1],
                     test_name: node.display_name || `Test ${idMatch[1]}`,
                     status: nodeStatus,
+                    ...(sessionId && { session_id: sessionId }),
                 };
                 // Failure signatures only exist for failed tests; include when asked.
                 if (includeFailureDetail && nodeStatus === TestStatus.FAILED) {

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

@@ -30,6 +30,7 @@ export interface FailedTestInfo {
     test_name: string;
     status?: TestStatus;
     failure?: TestFailureSignature;
+    session_id?: string;
 }
 export declare enum RCAState {
     PENDING = "pending",

package/dist/tools/rca-agent.js

@@ -177,7 +177,7 @@ export default function addRCATools(server, config) {
             return handleMCPError("listBuildId", server, config, error);
         }
     });
-    tools.listTestIds = server.tool("listTestIds", "List all tests of a BrowserStack build (each with its status); optional status filter." +
+    tools.listTestIds = server.tool("listTestIds", "List all tests of a BrowserStack build (each with its status and session id); optional status filter." +
         NEEDS_BUILD_ID, LIST_TEST_IDS_PARAMS, {
         title: "List Test IDs",
         readOnlyHint: true,

package/dist/tools/review-agent.js

@@ -1,3 +1,4 @@
+import { wrapUntrusted } from "../lib/untrusted-content.js";
 import { getBrowserStackAuth } from "../lib/get-auth.js";
 import { getPercyBuildCount } from "./review-agent-utils/build-counts.js";
 import { getChangedPercySnapshotIds } from "./review-agent-utils/percy-snapshots.js";
@@ -50,7 +51,7 @@ export async function fetchPercyChanges(args, config) {
     return {
         content: allDiffs.map((diff) => ({
             type: "text",
-            text: `${diff.name} → ${diff.title}: ${diff.description ?? ""}`,
+            text: wrapUntrusted("Percy AI visual-diff description", `${diff.name} → ${diff.title}: ${diff.description ?? ""}`),
         })),
     };
 }

package/dist/tools/sdk-utils/common/constants.d.ts

@@ -1,4 +1,4 @@
-export declare const IMPORTANT_SETUP_WARNING = "IMPORTANT: DO NOT SKIP ANY STEP. All the setup steps described below MUST be executed regardless of any existing configuration or setup. This ensures proper BrowserStack SDK setup.";
+export declare const IMPORTANT_SETUP_WARNING: string;
 export declare const SETUP_PERCY_DESCRIPTION = "Set up or expand Percy visual testing configuration with comprehensive coverage for existing projects that might have Percy integrated. This supports both Percy Web Standalone and Percy Automate. Example prompts: Expand percy coverage for this project {project_name}";
 export declare const LIST_TEST_FILES_DESCRIPTION = "Lists all test files for a given set of directories.";
 export declare const PERCY_SNAPSHOT_COMMANDS_DESCRIPTION = "Adds Percy snapshot commands to the specified test files.";

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

@@ -1,4 +1,5 @@
-export const IMPORTANT_SETUP_WARNING = "IMPORTANT: DO NOT SKIP ANY STEP. All the setup steps described below MUST be executed regardless of any existing configuration or setup. This ensures proper BrowserStack SDK setup.";
+export const IMPORTANT_SETUP_WARNING = "IMPORTANT: DO NOT SKIP ANY STEP. All the setup steps described below MUST be executed regardless of any existing configuration or setup. This ensures proper BrowserStack SDK setup. " +
+    "If you cannot run commands or edit files in the user's project (e.g. a chat-only client), present every step below to the user in full — including each shell command, the package.json changes, and the complete browserstack.yml contents — instead of summarizing them.";
 export const SETUP_PERCY_DESCRIPTION = "Set up or expand Percy visual testing configuration with comprehensive coverage for existing projects that might have Percy integrated. This supports both Percy Web Standalone and Percy Automate. Example prompts: Expand percy coverage for this project {project_name}";
 export const LIST_TEST_FILES_DESCRIPTION = "Lists all test files for a given set of directories.";
 export const PERCY_SNAPSHOT_COMMANDS_DESCRIPTION = "Adds Percy snapshot commands to the specified test files.";

package/dist/tools/selfheal.js

@@ -506,7 +506,7 @@ export default function addSelfHealTools(server, config) {
         sessions: sessionsFieldSchema.describe("Sessions to plan edits for. See tool description for accepted shapes."),
     }, {
         title: "Prepare Self-Healing Plan",
-        readOnlyHint: true,
+        readOnlyHint: false,
         openWorldHint: false,
         destructiveHint: false,
         idempotentHint: true,

package/dist/tools/testmanagement-utils/testcase-from-file.js

@@ -1,3 +1,4 @@
+import { wrapUntrusted } from "../../lib/untrusted-content.js";
 import { fetchFormFields, triggerTestCaseGeneration, pollScenariosTestDetails, bulkCreateTestCases, } from "./TCG-utils/api.js";
 import { buildDefaultFieldMaps, findBooleanFieldId, } from "./TCG-utils/helpers.js";
 import { signedUrlMap } from "../../lib/inmemory-store.js";
@@ -37,7 +38,7 @@ export async function createTestCasesFromFile(args, context, config) {
         content: [
             {
                 type: "text",
-                text: resultString,
+                text: wrapUntrusted("AI-generated test cases from the uploaded document", resultString),
             },
             {
                 type: "text",

package/dist/tools/testmanagement-utils/upload-file.js

@@ -19,16 +19,30 @@ export const UploadFileSchema = z.object({
         .describe("ID of the project where the file should be uploaded. Do not assume it, always ask user for it."),
     file_path: z
         .string()
-        .describe("Full path to the file that should be uploaded"),
+        .describe("Full path to the file that should be uploaded. Must be inside the " +
+        "directory configured via the MCP_UPLOAD_BASE_DIR environment variable."),
 });
 /**
  * Uploads a file to BrowserStack Test Management and returns the signed URL.
  */
 export async function uploadFile(args, config) {
     const { project_identifier, file_path } = args;
+    if (!appConfig.UPLOAD_BASE_DIR) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: "File upload is disabled. Set the MCP_UPLOAD_BASE_DIR environment " +
+                        "variable to a directory that contains the files you want to upload, " +
+                        "then restart the MCP server. Uploads are restricted to that directory.",
+                },
+            ],
+            isError: true,
+        };
+    }
     try {
         // Canonicalize path and enforce upload safety rules (extension, size,
-        // hidden-directory traversal, optional base-dir containment).
+        // hidden-directory traversal, base-dir containment).
         const safePath = validateUploadPath(file_path, {
             allowedExtensions: TEST_MANAGEMENT_ATTACHMENT_EXTENSIONS,
             maxSizeBytes: MAX_ATTACHMENT_UPLOAD_BYTES,

package/dist/tools/testmanagement.js

@@ -19,7 +19,7 @@ import { getTestPlan, GetTestPlanSchema, } from "./testmanagement-utils/get-test
 import { listSubTestPlans, ListSubTestPlansSchema, } from "./testmanagement-utils/list-sub-testplans.js";
 import { getSubTestPlan, GetSubTestPlanSchema, } from "./testmanagement-utils/get-sub-testplan.js";
 import { elicitCredentialsIfSupported } from "../lib/elicit-credentials.js";
-import { NEEDS_PROJECT_ID, NEEDS_TEST_PLAN_ID } from "./tool-handoff.js";
+import { NEEDS_PROJECT_ID, NEEDS_TEST_PLAN_ID, PLAN_WRITES_VIA_AGENT, PROJECT_ID_ONLY_FOR_FOLDER, } from "./tool-handoff.js";
 //TODO: Moving the traceMCP and catch block to the parent(server) function
 /**
  * Wrapper to call createProjectOrFolder util.
@@ -434,7 +434,7 @@ 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." +
-        NEEDS_PROJECT_ID, CreateProjFoldSchema.shape, {
+        PROJECT_ID_ONLY_FOR_FOLDER, CreateProjFoldSchema.shape, {
         title: "Create Project or Folder",
         readOnlyHint: false,
         openWorldHint: false,
@@ -535,7 +535,8 @@ export default function addTestManagementTools(server, config) {
         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." +
-        NEEDS_PROJECT_ID, ListTestPlansSchema.shape, {
+        NEEDS_PROJECT_ID +
+        PLAN_WRITES_VIA_AGENT, ListTestPlansSchema.shape, {
         title: "List Test Plans",
         readOnlyHint: true,
         openWorldHint: false,
@@ -544,7 +545,8 @@ export default function addTestManagementTools(server, config) {
     }, (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." +
         NEEDS_PROJECT_ID +
-        NEEDS_TEST_PLAN_ID, GetTestPlanSchema.shape, {
+        NEEDS_TEST_PLAN_ID +
+        PLAN_WRITES_VIA_AGENT, GetTestPlanSchema.shape, {
         title: "Get Test Plan",
         readOnlyHint: true,
         openWorldHint: false,
@@ -553,7 +555,8 @@ export default function addTestManagementTools(server, config) {
     }, (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." +
         NEEDS_PROJECT_ID +
-        NEEDS_TEST_PLAN_ID, ListSubTestPlansSchema.shape, {
+        NEEDS_TEST_PLAN_ID +
+        PLAN_WRITES_VIA_AGENT, ListSubTestPlansSchema.shape, {
         title: "List Sub Test Plans",
         readOnlyHint: true,
         openWorldHint: false,
@@ -562,7 +565,8 @@ export default function addTestManagementTools(server, config) {
     }, (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." +
         NEEDS_PROJECT_ID +
-        NEEDS_TEST_PLAN_ID, GetSubTestPlanSchema.shape, {
+        NEEDS_TEST_PLAN_ID +
+        PLAN_WRITES_VIA_AGENT, GetSubTestPlanSchema.shape, {
         title: "Get Sub Test Plan",
         readOnlyHint: true,
         openWorldHint: false,

package/dist/tools/tool-handoff.d.ts

@@ -23,11 +23,40 @@
 export declare const NEEDS_PROJECT_ID: string;
 /** A sibling tool can produce the id — prefer it over the agent. */
 export declare function needsIdFrom(idLabel: string, sourceTool: string): string;
+/**
+ * createProjectOrFolder must NOT carry NEEDS_PROJECT_ID: `project_identifier` is optional
+ * there, and the create-a-PROJECT half needs no id at all. With the generic constant the
+ * tool read "Requires a project identifier ... call askBrowserStackAI", which routed
+ * "create me a project" through the agent before letting the tool run.
+ */
+export declare const PROJECT_ID_ONLY_FOR_FOLDER: string;
 /** A test plan id (TP-*) comes from listTestPlans. */
 export declare const NEEDS_TEST_PLAN_ID: string;
+/**
+ * The ONLY capability handoff here: every other constant points at a tool that produces a
+ * missing *id*, but plan WRITES have no tool at all — the surface is `listTestPlans`,
+ * `getTestPlan`, `listSubTestPlans`, `getSubTestPlan` and nothing else. Atlas can do them
+ * (the tm harness allows POST /api/v1/projects/{id}/test-plans plus /update, /delete,
+ * /clone, /test-runs and /test-runs/unlink), so without this line the model reads the four
+ * read tools, finds no create, and reports the capability as absent — which is exactly what
+ * a QA eval concluded.
+ *
+ * Deliberately narrow: it names the specific operations that are missing rather than
+ * inviting the model to route plan work to the agent generally, because the tool
+ * descriptions otherwise say to prefer a specific tool whenever one fits.
+ *
+ * Caveat worth knowing: askBrowserStackAI pins every write to human approval, so this path
+ * only completes on a client that can show a prompt. On one that cannot, the intended write
+ * comes back in `needs_approval` instead of happening.
+ */
+export declare const PLAN_WRITES_VIA_AGENT: string;
 /** A build id comes from either build-lookup tool. */
 export declare const NEEDS_BUILD_ID: string;
-/** Session ids are not listable by any tool here. */
+/**
+ * Session ids ARE listable now — PR #395 added `listSessions`, which merged into main while
+ * this branch was open. This used to send the model to askBrowserStackAI for want of a tool;
+ * pointing at the agent when a real tool exists is exactly what the header above forbids.
+ */
 export declare const NEEDS_SESSION_ID: string;
 /** A completed scan's ids come from startAccessibilityScan, or from the agent. */
 export declare const NEEDS_A11Y_SCAN_ID: string;

package/dist/tools/tool-handoff.js

@@ -27,21 +27,52 @@ export const NEEDS_PROJECT_ID = " Requires a project identifier (PR-*). No tool
 export function needsIdFrom(idLabel, sourceTool) {
     return ` Requires ${idLabel}. Call ${sourceTool} first if you do not have it.`;
 }
+/**
+ * createProjectOrFolder must NOT carry NEEDS_PROJECT_ID: `project_identifier` is optional
+ * there, and the create-a-PROJECT half needs no id at all. With the generic constant the
+ * tool read "Requires a project identifier ... call askBrowserStackAI", which routed
+ * "create me a project" through the agent before letting the tool run.
+ */
+export const PROJECT_ID_ONLY_FOR_FOLDER = " Creating a project needs no identifier. Creating a folder inside an EXISTING project " +
+    "needs that project's identifier (PR-*); no tool here lists projects, so ask " +
+    'askBrowserStackAI with product "tm" for it.';
 /** A test plan id (TP-*) comes from listTestPlans. */
 export const NEEDS_TEST_PLAN_ID = needsIdFrom("a test plan identifier (TP-*)", "listTestPlans");
+/**
+ * The ONLY capability handoff here: every other constant points at a tool that produces a
+ * missing *id*, but plan WRITES have no tool at all — the surface is `listTestPlans`,
+ * `getTestPlan`, `listSubTestPlans`, `getSubTestPlan` and nothing else. Atlas can do them
+ * (the tm harness allows POST /api/v1/projects/{id}/test-plans plus /update, /delete,
+ * /clone, /test-runs and /test-runs/unlink), so without this line the model reads the four
+ * read tools, finds no create, and reports the capability as absent — which is exactly what
+ * a QA eval concluded.
+ *
+ * Deliberately narrow: it names the specific operations that are missing rather than
+ * inviting the model to route plan work to the agent generally, because the tool
+ * descriptions otherwise say to prefer a specific tool whenever one fits.
+ *
+ * Caveat worth knowing: askBrowserStackAI pins every write to human approval, so this path
+ * only completes on a client that can show a prompt. On one that cannot, the intended write
+ * comes back in `needs_approval` instead of happening.
+ */
+export const PLAN_WRITES_VIA_AGENT = " Creating a test plan or sub-plan, and linking or unlinking test runs on one, are not " +
+    'available as tools here: call askBrowserStackAI with product "tm" and describe what you ' +
+    "want. It asks you to confirm before changing anything.";
 /** A build id comes from either build-lookup tool. */
 export const NEEDS_BUILD_ID = needsIdFrom("a BrowserStack build id", "getBuildId or listBuildId");
-/** Session ids are not listable by any tool here. */
-export const NEEDS_SESSION_ID = " Requires a session id, which no tool here lists. If you only know the build, call " +
-    "getBuildId or listBuildId; if you have neither, call askBrowserStackAI with product " +
-    '"tra" and describe the run you mean.';
+/**
+ * Session ids ARE listable now — PR #395 added `listSessions`, which merged into main while
+ * this branch was open. This used to send the model to askBrowserStackAI for want of a tool;
+ * pointing at the agent when a real tool exists is exactly what the header above forbids.
+ */
+export const NEEDS_SESSION_ID = " Requires a session id. listSessions lists them for a build; if you do not have the " +
+    "build either, getBuildId or listBuildId resolves one from a project and build name.";
 /** A completed scan's ids come from startAccessibilityScan, or from the agent. */
-export const NEEDS_A11Y_SCAN_ID = " Requires the ids of a completed scan. They are returned by startAccessibilityScan; " +
-    'for a scan run earlier, call askBrowserStackAI with product "a11y" to locate it, since ' +
-    "no tool here lists past scans.";
+export const NEEDS_A11Y_SCAN_ID = " Requires the ids of a completed scan, which are returned by startAccessibilityScan. " +
+    "No tool here lists past scans, so if you do not have the ids, start a new scan rather " +
+    "than guessing.";
 /** Auth-config ids are not listable by any tool here. */
 export const NEEDS_A11Y_CONFIG_ID = " Requires the numeric id returned by createAccessibilityAuthConfig. No tool here lists " +
-    "existing configurations, so if you do not have the id, call askBrowserStackAI with " +
-    'product "a11y".';
+    "existing configurations, so if you do not have the id, create one rather than guessing.";
 /** Test ids come from listTestIds, which itself needs a build id. */
 export const NEEDS_TEST_IDS = needsIdFrom("test ids", "listTestIds");

package/package.json

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