@browserstack/mcp-server 1.5.0-beta.17 → 1.5.0-beta.19

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

@@ -20,7 +20,7 @@ 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 { ambiguousProducts, searchCapabilities, singular, terms, vocabularyOf, } from "./search.js";
+import { ambiguousProducts, isBrowseQuery, searchCapabilities, singular, terms, vocabularyOf, } from "./search.js";
 export const PERMISSION_VALUES = ["not_asked", "granted", "denied"];
 /**
  * The search-side twin of `user_permission`: did a human choose the product, or did you?
@@ -219,10 +219,18 @@ export function addCapabilityRegistryTools(server, deps, config) {
         "It does NOT carry parameters or response shapes. Once you have picked one, call " +
         "describeCapability for its full contract, then invokeCapability. Fetching the " +
         "contract only for the one you chose is the difference between ~1k and ~8.6k tokens " +
-        "a search. Results are ranked and capped, and `truncated` says when more matched.", {
+        "a search. Results are ranked and capped. " +
+        "TO SEE EVERYTHING rather than search, pass query='*' — that lists the product " +
+        "(honouring `entity` and `mode`) in a stable order instead of ranking it, which is " +
+        "what you want when the task is 'what can this product do' rather than a lookup. " +
+        "TO PAGE, send `offset`: every response carries `offset` and, when more matched, " +
+        "`next_offset` — resend the SAME query with that value. `next_offset` is absent on " +
+        "the last page, so walk until it stops rather than comparing counts.", {
         query: z
             .string()
-            .describe("What you are trying to do, in plain language."),
+            .describe("What you are trying to do, in plain language. Pass '*' (or 'all') to BROWSE " +
+            "instead of search: every capability in the product, in a stable order, " +
+            "paginated — use it when you want to see the surface rather than find one thing."),
         entity: z
             .string()
             .optional()
@@ -257,13 +265,18 @@ export function addCapabilityRegistryTools(server, deps, config) {
             .optional()
             .describe("Restrict to reads or writes. Omit to let the query decide."),
         limit: z.number().optional().describe("Max results (default 8)."),
+        offset: z
+            .number()
+            .optional()
+            .describe("Skip this many results — send the `next_offset` from the previous response " +
+            "with the SAME query to get the next page. Omit for the first page."),
     }, {
         title: "Search Capabilities",
         readOnlyHint: true,
         destructiveHint: false,
         idempotentHint: true,
         openWorldHint: false,
-    }, async ({ query, entity, product, product_choice, mode, limit }) => {
+    }, async ({ query, entity, product, product_choice, mode, limit, offset }) => {
         track("searchCapability");
         // THE GATE. Nothing here can tell whether a human was asked — same as the write
         // gate, which also takes the caller's word. What it can do is refuse to answer a
@@ -274,7 +287,13 @@ export function addCapabilityRegistryTools(server, deps, config) {
         // both products claim. 27 of the 198 eval queries, against 135 if constituent words
         // counted. `entity` is an explicit narrowing, so a caller that named one has already
         // been specific enough and is not asked again.
-        if (product_choice !== "user_confirmed" && !entity) {
+        // The ambiguity gate asks the USER which product a word belongs to. A browse query
+        // contains no word to be ambiguous about — `*` names nothing — so there is nothing
+        // to ask, and asking anyway would block the one query whose whole purpose is to
+        // show what a product contains.
+        if (product_choice !== "user_confirmed" &&
+            !entity &&
+            !isBrowseQuery(query)) {
             const ambiguity = ambiguousProducts(registry.index.products, query);
             if (ambiguity.products.length > 1) {
                 // EVERYTHING NEEDED TO ASK, IN THE REFUSAL. Telling the agent to go and call
@@ -323,6 +342,7 @@ export function addCapabilityRegistryTools(server, deps, config) {
             product,
             mode: mode,
             limit,
+            offset,
         });
         return ok({
             // NO build_id. It is provenance — for our logs and for cache busting — and

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

@@ -18,6 +18,14 @@ import { Capability, Mode, ProductIndex } from "./types.js";
  * 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.
@@ -72,6 +80,18 @@ 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.
      *
@@ -146,4 +166,5 @@ export declare function searchCapabilities(products: Record<string, ProductIndex
     product?: string;
     mode?: Mode;
     limit?: number;
+    offset?: number;
 }): SearchResult;

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

@@ -111,6 +111,17 @@ const PLURAL_INTENT = new Set([
  * 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 function isBrowseQuery(query) {
+    const q = (query || "").trim().toLowerCase();
+    return q === "*" || q === "all";
+}
 export function terms(text) {
     return [
         ...(text || "")
@@ -592,6 +603,39 @@ export function vocabularyOf(products, only) {
 }
 export function searchCapabilities(products, query, options = {}) {
     const limit = options.limit && options.limit > 0 ? options.limit : 8;
+    const offset = options.offset && options.offset > 0 ? Math.floor(options.offset) : 0;
+    // BROWSE MODE: `*` lists the product instead of searching it.
+    //
+    // Scoring keeps only capabilities with matched > 0, so there was no query that returned
+    // everything — an agent that wanted to see what exists had to guess words until the
+    // shortlist looked complete, and could never tell when it was. `*` skips scoring
+    // entirely and pages the filtered set in a STABLE order (name, then path), because a
+    // ranked order is not a safe thing to paginate: ranking is query-dependent and ties
+    // break arbitrarily, so page 2 of a ranked list can repeat or skip rows. Browse is
+    // ordered by identity, so offset means the same thing on every call.
+    if (isBrowseQuery(query)) {
+        const all = Object.entries(products)
+            .filter(([name]) => !options.product || name === options.product)
+            .flatMap(([name, bundle]) => bundle.capabilities
+            .filter((capability) => (!options.entity || capability.entity === options.entity) &&
+            (!options.mode || capability.mode === options.mode))
+            .map((capability) => ({ product: name, capability })))
+            .sort((a, b) => (a.capability.name || "").localeCompare(b.capability.name || "") ||
+            a.capability.path.localeCompare(b.capability.path));
+        const page = all.slice(offset, offset + limit);
+        const end = offset + page.length;
+        return {
+            hits: page,
+            truncated: end < all.length,
+            total_matched: all.length,
+            top_matched: 0,
+            coverage: 1,
+            weak: false,
+            offset,
+            ...(end < all.length ? { next_offset: end } : {}),
+            browse: true,
+        };
+    }
     // Forms are computed once per query, not per capability: 173 capabilities x 6 haystacks
     // would otherwise rebuild the same handful of strings a thousand times.
     const wanted = terms(query).map(termForms);
@@ -650,12 +694,14 @@ export function searchCapabilities(products, query, options = {}) {
     // products and across `product`/`entity` narrowing — which the raw score is not.
     const perfect = weights.reduce((sum, w) => sum + IDENTITY_WEIGHT * w, 0);
     const coverage = perfect > 0 ? topMatched / perfect : 1;
+    const page = scored.slice(offset, offset + limit);
+    const end = offset + page.length;
     return {
-        hits: scored
-            .slice(0, limit)
-            .map(({ product, capability }) => ({ product, capability })),
-        truncated: scored.length > limit,
+        hits: page.map(({ product, capability }) => ({ product, capability })),
+        truncated: end < scored.length,
         total_matched: scored.length,
+        offset,
+        ...(end < scored.length ? { next_offset: end } : {}),
         top_matched: topMatched,
         coverage,
         weak: wanted.length > 0 && perfect > 0 && coverage < WEAK_COVERAGE,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserstack/mcp-server",
-  "version": "1.5.0-beta.17",
+  "version": "1.5.0-beta.19",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",
@@ -16,6 +16,7 @@
     "test": "vitest run",
     "lint": "eslint . --ext .ts",
     "format": "prettier --write \"src/**/*.ts\"",
+    "check:contract": "python3 scripts/check-contract.py capability/tm.capability-index.json --baseline scripts/contract-baseline/tm.json --quiet && python3 scripts/check-contract.py capability/loadtesting.capability-index.json --baseline scripts/contract-baseline/loadtesting.json --quiet",
     "eval:index": "tsx scripts/eval-index.mts",
     "seed:live": "tsx scripts/seed-live.mts",
     "plan:tests": "tsx scripts/plan-capability-tests.mts",