@browserstack/mcp-server 2.2.3 → 2.3.0-beta.2

package/dist/tools/capability-registry/index-loader.js

@@ -6,12 +6,23 @@
  * lets searchCapability rank across products from N single-product files.
  */
 import { readFileSync } from "node:fs";
+import appConfig from "../../config.js";
 import { basename, dirname } from "node:path";
 import { ENVELOPE_KEYS, SUPPORTED_SCHEMA_VERSION, } from "./types.js";
 export class IndexError extends Error {
 }
 /** Thrown to the caller as a tool error, so the wording is caller-facing. */
 export class InvocationError extends Error {
+    /**
+     * Set when the handle exists in the artifact but this surface withholds it.
+     *
+     * The MESSAGE deliberately does not say so — a caller is told the capability does not
+     * exist, because "withheld" invites a retry, a search for synonyms, or a question to the
+     * user about enabling it, none of which can succeed here. The flag keeps the distinction
+     * for telemetry, where knowing how often a withheld handle is reached for is how we learn
+     * whether withholding it was the right call.
+     */
+    withheld;
 }
 /** The file inside a product subdirectory, for the earlier nested layout. */
 export const INDEX_FILE = "index.json";
@@ -43,9 +54,59 @@ export function endpointKey(method, path) {
  * FAILS CLOSED: any truthy `disabled` hides it, not just `=== true`. The flag exists to
  * suppress something that cannot work, so an unexpected shape must hide it rather than be
  * ignored — the opposite default would turn a typo into a silently re-enabled capability.
+ *
+ * `local_only` withholds on a remote server only, for a capability that reads the caller's
+ * own machine: there, the path it would take resolves against the operator's disk instead.
+ * Read at call time rather than captured, because the remote server builds its config per
+ * session and a value captured at module load would outlive the deployment it described.
  */
 export function isDisabled(capability) {
-    return Boolean(capability.disabled);
+    if (capability.disabled)
+        return true;
+    return Boolean(capability.local_only) && Boolean(appConfig.REMOTE_MCP);
+}
+/**
+ * Is this capability published for reference only on this surface?
+ *
+ * `local_only` on a remote server. The capability is real and the caller may well be asking
+ * for exactly it, so hiding it leaves the agent concluding no such route exists. Publishing
+ * it without the means to call it, and with a note saying what to do instead, answers the
+ * question it was asked.
+ */
+export function isReferenceOnly(capability) {
+    if (capability.disabled)
+        return false;
+    return Boolean(capability.local_only) && Boolean(appConfig.REMOTE_MCP);
+}
+/**
+ * The reference form: what it is and what to do instead, and nothing to call it with.
+ *
+ * The parameters and response shapes go because publishing them invites the attempt — a
+ * model handed a body schema will fill it in. `intent` stays, because that is what the
+ * search matched on, and `mode` stays so a reader can still see what kind of operation it
+ * would have been.
+ */
+function asReference(capability) {
+    const reference = { ...capability };
+    for (const field of [
+        "path_params",
+        "query",
+        "body",
+        "responses",
+        "returns",
+        "paginated",
+        "max_page_size",
+        "encoding",
+    ]) {
+        delete reference[field];
+    }
+    return {
+        ...reference,
+        invocable: false,
+        guidance: capability.unavailable_note
+            ? [capability.unavailable_note]
+            : ["This capability cannot be called on this server."],
+    };
 }
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -181,6 +242,16 @@ export class CapabilityRegistry {
                 // between a disabled name and a live one is still a broken artifact, and skipping
                 // the disabled half would mean re-enabling the flag could fail the load later,
                 // somewhere with less context than here.
+                if (isReferenceOnly(capability)) {
+                    // PUBLISHED, BUT NOT CALLABLE. It keeps its name and intent so the search that
+                    // should find it does, and loses everything a caller would need to invoke it.
+                    const reference = asReference(capability);
+                    enabled.push(reference);
+                    lookup.set(endpointKey(capability.method, capability.path), reference);
+                    if (capability.name)
+                        names.set(capability.name, reference);
+                    continue;
+                }
                 if (isDisabled(capability)) {
                     withheld.set(endpointKey(capability.method, capability.path), capability);
                     if (capability.name)
@@ -219,26 +290,25 @@ export class CapabilityRegistry {
         this.index = { ...index, products };
     }
     /**
-     * The `capability_disabled` message for a handle this build withholds, if it is one.
+     * Does this build withhold the handle?
      *
-     * Says THAT it is disabled and nothing about why. The reason is documentation and lives
-     * with the decision; repeating it here would put four copies of a paragraph in the
-     * shipped artifact to serve a path the flag itself makes rare.
+     * WHAT THE CALLER IS TOLD IS THAT IT DOES NOT EXIST, which is why this returns a boolean
+     * rather than a message. Saying "withheld" describes the artifact rather than the
+     * surface, and every action it invites — retry, hunt for a synonym, ask the user to turn
+     * it on — fails here. A capability absent from search, describe and every listing should
+     * read the same way at invocation as it does everywhere else.
      *
-     * Returns undefined for anything else, so the caller falls through to its own
-     * not-found wording.
+     * The caller raises its own not-found error and marks it `withheld`, so the distinction
+     * survives in telemetry without reaching the agent.
      */
-    withheldMatch(handle, product) {
+    isWithheld(handle, product) {
         for (const [owner, withheld] of this.withheld) {
             if (product && owner !== product)
                 continue;
-            if (!withheld.has(handle))
-                continue;
-            return (`capability_disabled: ${handle} is disabled on this surface. This is ` +
-                `deliberate — it is withheld by the ${owner} index, not missing from it — so ` +
-                `retrying will not help.`);
+            if (withheld.has(handle))
+                return true;
         }
-        return undefined;
+        return false;
     }
     /** How many capabilities each product withholds. Startup logging only. */
     disabledCounts() {
@@ -326,13 +396,13 @@ export class CapabilityRegistry {
                 matches.push({ product: owner, capability });
         }
         if (matches.length === 0) {
-            // WITHHELD IS A DIFFERENT ANSWER FROM ABSENT, and only here. Search cannot surface a
-            // disabled capability, so reaching this branch means the caller already held the
-            // exact handle — from an older index, a doc, or a human. "unknown_capability" would
-            // send it hunting for a synonym that does not exist; the reason ends the attempt.
-            const off = this.withheldMatch(name, product);
-            if (off)
-                throw new InvocationError(off);
+            // A WITHHELD HANDLE ANSWERS THE SAME WAY AS AN ABSENT ONE. Search, describe and the
+            // listings already behave as though it does not exist, and invocation is no place to
+            // contradict them: "withheld" is a fact about the artifact, not about this surface,
+            // and it invites a retry, a hunt for a synonym, or a question to the user about
+            // enabling something that cannot be enabled here. The error carries `withheld` so the
+            // attempt is still countable in telemetry.
+            const withheldHere = this.isWithheld(name, product);
             // Say whether names are published at all for the product asked about: "no such name"
             // and "this product does not name its capabilities" need different fixes.
             const unnamed = [...this.byName]
@@ -342,7 +412,10 @@ export class CapabilityRegistry {
                 ? ` ${unnamed.sort().join(", ")} ${unnamed.length > 1 ? "publish" : "publishes"} ` +
                     `no capability names yet — call those by \`method\` and \`path\` instead.`
                 : " Search again — names come from searchCapability and describeEntity.";
-            throw new InvocationError(`unknown_capability: ${name}.${hint}`);
+            const error = new InvocationError(`unknown_capability: ${name}.${hint}`);
+            if (withheldHere)
+                error.withheld = true;
+            throw error;
         }
         if (matches.length > 1 && !product) {
             const owners = matches
@@ -371,11 +444,11 @@ export class CapabilityRegistry {
                 matches.push({ product: name, capability });
         }
         if (matches.length === 0) {
-            const off = this.withheldMatch(key, product);
-            if (off)
-                throw new InvocationError(off);
-            throw new InvocationError(`unknown_endpoint: ${key}. Search again — send \`method\` and \`path\` exactly as ` +
+            const error = new InvocationError(`unknown_endpoint: ${key}. Search again — send \`method\` and \`path\` exactly as ` +
                 `searchCapability returned them, placeholders included.`);
+            if (this.isWithheld(key, product))
+                error.withheld = true;
+            throw error;
         }
         if (matches.length > 1 && !product) {
             const owners = matches

package/dist/tools/capability-registry/register.d.ts

@@ -32,7 +32,7 @@ export interface RegistryDeps {
      * Per-product base URL. Never baked into the artifact — it is environment AND account
      * specific: tm is region-sharded, so this is resolved per call, not once at startup.
      */
-    baseUrlFor: (product: string) => Promise<string>;
+    baseUrlFor: (product: string, host?: string) => Promise<string>;
     credentialsFor: () => Credentials;
     transport?: Transport;
 }

package/dist/tools/capability-registry/register.js

@@ -81,7 +81,7 @@ export function addCapabilityRegistryToolsFromConfig(server, config) {
         registry,
         // The whole product bundle, not just its host: a region-sharded product declares
         // several candidates and the probe needs an endpoint from its own capabilities.
-        baseUrlFor: (product) => resolveBaseUrl(product, config, registry.index.products[product]),
+        baseUrlFor: (product, host) => resolveBaseUrl(product, config, registry.index.products[product], undefined, host),
         // Read per call, not captured: the remote server rebuilds config per session, so a
         // captured credential would outlive the session it belongs to.
         credentialsFor: () => ({
@@ -147,7 +147,12 @@ export function addCapabilityRegistryTools(server, deps, config) {
      * below pin each branch against the message its source actually produces; if you reword
      * a refusal, one of them will tell you.
      */
-    const invocationReason = (message) => {
+    const invocationReason = (message, error) => {
+        // A WITHHELD HANDLE IS REPORTED TO THE CALLER AS NOT FOUND, so the message cannot be
+        // what distinguishes it. The flag on the error can, which keeps the refusal countable
+        // without the wording admitting the capability exists.
+        if (error instanceof InvocationError && error.withheld)
+            return "capability_disabled";
         if (message.startsWith("unknown_capability:"))
             return "unknown_capability";
         if (message.startsWith("unknown_endpoint:"))
@@ -812,7 +817,7 @@ export function addCapabilityRegistryTools(server, deps, config) {
         }
         catch (error) {
             if (error instanceof InvocationError)
-                return refuse("describeCapability", invocationReason(error.message), error.message, undefined, identity);
+                return refuse("describeCapability", invocationReason(error.message, error), error.message, undefined, identity);
             logger.error("describeCapability failed: %s", error instanceof Error ? error.message : String(error));
             return refuse("describeCapability", "unexpected_error", "that capability could not be described", undefined, identity);
         }
@@ -910,6 +915,17 @@ export function addCapabilityRegistryTools(server, deps, config) {
                 query: input.query,
                 body: input.body,
             };
+            if (capability.invocable === false) {
+                // THE ONE PLACE describe AND invoke DIVERGE, deliberately. Everywhere else a name
+                // that describes is a name that invokes, and breaking that is its own bug class —
+                // but a reference-only capability exists precisely to be read and not called. The
+                // refusal carries the instruction, because the note is the whole point of it
+                // still being published.
+                return refuse("invokeCapability", "capability_not_invocable", `${handle} cannot be called on this server. ` +
+                    (capability.guidance?.[0] ??
+                        "Describe it for what to do instead.") +
+                    " Follow that instead of retrying.", undefined, identity);
+            }
             if (capability.mode === "destructive") {
                 // Refused before binding, so consent is never sought for something that cannot run.
                 return refuse("invokeCapability", "destructive_blocked", `${handle} is a destructive operation and is not available through this surface`, undefined, identity);
@@ -932,7 +948,7 @@ export function addCapabilityRegistryTools(server, deps, config) {
                     return refuse("invokeCapability", "change_summary_missing", "change_summary is required: state what will change", undefined, identity);
                 }
             }
-            const result = await invoke(capability, args, await deps.baseUrlFor(product), deps.credentialsFor(), transport, registry.index.products[product]?.auth, product);
+            const result = await invoke(capability, args, await deps.baseUrlFor(product, capability.host), deps.credentialsFor(), transport, registry.index.products[product]?.auth, product);
             // The one row for a completed invoke. invoke() returns a 4xx/5xx rather than
             // throwing, so `success` keeps its tool-level meaning and these two fields carry
             // whether the product call worked. Status 0 means it could not be reached.
@@ -946,7 +962,7 @@ export function addCapabilityRegistryTools(server, deps, config) {
         }
         catch (error) {
             if (error instanceof InvocationError)
-                return refuse("invokeCapability", invocationReason(error.message), error.message, undefined, identity);
+                return refuse("invokeCapability", invocationReason(error.message, error), error.message, undefined, identity);
             logger.error("invokeCapability failed: %s", error instanceof Error ? error.message : String(error));
             return refuse("invokeCapability", "unexpected_error", "that capability could not be invoked", undefined, identity);
         }

package/dist/tools/capability-registry/resolve.js

@@ -16,6 +16,8 @@ import { invalidateToken } from "../../lib/central-oauth.js";
 import { bind } from "./bind.js";
 import { authHeaders } from "./egress.js";
 import { resolveScope, resolveTokenUrl } from "./oauth.js";
+import { openAsBlob } from "node:fs";
+import { basename } from "node:path";
 import { InvocationError } from "./index-loader.js";
 function hasNextPage(body) {
     if (typeof body !== "object" || body === null || Array.isArray(body))
@@ -63,6 +65,30 @@ function assertTransportSafe(baseUrl) {
         `carries your BrowserStack access key, so the base URL must be https (or a local ` +
         `host for development). Check CAPABILITY_REGISTRY_BASE_URL_* for a typo.`);
 }
+/**
+ * Turn a bound body into a FormData, streaming any `file` parameter from disk.
+ *
+ * `bind` has already canonicalised and checked the path, so what arrives here is a file
+ * this server is configured to read. The blob is opened rather than buffered: an app build
+ * runs to gigabytes and reading one into memory to post it is how a server falls over.
+ */
+async function multipartBody(capability, body) {
+    const form = new FormData();
+    for (const param of capability.body || []) {
+        const value = body?.[param.name];
+        if (value === undefined || value === null)
+            continue;
+        if (param.type === "file") {
+            const path = String(value);
+            const blob = await openAsBlob(path);
+            form.append(param.name, blob, basename(path));
+        }
+        else {
+            form.append(param.name, String(value));
+        }
+    }
+    return form;
+}
 export async function invoke(capability, args, baseUrl, credentials, transport, auth, product) {
     if (!baseUrl)
         throw new InvocationError("no base URL is configured for that product");
@@ -71,7 +97,22 @@ export async function invoke(capability, args, baseUrl, credentials, transport,
     // Before binding would be wrong and after sending is too late: a scheme that mints a
     // token must not spend a round trip on a call that `bind` was going to reject anyway.
     const url = `${baseUrl.replace(/\/$/, "")}${bound.path}`;
-    const send = async () => transport(capability.method, url, await authHeaders(credentials, auth, product), bound.query, bound.body);
+    const multipart = capability.encoding === "multipart"
+        ? await multipartBody(capability, bound.body)
+        : undefined;
+    const send = async () => {
+        const headers = await authHeaders(credentials, auth, product);
+        if (multipart) {
+            // fetch writes its own Content-Type with the boundary. Leaving the JSON one on sends
+            // a body the product cannot parse, under a header that says it should be able to.
+            delete headers["Content-Type"];
+        }
+        const payload = multipart ??
+            (bound.body === undefined && capability.send_empty_body
+                ? {}
+                : bound.body);
+        return transport(capability.method, url, headers, bound.query, payload);
+    };
     let response = await send();
     /**
      * One replay, for a minted token the product rejected.

package/dist/tools/capability-registry/types.d.ts

@@ -116,6 +116,23 @@ export interface Capability {
     name?: string;
     method: string;
     path: string;
+    /**
+     * Which of the product's named `hosts` serves this one capability, when it is not the
+     * product's own `base_url`.
+     *
+     * A product is normally one host. App Automate is not: the account-level API (devices,
+     * app builds, plan, session records) answers on one origin and the Appium hub that
+     * drives the device answers on another, and neither serves the other's paths. Splitting
+     * them into two products would split one entity too — the session a hub capability
+     * creates is the session the account-level API reports on — and a caller holding the id
+     * would have to know it had changed products to use it.
+     *
+     * Unset means the product's own host, so every existing index is unaffected. A name that
+     * `hosts` does not define is refused by name at invocation rather than quietly falling
+     * back, because the fallback would send the call to a host that cannot serve the path and
+     * return a 404 that reads like the caller's mistake.
+     */
+    host?: string;
     mode: Mode;
     entity: string;
     path_params?: WireParam[];
@@ -155,6 +172,63 @@ export interface Capability {
      * suppression must not be ignored for arriving in an unexpected shape.
      */
     disabled?: boolean;
+    /**
+     * Withheld when the server is not running on the caller's own machine.
+     *
+     * Some capabilities only mean anything when the person and the process share a computer:
+     * one that reads a file the caller names is the clear case. On a remote server that path
+     * resolves against the OPERATOR's disk, so honouring it would read one user's files on
+     * another's behalf — the capability does not become unreliable there, it becomes wrong.
+     *
+     * Distinct from `disabled`, which withholds a capability everywhere. This one is a claim
+     * about where it can run, so the same artifact serves both deployments: a local server
+     * publishes it and a remote one does not.
+     *
+     * FAILS CLOSED in the same way, and takes the same `capability_disabled` path at
+     * invocation, so a caller holding the handle is told the absence is deliberate rather
+     * than hunting for a synonym.
+     */
+    local_only?: boolean;
+    /**
+     * What to do instead, on a surface where this capability cannot run.
+     *
+     * A `local_only` capability is NOT hidden on a remote server: the query that should find
+     * it still finds it, because an agent asked to upload a file from the user's machine
+     * needs to learn that the route exists and what replaces it here. What it loses is the
+     * means to call it — the parameters and response shapes are stripped at load, and
+     * invocation is refused — so the note is the whole of what remains.
+     *
+     * Write it as the instruction the caller should follow, not as an apology.
+     */
+    unavailable_note?: string;
+    /**
+     * FALSE when this build publishes the capability for reference but will not call it.
+     *
+     * Set by the loader, never authored: it is the surface's answer, not the artifact's.
+     */
+    invocable?: boolean;
+    /**
+     * How the request body is encoded. Absent means JSON, which is every capability today.
+     *
+     * `multipart` exists for endpoints that take the bytes of a file rather than a reference
+     * to one. A capability declaring it must also declare a `file` parameter, and should be
+     * `local_only`: the path names the caller's own machine.
+     */
+    encoding?: "multipart";
+    /**
+     * Send `{}` rather than no body at all, for an endpoint that takes no parameters.
+     *
+     * Normally a capability with nothing to send sends nothing, which is right for a REST API
+     * and wrong for W3C WebDriver: Chrome answers 400 "invalid argument" to a parameterless
+     * POST with the body omitted and 200 to the same call carrying `{}`. Appium tolerates the
+     * omission, which is why the identical capability needs this on Automate and not on App
+     * Automate.
+     *
+     * Opt-in per capability rather than a rule for every bodyless POST, because 27 of those
+     * exist across the shipped indexes and changing what reaches their products is not
+     * something this can verify.
+     */
+    send_empty_body?: boolean;
     paginated?: boolean;
     /** The largest page the operation declares. */
     max_page_size?: number;
@@ -313,6 +387,18 @@ export interface ProductIndex {
      * (see `discovery.probePath`); declare it when the derived choice would be wrong.
      */
     probe_path?: string;
+    /**
+     * Additional hosts this product is served from, by name, for capabilities that declare
+     * `host`.
+     *
+     * DISTINCT FROM `base_urls`, which is a list of CANDIDATES for one host — probed in turn
+     * so a region-sharded product lands on the account's own region. These are several hosts
+     * that all serve the product at once, each addressing a different part of it, and the
+     * capability says which it needs rather than the server discovering it.
+     *
+     * `base_url` remains the default for every capability that names no host.
+     */
+    hosts?: Record<string, string>;
     capabilities: Capability[];
     entities: Record<string, EntityDoc>;
     paging?: Record<string, PagingRule>;

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

@@ -1,6 +1,6 @@
 import { apiClient } from "../../lib/apiClient.js";
 import { z } from "zod";
-import { errorText } from "../../lib/error.js";
+import { formatAxiosError } from "../../lib/error.js";
 import { fetchFormFields, normalizeDefaultFields as normalizeDefaultFieldsFromForm, projectIdentifierToId, } from "./TCG-utils/api.js";
 import { getTMBaseURL } from "../../lib/tm-base-url.js";
 import { getBrowserStackAuth } from "../../lib/get-auth.js";
@@ -218,14 +218,12 @@ Error details: ${JSON.stringify(err.response?.data || err.message)}`,
                 isError: true,
             };
         }
-        const status = err.response?.status;
-        const detail = errorText(err, "unknown error");
-        const hint = status === 401 ? " Check the BrowserStack credentials in use." : "";
+        const errorMessage = formatAxiosError(err, "Failed to update test case");
         return {
             content: [
                 {
                     type: "text",
-                    text: `Failed to update test case${status ? ` (HTTP ${status})` : ""}: ${detail}.${hint}`,
+                    text: `Failed to update test case: ${errorMessage}. Please verify your credentials and try again.`,
                 },
             ],
             isError: true,

package/package.json

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