@browserstack/mcp-server 2.3.0-beta.5 → 2.3.0-beta.6

package/dist/tools/applive.js

@@ -3,6 +3,7 @@ import fs from "fs";
 import { startSession } from "./applive-utils/start-session.js";
 import logger from "../logger.js";
 import { trackMCP } from "../lib/instrumentation.js";
+import { isEnabled as capabilityRegistryEnabled } from "./capability-registry/config.js";
 /**
  * Launches an App Live Session on BrowserStack.
  */
@@ -54,7 +55,15 @@ export async function startAppLiveSession(args, config) {
 }
 export default function addAppLiveTools(server, config) {
     const tools = {};
-    tools.runAppLiveSession = server.tool("runAppLiveSession", "Use this tool when user wants to manually check their app on a particular mobile device using BrowserStack's cloud infrastructure. Can be used to debug crashes, slow performance, etc.", {
+    // A Live session is for a PERSON. The agent cannot tap, type, read the screen or take a
+    // screenshot in it, and every eval where an agent was asked to operate an app and chose
+    // this tool ended with "my tools can start it but can't tap anything in it". The
+    // description says so, and names the surface that can — only when that surface is on.
+    const description = "Open a manual App Live session for the user to operate by hand. It cannot be driven by the agent." +
+        (capabilityRegistryEnabled()
+            ? " To tap, type or read the app yourself, use a mobiledevicecontrol session via invokeCapability."
+            : "");
+    tools.runAppLiveSession = server.tool("runAppLiveSession", description, {
         desiredPhone: z
             .string()
             .describe("The full name of the device to run the app on. Example: 'iPhone 12 Pro' or 'Samsung Galaxy S20' or 'Google Pixel 6'. Always ask the user for the device they want to use, do not assume it. "),

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

@@ -0,0 +1,40 @@
+/**
+ * Try the next thing when the product refuses, as the index says to.
+ *
+ * ONE REQUEST, ONE RESPONSE is still the rule for every capability that declares nothing
+ * here. A `fallbacks` list is the one authored exception: when THIS call answers a given
+ * status, the index knows a sibling capability that may do the job, and names it with the
+ * body to send. The chain exists for hide_keyboard on an iPhone, where the plain call
+ * answers 400 because the keyboard has no dismiss key, and the only way on is to press one
+ * of its own keys — Done where it exists, Return where it does not.
+ *
+ * The caller's consent covers the chain: it was given for the capability invoked, and the
+ * chain is that capability's published contract. What a step may do — press Return, which
+ * an app may treat as submit — is therefore the capability's guidance to state, not
+ * something this module decides. It does refuse two things no guidance could make right: a
+ * step naming a destructive capability, and one naming a capability this surface will not
+ * call.
+ *
+ * Every attempt is reported, in order, with the status it got, so the caller knows which
+ * step did the work and can read the screen back afterwards.
+ */
+import { GroupedArguments } from "./bind.js";
+import { InvokeResult } from "./resolve.js";
+import { Capability } from "./types.js";
+export interface Attempt {
+    capability: string;
+    status: number;
+    /** The authored body the step sent, so the caller can see which keys were tried. */
+    body?: Record<string, unknown>;
+}
+export interface FallbackOutcome {
+    /** The last response: the first 2xx, or the final refusal. */
+    result: InvokeResult;
+    /** Present only when the chain ran; the first entry is the original call. */
+    attempts?: Attempt[];
+}
+/** Makes one request for one capability — `invoke`, with the deps already bound. */
+export type Runner = (capability: Capability, args: GroupedArguments) => Promise<InvokeResult>;
+/** Resolves a step's name within the product of the capability being invoked. */
+export type Lookup = (name: string) => Capability;
+export declare function invokeWithFallbacks(capability: Capability, args: GroupedArguments, run: Runner, lookup: Lookup): Promise<FallbackOutcome>;

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

@@ -0,0 +1,61 @@
+/**
+ * Try the next thing when the product refuses, as the index says to.
+ *
+ * ONE REQUEST, ONE RESPONSE is still the rule for every capability that declares nothing
+ * here. A `fallbacks` list is the one authored exception: when THIS call answers a given
+ * status, the index knows a sibling capability that may do the job, and names it with the
+ * body to send. The chain exists for hide_keyboard on an iPhone, where the plain call
+ * answers 400 because the keyboard has no dismiss key, and the only way on is to press one
+ * of its own keys — Done where it exists, Return where it does not.
+ *
+ * The caller's consent covers the chain: it was given for the capability invoked, and the
+ * chain is that capability's published contract. What a step may do — press Return, which
+ * an app may treat as submit — is therefore the capability's guidance to state, not
+ * something this module decides. It does refuse two things no guidance could make right: a
+ * step naming a destructive capability, and one naming a capability this surface will not
+ * call.
+ *
+ * Every attempt is reported, in order, with the status it got, so the caller knows which
+ * step did the work and can read the screen back afterwards.
+ */
+import { InvocationError } from "./index-loader.js";
+function handle(capability) {
+    return capability.name || `${capability.method} ${capability.path}`;
+}
+export async function invokeWithFallbacks(capability, args, run, lookup) {
+    let result = await run(capability, args);
+    const chain = capability.fallbacks ?? [];
+    if (result.ok || chain.length === 0)
+        return { result };
+    const attempts = [
+        { capability: handle(capability), status: result.http_response.status },
+    ];
+    for (const step of chain) {
+        // Matched against the LATEST status, not the first: a step that answers something
+        // the next step does not name ends the chain there, with that answer.
+        if (result.http_response.status !== step.when.status)
+            continue;
+        const next = lookup(step.capability);
+        if (next.mode === "destructive")
+            throw new InvocationError(`${handle(capability)} names ${step.capability} as a fallback, which is destructive and cannot run`);
+        if (next.invocable === false)
+            throw new InvocationError(`${handle(capability)} names ${step.capability} as a fallback, which cannot be called on this server`);
+        // Only the path parameters travel: the step's body and query are the index's own, so
+        // a caller cannot steer the chain into sending something the contract never showed.
+        result = await run(next, {
+            path_params: args.path_params,
+            query: step.query,
+            body: step.body,
+        });
+        attempts.push({
+            capability: step.capability,
+            status: result.http_response.status,
+            ...(step.body ? { body: step.body } : {}),
+        });
+        if (result.ok)
+            break;
+    }
+    // A chain that matched nothing is not a chain that ran: the caller sees the plain
+    // refusal, as it would from a capability that declares no fallbacks at all.
+    return attempts.length > 1 ? { result, attempts } : { result };
+}

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

@@ -100,14 +100,53 @@ function asReference(capability) {
     ]) {
         delete reference[field];
     }
+    // Guidance is NOT touched here. `withSurfaceGuidance` has already folded in
+    // `remote_guidance` — which is where a reference-only capability says what to do
+    // instead — and it runs for every capability, not only this branch.
+    // `withSurfaceGuidance` has already run, so guidance is a plain array here — and for a
+    // reference-only capability its `remote` half is where "what to do instead" lives.
+    const named = Array.isArray(capability.guidance)
+        ? capability.guidance.length > 0
+        : false;
     return {
         ...reference,
         invocable: false,
-        guidance: capability.unavailable_note
-            ? [capability.unavailable_note]
-            : ["This capability cannot be called on this server."],
+        ...(named
+            ? {}
+            : { guidance: ["This capability cannot be called on this server."] }),
     };
 }
+/**
+ * Flatten `guidance` to the lines that apply to the surface doing the loading.
+ *
+ * A capability may say three things about how to use it: what is true everywhere, what is
+ * true only where the server sits beside the user, and what is true only on a remote one.
+ * Only one of the last two can ever apply, so the caller is handed exactly that and never
+ * has to work out which half was meant for them.
+ *
+ * COMPOSED, NOT REPLACED. An earlier shape put the remote instruction in a single
+ * `unavailable_note` that replaced the guidance outright, which threw away lines still true
+ * there — the accepted file types, how long a large upload takes — and invited them to be
+ * restated in the note, where the two copies could drift. Shared lines are now written once.
+ *
+ * The object form is flattened away here, so no reader downstream sees anything but a plain
+ * array, and which surface this is stays ours to know rather than a fact the caller acts on.
+ */
+function withSurfaceGuidance(capability) {
+    const g = capability.guidance;
+    if (!g || Array.isArray(g))
+        return capability;
+    const lines = [
+        ...(g.shared ?? []),
+        ...(appConfig.REMOTE_MCP ? (g.remote ?? []) : (g.local ?? [])),
+    ];
+    const next = { ...capability };
+    if (lines.length)
+        next.guidance = lines;
+    else
+        delete next.guidance;
+    return next;
+}
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -237,11 +276,14 @@ export class CapabilityRegistry {
             const names = new Map();
             const withheld = new Map();
             const enabled = [];
-            for (const capability of bundle.capabilities) {
+            for (let capability of bundle.capabilities) {
                 // UNIQUENESS IS CHECKED OVER EVERY CAPABILITY, disabled ones included. A clash
                 // 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.
+                // Surface guidance is folded in for EVERY capability, before any of the branches
+                // below, so a reference-only one and an ordinary one are composed the same way.
+                capability = withSurfaceGuidance(capability);
                 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.

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

@@ -22,8 +22,10 @@ import { redact } from "./redact.js";
 import { fetchTransport } from "./egress.js";
 import { CapabilityRegistry, InvocationError, resolveResponses, } from "./index-loader.js";
 import { narrowResponse } from "./narrow.js";
+import { invokeWithFallbacks } from "./fallback.js";
 import { invoke } from "./resolve.js";
 import { ambiguousProducts, productAnchors, isBrowseQuery, searchCapabilities, singular, terms, vocabularyOf, } from "./search.js";
+import { guidanceLines } from "./types.js";
 export const PERMISSION_VALUES = ["not_asked", "granted", "denied"];
 /**
  * The search-side twin of `user_permission`: did a human choose the product, or did you?
@@ -702,8 +704,8 @@ export function addCapabilityRegistryTools(server, deps, config) {
                 mode: capability.mode,
                 entity: capability.entity,
                 ...(capability.intent ? { intent: capability.intent } : {}),
-                ...(capability.guidance?.length
-                    ? { guidance: capability.guidance }
+                ...(guidanceLines(capability.guidance).length
+                    ? { guidance: guidanceLines(capability.guidance) }
                     : {}),
             })),
             ...rest,
@@ -967,7 +969,7 @@ export function addCapabilityRegistryTools(server, deps, config) {
                 // 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] ??
+                    (guidanceLines(capability.guidance)[0] ??
                         "Describe it for what to do instead.") +
                     " Follow that instead of retrying.", undefined, identity);
             }
@@ -993,7 +995,9 @@ 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, capability.host), deps.credentialsFor(), transport, registry.index.products[product]?.auth, product);
+            // The base URL is resolved per target rather than once: a fallback step may sit
+            // on a different named host from the capability that declared it.
+            const { result, attempts } = await invokeWithFallbacks(capability, args, async (target, targetArgs) => invoke(target, targetArgs, await deps.baseUrlFor(product, target.host), deps.credentialsFor(), transport, registry.index.products[product]?.auth, product), (name) => registry.byNameLookup(name, product).capability);
             // NARROWING IS APPLIED TO A SUCCESS ONLY. A 4xx body is the diagnosis the caller
             // needs whole, and a selection that happened to match none of its keys would
             // quietly empty it. `narrowResponse` refuses an unsupported `select` by throwing,
@@ -1001,13 +1005,18 @@ export function addCapabilityRegistryTools(server, deps, config) {
             const narrowed = result.ok
                 ? narrowResponse(capability, result.http_response.body, input.select)
                 : undefined;
-            const answer = narrowed
-                ? {
-                    ...result,
-                    http_response: { ...result.http_response, body: narrowed.body },
-                    narrowed: narrowed.narrowing,
-                }
-                : result;
+            const answer = {
+                ...(narrowed
+                    ? {
+                        ...result,
+                        http_response: { ...result.http_response, body: narrowed.body },
+                        narrowed: narrowed.narrowing,
+                    }
+                    : result),
+                // Only when the chain ran: a capability without `fallbacks` answers exactly as
+                // before, and one whose first call succeeded has nothing to report.
+                ...(attempts ? { fallback: { attempts } } : {}),
+            };
             // 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.
@@ -1016,6 +1025,7 @@ export function addCapabilityRegistryTools(server, deps, config) {
                 upstream_ok: result.ok,
                 upstream_status: result.http_response.status,
                 change_summary: redact(input.change_summary),
+                ...(attempts ? { fallback_steps: attempts.length - 1 } : {}),
                 ...(narrowed
                     ? {
                         narrowed_from: narrowed.narrowing.from,

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

@@ -11,6 +11,7 @@
  *  * CARDINALITY. A "list" query answered by a single-record getter sends the caller to a
  *    capability needing an id it cannot possibly have yet.
  */
+import { guidanceLines, } from "./types.js";
 /**
  * Every non-alphanumeric character separates, `_` included.
  *
@@ -408,7 +409,7 @@ function score(capability, wanted, weights, aliases, hint, plural) {
         // `test_cases_count`); gating it on an identity match instead made a field reachable
         // only through returns unreachable, which is worse.
         [(capability.returns || []).join(" "), 1],
-        [(capability.guidance || []).join(" "), 1],
+        [guidanceLines(capability.guidance).join(" "), 1],
         // Parameter names, their descriptions, and their enum values — 330 descriptions and 34
         // value lists that the artifact already carries and nothing was reading. The vocabulary
         // a caller uses is often the value they mean to send: `pass` and `fail` appear nowhere

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

@@ -102,6 +102,53 @@ export interface ResponseDoc extends ComponentRef {
     schema?: SchemaNode;
 }
 /** A capability, keyed by the endpoint it exposes. There is deliberately no name. */
+/**
+ * How to call the endpoint correctly, optionally split by which surface is serving it.
+ *
+ * A plain array is shared — true wherever this runs, which is almost everything, and the
+ * form every shipped index already uses. The object form adds lines that are true on only
+ * one surface: `local` where the server sits beside the user, `remote` where it does not.
+ * `shared` is the same list the plain array would have been, so a capability can carry
+ * facts of both kinds without repeating any of them.
+ *
+ * The loader folds the applicable half into one array before anything reads it, so a
+ * caller is handed exactly the guidance that applies to the server it is talking to and
+ * never has to work out which half was meant for it. The split itself is ours to know:
+ * these keys do not survive into what describeCapability or searchCapability return.
+ *
+ * WHY A LINE IS SURFACE-SPECIFIC RATHER THAN SHARED: on a remote server, advice about the
+ * caller's own filesystem is not merely useless but wrong — it would have an agent tell the
+ * user to configure a machine they are not on. And for a `local_only` capability, `remote`
+ * is where "what to do instead" lives, which searchCapability puts in front of the caller
+ * before they pick anything, let alone call it.
+ */
+export type Guidance = string[] | {
+    shared?: string[];
+    local?: string[];
+    remote?: string[];
+};
+/**
+ * The guidance lines as a plain array, whichever form was authored.
+ *
+ * The loader flattens the object form at load, so everything downstream genuinely does hold
+ * an array — this exists so that is checked rather than asserted, and so a capability read
+ * straight from a file (a test, a checker) behaves the same as one from the registry.
+ * Without the surface to decide between them, only the shared lines can be returned.
+ */
+export declare function guidanceLines(guidance?: Guidance): string[];
+/** One step of a capability's `fallbacks` chain. */
+export interface Fallback {
+    /** Runs when the latest response carried this status. */
+    when: {
+        status: number;
+    };
+    /** The sibling capability to call, by published name, in the same product. */
+    capability: string;
+    /** The body to send it — authored, never the caller's. */
+    body?: Record<string, unknown>;
+    /** Query parameters to send it, if it takes any. */
+    query?: Record<string, unknown>;
+}
 export interface Capability {
     /**
      * The caller-facing handle — the snake-cased `operationId`, unique within its product.
@@ -139,14 +186,8 @@ export interface Capability {
     query?: WireParam[];
     body?: WireParam[];
     intent?: string;
-    /**
-     * How to call the endpoint correctly.
-     *
-     * ABSENT from the released artifact — the export dropped it, and the shape-change note
-     * does not say whether that was intended. Kept optional and still scored by search so the
-     * server works either way; nothing may depend on it being present.
-     */
-    guidance?: string[];
+    /** How to call it; see `Guidance` for the local/remote split. */
+    guidance?: Guidance;
     /** Allowlisted row fields. Absent when `shape` is "discovered". */
     returns?: string[];
     /** "discovered" when the product declares no response schema for this operation. */
@@ -189,18 +230,6 @@ export interface Capability {
      * 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.
      *
@@ -255,6 +284,21 @@ export interface Capability {
         /** One line for the contract: why this is here rather than on the wire. */
         note?: string;
     };
+    /**
+     * What to try next when the product refuses THIS call, in order.
+     *
+     * The one authored exception to one-request-one-response. Each step names a sibling
+     * capability in the same product and the fixed body to send it; the original call's
+     * path parameters are carried over, nothing else. A step runs only when the LATEST
+     * response has the status it names, and the chain stops at the first 2xx.
+     *
+     * Exists for hide_keyboard on an iPhone: the keyboard has no dismiss key, so the plain
+     * call is refused, and the only way on is to press one of the keys it does carry. The
+     * caller's consent covers the chain, because the chain is this capability's published
+     * contract — so what a step may do (press Return, which an app may treat as submit) is
+     * the capability's guidance to state. Every attempt is reported with its status.
+     */
+    fallbacks?: Fallback[];
     paginated?: boolean;
     /** The largest page the operation declares. */
     max_page_size?: number;

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

@@ -31,3 +31,16 @@ export const ENVELOPE_KEYS = [
     "harness_commit",
     "products",
 ];
+/**
+ * The guidance lines as a plain array, whichever form was authored.
+ *
+ * The loader flattens the object form at load, so everything downstream genuinely does hold
+ * an array — this exists so that is checked rather than asserted, and so a capability read
+ * straight from a file (a test, a checker) behaves the same as one from the registry.
+ * Without the surface to decide between them, only the shared lines can be returned.
+ */
+export function guidanceLines(guidance) {
+    if (!guidance)
+        return [];
+    return Array.isArray(guidance) ? guidance : (guidance.shared ?? []);
+}

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

@@ -4,7 +4,7 @@ import { apiClient } from "../../lib/apiClient.js";
 import { wrapUntrusted } from "../../lib/untrusted-content.js";
 // DEVICE LOGS
 export async function retrieveDeviceLogs(sessionId, buildId, config) {
-    const url = `https://api.browserstack.com/app-automate/builds/${buildId}/sessions/${sessionId}/deviceLogs`;
+    const url = `https://api.browserstack.com/app-automate/builds/${buildId}/sessions/${sessionId}/devicelogs`;
     const authString = getBrowserStackAuth(config);
     const auth = Buffer.from(authString).toString("base64");
     const response = await apiClient.get({

package/dist/tools/live.js

@@ -3,6 +3,7 @@ import logger from "../logger.js";
 import { startBrowserSession } from "./live-utils/start-session.js";
 import { PlatformType } from "./live-utils/types.js";
 import { trackMCP } from "../lib/instrumentation.js";
+import { isEnabled as capabilityRegistryEnabled } from "./capability-registry/config.js";
 import globalConfig from "../config.js";
 // Define the schema shape
 const LiveArgsShape = {
@@ -88,7 +89,13 @@ async function runBrowserSession(rawArgs, config) {
 }
 export default function addBrowserLiveTools(server, config) {
     const tools = {};
-    tools.runBrowserLiveSession = server.tool("runBrowserLiveSession", "Launch a BrowserStack Live session (desktop or mobile).", LiveArgsShape, {
+    // Same rule as runAppLiveSession: Live is for a person, and an agent that picks it for a
+    // click-by-locator task ends up reporting that Live cannot click by locator.
+    const description = "Open a manual Live browser session (desktop or mobile) for the user to operate by hand. It cannot be driven by the agent." +
+        (capabilityRegistryEnabled()
+            ? " To click, type or read the page yourself, use a devicecontrol session via invokeCapability."
+            : "");
+    tools.runBrowserLiveSession = server.tool("runBrowserLiveSession", description, LiveArgsShape, {
         title: "Run Browser Live Session",
         readOnlyHint: false,
         openWorldHint: true,

package/package.json

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