@browserstack/mcp-server 1.4.0-beta.1 → 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/server-factory.js

@@ -16,7 +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 addAskBrowserstackAITool from "./tools/ask-browserstack/register.js";
+import addAskBrowserStackAITool from "./tools/ask-browserstack/register.js";
 /**
  * Wrapper class for BrowserStack MCP Server
  * Stores a map of registered tools by name
@@ -55,7 +55,7 @@ export class BrowserStackMcpServer {
             // Hands a plain-language task to BrowserStack's agent and relays its mid-run
             // permission asks back to this client, so a write can be confirmed by the human
             // sitting in front of it rather than refused for want of anyone to ask.
-            addAskBrowserstackAITool,
+            addAskBrowserStackAITool,
         ];
         toolAdders.forEach((adder) => {
             // Each adder now returns a Record<string, Tool>

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) {
@@ -258,7 +264,7 @@ export async function mintCentralToken(url, credentials, transport, now = Date.n
     const pending = mintOnce(url, credentials, transport)
         .then(({ token, lifetimeMs }) => {
         cache.set(key, { token, expiresAt: now + lifetimeMs });
-        logger.info("askBrowserstackAI: signed in as %s (lifetime %ss)", credentials.username, Math.round(lifetimeMs / 1000));
+        logger.info("askBrowserStackAI: signed in as %s (lifetime %ss)", credentials.username, Math.round(lifetimeMs / 1000));
         return token;
     })
         .catch((error) => {

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;
 }
 /**
  * ============================================================================
@@ -98,7 +104,7 @@ function announce(what, url, source) {
     if (announced.has(line))
         return;
     announced.add(line);
-    logger.info("askBrowserstackAI: %s is %s (source: %s)", what, url, source);
+    logger.info("askBrowserStackAI: %s is %s (source: %s)", what, url, source);
 }
 /**
  * Resolve Atlas's base URL:
@@ -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.d.ts

@@ -1,5 +1,5 @@
 /**
- * `askBrowserstackAI` — one tool call in, one tool result out, with a human's approval
+ * `askBrowserStackAI` — one tool call in, one tool result out, with a human's approval
  * relayed through the middle of it.
  *
  * The shape, and why:
@@ -55,7 +55,7 @@ export interface AskDeps {
     decisionTransport?: DecisionTransport;
 }
 export declare function relayMode(server: McpServer): RelayMode;
-export declare function addAskBrowserstackAITool(server: McpServer, deps: AskDeps, config?: BrowserStackConfig): Record<string, RegisteredTool>;
+export declare function addAskBrowserStackAITool(server: McpServer, deps: AskDeps, config?: BrowserStackConfig): Record<string, RegisteredTool>;
 /** The tool-adder the server factory calls. */
-export declare function addAskBrowserstackAIToolFromConfig(server: McpServer, config: BrowserStackConfig): Record<string, RegisteredTool>;
-export default addAskBrowserstackAIToolFromConfig;
+export declare function addAskBrowserStackAIToolFromConfig(server: McpServer, config: BrowserStackConfig): Record<string, RegisteredTool>;
+export default addAskBrowserStackAIToolFromConfig;

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

@@ -1,5 +1,5 @@
 /**
- * `askBrowserstackAI` — one tool call in, one tool result out, with a human's approval
+ * `askBrowserStackAI` — one tool call in, one tool result out, with a human's approval
  * relayed through the middle of it.
  *
  * The shape, and why:
@@ -47,7 +47,16 @@ import { PRODUCTS, } from "./types.js";
  * words alone, before any call is made — so the ordering is deliberate: when to reach for it
  * first, what it does second, and the consent behaviour last.
  */
-const DESCRIPTION = "Use this when no other BrowserStack tool here fits the task, or when the ones you tried " +
+const DESCRIPTION = 
+// Alpha status leads, deliberately. The model reads this before deciding to call, and a
+// tool that is not enabled for the account cannot do the job at all — so "there is a
+// per-account gate, fall back to the individual tools" is the most useful thing to say
+// first. Parenthesised so it reads as a status note, not as the tool's purpose.
+"(Alpha, limited availability. Enabled per account and per product; if it is not enabled " +
+    "the call returns an entitlement error, nothing runs, and you should complete the task " +
+    "with the individual tools instead. To request access, the user should contact their " +
+    "BrowserStack account owner.) " +
+    "Use this when no other BrowserStack tool here fits the task, or when the ones you tried " +
     "did not get you there. Prefer a specific tool whenever one fits: it is faster and more " +
     "predictable than handing the job to an agent. " +
     "Otherwise, describe what you want in plain language and BrowserStack's agent decides " +
@@ -147,7 +156,7 @@ async function relayOneAsk(server, ask, approvals, relatedRequestId) {
     // The SHAPE of the answer only — a fixed action enum and a boolean, never the description
     // or anything a user typed. Logged so that what a client actually submits can be read next
     // time rather than inferred from a compiled binary.
-    logger.info("askBrowserstackAI: elicitation answered %s", elicitationShape(answer));
+    logger.info("askBrowserStackAI: elicitation answered %s", elicitationShape(answer));
     const { decision, reason } = decide(answer);
     approvals.push({ description: ask.description, decision, reason });
     return { perm_id: ask.perm_id, decision, reason };
@@ -224,14 +233,14 @@ async function runStreamed(server, streamTransport, decisionTransport, url, head
         // description cannot produce an answerable prompt, so it must not produce a prompt.
         const ask = parseAsk(event.data);
         if (!ask) {
-            logger.error("askBrowserstackAI: unusable permission ask on the stream; ignoring");
+            logger.error("askBrowserStackAI: unusable permission ask on the stream; ignoring");
             continue;
         }
         if (!runId) {
             // Atlas emits `run` before any ask precisely so this cannot happen. If it does,
             // there is nowhere to send a decision — so do not prompt a human for an answer
             // that could never be delivered.
-            logger.error("askBrowserstackAI: permission ask arrived before run_id; cannot answer");
+            logger.error("askBrowserStackAI: permission ask arrived before run_id; cannot answer");
             continue;
         }
         // `relayOneAsk` RETHROWS on an unexpected elicitation failure. Under A2 that was
@@ -246,7 +255,7 @@ async function runStreamed(server, streamTransport, decisionTransport, url, head
             decision = await relayOneAsk(server, ask, approvals, relatedRequestId);
         }
         catch (error) {
-            logger.warn("askBrowserstackAI: elicitation failed, denying explicitly: %s", error instanceof Error ? error.message : String(error));
+            logger.warn("askBrowserStackAI: elicitation failed, denying explicitly: %s", error instanceof Error ? error.message : String(error));
             decision = { perm_id: ask.perm_id, decision: "deny", reason: "error" };
         }
         const status = await decisionTransport(decisionUrl(url, runId), headers, {
@@ -259,7 +268,7 @@ async function runStreamed(server, streamTransport, decisionTransport, url, head
             // own expiry, so a lost decision is safe — it can only cost an approval, never
             // grant one. Retrying risks the opposite: a duplicate that 409s, or worse, an
             // approval applied to a step the run has already moved past.
-            logger.warn("askBrowserstackAI: decision for %s was not accepted (HTTP %s)", decision.perm_id, status);
+            logger.warn("askBrowserStackAI: decision for %s was not accepted (HTTP %s)", decision.perm_id, status);
         }
     }
     if (!sawResult) {
@@ -283,7 +292,7 @@ export function relayMode(server) {
         ? "offered"
         : "no_human";
 }
-export function addAskBrowserstackAITool(server, deps, config) {
+export function addAskBrowserStackAITool(server, deps, config) {
     // A1 (CONTRACT v2) is the only path; A2 is gone. No version flag is needed to talk to
     // an Atlas that predates the stream: such a server answers `POST /agent` with ordinary
     // JSON, the parser sees no `text/event-stream`, and the run degrades to a read-only
@@ -300,10 +309,10 @@ export function addAskBrowserstackAITool(server, deps, config) {
             // Telemetry must not decide whether a tool call succeeds.
         }
     };
-    tools.askBrowserstackAI = server.tool("askBrowserstackAI", DESCRIPTION, {
+    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()
@@ -314,9 +323,14 @@ export function addAskBrowserstackAITool(server, deps, config) {
         // sets it false: consent is not a licence to delete.
         readOnlyHint: false,
         destructiveHint: false,
-        title: "Ask BrowserStack AI",
+        // 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");
+        track("askBrowserStackAI");
         const approvals = [];
         // Negotiated before anything else so the failure paths below report the mode they
         // would have run in.
@@ -347,7 +361,7 @@ export function addAskBrowserstackAITool(server, deps, config) {
             else {
                 // Omitted ENTIRELY, not sent empty: its absence is what selects Atlas's
                 // read-only HeadlessGate.
-                logger.info("askBrowserstackAI: no permission relay (%s); running read-only", mode);
+                logger.info("askBrowserStackAI: no permission relay (%s); running read-only", mode);
             }
             // `product` reaches the result so an entitlement refusal can name it: the flags
             // are per product, and a bare "not enabled" sends the user to their admin
@@ -361,7 +375,15 @@ export function addAskBrowserstackAITool(server, deps, config) {
             const message = error instanceof AskError || error instanceof Error
                 ? error.message
                 : String(error);
-            logger.error("askBrowserstackAI failed: %s", message);
+            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));
@@ -373,9 +395,9 @@ export function addAskBrowserstackAITool(server, deps, config) {
     return tools;
 }
 /** The tool-adder the server factory calls. */
-export function addAskBrowserstackAIToolFromConfig(server, config) {
+export function addAskBrowserStackAIToolFromConfig(server, config) {
     if (!isEnabled()) {
-        logger.info("askBrowserstackAI disabled by ASK_BROWSERSTACK_DISABLED");
+        logger.info("askBrowserStackAI disabled by ASK_BROWSERSTACK_DISABLED");
         return {};
     }
     const credentials = () => ({
@@ -383,7 +405,7 @@ export function addAskBrowserstackAIToolFromConfig(server, config) {
         accessKey: config["browserstack-access-key"],
     });
     const tokenTransport = fetchTokenTransport();
-    return addAskBrowserstackAITool(server, {
+    return addAskBrowserStackAITool(server, {
         // Both resolved per call. An unconfigured host surfaces as a named error from the
         // tool rather than as a missing tool, so the cause is visible to whoever hits it.
         agentUrl,
@@ -391,4 +413,4 @@ export function addAskBrowserstackAIToolFromConfig(server, config) {
         credentialsFor: credentials,
     }, config);
 }
-export default addAskBrowserstackAIToolFromConfig;
+export default addAskBrowserStackAIToolFromConfig;

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

@@ -58,10 +58,11 @@ export const RELAY_OFF_DETAILS = {
     // Not a refusal by anyone and not a relay problem at all: the account is not on the
     // product's agent flag. The product-specific sentence and what to do about it live in
     // `error`, so this one points there rather than duplicating the plumbing.
-    not_entitled: "NOBODY DECLINED THIS AND NOTHING RAN. BrowserStack AI is not enabled for this account, " +
-        "so the request was refused before the agent started. `error` says which product and " +
-        "what to do about it. This is an entitlement on the account, not a problem with your " +
-        "credentials and not a decision anyone made about your request.",
+    not_entitled: "NOBODY DECLINED THIS AND NOTHING RAN. Ask AI (Alpha) is not enabled on this account. " +
+        "Ask AI is in limited alpha and available only to enrolled accounts, so the request was " +
+        "refused before the agent started. `error` names the product. This is an entitlement on " +
+        "the account, not a problem with your credentials and not a decision anyone made about " +
+        "your request.",
     // The request never got as far as the agent. Distinct from `disabled` (the agent ran, with
     // the relay switched off) and from a decline (someone was asked and said no), because the
     // three call for completely different things from whoever reads them.
@@ -137,9 +138,10 @@ export function isNotEntitled(response) {
  */
 export const NOT_ENTITLED_DETAIL = (product) => {
     const scope = product && product.trim() ? ` for \`${product.trim()}\`` : "";
-    return (`BrowserStack AI is not enabled${scope} on your account. Please contact your admin. ` +
-        `YOUR CREDENTIALS ARE FINE — they authenticated successfully; this is a per-product ` +
-        `entitlement on the account. Nothing was run and nobody declined anything.`);
+    return (`Ask AI (Alpha) is not enabled${scope} on this account. Ask AI is in limited alpha and ` +
+        `available only to enrolled accounts. Authentication succeeded and nothing was run. ` +
+        `To request access, contact your BrowserStack account owner, or reach out at ` +
+        `https://www.browserstack.com/contact-sales`);
 };
 export function neverReachedAgent(response) {
     // No response at all: nothing could have run.

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";
 /**
@@ -120,7 +121,7 @@ export function parseFrame(frame) {
         // A frame we cannot read is not a frame we may guess at. Dropping it is safe
         // because the only consequence is that an ask goes unanswered and the gate denies
         // on its own expiry — never that something is approved.
-        logger.warn("askBrowserstackAI: unparseable stream frame, ignoring");
+        logger.warn("askBrowserStackAI: unparseable stream frame, ignoring");
         return null;
     }
 }
@@ -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

@@ -8,7 +8,7 @@
  * where the missing identifier comes from.
  *
  * Point at a sibling tool whenever one can produce the id — it is faster and more
- * predictable than an agent. Point at `askBrowserstackAI` only when NO tool here can.
+ * predictable than an agent. Point at `askBrowserStackAI` only when NO tool here can.
  *
  * The one that matters most: 15 of the 17 Test Management tools require a project
  * identifier and NONE of them accepts its absence, yet no tool in this server lists
@@ -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

@@ -8,7 +8,7 @@
  * where the missing identifier comes from.
  *
  * Point at a sibling tool whenever one can produce the id — it is faster and more
- * predictable than an agent. Point at `askBrowserstackAI` only when NO tool here can.
+ * predictable than an agent. Point at `askBrowserStackAI` only when NO tool here can.
  *
  * The one that matters most: 15 of the 17 Test Management tools require a project
  * identifier and NONE of them accepts its absence, yet no tool in this server lists
@@ -21,27 +21,55 @@
  */
 /** No tool lists projects, so this genuinely has to go to the agent. */
 export const NEEDS_PROJECT_ID = " Requires a project identifier (PR-*). No tool here lists projects, so if you do not " +
-    'have one, call askBrowserstackAI with product "tm" and ask which projects exist, then ' +
+    'have one, call askBrowserStackAI with product "tm" and ask which projects exist, then ' +
     "retry this tool with the identifier it returns.";
 /** A sibling tool can produce the id — prefer it over the agent. */
 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 " +
+    "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.1",
+  "version": "1.4.0-beta.3",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",