@browserstack/mcp-server 1.4.0-beta.2 → 1.5.0-beta.1

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

@@ -0,0 +1,44 @@
+/**
+ * The outbound call: auth, attribution, and one HTTP request.
+ *
+ * AUTH IS THE CALLER'S OWN CREDENTIALS, FORWARDED — never a token this server mints. How
+ * they are presented is the PRODUCT's to declare, in the OpenAPI `securityScheme` terms its
+ * own spec already uses. Absent a declaration the default is tm's: `Api-Token:
+ * <username>:<access_key>`, accepted by every /api/v1 route and validated against IAAM
+ * OAuth2 v2 — the same identity resolution a minted bearer token produces, one hop earlier.
+ * Verified in browserstack/teststack: the 59 v1 controllers inheriting
+ * ApplicationApiController resolve it in `current_user`, the 5 inheriting
+ * Api::V1::ApiController in `authenticate_token`.
+ *
+ * That default is right for tm and wrong to assume of everyone. Load Testing's
+ * /api/v1/agent/* surface is reported to take HTTP Basic, and before this there was nowhere
+ * to say so: the requirement lived in a pull request description while the server sent
+ * Api-Token regardless, and the mismatch surfaced as a 401 that reads like the user's
+ * credentials are wrong.
+ */
+import { AuthScheme } from "./types.js";
+export interface Credentials {
+    username: string;
+    accessKey: string;
+}
+export interface HttpResponse {
+    status: number;
+    body: unknown;
+    error?: string;
+}
+export type Transport = (method: string, url: string, headers: Record<string, string>, query: Record<string, unknown>, body?: unknown) => Promise<HttpResponse>;
+/** The historical default, and what an index without an `auth` block still gets. */
+export declare const DEFAULT_AUTH: AuthScheme;
+/**
+ * Fill a credential template.
+ *
+ * An unknown placeholder is REFUSED, never passed through. Emitting `{user_id}` literally
+ * would send a header that looks well-formed and comes back 401 — indistinguishable from
+ * bad credentials, which is the failure this whole mechanism exists to remove. The harness
+ * really does carry templates this server cannot fill (`{user_id}_{group_id}`), so this is
+ * the common case, not a hypothetical.
+ */
+export declare function renderTemplate(template: string, credentials: Credentials): string;
+export declare function authHeaders(credentials: Credentials, auth?: AuthScheme): Record<string, string>;
+/** A fetch-based transport. Redirects are NOT followed. */
+export declare function fetchTransport(timeoutMs?: number): Transport;

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

@@ -0,0 +1,128 @@
+/**
+ * The outbound call: auth, attribution, and one HTTP request.
+ *
+ * AUTH IS THE CALLER'S OWN CREDENTIALS, FORWARDED — never a token this server mints. How
+ * they are presented is the PRODUCT's to declare, in the OpenAPI `securityScheme` terms its
+ * own spec already uses. Absent a declaration the default is tm's: `Api-Token:
+ * <username>:<access_key>`, accepted by every /api/v1 route and validated against IAAM
+ * OAuth2 v2 — the same identity resolution a minted bearer token produces, one hop earlier.
+ * Verified in browserstack/teststack: the 59 v1 controllers inheriting
+ * ApplicationApiController resolve it in `current_user`, the 5 inheriting
+ * Api::V1::ApiController in `authenticate_token`.
+ *
+ * That default is right for tm and wrong to assume of everyone. Load Testing's
+ * /api/v1/agent/* surface is reported to take HTTP Basic, and before this there was nowhere
+ * to say so: the requirement lived in a pull request description while the server sent
+ * Api-Token regardless, and the mismatch surfaced as a 401 that reads like the user's
+ * credentials are wrong.
+ */
+import { InvocationError } from "./index-loader.js";
+/** What this server can put into a credential template. Nothing else is fillable. */
+const PLACEHOLDERS = ["username", "access_key"];
+/** The historical default, and what an index without an `auth` block still gets. */
+export const DEFAULT_AUTH = {
+    type: "apiKey",
+    in: "header",
+    name: "Api-Token",
+    template: "{username}:{access_key}",
+};
+/**
+ * Fill a credential template.
+ *
+ * An unknown placeholder is REFUSED, never passed through. Emitting `{user_id}` literally
+ * would send a header that looks well-formed and comes back 401 — indistinguishable from
+ * bad credentials, which is the failure this whole mechanism exists to remove. The harness
+ * really does carry templates this server cannot fill (`{user_id}_{group_id}`), so this is
+ * the common case, not a hypothetical.
+ */
+export function renderTemplate(template, credentials) {
+    const unknown = [...template.matchAll(/\{([a-z_]+)\}/g)]
+        .map((match) => match[1])
+        .filter((nameed) => !PLACEHOLDERS.includes(nameed));
+    if (unknown.length > 0) {
+        throw new InvocationError(`auth template uses placeholder(s) this server cannot fill: ` +
+            `${[...new Set(unknown)].sort().join(", ")}. Available: ` +
+            `${PLACEHOLDERS.map((placeholder) => `{${placeholder}}`).join(", ")}`);
+    }
+    return template
+        .replaceAll("{username}", credentials.username)
+        .replaceAll("{access_key}", credentials.accessKey);
+}
+export function authHeaders(credentials, auth = DEFAULT_AUTH) {
+    if (!credentials?.username || !credentials?.accessKey) {
+        // Refusing here beats sending unauthenticated and surfacing the product's 401, which
+        // reads like the user's problem when it is our missing configuration.
+        throw new InvocationError("this request is not authenticated: BrowserStack username and access key are required");
+    }
+    const common = {
+        // Attribution, so the downstream service can see the call came from an agent.
+        "request-source": "ai-chatbot",
+        "Content-Type": "application/json",
+    };
+    const value = renderTemplate(auth.template || DEFAULT_AUTH.template, credentials);
+    if (auth.type === "apiKey") {
+        // Header only. `cookie` needs a session this server does not have, and `query` would
+        // put the credential in a URL, where access logs and proxies keep it.
+        if (auth.in && auth.in !== "header") {
+            throw new InvocationError(`unsupported auth location '${auth.in}': this server can only send credentials ` +
+                `in a header`);
+        }
+        if (!auth.name) {
+            throw new InvocationError("apiKey auth declares no header name");
+        }
+        return { [auth.name]: value, ...common };
+    }
+    if (auth.type === "http" && (auth.scheme || "").toLowerCase() === "basic") {
+        return {
+            Authorization: `Basic ${Buffer.from(value).toString("base64")}`,
+            ...common,
+        };
+    }
+    // By name, and refusing: sending nothing would be a 401 the caller reads as their own
+    // fault, and guessing a scheme is how credentials end up somewhere they should not be.
+    throw new InvocationError(`unsupported auth scheme for this product: ` +
+        `${JSON.stringify({ type: auth.type, scheme: auth.scheme })}`);
+}
+/** A fetch-based transport. Redirects are NOT followed. */
+export function fetchTransport(timeoutMs = 45_000) {
+    return async (method, url, headers, query, body) => {
+        const target = new URL(url);
+        for (const [key, value] of Object.entries(query || {})) {
+            if (value !== undefined && value !== null)
+                target.searchParams.set(key, String(value));
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetch(target.toString(), {
+                method,
+                headers,
+                // Only send a body when there IS one: a literal `null` payload with a JSON
+                // content-type is rejected by several endpoints.
+                body: body === undefined ? undefined : JSON.stringify(body),
+                // A redirect from an authenticated API is usually a login bounce, and following it
+                // turns a clear 401/302 into a 200 carrying an HTML sign-in page — which the
+                // resolver would then read as an empty result set rather than a failure.
+                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 };
+        }
+        catch {
+            // Upstream detail stays out of the reply; the resolver treats status 0 as a failed call.
+            return {
+                status: 0,
+                body: null,
+                error: "the product could not be reached",
+            };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+}

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

@@ -0,0 +1,119 @@
+/**
+ * Load the index artifact(s) and expose the lookups the tools need.
+ *
+ * ONE FILE PER PRODUCT is the released contract, so loading is a merge across files. The
+ * merged model keeps the products map the rest of the server already reads, which is what
+ * lets searchCapability rank across products from N single-product files.
+ */
+import { Capability, ProductIndex, Provenance, RegistryIndex, ResponseDoc, SchemaNode } from "./types.js";
+export declare class IndexError extends Error {
+}
+/** Thrown to the caller as a tool error, so the wording is caller-facing. */
+export declare class InvocationError extends Error {
+}
+/** The file inside a product subdirectory, for the earlier nested layout. */
+export declare const INDEX_FILE = "index.json";
+/** The stored layout, and the name the export publishes: `<product>.capability-index.json`. */
+export declare const FLAT_SUFFIX = ".capability-index.json";
+/**
+ * The product a file's LOCATION claims to describe, if its layout says so.
+ *
+ * `capability/tm.capability-index.json` and `capability/tm/index.json` both name their
+ * product, and
+ * `fromFiles` cross-checks that against the product key inside. A file in the wrong place
+ * would otherwise register its product under the directory's name and answer for endpoints
+ * it does not have.
+ */
+export declare function productFromPath(file: string): string | undefined;
+export declare function endpointKey(method: string, path: string): string;
+export interface LoadedProduct {
+    name: string;
+    product: ProductIndex;
+    provenance: Provenance;
+}
+/**
+ * Read one artifact file into the product it carries.
+ *
+ * SHAPE DETECTION, NOT VERSION DETECTION. The released envelope and the pre-release one
+ * both declare `schema_version: 1`, so the number cannot tell them apart; the `products`
+ * wrapper can, and is the documented discriminator. The pre-release branch is defensive
+ * only — that shape was never deployed.
+ */
+export declare function readIndexFile(raw: unknown, source?: string): LoadedProduct;
+export declare class CapabilityRegistry {
+    readonly index: RegistryIndex;
+    /** product -> provenance of the file it came from. */
+    readonly provenance: Record<string, Provenance>;
+    /** product -> "METHOD /path" -> capability */
+    private readonly byEndpoint;
+    constructor(index: RegistryIndex, provenance?: Record<string, Provenance>);
+    static fromFile(file: string): CapabilityRegistry;
+    /**
+     * Merge every discovered artifact into one registry.
+     *
+     * ANY unreadable file fails the whole load, deliberately. Skipping one and carrying on
+     * would leave a registry that answers "no such capability" for a product that exists —
+     * a confident wrong answer, which is worse than the caller-visible absence of the whole
+     * surface (which `register.ts` logs a reason for).
+     */
+    static fromFiles(files: string[]): CapabilityRegistry;
+    /** The single product's build id, or `name:id` pairs when several are loaded. */
+    get buildId(): string;
+    productNames(): string[];
+    /** 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.
+     *
+     * 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
+     * working from stale search output needs to know to search again, not to retry.
+     */
+    byEndpointLookup(method: string, path: string, product?: string): {
+        product: string;
+        capability: Capability;
+    };
+}
+/**
+ * Resolve a `{$response|$schema: "Name"}` reference against the product's lookup tables.
+ *
+ * ONE HOP. The named component it returns may itself contain references — 39 of tm's 53
+ * named responses do — so this is the primitive, not the whole job. Use `resolveResponses`
+ * to get a tree with nothing left to look up.
+ *
+ * A node that is not a reference is returned as-is, and an unresolvable name yields
+ * `undefined` rather than throwing: the tables are additive and their absence means "no
+ * response schema available".
+ */
+export declare function resolveComponent<T extends ResponseDoc | SchemaNode>(product: ProductIndex, node: T | undefined): T | undefined;
+/**
+ * Resolve every reference in a tree, however deep.
+ *
+ * REFERENCES ARE NESTED, which is the part a one-hop reader gets wrong. They appear at the
+ * top of a response (`{"$response": "BadRequest"}`), on its schema
+ * (`.../schema/{"$schema": "TestCaseListResponse"}`), and inside the schema's own
+ * properties (`.../schema/properties/data/properties/folder`). Chains are real too: a
+ * capability's 400 resolves to the named `BadRequest`, whose schema is `{"$schema":
+ * "ErrorResponse"}`.
+ *
+ * AN UNRESOLVABLE REFERENCE IS LEFT IN PLACE, not dropped and not thrown on. A dangling
+ * name (the tables are built separately from the capabilities) or a cycle (a folder whose
+ * schema contains folders) then shows up as the `{"$schema": "…"}` node it is, which a
+ * reader can still act on, rather than as a silently truncated schema.
+ */
+export declare function resolveDeep<T>(product: ProductIndex, node: T): T;
+/** Which declared responses to hand back. */
+export type ResponseSelection = "success" | "all" | "none";
+/**
+ * A capability's declared responses with every reference followed.
+ *
+ * SUCCESS ONLY BY DEFAULT. The error entries are near-identical across the surface — 148 of
+ * 173 capabilities declare the same `InternalServerError`, and all of them bottom out in
+ * one `ErrorResponse` schema — so including them multiplies a search payload by 6.4x to
+ * repeat boilerplate the caller learns from the actual failure anyway. The 2xx entry is the
+ * one that says what a successful call returns, which is what a caller needs BEFORE calling.
+ *
+ * Returns undefined when the capability declares none — which is every capability in an
+ * index built before the response tables were added, and is not an error.
+ */
+export declare function resolveResponses(product: ProductIndex, capability: Capability, selection?: ResponseSelection): Record<string, ResponseDoc> | undefined;

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

@@ -0,0 +1,314 @@
+/**
+ * Load the index artifact(s) and expose the lookups the tools need.
+ *
+ * ONE FILE PER PRODUCT is the released contract, so loading is a merge across files. The
+ * merged model keeps the products map the rest of the server already reads, which is what
+ * lets searchCapability rank across products from N single-product files.
+ */
+import { readFileSync } from "node:fs";
+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 {
+}
+/** The file inside a product subdirectory, for the earlier nested layout. */
+export const INDEX_FILE = "index.json";
+/** The stored layout, and the name the export publishes: `<product>.capability-index.json`. */
+export const FLAT_SUFFIX = ".capability-index.json";
+/**
+ * The product a file's LOCATION claims to describe, if its layout says so.
+ *
+ * `capability/tm.capability-index.json` and `capability/tm/index.json` both name their
+ * product, and
+ * `fromFiles` cross-checks that against the product key inside. A file in the wrong place
+ * would otherwise register its product under the directory's name and answer for endpoints
+ * it does not have.
+ */
+export function productFromPath(file) {
+    const base = basename(file);
+    if (base.endsWith(FLAT_SUFFIX))
+        return base.slice(0, -FLAT_SUFFIX.length);
+    if (base === INDEX_FILE)
+        return basename(dirname(file));
+    return undefined;
+}
+export function endpointKey(method, path) {
+    return `${(method || "").trim().toUpperCase()} ${(path || "").trim()}`;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Read one artifact file into the product it carries.
+ *
+ * SHAPE DETECTION, NOT VERSION DETECTION. The released envelope and the pre-release one
+ * both declare `schema_version: 1`, so the number cannot tell them apart; the `products`
+ * wrapper can, and is the documented discriminator. The pre-release branch is defensive
+ * only — that shape was never deployed.
+ */
+export function readIndexFile(raw, source = "index") {
+    if (!isPlainObject(raw)) {
+        throw new IndexError(`${source}: expected a JSON object`);
+    }
+    if (raw.schema_version !== SUPPORTED_SCHEMA_VERSION) {
+        // Refuse rather than best-effort read: a shape change the generator announced is
+        // exactly the case where guessing produces silently wrong tool output.
+        throw new IndexError(`${source}: unsupported index schema_version ${raw.schema_version}; this build reads ` +
+            `${SUPPORTED_SCHEMA_VERSION}. Rebuild the artifact or update the server.`);
+    }
+    const provenance = {
+        build_id: typeof raw.build_id === "string" ? raw.build_id : "",
+        ...(typeof raw.version === "string" ? { version: raw.version } : {}),
+    };
+    if (isPlainObject(raw.products)) {
+        // Pre-release shape. Never deployed; recognised so a stray file reads rather than
+        // failing in a way that looks like a corrupt artifact.
+        const entries = Object.entries(raw.products);
+        if (entries.length === 0)
+            throw new IndexError(`${source}: contains no products`);
+        if (entries.length > 1) {
+            throw new IndexError(`${source}: carries ${entries.length} products; one file describes one product`);
+        }
+        const [name, product] = entries[0];
+        return {
+            name,
+            product: asProduct(product, `${source}:${name}`),
+            provenance,
+        };
+    }
+    // Released shape: exactly one key that is not part of the envelope.
+    const envelope = new Set(ENVELOPE_KEYS);
+    const entries = Object.entries(raw).filter(([key, value]) => !envelope.has(key) && isPlainObject(value));
+    if (entries.length === 0) {
+        throw new IndexError(`${source}: no product object found; expected one top-level key besides ` +
+            `${[...envelope].join(", ")}`);
+    }
+    if (entries.length > 1) {
+        throw new IndexError(`${source}: found ${entries.length} candidate product keys ` +
+            `(${entries
+                .map(([key]) => key)
+                .sort()
+                .join(", ")}); one file describes one product`);
+    }
+    const [name, product] = entries[0];
+    return { name, product: asProduct(product, `${source}:${name}`), provenance };
+}
+function asProduct(value, source) {
+    if (!isPlainObject(value) || !Array.isArray(value.capabilities)) {
+        throw new IndexError(`${source}: product object has no capabilities[]`);
+    }
+    return value;
+}
+export class CapabilityRegistry {
+    index;
+    /** product -> provenance of the file it came from. */
+    provenance;
+    /** product -> "METHOD /path" -> capability */
+    byEndpoint = 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 ` +
+                `${SUPPORTED_SCHEMA_VERSION}. Rebuild the artifact or update the server.`);
+        }
+        if (!index.products || Object.keys(index.products).length === 0) {
+            throw new IndexError("index contains no products");
+        }
+        this.index = index;
+        this.provenance = provenance;
+        for (const [product, bundle] of Object.entries(index.products)) {
+            const lookup = new Map();
+            for (const capability of bundle.capabilities) {
+                lookup.set(endpointKey(capability.method, capability.path), capability);
+            }
+            this.byEndpoint.set(product, lookup);
+        }
+    }
+    static fromFile(file) {
+        return CapabilityRegistry.fromFiles([file]);
+    }
+    /**
+     * Merge every discovered artifact into one registry.
+     *
+     * ANY unreadable file fails the whole load, deliberately. Skipping one and carrying on
+     * would leave a registry that answers "no such capability" for a product that exists —
+     * a confident wrong answer, which is worse than the caller-visible absence of the whole
+     * surface (which `register.ts` logs a reason for).
+     */
+    static fromFiles(files) {
+        if (files.length === 0)
+            throw new IndexError("no index files to load");
+        const products = {};
+        const provenance = {};
+        for (const file of files) {
+            let parsed;
+            try {
+                parsed = JSON.parse(readFileSync(file, "utf8"));
+            }
+            catch (error) {
+                throw new IndexError(`${file}: could not be read as JSON (${error instanceof Error ? error.message : String(error)})`);
+            }
+            const loaded = readIndexFile(parsed, file);
+            const claimed = productFromPath(file);
+            if (claimed && claimed !== loaded.name) {
+                // The name is stated twice — by the path and by the key inside — and they must
+                // agree. Trusting either one alone would serve a product's endpoints under the
+                // other's name, and every search result would then point at the wrong host.
+                throw new IndexError(`${file}: is stored as product '${claimed}' but declares '${loaded.name}'`);
+            }
+            if (products[loaded.name]) {
+                // Two files claiming one product cannot both be right, and picking one silently
+                // decides which endpoints exist.
+                throw new IndexError(`product '${loaded.name}' is declared by more than one index file; ${file} is a duplicate`);
+            }
+            products[loaded.name] = loaded.product;
+            provenance[loaded.name] = loaded.provenance;
+        }
+        return new CapabilityRegistry({
+            schema_version: SUPPORTED_SCHEMA_VERSION,
+            build_id: compositeBuildId(provenance),
+            products,
+        }, provenance);
+    }
+    /** The single product's build id, or `name:id` pairs when several are loaded. */
+    get buildId() {
+        return this.index.build_id;
+    }
+    productNames() {
+        return Object.keys(this.index.products).sort();
+    }
+    /** Per-product `{build_id, version}`, for logging and cache-busting only. */
+    buildInfo() {
+        return this.provenance;
+    }
+    /**
+     * Find a capability by the endpoint it exposes — the published handle.
+     *
+     * 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
+     * working from stale search output needs to know to search again, not to retry.
+     */
+    byEndpointLookup(method, path, product) {
+        const key = endpointKey(method, path);
+        const matches = [];
+        for (const [name, lookup] of this.byEndpoint) {
+            if (product && name !== product)
+                continue;
+            const capability = lookup.get(key);
+            if (capability)
+                matches.push({ product: name, capability });
+        }
+        if (matches.length === 0) {
+            throw new InvocationError(`unknown_endpoint: ${key}. Search again — send \`method\` and \`path\` exactly as ` +
+                `searchCapability returned them, placeholders included.`);
+        }
+        if (matches.length > 1 && !product) {
+            const owners = matches
+                .map((m) => m.product)
+                .sort()
+                .join(", ");
+            throw new InvocationError(`${key} exists in several products (${owners}); pass product`);
+        }
+        return matches[0];
+    }
+}
+function compositeBuildId(provenance) {
+    const names = Object.keys(provenance).sort();
+    if (names.length === 1)
+        return provenance[names[0]].build_id;
+    return names.map((name) => `${name}:${provenance[name].build_id}`).join(" ");
+}
+/**
+ * Resolve a `{$response|$schema: "Name"}` reference against the product's lookup tables.
+ *
+ * ONE HOP. The named component it returns may itself contain references — 39 of tm's 53
+ * named responses do — so this is the primitive, not the whole job. Use `resolveResponses`
+ * to get a tree with nothing left to look up.
+ *
+ * A node that is not a reference is returned as-is, and an unresolvable name yields
+ * `undefined` rather than throwing: the tables are additive and their absence means "no
+ * response schema available".
+ */
+export function resolveComponent(product, node) {
+    if (!node || typeof node !== "object")
+        return node;
+    const ref = node;
+    if (typeof ref.$response === "string") {
+        return product.responses?.[ref.$response];
+    }
+    if (typeof ref.$schema === "string") {
+        return product.schemas?.[ref.$schema];
+    }
+    return node;
+}
+/**
+ * Resolve every reference in a tree, however deep.
+ *
+ * REFERENCES ARE NESTED, which is the part a one-hop reader gets wrong. They appear at the
+ * top of a response (`{"$response": "BadRequest"}`), on its schema
+ * (`.../schema/{"$schema": "TestCaseListResponse"}`), and inside the schema's own
+ * properties (`.../schema/properties/data/properties/folder`). Chains are real too: a
+ * capability's 400 resolves to the named `BadRequest`, whose schema is `{"$schema":
+ * "ErrorResponse"}`.
+ *
+ * AN UNRESOLVABLE REFERENCE IS LEFT IN PLACE, not dropped and not thrown on. A dangling
+ * name (the tables are built separately from the capabilities) or a cycle (a folder whose
+ * schema contains folders) then shows up as the `{"$schema": "…"}` node it is, which a
+ * reader can still act on, rather than as a silently truncated schema.
+ */
+export function resolveDeep(product, node) {
+    return resolveNode(product, node, new Set());
+}
+function resolveNode(product, node, seen) {
+    if (Array.isArray(node)) {
+        return node.map((item) => resolveNode(product, item, seen));
+    }
+    if (typeof node !== "object" || node === null)
+        return node;
+    const ref = node;
+    const kind = typeof ref.$response === "string"
+        ? "$response"
+        : typeof ref.$schema === "string"
+            ? "$schema"
+            : undefined;
+    if (kind) {
+        const name = (kind === "$response" ? ref.$response : ref.$schema);
+        const key = `${kind}:${name}`;
+        const target = kind === "$response"
+            ? product.responses?.[name]
+            : product.schemas?.[name];
+        // Leave the reference visible when it cannot be followed, or when following it would
+        // revisit a name already on this path.
+        if (!target || seen.has(key))
+            return node;
+        return resolveNode(product, target, new Set([...seen, key]));
+    }
+    const out = {};
+    for (const [field, value] of Object.entries(node)) {
+        out[field] = resolveNode(product, value, seen);
+    }
+    return out;
+}
+/**
+ * A capability's declared responses with every reference followed.
+ *
+ * SUCCESS ONLY BY DEFAULT. The error entries are near-identical across the surface — 148 of
+ * 173 capabilities declare the same `InternalServerError`, and all of them bottom out in
+ * one `ErrorResponse` schema — so including them multiplies a search payload by 6.4x to
+ * repeat boilerplate the caller learns from the actual failure anyway. The 2xx entry is the
+ * one that says what a successful call returns, which is what a caller needs BEFORE calling.
+ *
+ * Returns undefined when the capability declares none — which is every capability in an
+ * index built before the response tables were added, and is not an error.
+ */
+export function resolveResponses(product, capability, selection = "success") {
+    if (selection === "none" || !capability.responses)
+        return undefined;
+    const wanted = selection === "all"
+        ? Object.entries(capability.responses)
+        : Object.entries(capability.responses).filter(([status]) => status.startsWith("2"));
+    if (wanted.length === 0)
+        return undefined;
+    return resolveDeep(product, Object.fromEntries(wanted));
+}

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

@@ -0,0 +1,34 @@
+/**
+ * The tool surface: four discovery tools plus ONE invoke tool.
+ *
+ * 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`
+ * enforced HERE rather than on a client-side hint — which is the one thing a separate
+ * read/write tool pair was buying.
+ */
+import { McpServer, RegisteredTool } from "@modelcontextprotocol/sdk/server/mcp.js";
+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"];
+export interface RegistryDeps {
+    registry: CapabilityRegistry;
+    /**
+     * 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>;
+    credentialsFor: () => Credentials;
+    transport?: Transport;
+}
+/**
+ * The tool-adder the server factory calls.
+ *
+ * Registers NOTHING when the artifact is absent or unreadable, rather than throwing: a
+ * missing index is a packaging problem, and taking the whole MCP server down with it would
+ * remove every other product's tools too. The reason is logged so it is not silent.
+ */
+export declare function addCapabilityRegistryToolsFromConfig(server: McpServer, config: BrowserStackConfig): Record<string, RegisteredTool>;
+export declare function addCapabilityRegistryTools(server: McpServer, deps: RegistryDeps, config?: BrowserStackConfig): Record<string, RegisteredTool>;
+export default addCapabilityRegistryToolsFromConfig;