@browserstack/mcp-server 1.5.0-beta.2 → 1.5.0-beta.20

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

@@ -8,6 +8,154 @@
  * Grouping removes the collision AND the rename, so a caller sends the spec's own names.
  */
 import { InvocationError } from "./index-loader.js";
+/**
+ * String formats worth ENFORCING, as opposed to merely publishing.
+ *
+ * A validator that rejects a correct value is worse than no validator: the caller cannot
+ * route around it, and the request that would have worked never leaves. So this covers only
+ * the formats where "wrong" is unambiguous and a legitimate value cannot trip it.
+ *
+ * tm declares eight formats. `date`, `date-time` and `uuid` are here. `email` and `uri` are
+ * deliberately NOT — every compact regex for either rejects addresses and URLs that servers
+ * accept, and being wrong in that direction blocks real work. `int64`, `float` and `binary`
+ * say what a number or blob is, which `type` already covers.
+ */
+const FORMATS = {
+    date: {
+        // A real calendar date, so 2026-02-31 fails rather than being reformatted.
+        test: (v) => /^\d{4}-\d{2}-\d{2}$/.test(v) &&
+            !Number.isNaN(Date.parse(`${v}T00:00:00Z`)) &&
+            new Date(`${v}T00:00:00Z`).toISOString().startsWith(v),
+        want: "a date (YYYY-MM-DD)",
+    },
+    "date-time": {
+        // Permissive on purpose: offset or Z, optional fractional seconds. Tightening this
+        // buys nothing and starts rejecting timestamps the product would have taken.
+        test: (v) => /^\d{4}-\d{2}-\d{2}[Tt ]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:?\d{2})?$/.test(v) && !Number.isNaN(Date.parse(v)),
+        want: "a date-time (e.g. 2026-01-31T09:30:00Z)",
+    },
+    uuid: {
+        test: (v) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v),
+        want: "a UUID",
+    },
+};
+/**
+ * A declared `pattern`, compiled once, or undefined if it will not compile here.
+ *
+ * `u` because tm's patterns use `\p{L}`/`\p{N}`, which are a syntax error without it. A
+ * pattern this engine cannot compile is SKIPPED rather than thrown: the index is generated
+ * from someone else's spec, and refusing to invoke a working endpoint because its regex
+ * dialect differs would be our bug landing on the caller.
+ */
+const patternCache = new Map();
+function compiled(pattern) {
+    if (!patternCache.has(pattern)) {
+        let regex;
+        try {
+            regex = new RegExp(pattern, "u");
+        }
+        catch {
+            try {
+                regex = new RegExp(pattern);
+            }
+            catch {
+                regex = undefined;
+            }
+        }
+        patternCache.set(pattern, regex);
+    }
+    return patternCache.get(pattern);
+}
+/**
+ * Every constraint the parameter declares, checked against the COERCED value.
+ *
+ * Runs inside `bind`, which register.ts calls dry before the write-consent gate — so a
+ * value that breaks a constraint is refused before the user is asked to approve anything,
+ * and nothing reaches egress.
+ *
+ * `label` carries the parent name for a nested field, so the message names `test_case.name`
+ * rather than a bare `name` the caller would have to go looking for.
+ */
+function checkConstraints(value, param, label = param.name) {
+    const fail = (what) => {
+        throw new InvocationError(`'${label}' ${what}`);
+    };
+    if (typeof value === "number") {
+        if (param.minimum !== undefined && value < param.minimum)
+            fail(`must be at least ${param.minimum}`);
+        if (param.maximum !== undefined && value > param.maximum)
+            fail(`must be at most ${param.maximum}`);
+        if (param.multipleOf !== undefined && param.multipleOf > 0) {
+            // Scale BOTH to integers before the modulo: 0.3 % 0.1 is 0.09999… in binary floating
+            // point and would reject a value the product accepts. The scale has to cover the
+            // value's decimals as well as the step's — scaling by the step alone rounds 0.25 to
+            // 3 against a step of 1, which then divides evenly and lets a bad value through.
+            const scale = 10 ** Math.max(decimals(param.multipleOf), decimals(value));
+            if (Math.round(value * scale) % Math.round(param.multipleOf * scale) !==
+                0)
+                fail(`must be a multiple of ${param.multipleOf}`);
+        }
+    }
+    if (typeof value === "string") {
+        if (param.minLength !== undefined && value.length < param.minLength)
+            fail(`must be at least ${param.minLength} character(s)`);
+        if (param.maxLength !== undefined && value.length > param.maxLength)
+            fail(`must be at most ${param.maxLength} character(s)`);
+        if (param.pattern) {
+            const regex = compiled(param.pattern);
+            if (regex && !regex.test(value))
+                fail(`must match ${param.pattern}`);
+        }
+        const format = param.format ? FORMATS[param.format] : undefined;
+        if (format && !format.test(value))
+            fail(`must be ${format.want}`);
+    }
+    if (Array.isArray(value)) {
+        if (param.minItems !== undefined && value.length < param.minItems)
+            fail(`must have at least ${param.minItems} item(s)`);
+        if (param.maxItems !== undefined && value.length > param.maxItems)
+            fail(`must have at most ${param.maxItems} item(s)`);
+        if (param.uniqueItems) {
+            const seen = new Set(value.map((item) => JSON.stringify(item)));
+            if (seen.size !== value.length)
+                fail("must not contain duplicate items");
+        }
+    }
+}
+/** Decimal places, for scaling `multipleOf` out of floating point. */
+function decimals(n) {
+    const text = String(n);
+    const dot = text.indexOf(".");
+    return dot < 0 ? 0 : text.length - dot - 1;
+}
+/**
+ * The declared fields one level inside an object, or inside each item of an array.
+ *
+ * Only what `fields` names is checked, and an undeclared key is left alone — `fields` is a
+ * projection of the shape, not a closed contract, so rejecting the rest would refuse valid
+ * bodies. That is the opposite of the top level, where the full parameter list IS known and
+ * an unknown name is an error.
+ */
+function checkFields(value, param) {
+    if (!param.fields?.length)
+        return;
+    const items = Array.isArray(value) ? value : [value];
+    for (const item of items) {
+        if (typeof item !== "object" || item === null || Array.isArray(item))
+            continue;
+        const record = item;
+        for (const field of param.fields) {
+            if (!(field.name in record)) {
+                if (field.required)
+                    throw new InvocationError(`missing required parameter(s): ${param.name}.${field.name}`);
+                continue;
+            }
+            const label = `${param.name}.${field.name}`;
+            const coerced = coerceType(record[field.name], field, label);
+            checkConstraints(coerced, field, label);
+        }
+    }
+}
 /**
  * Check one argument against its declared schema, raising a caller-safe error.
  *
@@ -16,23 +164,29 @@ import { InvocationError } from "./index-loader.js";
  * rather than being encoded into a URL.
  */
 export function coerce(value, param) {
+    const coerced = coerceType(value, param);
+    checkConstraints(coerced, param);
+    checkFields(coerced, param);
+    return coerced;
+}
+function coerceType(value, param, label = param.name) {
     const expected = param.type;
     if (expected === "object" || expected === "array") {
         // An opaque body object is passed through as given: the spec does not describe its
         // fields, so validating or reshaping it would mean inventing a contract.
         if (expected === "object" &&
             (typeof value !== "object" || value === null || Array.isArray(value))) {
-            throw new InvocationError(`'${param.name}' must be an object`);
+            throw new InvocationError(`'${label}' must be an object`);
         }
         if (expected === "array" && !Array.isArray(value)) {
-            throw new InvocationError(`'${param.name}' must be a list`);
+            throw new InvocationError(`'${label}' must be a list`);
         }
         return value;
     }
     if (expected === "integer" || expected === "number") {
         const parsed = Number(String(value).trim());
         if (!Number.isFinite(parsed)) {
-            throw new InvocationError(`'${param.name}' must be a number`);
+            throw new InvocationError(`'${label}' must be a number`);
         }
         return expected === "integer" ? Math.trunc(parsed) : parsed;
     }
@@ -44,13 +198,29 @@ export function coerce(value, param) {
             return true;
         if (["false", "0", "no"].includes(text))
             return false;
-        throw new InvocationError(`'${param.name}' must be true or false`);
+        throw new InvocationError(`'${label}' must be true or false`);
+    }
+    // NO DECLARED TYPE: pass the value through as given.
+    //
+    // The fallthrough below is String(value), which is right for a declared string and
+    // silently destructive for anything the spec left untyped. create_report_v2 declares
+    // `mail_to` and `report_filters` with no type and the API wants objects for both, so a
+    // correct payload was serialised to the literal "[object Object]" and refused:
+    //
+    //   The property '#/mail_to' of type string did not match the following type: object
+    //
+    // The caller sent the right thing, this layer broke it, and the server's message blames
+    // the caller for a string it never wrote. An untyped parameter means the spec declines to
+    // say what shape it is — which is a reason to leave it alone, not to guess "string".
+    const untyped = !expected;
+    if (untyped && (typeof value === "object" || typeof value === "boolean")) {
+        return value;
     }
     const text = String(value);
     if (param.values && param.values.length > 0) {
         const allowed = param.values.map((v) => String(v));
         if (!allowed.includes(text)) {
-            throw new InvocationError(`'${param.name}' must be one of: ${allowed.join(", ")}`);
+            throw new InvocationError(`'${label}' must be one of: ${allowed.join(", ")}`);
         }
     }
     return text;
@@ -90,8 +260,33 @@ export function bind(capability, args) {
         // misspelled filter would return a larger result set that looks like a correct answer.
         const unknown = Object.keys(supplied).filter((name) => !byName.has(name));
         if (unknown.length > 0) {
+            // A CALLER WHO SENT THE WRAPPER WE BUILD DESERVES TO BE TOLD SO.
+            //
+            // Most of these endpoints want a nested body — Rails `params.require(:test_case)` —
+            // and the fields declare that as `json_path: /test_case/name`, so this layer
+            // assembles the wrapper itself and the caller sends the fields flat. A caller who
+            // wraps it by hand therefore sends a key that is never a declared param, and the
+            // bare message reads as "that field does not exist" when the truth is the opposite:
+            // it exists, and building it is our job.
+            //
+            // Worth special-casing because the guidance itself has been telling callers to wrap:
+            // 25 tm capabilities carried a line describing the WIRE format to a caller who never
+            // writes the wire. Those lines are being corrected, but an agent working from an
+            // older artifact, or reasoning from the Rails convention, lands here either way.
+            const wrappers = new Set(params
+                .map((param) => param.json_path)
+                .filter((path) => Boolean(path))
+                .map((path) => path.replace(/^\//, "").split("/")[0])
+                .filter((segment) => segment && !byName.has(segment)));
+            const sentAWrapper = unknown.filter((name) => wrappers.has(name));
             throw new InvocationError(`unknown ${group}: ${unknown.sort().join(", ")}. accepted: ` +
-                `${[...byName.keys()].sort().join(", ") || "none"}`);
+                `${[...byName.keys()].sort().join(", ") || "none"}` +
+                (sentAWrapper.length > 0
+                    ? `. ${sentAWrapper.sort().join(" and ")} ` +
+                        `${sentAWrapper.length > 1 ? "are wrappers" : "is a wrapper"} this ` +
+                        `surface builds for you from each field's json_path — send the fields ` +
+                        `directly instead of nesting them`
+                    : ""));
         }
         for (const [name, raw] of Object.entries(supplied)) {
             const param = byName.get(name);

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

@@ -83,6 +83,54 @@ export function authHeaders(credentials, auth = DEFAULT_AUTH) {
     throw new InvocationError(`unsupported auth scheme for this product: ` +
         `${JSON.stringify({ type: auth.type, scheme: auth.scheme })}`);
 }
+/** Longest response text kept when it is not JSON. Enough for an error, not a whole page. */
+const TEXT_BODY_LIMIT = 2000;
+/**
+ * Read the response, and NEVER silently discard it.
+ *
+ * This used to parse the body only when the content-type said JSON and return `null`
+ * otherwise, which meant an error could arrive as `{status: 500, body: null}` — a status
+ * code and nothing else. That is worse than it sounds: an unhandled exception in a Rails
+ * app renders `text/html`, so the one case where you most need the message is exactly the
+ * case where the content-type is not JSON. It also made two very different situations
+ * indistinguishable — "the product sent no message" and "we threw the message away" — and
+ * a live probe of `test_case_results_v1` had to leave that ambiguity open in its findings
+ * because nothing downstream could tell which had happened.
+ *
+ * So: JSON is parsed as before. Anything textual is kept as a truncated string. Malformed
+ * JSON keeps its raw text rather than becoming `null`, because a body that fails to parse
+ * is itself the diagnosis. Binary is described rather than decoded — dumping PDF bytes
+ * into an agent's context helps nobody, but knowing a PDF arrived does.
+ */
+async function readBody(response) {
+    const contentType = response.headers.get("content-type") || "";
+    // Anything that is not plausibly text: report what came back without decoding it.
+    const textual = !contentType ||
+        /^text\//i.test(contentType) ||
+        /\b(json|xml|yaml|csv|javascript|x-www-form-urlencoded)\b/i.test(contentType);
+    if (!textual) {
+        const size = response.headers.get("content-length");
+        return `<non-text response: ${contentType}${size ? `, ${size} bytes` : ""}>`;
+    }
+    const raw = await response.text().catch(() => "");
+    if (!raw.trim())
+        return null;
+    if (contentType.includes("json")) {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            // Declared JSON that is not JSON. The text is the evidence; keep it.
+            return truncate(raw);
+        }
+    }
+    return truncate(raw);
+}
+function truncate(text) {
+    return text.length <= TEXT_BODY_LIMIT
+        ? text
+        : `${text.slice(0, TEXT_BODY_LIMIT)}… [truncated, ${text.length} chars total]`;
+}
 /** A fetch-based transport. Redirects are NOT followed. */
 export function fetchTransport(timeoutMs = 45_000) {
     return async (method, url, headers, query, body) => {
@@ -106,12 +154,10 @@ export function fetchTransport(timeoutMs = 45_000) {
                 redirect: "manual",
                 signal: controller.signal,
             });
-            let parsed = null;
-            const contentType = response.headers.get("content-type") || "";
-            if (contentType.includes("json")) {
-                parsed = await response.json().catch(() => null);
-            }
-            return { status: response.status, body: parsed };
+            return {
+                status: response.status,
+                body: await readBody(response),
+            };
         }
         catch {
             // Upstream detail stays out of the reply; the resolver treats status 0 as a failed call.

package/dist/tools/capability-registry/index-loader.d.ts

@@ -46,6 +46,8 @@ export declare class CapabilityRegistry {
     readonly provenance: Record<string, Provenance>;
     /** product -> "METHOD /path" -> capability */
     private readonly byEndpoint;
+    /** product -> capability name -> capability. Empty for products that publish no names. */
+    private readonly byName;
     constructor(index: RegistryIndex, provenance?: Record<string, Provenance>);
     static fromFile(file: string): CapabilityRegistry;
     /**
@@ -63,7 +65,19 @@ export declare class CapabilityRegistry {
     /** Per-product `{build_id, version}`, for logging and cache-busting only. */
     buildInfo(): Record<string, Provenance>;
     /**
-     * Find a capability by the endpoint it exposes — the published handle.
+     * Find a capability by its published name — the preferred handle.
+     *
+     * Names are unique within a product but not across products, so an ambiguous name is
+     * reported rather than resolved by load order. A name that exists in no index is
+     * `unknown_capability`: a distinct outcome from a name that exists elsewhere, because the
+     * caller's next move differs — search again, versus pass `product`.
+     */
+    byNameLookup(name: string, product?: string): {
+        product: string;
+        capability: Capability;
+    };
+    /**
+     * Find a capability by the endpoint it exposes — the handle for unnamed products.
      *
      * The endpoint is what searchCapability returns, so it is the only thing a caller can
      * hold. `unknown_endpoint` is a defined outcome rather than a generic failure: a caller

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

@@ -107,6 +107,8 @@ export class CapabilityRegistry {
     provenance;
     /** product -> "METHOD /path" -> capability */
     byEndpoint = new Map();
+    /** product -> capability name -> capability. Empty for products that publish no names. */
+    byName = new Map();
     constructor(index, provenance = {}) {
         if (index?.schema_version !== SUPPORTED_SCHEMA_VERSION) {
             throw new IndexError(`unsupported index schema_version ${index?.schema_version}; this build reads ` +
@@ -119,10 +121,25 @@ export class CapabilityRegistry {
         this.provenance = provenance;
         for (const [product, bundle] of Object.entries(index.products)) {
             const lookup = new Map();
+            const names = new Map();
             for (const capability of bundle.capabilities) {
                 lookup.set(endpointKey(capability.method, capability.path), capability);
+                if (!capability.name)
+                    continue;
+                const clash = names.get(capability.name);
+                if (clash) {
+                    // A duplicate name makes one of the two permanently unreachable, and which one
+                    // wins would depend on array order. The export gates this, but a hand-edited or
+                    // stale artifact must not load and then silently drop an endpoint.
+                    throw new IndexError(`${product}: capability name '${capability.name}' is used by both ` +
+                        `${endpointKey(clash.method, clash.path)} and ` +
+                        `${endpointKey(capability.method, capability.path)}; names must be unique ` +
+                        `within a product`);
+                }
+                names.set(capability.name, capability);
             }
             this.byEndpoint.set(product, lookup);
+            this.byName.set(product, names);
         }
     }
     static fromFile(file) {
@@ -183,7 +200,45 @@ export class CapabilityRegistry {
         return this.provenance;
     }
     /**
-     * Find a capability by the endpoint it exposes — the published handle.
+     * Find a capability by its published name — the preferred handle.
+     *
+     * Names are unique within a product but not across products, so an ambiguous name is
+     * reported rather than resolved by load order. A name that exists in no index is
+     * `unknown_capability`: a distinct outcome from a name that exists elsewhere, because the
+     * caller's next move differs — search again, versus pass `product`.
+     */
+    byNameLookup(name, product) {
+        const matches = [];
+        for (const [owner, lookup] of this.byName) {
+            if (product && owner !== product)
+                continue;
+            const capability = lookup.get(name);
+            if (capability)
+                matches.push({ product: owner, capability });
+        }
+        if (matches.length === 0) {
+            // 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]
+                .filter(([owner, lookup]) => (!product || owner === product) && lookup.size === 0)
+                .map(([owner]) => owner);
+            const hint = unnamed.length
+                ? ` ${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}`);
+        }
+        if (matches.length > 1 && !product) {
+            const owners = matches
+                .map((m) => m.product)
+                .sort()
+                .join(", ");
+            throw new InvocationError(`capability name '${name}' exists in several products (${owners}); pass product`);
+        }
+        return matches[0];
+    }
+    /**
+     * Find a capability by the endpoint it exposes — the handle for unnamed products.
      *
      * The endpoint is what searchCapability returns, so it is the only thing a caller can
      * hold. `unknown_endpoint` is a defined outcome rather than a generic failure: a caller
@@ -282,7 +337,42 @@ function resolveNode(product, node, seen) {
         // revisit a name already on this path.
         if (!target || seen.has(key))
             return node;
-        return resolveNode(product, target, new Set([...seen, key]));
+        const resolved = resolveNode(product, target, new Set([...seen, key]));
+        // KEYS WRITTEN BESIDE THE REF SURVIVE IT, AND WIN.
+        //
+        // This used to return the target and drop every sibling, which silently ate 16 nodes
+        // in the shipped tm index: 14 authored descriptions and two `nullable: true` flags.
+        // The losses are exactly the caveats hardest to rediscover — "only when no step
+        // results were submitted", "Present only on root-folder creation", and a `nullable`
+        // marking the one field that comes back NULL when a search fails, which is the
+        // absent-versus-explicitly-null distinction a caller cannot otherwise make.
+        //
+        // It also cost real work downstream. A live probe reported one of those caveats as a
+        // missing conditional and it had been written all along — this resolver removed it
+        // between the author and the caller. Worse, the product team began splitting shared
+        // schemas so a caveat would have somewhere to live that survived, trading a lost
+        // sentence for two descriptions of one serializer that then drift apart.
+        //
+        // SIBLINGS WIN over the resolved target, not the reverse. A description written at the
+        // reference site is about THAT usage — "only when no step results were submitted" is
+        // true of one consumer of TestResult, not of TestResult everywhere — which is the
+        // whole reason it was written beside the ref instead of on the schema.
+        const siblings = {};
+        for (const [field, value] of Object.entries(node)) {
+            if (field !== "$schema" && field !== "$response")
+                siblings[field] = value;
+        }
+        if (Object.keys(siblings).length === 0)
+            return resolved;
+        if (typeof resolved !== "object" ||
+            resolved === null ||
+            Array.isArray(resolved)) {
+            return resolved;
+        }
+        return {
+            ...resolved,
+            ...resolveNode(product, siblings, seen),
+        };
     }
     const out = {};
     for (const [field, value] of Object.entries(node)) {

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

@@ -1,6 +1,12 @@
 /**
  * The tool surface: four discovery tools plus ONE invoke tool.
  *
+ * Discovery is deliberately two steps. `searchCapability` returns a shortlist — enough to
+ * CHOOSE — and `describeCapability` returns the contract for the one chosen. Parameters and
+ * response shapes are 86% of a full record and are needed once, not eight times: measured
+ * over eight queries, ~8.6k tokens a search becomes ~1.1k, and even describing every result
+ * still costs less than the single fat call did.
+ *
  * ONE invoke tool means one set of MCP annotations, so they describe the whole surface
  * honestly: it can write (not read-only) and it can never delete, because destructive
  * endpoints are refused before binding. Write consent therefore rests on `user_permission`
@@ -12,6 +18,14 @@ import { BrowserStackConfig } from "../../lib/types.js";
 import { Credentials, Transport } from "./egress.js";
 import { CapabilityRegistry } from "./index-loader.js";
 export declare const PERMISSION_VALUES: readonly ["not_asked", "granted", "denied"];
+/**
+ * The search-side twin of `user_permission`: did a human choose the product, or did you?
+ *
+ * No `denied`. A refused write is a thing the caller must not do; a refused product choice
+ * is not a state — the user either named one, in which case you search it, or has not been
+ * asked, in which case there is nothing to search yet.
+ */
+export declare const PRODUCT_CHOICE_VALUES: readonly ["not_asked", "user_confirmed"];
 export interface RegistryDeps {
     registry: CapabilityRegistry;
     /**