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

package/dist/config.d.ts

@@ -11,7 +11,10 @@ export declare class Config {
     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);
+    readonly ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY: boolean;
+    readonly ASK_BROWSERSTACK_ATLAS_URL: string | undefined;
+    readonly ASK_BROWSERSTACK_AUTH_TOKEN_URL: string | undefined;
+    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, ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY: boolean, ASK_BROWSERSTACK_ATLAS_URL: string | undefined, ASK_BROWSERSTACK_AUTH_TOKEN_URL: string | undefined);
 }
 declare const config: Config;
 export default config;

package/dist/config.js

@@ -47,7 +47,18 @@ export class Config {
     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) {
+    ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY;
+    ASK_BROWSERSTACK_ATLAS_URL;
+    ASK_BROWSERSTACK_AUTH_TOKEN_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, 
+    // askBrowserStackAI's process-startup settings. Declared here rather than read from
+    // process.env inside src/tools/, per rules/tool-design.md — and so the remote wrapper,
+    // which only forwards env it knows about, has one place to look.
+    //
+    // ASK_BROWSERSTACK_DISABLED is deliberately NOT here: it is a kill switch, and reading
+    // it per call keeps it effective without a restart. Fixing it at boot would mean a pod
+    // roll to disable the tool, which is slowest exactly when you need it fastest.
+    ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY, ASK_BROWSERSTACK_ATLAS_URL, ASK_BROWSERSTACK_AUTH_TOKEN_URL) {
         this.DEV_MODE = DEV_MODE;
         this.browserstackLocalOptions = browserstackLocalOptions;
         this.USE_OWN_LOCAL_BINARY_PROCESS = USE_OWN_LOCAL_BINARY_PROCESS;
@@ -56,6 +67,9 @@ export class Config {
         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;
+        this.ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY = ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY;
+        this.ASK_BROWSERSTACK_ATLAS_URL = ASK_BROWSERSTACK_ATLAS_URL;
+        this.ASK_BROWSERSTACK_AUTH_TOKEN_URL = ASK_BROWSERSTACK_AUTH_TOKEN_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
@@ -69,5 +83,12 @@ const config = new Config(process.env.DEV_MODE === "true", browserstackLocalOpti
     : 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);
+    : DEFAULT_BROWSERSTACK_O11Y_UI_BASE_URL, (process.env.ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY || "").toLowerCase() ===
+    "true", process.env.ASK_BROWSERSTACK_ATLAS_URL &&
+    process.env.ASK_BROWSERSTACK_ATLAS_URL.trim().length > 0
+    ? process.env.ASK_BROWSERSTACK_ATLAS_URL
+    : undefined, process.env.ASK_BROWSERSTACK_AUTH_TOKEN_URL &&
+    process.env.ASK_BROWSERSTACK_AUTH_TOKEN_URL.trim().length > 0
+    ? process.env.ASK_BROWSERSTACK_AUTH_TOKEN_URL
+    : undefined);
 export default config;

package/dist/tools/ask-browserstack/central-oauth.d.ts

@@ -101,7 +101,13 @@ export declare const AUTH_SERVER_ERROR_DETAIL: (status: number) => string;
 export declare const AUTH_UNUSABLE_DETAIL: (status: number) => string;
 /** Drop every cached token. For tests, and for a credential rotation. */
 export declare function resetTokenCache(): void;
-/** A fetch-based transport for the token endpoint. */
+/**
+ * The token endpoint, through `apiClient` per rules/security.md — no bare `fetch`.
+ *
+ * `raise_error: false` keeps the status-first contract this transport has always had: the
+ * caller distinguishes a 400 scope refusal from a 401 rejection from an unreachable host,
+ * so a thrown AxiosError on any non-2xx would destroy the only signal it reads.
+ */
 export declare function fetchTokenTransport(timeoutMs?: number): TokenTransport;
 /** The exact form body of the `client_credentials` grant. */
 export declare function mintForm(credentials: Credentials): Record<string, string>;

package/dist/tools/ask-browserstack/central-oauth.js

@@ -14,6 +14,8 @@
  * logged, returned, or put in an error message. Only a status code is.
  */
 import { createHash } from "node:crypto";
+import { apiClient } from "../../lib/apiClient.js";
+import appConfig from "../../config.js";
 import logger from "../../logger.js";
 import { AGENT_TIMEOUT_MS, AskError } from "./config.js";
 /**
@@ -157,40 +159,33 @@ function cacheKey(url, credentials) {
         .digest("hex");
     return `${url} ${credentials.username} ${CENTRAL_SCOPE} ${digest}`;
 }
-/** A fetch-based transport for the token endpoint. */
+/**
+ * The token endpoint, through `apiClient` per rules/security.md — no bare `fetch`.
+ *
+ * `raise_error: false` keeps the status-first contract this transport has always had: the
+ * caller distinguishes a 400 scope refusal from a 401 rejection from an unreachable host,
+ * so a thrown AxiosError on any non-2xx would destroy the only signal it reads.
+ */
 export function fetchTokenTransport(timeoutMs = TOKEN_TIMEOUT_MS) {
     return async (url, form) => {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), timeoutMs);
         try {
-            const response = await fetch(url, {
-                method: "POST",
+            const response = await apiClient.post({
+                url,
                 headers: {
                     "Content-Type": "application/x-www-form-urlencoded",
                     Accept: "application/json",
                 },
                 body: new URLSearchParams(form).toString(),
-                redirect: "manual",
-                signal: controller.signal,
+                timeout: timeoutMs,
+                raise_error: false,
             });
-            let parsed = null;
-            try {
-                parsed = await response.json();
-            }
-            catch {
-                // An HTML error page behind any status. The caller only reads the status.
-                parsed = null;
-            }
-            return { status: response.status, body: parsed };
+            return { status: response.status, body: response.data ?? null };
         }
         catch {
             // DNS, TLS, timeout — all of them mean "no token". The reason is deliberately not
             // carried: it can name the URL and, on some stacks, echo the request body.
             return { status: 0, body: null, error: "auth could not be reached" };
         }
-        finally {
-            clearTimeout(timer);
-        }
     };
 }
 /** The exact form body of the `client_credentials` grant. */
@@ -247,6 +242,17 @@ export async function mintCentralToken(url, credentials, transport, now = Date.n
         throw new AskError("BrowserStack AI is not authenticated: BROWSERSTACK_USERNAME and " +
             "BROWSERSTACK_ACCESS_KEY are required to sign in");
     }
+    // NOT CACHED IN HOSTED MODE. These tokens are per-user, attested credentials, and the
+    // process is shared by every tenant — `rules/multi-tenant-safety.md` forbids holding user
+    // data in module-level state there, so remote mode mints per call. Keying on
+    // username + sha256(accessKey) already means one user can never be SERVED another's token,
+    // but containment is not the contract; not holding it at all is.
+    if (appConfig.REMOTE_MCP) {
+        return mintOnce(url, credentials, transport).then(({ token }) => {
+            logger.info("askBrowserStackAI: signed in as %s", credentials.username);
+            return token;
+        });
+    }
     const key = cacheKey(url, credentials);
     const entry = cache.get(key);
     if (entry && entry.token && now < entry.expiresAt - REFRESH_SKEW_MS) {

package/dist/tools/ask-browserstack/config.d.ts

@@ -22,7 +22,13 @@ export declare const ELICITATION_TIMEOUT_MS = 270000;
 /** Thrown for anything this tool refuses to attempt. Never carries a credential. */
 export declare class AskError extends Error {
 }
-/** Off by default is wrong for a shipped feature, but a kill switch is not. */
+/**
+ * Off by default is wrong for a shipped feature, but a kill switch is not.
+ *
+ * The only setting here still read from `process.env` per call, and deliberately: a kill
+ * switch that needs a process restart is slowest exactly when it is needed fastest. The
+ * other three are on the config singleton (rules/tool-design.md).
+ */
 export declare function isEnabled(): boolean;
 /**
  * May the relay be offered in the hosted (`REMOTE_MCP`) deployment?

package/dist/tools/ask-browserstack/config.js

@@ -1,3 +1,4 @@
+import appConfig from "../../config.js";
 import logger from "../../logger.js";
 /**
  * Where Atlas lives, and the timeout ladder.
@@ -23,7 +24,13 @@ export const ELICITATION_TIMEOUT_MS = 270_000;
 /** Thrown for anything this tool refuses to attempt. Never carries a credential. */
 export class AskError extends Error {
 }
-/** Off by default is wrong for a shipped feature, but a kill switch is not. */
+/**
+ * Off by default is wrong for a shipped feature, but a kill switch is not.
+ *
+ * The only setting here still read from `process.env` per call, and deliberately: a kill
+ * switch that needs a process restart is slowest exactly when it is needed fastest. The
+ * other three are on the config singleton (rules/tool-design.md).
+ */
 export function isEnabled() {
     return (process.env.ASK_BROWSERSTACK_DISABLED || "").toLowerCase() !== "true";
 }
@@ -41,8 +48,7 @@ export function isEnabled() {
  * run. This flag only removes the blanket refusal.
  */
 export function allowRemoteRelay() {
-    return ((process.env.ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY || "").toLowerCase() ===
-        "true");
+    return appConfig.ASK_BROWSERSTACK_ALLOW_REMOTE_RELAY;
 }
 /**
  * ============================================================================
@@ -111,7 +117,7 @@ function announce(what, url, source) {
  * no selector: one default, one override.
  */
 export function atlasBaseUrl() {
-    const explicit = process.env.ASK_BROWSERSTACK_ATLAS_URL;
+    const explicit = appConfig.ASK_BROWSERSTACK_ATLAS_URL;
     const url = explicit && explicit.trim() ? trimUrl(explicit) : DEFAULT_ATLAS_URL;
     announce("Atlas", url, explicit && explicit.trim() ? "env" : "default");
     return url;
@@ -127,7 +133,7 @@ export function agentUrl() {
  * the only way in. Same two rungs as the host, and the same staging default.
  */
 export function authTokenUrl() {
-    const explicit = process.env.ASK_BROWSERSTACK_AUTH_TOKEN_URL;
+    const explicit = appConfig.ASK_BROWSERSTACK_AUTH_TOKEN_URL;
     const url = explicit && explicit.trim() ? trimUrl(explicit) : DEFAULT_AUTH_TOKEN_URL;
     announce("auth token endpoint", url, explicit && explicit.trim() ? "env" : "default");
     return url;

package/dist/tools/ask-browserstack/register.js

@@ -312,7 +312,7 @@ export function addAskBrowserStackAITool(server, deps, config) {
     tools.askBrowserStackAI = server.tool("askBrowserStackAI", DESCRIPTION, {
         product: z
             .enum(PRODUCTS)
-            .describe("Which product to work in: tm (Test Management), a11y (Accessibility), " +
+            .describe("Which product to work in: tm (Test Management), " +
             "tra (Test Reporting & Analytics)."),
         query: z
             .string()
@@ -323,6 +323,11 @@ export function addAskBrowserStackAITool(server, deps, config) {
         // sets it false: consent is not a licence to delete.
         readOnlyHint: false,
         destructiveHint: false,
+        // openWorldHint: the agent fans out to product APIs chosen at runtime, so the set of
+        // effects is not knowable from this schema. idempotentHint false because a repeated
+        // call can create a second record — the relay asks again, it does not dedupe.
+        openWorldHint: true,
+        idempotentHint: false,
         title: "Ask BrowserStack AI (Alpha)",
     }, async ({ product, query }, extra) => {
         track("askBrowserStackAI");
@@ -371,6 +376,14 @@ export function addAskBrowserStackAITool(server, deps, config) {
                 ? error.message
                 : String(error);
             logger.error("askBrowserStackAI failed: %s", message);
+            // Error telemetry, in the same never-fatal shape as the success-path `track()`:
+            // a failing tool call must not be made worse by a failing analytics call.
+            try {
+                trackMCP("askBrowserStackAI", server.server.getClientVersion(), error, config);
+            }
+            catch {
+                /* ignore */
+            }
             // No `canElicit` argument: the request never left this process, so whether the
             // client could have been prompted is not what the reader needs to know.
             return toResult(errorResult(message, approvals));

package/dist/tools/ask-browserstack/stream.js

@@ -22,6 +22,7 @@
  * is a pipe. Keeping the judgement out of the transport is why swapping A2 for A1 does
  * not risk the fail-closed behaviour.
  */
+import { apiClient } from "../../lib/apiClient.js";
 import logger from "../../logger.js";
 import { AskError } from "./config.js";
 /**
@@ -208,15 +209,16 @@ export function fetchAgentStreamTransport(timeoutMs = WHOLE_RUN_TIMEOUT_MS) {
 /** The decision POST. 30s, because it is an ordinary short request. */
 export function fetchDecisionTransport(timeoutMs = 30_000) {
     return async (url, headers, body) => {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), timeoutMs);
         try {
-            const response = await fetch(url, {
-                method: "POST",
+            // Through `apiClient` per rules/security.md. `raise_error: false` because the caller
+            // reads the STATUS: a 404 (run gone) and a 409 (already decided) are both answers,
+            // and a thrown AxiosError would collapse them into the unreachable case below.
+            const response = await apiClient.post({
+                url,
                 headers,
-                body: JSON.stringify(body),
-                redirect: "manual",
-                signal: controller.signal,
+                body,
+                timeout: timeoutMs,
+                raise_error: false,
             });
             return response.status;
         }
@@ -226,9 +228,6 @@ export function fetchDecisionTransport(timeoutMs = 30_000) {
             // the caller can say that rather than implying a human refused.
             return 0;
         }
-        finally {
-            clearTimeout(timer);
-        }
     };
 }
 /** `POST /agent/{run_id}/permission`, built from the base URL the tool already resolved. */

package/dist/tools/ask-browserstack/types.d.ts

@@ -6,7 +6,7 @@
  * different repo, at the same time. A field renamed here to read better is a field the
  * other half will never send. Nothing here changes without changing that document first.
  */
-export declare const PRODUCTS: readonly ["tm", "a11y", "tra"];
+export declare const PRODUCTS: readonly ["tm", "tra"];
 export type Product = (typeof PRODUCTS)[number];
 /** CONTRACT §2 — what Atlas emits on the run's stream when its gate needs a human. */
 export interface PermissionAsk {

package/dist/tools/ask-browserstack/types.js

@@ -6,5 +6,9 @@
  * different repo, at the same time. A field renamed here to read better is a field the
  * other half will never send. Nothing here changes without changing that document first.
  */
-export const PRODUCTS = ["tm", "a11y", "tra"];
+// a11y is deliberately ABSENT while Ask AI is in limited alpha. Atlas itself serves the
+// product; this tool just does not offer it yet. Re-adding it means this list, the `product`
+// describe text in register.ts, and the two a11y handoffs in tool-handoff.ts — which stop
+// pointing here precisely because the call would now be rejected.
+export const PRODUCTS = ["tm", "tra"];
 export const ASK_STATUSES = ["ok", "blocked", "error", "rate_limited"];

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,8 +23,33 @@
 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. */

package/dist/tools/tool-handoff.js

@@ -27,8 +27,37 @@ 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. */
@@ -36,12 +65,11 @@ export const NEEDS_SESSION_ID = " Requires a session id, which no tool here list
     "getBuildId or listBuildId; if you have neither, call askBrowserStackAI with product " +
     '"tra" and describe the run you mean.';
 /** 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-beta.3",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",