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

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

@@ -200,6 +200,22 @@ function coerceType(value, param, label = param.name) {
             return false;
         throw new InvocationError(`'${label}' must be true or false`);
     }
+    // NO DECLARED TYPE: pass the value through as given.
+    //
+    // The fallthrough below is String(value), which is right for a declared string and
+    // silently destructive for anything the spec left untyped. create_report_v2 declares
+    // `mail_to` and `report_filters` with no type and the API wants objects for both, so a
+    // correct payload was serialised to the literal "[object Object]" and refused:
+    //
+    //   The property '#/mail_to' of type string did not match the following type: object
+    //
+    // The caller sent the right thing, this layer broke it, and the server's message blames
+    // the caller for a string it never wrote. An untyped parameter means the spec declines to
+    // say what shape it is — which is a reason to leave it alone, not to guess "string".
+    const untyped = !expected;
+    if (untyped && (typeof value === "object" || typeof value === "boolean")) {
+        return value;
+    }
     const text = String(value);
     if (param.values && param.values.length > 0) {
         const allowed = param.values.map((v) => String(v));
@@ -244,8 +260,33 @@ export function bind(capability, args) {
         // misspelled filter would return a larger result set that looks like a correct answer.
         const unknown = Object.keys(supplied).filter((name) => !byName.has(name));
         if (unknown.length > 0) {
+            // A CALLER WHO SENT THE WRAPPER WE BUILD DESERVES TO BE TOLD SO.
+            //
+            // Most of these endpoints want a nested body — Rails `params.require(:test_case)` —
+            // and the fields declare that as `json_path: /test_case/name`, so this layer
+            // assembles the wrapper itself and the caller sends the fields flat. A caller who
+            // wraps it by hand therefore sends a key that is never a declared param, and the
+            // bare message reads as "that field does not exist" when the truth is the opposite:
+            // it exists, and building it is our job.
+            //
+            // Worth special-casing because the guidance itself has been telling callers to wrap:
+            // 25 tm capabilities carried a line describing the WIRE format to a caller who never
+            // writes the wire. Those lines are being corrected, but an agent working from an
+            // older artifact, or reasoning from the Rails convention, lands here either way.
+            const wrappers = new Set(params
+                .map((param) => param.json_path)
+                .filter((path) => Boolean(path))
+                .map((path) => path.replace(/^\//, "").split("/")[0])
+                .filter((segment) => segment && !byName.has(segment)));
+            const sentAWrapper = unknown.filter((name) => wrappers.has(name));
             throw new InvocationError(`unknown ${group}: ${unknown.sort().join(", ")}. accepted: ` +
-                `${[...byName.keys()].sort().join(", ") || "none"}`);
+                `${[...byName.keys()].sort().join(", ") || "none"}` +
+                (sentAWrapper.length > 0
+                    ? `. ${sentAWrapper.sort().join(" and ")} ` +
+                        `${sentAWrapper.length > 1 ? "are wrappers" : "is a wrapper"} this ` +
+                        `surface builds for you from each field's json_path — send the fields ` +
+                        `directly instead of nesting them`
+                    : ""));
         }
         for (const [name, raw] of Object.entries(supplied)) {
             const param = byName.get(name);

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

@@ -83,6 +83,54 @@ export function authHeaders(credentials, auth = DEFAULT_AUTH) {
     throw new InvocationError(`unsupported auth scheme for this product: ` +
         `${JSON.stringify({ type: auth.type, scheme: auth.scheme })}`);
 }
+/** Longest response text kept when it is not JSON. Enough for an error, not a whole page. */
+const TEXT_BODY_LIMIT = 2000;
+/**
+ * Read the response, and NEVER silently discard it.
+ *
+ * This used to parse the body only when the content-type said JSON and return `null`
+ * otherwise, which meant an error could arrive as `{status: 500, body: null}` — a status
+ * code and nothing else. That is worse than it sounds: an unhandled exception in a Rails
+ * app renders `text/html`, so the one case where you most need the message is exactly the
+ * case where the content-type is not JSON. It also made two very different situations
+ * indistinguishable — "the product sent no message" and "we threw the message away" — and
+ * a live probe of `test_case_results_v1` had to leave that ambiguity open in its findings
+ * because nothing downstream could tell which had happened.
+ *
+ * So: JSON is parsed as before. Anything textual is kept as a truncated string. Malformed
+ * JSON keeps its raw text rather than becoming `null`, because a body that fails to parse
+ * is itself the diagnosis. Binary is described rather than decoded — dumping PDF bytes
+ * into an agent's context helps nobody, but knowing a PDF arrived does.
+ */
+async function readBody(response) {
+    const contentType = response.headers.get("content-type") || "";
+    // Anything that is not plausibly text: report what came back without decoding it.
+    const textual = !contentType ||
+        /^text\//i.test(contentType) ||
+        /\b(json|xml|yaml|csv|javascript|x-www-form-urlencoded)\b/i.test(contentType);
+    if (!textual) {
+        const size = response.headers.get("content-length");
+        return `<non-text response: ${contentType}${size ? `, ${size} bytes` : ""}>`;
+    }
+    const raw = await response.text().catch(() => "");
+    if (!raw.trim())
+        return null;
+    if (contentType.includes("json")) {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            // Declared JSON that is not JSON. The text is the evidence; keep it.
+            return truncate(raw);
+        }
+    }
+    return truncate(raw);
+}
+function truncate(text) {
+    return text.length <= TEXT_BODY_LIMIT
+        ? text
+        : `${text.slice(0, TEXT_BODY_LIMIT)}… [truncated, ${text.length} chars total]`;
+}
 /** A fetch-based transport. Redirects are NOT followed. */
 export function fetchTransport(timeoutMs = 45_000) {
     return async (method, url, headers, query, body) => {
@@ -106,12 +154,10 @@ export function fetchTransport(timeoutMs = 45_000) {
                 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 };
+            return {
+                status: response.status,
+                body: await readBody(response),
+            };
         }
         catch {
             // Upstream detail stays out of the reply; the resolver treats status 0 as a failed call.

package/dist/tools/capability-registry/index-loader.js

@@ -337,7 +337,42 @@ function resolveNode(product, node, seen) {
         // revisit a name already on this path.
         if (!target || seen.has(key))
             return node;
-        return resolveNode(product, target, new Set([...seen, key]));
+        const resolved = resolveNode(product, target, new Set([...seen, key]));
+        // KEYS WRITTEN BESIDE THE REF SURVIVE IT, AND WIN.
+        //
+        // This used to return the target and drop every sibling, which silently ate 16 nodes
+        // in the shipped tm index: 14 authored descriptions and two `nullable: true` flags.
+        // The losses are exactly the caveats hardest to rediscover — "only when no step
+        // results were submitted", "Present only on root-folder creation", and a `nullable`
+        // marking the one field that comes back NULL when a search fails, which is the
+        // absent-versus-explicitly-null distinction a caller cannot otherwise make.
+        //
+        // It also cost real work downstream. A live probe reported one of those caveats as a
+        // missing conditional and it had been written all along — this resolver removed it
+        // between the author and the caller. Worse, the product team began splitting shared
+        // schemas so a caveat would have somewhere to live that survived, trading a lost
+        // sentence for two descriptions of one serializer that then drift apart.
+        //
+        // SIBLINGS WIN over the resolved target, not the reverse. A description written at the
+        // reference site is about THAT usage — "only when no step results were submitted" is
+        // true of one consumer of TestResult, not of TestResult everywhere — which is the
+        // whole reason it was written beside the ref instead of on the schema.
+        const siblings = {};
+        for (const [field, value] of Object.entries(node)) {
+            if (field !== "$schema" && field !== "$response")
+                siblings[field] = value;
+        }
+        if (Object.keys(siblings).length === 0)
+            return resolved;
+        if (typeof resolved !== "object" ||
+            resolved === null ||
+            Array.isArray(resolved)) {
+            return resolved;
+        }
+        return {
+            ...resolved,
+            ...resolveNode(product, siblings, seen),
+        };
     }
     const out = {};
     for (const [field, value] of Object.entries(node)) {

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

@@ -462,8 +462,24 @@ function score(capability, wanted, weights, aliases, hint, plural) {
  * that work at 0.44–1.94. The absolute score cannot separate those (misses reach 2.9,
  * good queries drop to 1.9); this does, with the gap in the same place in all three
  * corpora, which is the property that was missing.
+ *
+ * RECALIBRATED AT v1.14, and the reason matters more than the number. The ratio is
+ * corpus-relative and still is — "make a new bucket for my tests" scores 0.259 against tm
+ * alone and 0.258 against both products, which is the property this was built for. What
+ * moved is neither corpus size nor query: it is how much TEXT each capability carries.
+ * v1.13 gave all 242 entries guidance and tripled the length of `intent`, so the numerator
+ * — the best hit's term score — roughly doubled, while the denominator depends only on the
+ * rarity of the query's own terms and did not. Both bands shifted up together: genuine
+ * misses now land at 0.00–0.46 and working queries at 0.24–4.16.
+ *
+ * At the old 0.25 the hand-off had silently stopped firing — "bucket", which is nobody's
+ * word for a folder, came in at 0.259 and read as a confident answer. Re-measured over 173
+ * served eval cases against five queries the product has no words for, 0.50 catches 5 of 5
+ * while flagging 3 of 173 served queries (1.7%), which is the same trade the original cut
+ * made. Expect to move it again the next time the artifact's text volume changes; the
+ * threshold tracks prose per capability, not the number of capabilities.
  */
-const WEAK_COVERAGE = 0.25;
+const WEAK_COVERAGE = 0.5;
 /** The heaviest field, and so the yardstick a perfect match is measured against. */
 const IDENTITY_WEIGHT = 6;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserstack/mcp-server",
-  "version": "1.5.0-beta.16",
+  "version": "1.5.0-beta.17",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",
@@ -15,7 +15,11 @@
     "dev": "tsx watch --clear-screen=false src/index.ts",
     "test": "vitest run",
     "lint": "eslint . --ext .ts",
-    "format": "prettier --write \"src/**/*.ts\""
+    "format": "prettier --write \"src/**/*.ts\"",
+    "eval:index": "tsx scripts/eval-index.mts",
+    "seed:live": "tsx scripts/seed-live.mts",
+    "plan:tests": "tsx scripts/plan-capability-tests.mts",
+    "replay:live": "tsx scripts/replay-live.mts"
   },
   "bin": {
     "browserstack-mcp-server": "dist/index.js"