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

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

@@ -0,0 +1,396 @@
+/**
+ * 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 { z } from "zod";
+import logger from "../../logger.js";
+import { trackMCP } from "../../lib/instrumentation.js";
+import { indexPaths, isEnabled, resolveBaseUrl } from "./config.js";
+import { fetchTransport } from "./egress.js";
+import { CapabilityRegistry, InvocationError, resolveResponses, } from "./index-loader.js";
+import { invoke } from "./resolve.js";
+import { searchCapabilities, vocabularyOf } from "./search.js";
+export const PERMISSION_VALUES = ["not_asked", "granted", "denied"];
+/**
+ * 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 function addCapabilityRegistryToolsFromConfig(server, config) {
+    if (!isEnabled()) {
+        logger.info("capability registry disabled by CAPABILITY_REGISTRY_DISABLED");
+        return {};
+    }
+    const files = indexPaths();
+    if (files.length === 0) {
+        logger.warn("capability registry index not found; its tools are not registered. Set " +
+            "CAPABILITY_REGISTRY_INDEX_DIR, or ship capabilities/<product>.capability-index.json " +
+            "at the package root.");
+        return {};
+    }
+    let registry;
+    try {
+        registry = CapabilityRegistry.fromFiles(files);
+    }
+    catch (error) {
+        // One unreadable file fails the whole load on purpose (see `fromFiles`), so this is
+        // the only place that decides the surface is absent, and it says why.
+        logger.error("capability registry index unusable (%s): %s", files.join(", "), error instanceof Error ? error.message : String(error));
+        return {};
+    }
+    const loaded = registry.buildInfo();
+    logger.info("capability registry loaded: %d product(s) — %s", registry.productNames().length, registry
+        .productNames()
+        .map((name) => `${name} build ${loaded[name]?.build_id || "?"}` +
+        (loaded[name]?.version ? ` v${loaded[name].version}` : ""))
+        .join(", "));
+    return addCapabilityRegistryTools(server, {
+        registry,
+        // The whole product bundle, not just its host: a region-sharded product declares
+        // several candidates and the probe needs an endpoint from its own capabilities.
+        baseUrlFor: (product) => resolveBaseUrl(product, config, registry.index.products[product]),
+        // Read per call, not captured: the remote server rebuilds config per session, so a
+        // captured credential would outlive the session it belongs to.
+        credentialsFor: () => ({
+            username: config["browserstack-username"],
+            accessKey: config["browserstack-access-key"],
+        }),
+    }, config);
+}
+function ok(payload) {
+    return { content: [{ type: "text", text: JSON.stringify(payload) }] };
+}
+function failed(message) {
+    return {
+        content: [
+            { type: "text", text: JSON.stringify({ ok: false, error: message }) },
+        ],
+        isError: true,
+    };
+}
+export function addCapabilityRegistryTools(server, deps, config) {
+    const { registry } = deps;
+    const productNames = registry.productNames();
+    /**
+     * The `product` argument, typed to what this build actually carries.
+     *
+     * An enum rather than a free string, so the accepted values travel in the SCHEMA the
+     * client validates against — the model sees them without spending a `listProducts` call,
+     * and a typo is rejected before the handler runs instead of coming back as a tool error.
+     * The set is fixed for the session because the index is read once at registration.
+     */
+    const productArg = () => productNames.length > 0
+        ? z.enum(productNames)
+        : z.string();
+    /** "tm, loadtesting" — for prose that has to name them. */
+    const productList = productNames.join(", ") || "none loaded";
+    /**
+     * One line per product, for the ONE tool whose job is routing between them.
+     *
+     * Only listProducts carries the summaries. They are authored prose of unbounded length —
+     * tm's is 90 characters, loadtesting's is 470 — and a tool description is static context
+     * on every request, so repeating them across five tools would cost more than the round
+     * trip they save. Everywhere else the names alone are what a caller needs.
+     *
+     * Each summary is cut to its first sentence and capped, and the whole catalog is
+     * budgeted: past the budget the names still route, which is the part that matters.
+     */
+    const productCatalog = (() => {
+        const lines = productNames.map((name) => {
+            const summary = registry.index.products[name].summary.trim();
+            const firstSentence = summary.split(/(?<=\.)\s/)[0] ?? summary;
+            const trimmed = firstSentence.length > 130
+                ? `${firstSentence.slice(0, 127).trimEnd()}…`
+                : firstSentence;
+            return `${name} — ${trimmed.replace(/\.$/, "")}`;
+        });
+        const joined = lines.join("; ");
+        return joined.length <= 500 ? joined : productList;
+    })();
+    const transport = deps.transport || fetchTransport();
+    const tools = {};
+    /** Instrumentation in the house style, and never fatal to the call it wraps. */
+    const track = (name) => {
+        try {
+            trackMCP(name, server.server.getClientVersion(), undefined, config);
+        }
+        catch {
+            // Telemetry must not decide whether a tool call succeeds.
+        }
+    };
+    tools.listProducts = server.tool("listProducts", "List the BrowserStack products this surface can reach, with a one-line summary each. " +
+        "Start here when you do not know which product a task belongs to. " +
+        `This build carries ${productCatalog}.`, {}, {
+        title: "List Capability Products",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async () => {
+        track("listProducts");
+        const info = registry.buildInfo();
+        return ok({
+            build_id: registry.buildId,
+            products: registry.productNames().map((name) => ({
+                name,
+                summary: registry.index.products[name].summary,
+                // Provenance for logging and cache-busting only — capability resolution must
+                // never depend on it.
+                build_id: info[name]?.build_id,
+                ...(info[name]?.version ? { version: info[name].version } : {}),
+            })),
+        });
+    });
+    tools.listEntities = server.tool("listEntities", "List the entities a product models (test case, folder, test plan, …). Use it to scope " +
+        "searchCapability, or to find the entity name describeEntity wants.", {
+        product: productArg().describe(`Which product to list entities for: ${productList}.`),
+    }, {
+        title: "List Product Entities",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async ({ product }) => {
+        track("listEntities");
+        const bundle = registry.index.products[product];
+        if (!bundle)
+            return failed(`unknown product '${product}'`);
+        return ok({ product, entities: Object.keys(bundle.entities).sort() });
+    });
+    tools.describeEntity = server.tool("describeEntity", "Describe one entity: what it is, what identifies it, what it relates to, and the " +
+        "vocabulary the product uses for it. Read this before filtering or writing, because " +
+        "ids and field values usually have to be resolved first.", {
+        product: productArg().describe(`Which product the entity belongs to: ${productList}.`),
+        entity: z.string().describe("Entity name from listEntities."),
+    }, {
+        title: "Describe Entity",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async ({ product, entity }) => {
+        track("describeEntity");
+        const bundle = registry.index.products[product];
+        if (!bundle)
+            return failed(`unknown product '${product}'`);
+        const doc = bundle.entities[entity];
+        if (!doc) {
+            return failed(`unknown entity '${entity}' in ${product}; known: ${Object.keys(bundle.entities).sort().join(", ")}`);
+        }
+        return ok({ product, entity, ...doc });
+    });
+    tools.searchCapability = server.tool("searchCapability", "Find endpoints this surface can call, by plain language, optionally narrowed to one " +
+        "entity, product or mode. " +
+        `Currently loaded products: ${productList} — call listProducts for what each does. ` +
+        "Search matches the product's OWN words, not synonyms. When your words are not the " +
+        "product's, the response says so: `weak_match: true` with a `suggested_vocabulary` " +
+        "map of the product's entities and their aliases. Results are still returned, but " +
+        "treat them as unconfirmed — pick the closest entity from that map and search again " +
+        "using its vocabulary, or call describeEntity on it for the fuller picture. That one " +
+        "extra round trip is far cheaper than invoking the wrong capability. " +
+        "Narrowing with `product` or `entity` sharpens results further. " +
+        "Each result carries the capability's `name` — the handle you pass to " +
+        "invokeCapability — plus its `method` and `path` (use those two only when a result " +
+        "has no `name`), and its parameters grouped into path_params / query / body under " +
+        "the spec's own names. Pass them straight back, no renaming. `intent` says what it does, " +
+        "`mode` tells you whether it writes, `product` says which product owns it, and " +
+        "`responses` describes what a successful call returns, fully expanded. Results are " +
+        "ranked and capped, and `truncated` says when more matched. Search before invoking.", {
+        query: z
+            .string()
+            .describe("What you are trying to do, in plain language."),
+        entity: z
+            .string()
+            .optional()
+            .describe("Restrict to one entity (see listEntities)."),
+        product: productArg()
+            .optional()
+            .describe(`Restrict to one product: ${productList}. Omit to search all of them.`),
+        mode: z
+            .enum(["read", "write", "destructive"])
+            .optional()
+            .describe("Restrict to reads or writes. Omit to let the query decide."),
+        limit: z.number().optional().describe("Max results (default 8)."),
+        include_responses: z
+            .enum(["success", "all", "none"])
+            .optional()
+            .describe("Which declared responses to expand: 'success' (default, the 2xx shape), 'all' " +
+            "(adds the error shapes — several times larger, and near-identical across " +
+            "endpoints), or 'none'."),
+    }, {
+        title: "Search Capabilities",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async ({ query, entity, product, mode, limit, include_responses }) => {
+        track("searchCapability");
+        const selection = (include_responses || "success");
+        const { hits, weak, top_matched, ...rest } = searchCapabilities(registry.index.products, query, {
+            entity,
+            product,
+            mode: mode,
+            limit,
+        });
+        return ok({
+            build_id: registry.buildId,
+            // Dereferenced HERE rather than in the artifact: the tables store each response and
+            // schema once and the capabilities name them, so the file stays a third of the size
+            // it would be inlined. Expanding on the way out means the caller never has to
+            // resolve a `{"$schema": "…"}` itself, and never sees one.
+            capabilities: hits.map(({ product: owner, capability }) => {
+                const responses = resolveResponses(registry.index.products[owner], capability, selection);
+                // The raw field is dropped, not merely overwritten: it holds `{"$response": …}`
+                // references, and spreading the capability would leak them straight through
+                // whenever the resolved value is absent.
+                const { responses: unresolved, ...rest } = capability;
+                void unresolved;
+                return {
+                    ...rest,
+                    product: owner,
+                    ...(responses ? { responses } : {}),
+                };
+            }),
+            ...rest,
+            // WHEN THE MATCH IS WEAK, HAND OVER THE VOCABULARY.
+            //
+            // A vocabulary miss returns a full page of confident-looking hits — nothing in the
+            // shape of the response says the caller's word does not exist in this product. This
+            // is that signal, plus the fix in the same round trip: the caller is a model, and it
+            // maps "bucket" to "folder" instantly once it can see the entity list.
+            //
+            // Additive, never a replacement — the results are still there, and the caller is
+            // told to re-search rather than to trust this. That is what makes a generous
+            // threshold safe.
+            ...(weak
+                ? {
+                    weak_match: true,
+                    suggested_vocabulary: vocabularyOf(registry.index.products, product),
+                    hint: "Nothing matched the product's own words strongly (best term score " +
+                        `${top_matched.toFixed(1)}). The results below may not answer the ` +
+                        "question. Re-search using a term from suggested_vocabulary, or call " +
+                        "describeEntity on the closest entity for its full vocabulary.",
+                }
+                : {}),
+        });
+    });
+    tools.invokeCapability = server.tool("invokeCapability", "Call a capability returned by searchCapability or describeEntity. Pass `name` exactly " +
+        "as given — that is the handle. Only when a result carries no `name` (some products " +
+        "do not publish them yet) pass `method` and `path` instead, exactly as returned. " +
+        "Arguments go in path_params / query / body under the spec's own names. One call " +
+        "makes exactly one request and returns the product's own response untouched; when " +
+        "`completed` is false there is another page, which you fetch by sending the " +
+        "capability's own page parameter. If the mode is 'write' you MUST ask the user " +
+        "first, then resend with user_permission='granted' and a change_summary; both are " +
+        "recorded. Capabilities whose mode is 'destructive' (deletes) are refused outright — " +
+        "archiving, closing and merging are ordinary writes and DO run, so read the mode and " +
+        "intent before confirming with the user.", {
+        name: z
+            .string()
+            .optional()
+            .describe("The capability's published name, exactly as returned (e.g. 'create_test_run_v1'). " +
+            "Preferred over method/path."),
+        method: z
+            .string()
+            .optional()
+            .describe("HTTP method — only for capabilities returned without a `name`."),
+        path: z
+            .string()
+            .optional()
+            .describe("Path with {placeholders} intact — only for capabilities returned without a `name`."),
+        path_params: z
+            .record(z.string(), z.any())
+            .optional()
+            .describe("Values for the {placeholders}."),
+        query: z
+            .record(z.string(), z.any())
+            .optional()
+            .describe("Query parameters."),
+        body: z
+            .record(z.string(), z.any())
+            .optional()
+            .describe("Body fields, under the spec's names."),
+        product: productArg()
+            .optional()
+            .describe(`Which product owns the capability (${productList}). searchCapability returns it ` +
+            "on every result; required only when two products share a name or a path."),
+        user_permission: z
+            .enum(PERMISSION_VALUES)
+            .optional()
+            .describe("Set to 'granted' only after the user has confirmed a write."),
+        change_summary: z
+            .string()
+            .optional()
+            .describe("What will change. Required for writes."),
+    }, {
+        title: "Invoke Capability",
+        // Not read-only: this is the one tool that writes. Never destructive, because
+        // destructive endpoints are refused before binding — the refusal is enforced here,
+        // not merely hinted at. Not idempotent: it creates, clones and starts runs. Closed
+        // world: it reaches BrowserStack products the index describes, nothing else.
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+    }, async (input) => {
+        track("invokeCapability");
+        try {
+            // Either handle resolves to the same capability. `name` wins when both are sent,
+            // rather than cross-checking them: a caller pasting a stale path alongside a good
+            // name should still reach the right operation, which is the point of naming.
+            if (!input.name && !(input.method && input.path)) {
+                return failed("pass `name` — or, for a capability returned without one, both `method` and " +
+                    "`path`, exactly as searchCapability returned them");
+            }
+            const { product, capability } = input.name
+                ? registry.byNameLookup(input.name, input.product)
+                : registry.byEndpointLookup(input.method, input.path, input.product);
+            /** What to call it in errors — the handle the caller actually used. */
+            const handle = capability.name || `${capability.method} ${capability.path}`;
+            const args = {
+                path_params: input.path_params,
+                query: input.query,
+                body: input.body,
+            };
+            if (capability.mode === "destructive") {
+                // Refused before binding, so consent is never sought for something that cannot run.
+                return failed(`${handle} is a destructive operation and is not available through this surface`);
+            }
+            if (capability.mode === "write") {
+                const permission = input.user_permission || "not_asked";
+                // PARAMETERS ARE VALIDATED BEFORE PERMISSION IS DEMANDED. The gate used to run
+                // first, so a caller with a typo'd parameter was told "ask the user to confirm this
+                // change", went back to the human for approval, and only then learned the parameter
+                // was wrong. A dry bind costs nothing and cannot mutate.
+                const { bind } = await import("./bind.js");
+                bind(capability, args);
+                if (permission !== "granted") {
+                    // Catches the careless path, not the adversarial one: the model fills this field
+                    // in, so it is an audit record and a speed bump, never authorisation.
+                    return failed("refused: this endpoint changes data — ask the user to confirm, then retry " +
+                        "with user_permission='granted' and a change_summary");
+                }
+                if (!(input.change_summary || "").trim()) {
+                    return failed("change_summary is required: state what will change");
+                }
+            }
+            const result = await invoke(capability, args, await deps.baseUrlFor(product), deps.credentialsFor(), transport, registry.index.products[product]?.auth);
+            return ok(result);
+        }
+        catch (error) {
+            if (error instanceof InvocationError)
+                return failed(error.message);
+            logger.error("invokeCapability failed: %s", error instanceof Error ? error.message : String(error));
+            return failed("that capability could not be invoked");
+        }
+    });
+    return tools;
+}
+export default addCapabilityRegistryToolsFromConfig;

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,45 @@
+/**
+ * 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;
+}
+export async function invoke(capability, args, baseUrl, credentials, transport, auth) {
+    if (!baseUrl)
+        throw new InvocationError("no base URL is configured for that product");
+    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,97 @@
+/**
+ * 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.
+ */
+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[];
+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 `get_root_folders_v1` — 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;
+    /**
+     * 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;
+    weak: boolean;
+}
+/** One entity's caller-facing vocabulary: what it is called, and what else it is called. */
+export interface VocabularyEntry {
+    entity: string;
+    title?: 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 only, deliberately. They are the vocabulary map — 19 entities in ~1.5KB, against a
+ * response that is routinely 38KB. The entity `key_facts` are richer prose but ten times the
+ * size, and a caller who needs them can ask describeEntity once it knows which entity to ask
+ * about — which is exactly what this hands over.
+ */
+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;
+}): SearchResult;