@browserstack/mcp-server 1.4.0-beta.3 → 1.5.0-beta.10

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

@@ -0,0 +1,99 @@
+/**
+ * Which regional host does THIS account live on?
+ *
+ * Generalised from `lib/tm-base-url.ts`, which asks the question for Test Management by
+ * walking test-management{,-eu,-in}.browserstack.com and keeping the one that authenticates.
+ * The mechanism is not tm-specific — any product sharded by region answers the same way —
+ * so the candidate hosts move into the product's own index (`base_urls`) and this module
+ * performs the walk for all of them.
+ *
+ * A PROBE, NOT A LOOKUP. An account's data lives in exactly one region and the other regions
+ * reject its credentials, so the right host identifies itself. There is no mapping table to
+ * keep in sync, which is the point: a table would go stale silently.
+ */
+import appConfig from "../../config.js";
+import logger from "../../logger.js";
+import { authHeaders } from "./egress.js";
+import { InvocationError } from "./index-loader.js";
+/**
+ * Cached per product AND per user, so the answer cannot cross accounts.
+ *
+ * `lib/tm-base-url.ts` disables its cache entirely under REMOTE_MCP because a process-wide
+ * single slot would serve the first user's region to everyone after them. Keying by user
+ * fixes that by construction, so the cache stays useful in remote mode too.
+ */
+const cache = new Map();
+/** Exposed for tests; a long-lived process must not pin a stale region forever. */
+export function clearDiscoveryCache() {
+    cache.clear();
+}
+/**
+ * Pick the endpoint to probe with.
+ *
+ * An explicit `probe_path` in the index wins. Otherwise derive one, and derive it
+ * CONSERVATIVELY — the probe reads a 2xx as "this is the account's region", so an endpoint
+ * that can fail for a reason unrelated to region would walk straight past the right host:
+ *
+ *  * reads only, and never with a path placeholder — there is no id to supply yet;
+ *  * no required query parameters, for the same reason;
+ *  * paginated, because a paged listing is a primary collection by construction;
+ *  * nothing under /admin, which 403s for an ordinary user;
+ *  * shortest path, to prefer the root collection over its variants.
+ *
+ * For tm this lands on `/api/v1/projects`, the same family as the hand-written probe.
+ */
+export function probePath(source) {
+    if (source.probe_path)
+        return source.probe_path;
+    const usable = (source.capabilities || []).filter((capability) => capability.mode === "read" &&
+        capability.paginated &&
+        !capability.path.includes("{") &&
+        !capability.path.includes("/admin") &&
+        !(capability.query || []).some((param) => param.required));
+    usable.sort((a, b) => a.path.length - b.path.length || a.path.localeCompare(b.path));
+    return usable[0]?.path;
+}
+/**
+ * Return the first candidate host that accepts the caller's credentials.
+ *
+ * Probed with the SAME auth the real calls use (`Api-Token`), not a second scheme, so a
+ * host that answers here is one that will answer for the invocation that follows.
+ */
+export async function discoverBaseUrl(product, source, credentials, transport) {
+    const candidates = (source.base_urls || []).map((url) => url.replace(/\/$/, ""));
+    if (candidates.length === 0) {
+        throw new InvocationError(`product '${product}' declares no base_urls to probe`);
+    }
+    // One candidate is not a region question; skip the round trip.
+    if (candidates.length === 1)
+        return candidates[0];
+    const key = `${product}\n${credentials.username}`;
+    const cached = cache.get(key);
+    if (cached) {
+        logger.debug("using cached %s host for this account: %s", product, cached);
+        return cached;
+    }
+    const path = probePath(source);
+    if (!path) {
+        throw new InvocationError(`product '${product}' declares several base_urls but no endpoint to probe them with; ` +
+            `set probe_path in its index`);
+    }
+    // The same scheme the invocation will use, so a host that answers here answers there.
+    const headers = authHeaders(credentials, source.auth);
+    const failures = [];
+    for (const candidate of candidates) {
+        const response = await transport("GET", `${candidate}${path}`, headers, {});
+        if (response.status >= 200 && response.status < 300) {
+            // Under REMOTE_MCP the key already carries the user, so this is safe to keep.
+            if (!appConfig.REMOTE_MCP || credentials.username)
+                cache.set(key, candidate);
+            logger.info("resolved %s to %s for this account", product, candidate);
+            return candidate;
+        }
+        failures.push(`${candidate}: HTTP ${response.status || "unreachable"}`);
+    }
+    // Every region refused. Saying which, and with what, is the difference between a
+    // debuggable report and "it did not work".
+    throw new InvocationError(`could not determine which region this account's ${product} lives on. Probed ${path} ` +
+        `on each host — ${failures.join("; ")}`);
+}

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,133 @@
+/**
+ * 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;
+    /** 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;
+    /**
+     * 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 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
+     * 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;