@browserstack/mcp-server 1.5.1 → 2.0.0

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): Promise<InvokeResult>;

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

@@ -0,0 +1,83 @@
+/**
+ * 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 { bind } from "./bind.js";
+import { authHeaders } from "./egress.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) {
+    if (!baseUrl)
+        throw new InvocationError("no base URL is configured for that product");
+    assertTransportSafe(baseUrl);
+    const bound = bind(capability, args);
+    const headers = authHeaders(credentials, auth);
+    const response = await transport(capability.method, `${baseUrl.replace(/\/$/, "")}${bound.path}`, headers, bound.query, bound.body);
+    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/search.d.ts

@@ -0,0 +1,170 @@
+/**
+ * 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;
+}
+/** Which products a query could plausibly be about, when more than one could. */
+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[];
+}
+/**
+ * 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;