@browserstack/mcp-server 1.5.1-beta.2 → 2.0.0-beta.1

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

@@ -0,0 +1,38 @@
+/**
+ * Invoke one endpoint and hand back what the product said.
+ *
+ * NO POST-PROCESSING, BY DECISION. There used to be row extraction by shape, a `returns`
+ * allowlist, a scalars-only filter for undeclared schemas, item counting, ordering, trimming,
+ * and guards that reported an empty projection as a registration defect. Every one of them
+ * was a place where we could be wrong ABOUT a correct answer — and each time we were, the
+ * caller saw a confident empty result rather than an error. The product's response is the
+ * answer; this module's job is to get it and return it.
+ *
+ * ONE REQUEST, ONE RESPONSE. Paging is therefore the caller's, which is why `p` and the
+ * page-size parameter are published for paginated endpoints (see `project.py::_is_public`).
+ * Hiding them made sense only while this module walked the pages itself.
+ */
+import { GroupedArguments } from "./bind.js";
+import { Credentials, Transport } from "./egress.js";
+import { AuthScheme } from "./types.js";
+import { Capability } from "./types.js";
+export interface InvokeResult {
+    /** The product answered 2xx. Nothing else decides this. */
+    ok: boolean;
+    /**
+     * Whether this response is the whole answer.
+     *
+     * False when the envelope itself says there is another page (`info.next`), so a caller
+     * knows to ask for one rather than assuming it has everything. This is a peek at one
+     * declared field, not a reshaping of the body.
+     */
+    completed: boolean;
+    /** The product's status, and its body exactly as sent. */
+    http_response: {
+        status: number;
+        body: unknown;
+        /** Only when there was no response at all to speak for itself. */
+        error?: string;
+    };
+}
+export declare function invoke(capability: Capability, args: GroupedArguments, baseUrl: string, credentials: Credentials, transport: Transport, auth?: AuthScheme, product?: string): Promise<InvokeResult>;

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

@@ -0,0 +1,104 @@
+/**
+ * Invoke one endpoint and hand back what the product said.
+ *
+ * NO POST-PROCESSING, BY DECISION. There used to be row extraction by shape, a `returns`
+ * allowlist, a scalars-only filter for undeclared schemas, item counting, ordering, trimming,
+ * and guards that reported an empty projection as a registration defect. Every one of them
+ * was a place where we could be wrong ABOUT a correct answer — and each time we were, the
+ * caller saw a confident empty result rather than an error. The product's response is the
+ * answer; this module's job is to get it and return it.
+ *
+ * ONE REQUEST, ONE RESPONSE. Paging is therefore the caller's, which is why `p` and the
+ * page-size parameter are published for paginated endpoints (see `project.py::_is_public`).
+ * Hiding them made sense only while this module walked the pages itself.
+ */
+import { invalidateToken } from "../../lib/central-oauth.js";
+import { bind } from "./bind.js";
+import { authHeaders } from "./egress.js";
+import { resolveScope, resolveTokenUrl } from "./oauth.js";
+import { InvocationError } from "./index-loader.js";
+function hasNextPage(body) {
+    if (typeof body !== "object" || body === null || Array.isArray(body))
+        return false;
+    const info = body.info;
+    if (typeof info !== "object" || info === null)
+        return false;
+    const next = info.next;
+    return next !== null && next !== undefined && next !== false;
+}
+/**
+ * Refuse to send credentials anywhere but over TLS.
+ *
+ * The very next thing `invoke` does is attach the caller's long-lived
+ * `username:access_key` to the request, and the host it attaches them to comes from an
+ * environment variable, account discovery or the index's own `base_url` — none of which
+ * was checked for a scheme. An operator typo of `http://` put those credentials on the
+ * wire in clear text, and nothing anywhere said no.
+ *
+ * Not attacker-controlled today: the index ships inside the package and the environment
+ * variables are operator-set. This is the cheap guard on the one path that forwards a
+ * credential, not a response to a known attack. `egress.authHeaders` already refuses
+ * `auth.in: "query"` so credentials never land in a URL; this is the same concern one
+ * layer up.
+ *
+ * `localhost` and `127.0.0.1` are exempt so a local product server can still be driven
+ * without a certificate.
+ */
+function assertTransportSafe(baseUrl) {
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        throw new InvocationError(`the configured base URL is not a valid URL: ${JSON.stringify(baseUrl)}`);
+    }
+    if (url.protocol === "https:")
+        return;
+    const local = url.hostname === "localhost" ||
+        url.hostname === "127.0.0.1" ||
+        url.hostname === "[::1]";
+    if (url.protocol === "http:" && local)
+        return;
+    throw new InvocationError(`refusing to send credentials over ${url.protocol}//${url.host}: this request ` +
+        `carries your BrowserStack access key, so the base URL must be https (or a local ` +
+        `host for development). Check CAPABILITY_REGISTRY_BASE_URL_* for a typo.`);
+}
+export async function invoke(capability, args, baseUrl, credentials, transport, auth, product) {
+    if (!baseUrl)
+        throw new InvocationError("no base URL is configured for that product");
+    assertTransportSafe(baseUrl);
+    const bound = bind(capability, args);
+    // Before binding would be wrong and after sending is too late: a scheme that mints a
+    // token must not spend a round trip on a call that `bind` was going to reject anyway.
+    const url = `${baseUrl.replace(/\/$/, "")}${bound.path}`;
+    const send = async () => transport(capability.method, url, await authHeaders(credentials, auth, product), bound.query, bound.body);
+    let response = await send();
+    /**
+     * One replay, for a minted token the product rejected.
+     *
+     * The expiry skirt covers clock skew; it does not cover a token revoked mid-life, and a
+     * cached one can outlive its welcome by up to its whole lifetime. Discarding it and
+     * retrying once turns that from a failed call into a slow one.
+     *
+     * SAFE TO REPLAY EVEN FOR A WRITE: a 401 means the request was never authorised, so
+     * nothing was changed. Once only — with genuinely bad credentials the second attempt
+     * fails identically, and a loop here would hammer the token endpoint on every wrong
+     * password.
+     */
+    if (response.status === 401 && auth?.type === "oauth2") {
+        invalidateToken(resolveTokenUrl(product ?? "this product", auth), resolveScope(auth), credentials);
+        response = await send();
+    }
+    const ok = response.status >= 200 && response.status < 300;
+    return {
+        ok,
+        completed: ok && !hasNextPage(response.body),
+        http_response: {
+            status: response.status,
+            body: response.body,
+            ...(response.status === 0
+                ? { error: response.error || "the product could not be reached" }
+                : {}),
+        },
+    };
+}

package/dist/tools/capability-registry/routing-token.d.ts

@@ -0,0 +1,25 @@
+/** What a routing call concluded about the user's request. */
+export interface RoutingVerdict {
+    /** `clash`: several products claim it. `blank`: no product's words at all. `settled`: one. */
+    verdict: "clash" | "blank" | "settled";
+    /** The product it settled on, for `settled`. */
+    product?: string;
+    /** The shared words, for `clash` — what the user has to be asked about. */
+    terms?: string[];
+    /** Issued-at, epoch seconds. */
+    iat: number;
+}
+/** Tokens outlive a turn, not a sitting. Long enough to answer a question, not to bank. */
+export declare const TOKEN_TTL_SECONDS: number;
+/** Sign a verdict into an opaque token the caller hands back. */
+export declare function signRouting(verdict: Omit<RoutingVerdict, "iat"> & {
+    iat?: number;
+}): string;
+/**
+ * Read a token back, or `undefined` if it was not issued here, was edited, or has expired.
+ *
+ * Every failure returns the same nothing on purpose: a caller learning WHY its token was
+ * rejected learns how to build a better one, and there is no legitimate caller that needs
+ * to know the difference.
+ */
+export declare function readRouting(token: string | undefined, now?: number): RoutingVerdict | undefined;

package/dist/tools/capability-registry/routing-token.js

@@ -0,0 +1,87 @@
+/**
+ * The routing step's verdict, signed so it can be handed back instead of remembered.
+ *
+ * The gate needs to know what the LAST routing call concluded — whether the request
+ * clashed, or settled, and on what. That is a fact about the conversation, and a tool call
+ * carries no conversation, so the server kept it: a set of unspent tokens and the listing's
+ * last verdict, both living for the life of the connection. Under stdio that is one process
+ * per client and harmless; it stops being harmless the moment one process serves several
+ * sessions, where a single shared `settledByListing` lets one client's listing satisfy
+ * another client's gate.
+ *
+ * So the verdict travels with the caller instead. It is signed with a per-process secret,
+ * which is what keeps it honest: the caller cannot mint one, cannot edit the product inside
+ * it, and cannot produce one at all without having made the routing call that issues it.
+ * Verification is recomputation — there is nothing to store, nothing to grow, and nothing
+ * to leak between sessions.
+ *
+ * WHAT THIS CANNOT DO, stated plainly: it proves a routing call happened and what it said.
+ * It cannot prove a human answered. Nothing a caller transmits can. A caller that reworded
+ * its request and ran discovery again on the new words holds a genuine token for a verdict
+ * it manufactured — closing THAT needs memory of the first question, which is the thing
+ * being removed here. `user_words`, checked against the index, remains the part that
+ * carries what the user actually said.
+ */
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+/**
+ * Per process, and deliberately not persisted.
+ *
+ * A restart invalidates every outstanding token, which is the right behaviour: a new
+ * process is a new conversation, and a verdict from the last one says nothing about this
+ * one. It also means nothing has to be configured to run the server.
+ */
+const SECRET = randomBytes(32);
+/** Tokens outlive a turn, not a sitting. Long enough to answer a question, not to bank. */
+export const TOKEN_TTL_SECONDS = 60 * 30;
+const b64 = (b) => b.toString("base64url");
+function seal(payload) {
+    return createHmac("sha256", SECRET).update(payload).digest("base64url");
+}
+/** Sign a verdict into an opaque token the caller hands back. */
+export function signRouting(verdict) {
+    const body = {
+        ...verdict,
+        iat: verdict.iat ?? Math.floor(Date.now() / 1000),
+    };
+    const payload = b64(Buffer.from(JSON.stringify(body)));
+    return `${payload}.${seal(payload)}`;
+}
+/**
+ * Read a token back, or `undefined` if it was not issued here, was edited, or has expired.
+ *
+ * Every failure returns the same nothing on purpose: a caller learning WHY its token was
+ * rejected learns how to build a better one, and there is no legitimate caller that needs
+ * to know the difference.
+ */
+export function readRouting(token, now = Math.floor(Date.now() / 1000)) {
+    if (!token)
+        return undefined;
+    const cut = token.lastIndexOf(".");
+    if (cut <= 0)
+        return undefined;
+    const payload = token.slice(0, cut);
+    const signature = token.slice(cut + 1);
+    const expected = Buffer.from(seal(payload));
+    const given = Buffer.from(signature);
+    // Length has to match before timingSafeEqual will look at the bytes, and comparing
+    // lengths first leaks only the length, which the caller already knows.
+    if (expected.length !== given.length)
+        return undefined;
+    if (!timingSafeEqual(expected, given))
+        return undefined;
+    try {
+        const body = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+        if (typeof body?.iat !== "number")
+            return undefined;
+        if (now - body.iat > TOKEN_TTL_SECONDS)
+            return undefined;
+        if (body.verdict !== "clash" &&
+            body.verdict !== "blank" &&
+            body.verdict !== "settled")
+            return undefined;
+        return body;
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -0,0 +1,197 @@
+/**
+ * Ranking capabilities against a plain-language query.
+ *
+ * Ported from the Python `discover._score`, including the two properties that were each
+ * fixed after a live mis-ranking:
+ *
+ *  * PENALTIES REORDER, THEY DO NOT EXCLUDE. `matched` is the pre-penalty term score and is
+ *    what decides inclusion; `ranked` carries the preferences. Conflating them dropped 40
+ *    legitimate matches outright, because a cardinality penalty took an otherwise-valid
+ *    score to zero and the caller saw "no such capability".
+ *  * 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 { Capability, Mode, ProductIndex } from "./types.js";
+/**
+ * Query/haystack terms. Verbs are deliberately NOT stopwords — they carry the intent.
+ *
+ * camelCase is split before lowercasing, so `testRunId`, `test_run_id` and `test run id`
+ * all tokenize alike.
+ */
+/**
+ * Is this the browse wildcard rather than a search?
+ *
+ * Accepts `*` and `all` — both are what a caller reaches for when the intent is "show me
+ * everything", and treating only one of them as the wildcard means the other silently
+ * becomes a bad search. Whitespace is tolerated so a pasted value still works.
+ */
+export declare function isBrowseQuery(query?: string): boolean;
+export declare function terms(text: string | undefined): string[];
+/**
+ * A term plus its naive singular variants.
+ *
+ * QUERY SIDE ONLY, which is what makes this cheap and safe. Matching is one-directional
+ * substring containment, so indexed `attachments` already contains a query of `attachment`;
+ * only the reverse — a plural query against singular text — needs help. Stemming the
+ * indexed side too would mean rewriting the product's own vocabulary to guess at English,
+ * for no additional match.
+ */
+export declare function termForms(term: string): string[];
+/**
+ * ONE canonical spelling of a word, so two spellings of a noun cannot look like two terms.
+ *
+ * `termForms` is deliberately generous — it offers every candidate and lets substring
+ * containment sort them out. Canonicalising needs the opposite: exactly one answer, and
+ * the right one. Taking the SHORTEST candidate is what a first cut did, and it folded
+ * `cases` to `cas`, so the vocabulary entry `test case` matched no query containing "test
+ * cases" — the phrase it exists for. The ambiguity check then fell through to `test`
+ * alone, reaching the right verdict by the wrong route.
+ *
+ * Strip `es` only after a sibilant, where English actually inserts it (`boxes`,
+ * `batches`, `statuses`). Otherwise strip the single `s`, which is right for the `-e`
+ * plurals this vocabulary is full of: case, suite, phase, template.
+ */
+export declare function singular(word: string): string;
+export declare function modeHint(query: string | undefined): "" | Mode;
+export declare function wantsCollection(query: string | undefined): boolean;
+/**
+ * True when a capability answers with many records rather than one.
+ *
+ * Pagination is the reliable signal — a paged operation is a listing by construction. The
+ * plural terminal path segment is a weaker fallback for unpaged collections. (The Python
+ * side used the capability NAME here. tm now publishes one, but its verbs are not
+ * consistent — the endpoint that lists folders is `list_root_folders` — so the path's
+ * terminal noun remains the better signal.)
+ */
+export declare function isCollection(capability: Capability): boolean;
+/**
+ * One ranked match, WITH the product it belongs to.
+ *
+ * Attribution is not decoration: the response tables are per product, so dereferencing a
+ * hit's schemas needs to know whose tables to read. It is also what lets a caller pass
+ * `product` to invokeCapability when two products share an endpoint — until now search
+ * ranked across products and then threw away the only thing that could disambiguate them.
+ */
+export interface SearchHit {
+    product: string;
+    capability: Capability;
+}
+export interface SearchResult {
+    hits: SearchHit[];
+    truncated: boolean;
+    total_matched: number;
+    /**
+     * Where this page started, and where the next one begins.
+     *
+     * `truncated` has always said more matched than fit; nothing said how to reach it, so
+     * the only way past the first page was to raise `limit` and re-read everything already
+     * seen. `next_offset` is absent on the last page, which is what makes "walk until it
+     * stops" terminate without the caller comparing counts.
+     */
+    offset: number;
+    next_offset?: number;
+    /** True when the query was the browse wildcard rather than a search. */
+    browse?: boolean;
+    /**
+     * The best pre-penalty term score, and whether it is weak enough to doubt.
+     *
+     * A vocabulary miss does NOT look like a miss from the outside: "make a new bucket for my
+     * tests" returns a full page of eight confident hits, exactly like a query that worked,
+     * because containment finds *something* for `make`, `new` and `tests`. The only thing that
+     * separates them is how little the match is worth.
+     */
+    top_matched: number;
+    /** `top_matched` as a fraction of a perfect match — the corpus-independent form. */
+    coverage: number;
+    weak: boolean;
+}
+export interface ProductAmbiguity {
+    /** The products that claim the query's words. Empty when the query settles itself. */
+    products: string[];
+    /** The shared vocabulary that caused it — what to put in front of the user. */
+    terms: string[];
+    /** The one product the query's own words point at, when they point at exactly one. */
+    settled?: string;
+    /** The words that pointed there — the evidence for `settled`. */
+    because?: string[];
+    /** No word in the request belongs to ANY product: there is nothing to route on. */
+    unknown?: boolean;
+}
+/**
+ * Products whose OWN vocabulary the query hits, when no word in the query settles it.
+ *
+ * Requiring `product` made every CALL unambiguous and did nothing about the agent making
+ * two of them: "list all projects" was answered by searching tm, then Load Testing, then
+ * merging — a question about which product the user meant, answered by guessing both.
+ * Tool-description prose asking the agent to check with the user is a suggestion it is
+ * free to decline, and declining is cheaper than interrupting someone.
+ *
+ * WHOLE VOCABULARY ENTRIES, never their constituent words. Splitting them makes almost
+ * everything look shared: Load Testing's "load test" and tm's "test case" both yield
+ * `test`, which flagged 135 of the 198 eval queries. Matching entries whole flags 27.
+ *
+ * A UNIQUE TERM SETTLES IT. "create a test case in a folder" contains `folder`, which
+ * both products claim, and `test case`, which only tm does — so the query has already
+ * answered the question and there is nothing to ask. Only queries whose every recognised
+ * word is shared are genuinely undecided.
+ */
+export declare function ambiguousProducts(products: Record<string, ProductIndex>, query: string | undefined): ProductAmbiguity;
+/** One entity's caller-facing vocabulary: what it is called, and what else it is called. */
+export interface VocabularyEntry {
+    entity: string;
+    description?: string;
+    aliases?: string[];
+}
+/**
+ * The product's vocabulary, for a caller whose words are not the product's words.
+ *
+ * THE ONE FAILURE LEXICAL SEARCH CANNOT FIX. "make a new bucket for my tests" wants the
+ * folder-create capability, and `bucket` appears nowhere in the index — no scoring change
+ * reaches it, because the word is simply absent. What CAN reach it is the caller: it is a
+ * language model, and given tm's entity list it maps bucket -> folder without effort. It
+ * just cannot guess the list unprompted.
+ *
+ * Aliases and a one-line `description`; `title` stays dropped as a near-duplicate of
+ * `entity` ("Test run" next to `test_run` buys nothing). Aliases alone route but do not
+ * DEFINE — `result -> outcome, execution-result, test-result` never says whether that is
+ * the per-case verdict inside a run or a run-level rollup — so an agent holding names and
+ * aliases has exactly one way to find out, which is describeEntity once per entity. For
+ * tm that is 19 calls at ~1.4KB each, ~27KB, to answer what ~1.6KB of description answers
+ * here for every entity at once. The `key_facts` remain out: ten times the size, and the
+ * caller can ask describeEntity for the one entity it settles on.
+ *
+ * Its share of the response grew when search became a shortlist: 3.2KB against a 38KB full
+ * search was 8%, against a 6.8KB shortlist it is nearly half. The absolute cost did not
+ * change and is still under a thousand tokens — far less than one wrong invoke — so this
+ * is budgeted in bytes rather than as a fraction of a baseline that now moves.
+ */
+export declare function vocabularyOf(products: Record<string, ProductIndex>, only?: string): Record<string, VocabularyEntry[]>;
+export declare function searchCapabilities(products: Record<string, ProductIndex>, query?: string, options?: {
+    entity?: string;
+    product?: string;
+    mode?: Mode;
+    limit?: number;
+    offset?: number;
+}): SearchResult;
+export interface ProductAnchor {
+    /** Products the quoted words point at, through a word only that product claims. */
+    products: string[];
+    /** The words that did the anchoring, so a refusal can quote them back. */
+    terms: string[];
+}
+/**
+ * Which products the USER'S OWN WORDS name, directly or through vocabulary only one
+ * product claims.
+ *
+ * This is the other half of `ambiguousProducts`. That one asks "is the query a word both
+ * products use?"; this asks "did the user say anything that settles it?" — and it reads
+ * the user's text, not a flag the caller sets about itself. A boolean saying the user
+ * confirmed is answered by whoever wants to proceed; a quote has to come from the
+ * conversation, and the words in it are checked against the index here.
+ *
+ * Anchors are of two kinds and both are needed. A product NAME ("test management",
+ * "observability") is the explicit case. A word only one product's vocabulary claims
+ * ("quality gate", "test plan") is the implicit one, and it is the common one: users say
+ * what they want, not which product owns it.
+ */
+export declare function productAnchors(products: Record<string, ProductIndex>, text: string | undefined): ProductAnchor;