@browserstack/mcp-server 2.3.0-beta.2 → 2.3.0-beta.4

package/capability/{automate.capability-index.json → devicecontrol.capability-index.json}

@@ -1,9 +1,9 @@
 {
  "schema_version": 1,
- "version": "0.1",
- "build_id": "automate-authored",
- "automate": {
-  "summary": "BrowserStack Automate: drive a real desktop or mobile browser page by page. The account side lists every operating system, browser and version combination available, reports parallel-session capacity, and keeps each session's record \u2014 status, shareable link, video, and console, network and profiling logs \u2014 after the browser is released. The session side opens a browser on a chosen combination and drives it: navigate, go back and forward, reload, read the page HTML and element text, find elements by CSS or XPath, click, type, clear, run JavaScript, screenshot the viewport, resize the window, move between tabs and iframes, and read cookies. Web pages are RUN here \u2014 unlike Test Management, which authors cases, and Test Reporting, which records results pushed in from a runner. Mobile APPS are not here: those are App Automate, which drives an installed app rather than a browser. Scrolling is done through execute_script, there is no capability that waits, and element ids go stale as soon as the page navigates or re-renders. A session holds a browser until it is ended.",
+ "version": "1.0",
+ "build_id": "8445466_2026-10-19T06:53:46Z",
+ "devicecontrol": {
+  "summary": "Device control: drive a real desktop or mobile browser page by page. The account side lists every operating system, browser and version combination available, reports parallel-session capacity, and keeps each session's record \u2014 status, shareable link, video, and console, network and profiling logs \u2014 after the browser is released. The session side opens a browser on a chosen combination and drives it: navigate, go back and forward, reload, read the page HTML, find elements by CSS or XPath, click, type, clear, run JavaScript, screenshot the viewport, resize the window, and move between tabs and iframes. Web pages are RUN here \u2014 unlike Test Management, which authors cases, and Test Reporting, which records results pushed in from a runner. Mobile APPS are not here: those are mobile device control, which drives an installed app rather than a browser. Scrolling is done through execute_script, there is no capability that waits, and element ids go stale as soon as the page navigates or re-renders. A session holds a browser until it is ended.",
   "routing_terms": [
    "automate",
    "browser",
@@ -31,7 +31,9 @@
    "network logs",
    "har",
    "browser session",
-   "cross browser"
+   "cross browser",
+   "device control",
+   "browser control"
   ],
   "base_url": "https://hub.browserstack.com",
   "hosts": {
@@ -50,10 +52,12 @@
     "entity": "browser",
     "intent": "List every operating system, browser and version combination this account can run a web session on, with the exact names create_session expects.",
     "guidance": [
-     "This is a very large answer \u2014 several thousand rows, one per combination \u2014 and there is no filtering on the wire. Narrow it yourself, and never read it whole into a reply.",
+     "The endpoint accepts no filtering on the wire \u2014 every query parameter is ignored, and a filtered call comes back byte-identical to the bare one \u2014 so pass `select` instead and never fetch this whole. The full answer is several thousand rows; `select` with `distinct` turns the usual question into a few hundred bytes.",
+     "To ask what values EXIST, use distinct rather than reading rows: distinct ['browser'] names every browser, distinct ['os','os_version'] every platform, distinct ['device'] every mobile device. To check one combination, put it in `where` and see whether anything comes back.",
      "A desktop row carries os, os_version, browser and browser_version, with device null. A mobile row carries device and real_mobile true instead, and its browser_version is null because the browser ships with the OS.",
-     "The browser names are lower case and are what create_session takes: chrome, firefox, edge, safari, opera, and chromium on mobile.",
-     "Pass the strings exactly as they appear; an unlisted combination is refused rather than substituted."
+     "os is spelled Windows, OS X, android and ios \u2014 two capitalised and two not, in the same column \u2014 and `where` matches case-insensitively, so either spelling finds them. Browser names are lower case apart from chromeForTesting.",
+     "Rows come back in the product's own order, which is OLDEST VERSION FIRST, and `limit` takes the first N of them \u2014 so a limit is the wrong way to find the newest build and will hand back Chrome 37 for Windows 11. Ask for the versions with distinct and no limit (a hundred-odd strings, under 3 KB) and read the end of the list.",
+     "Pass the strings into create_session exactly as they appear here; an unlisted combination is refused rather than substituted."
     ],
     "returns": [
      "browser",
@@ -74,7 +78,18 @@
       "$response": "Unauthorized"
      }
     },
-    "host": "api"
+    "host": "api",
+    "narrowable": {
+     "fields": [
+      "os",
+      "os_version",
+      "browser",
+      "browser_version",
+      "device",
+      "real_mobile"
+     ],
+     "note": "The endpoint takes no parameters of its own, so this narrowing is applied to the response after the call."
+    }
    },
    {
     "name": "get_plan",
@@ -204,7 +219,7 @@
       "type": "string",
       "maxLength": 255,
       "description": "Short explanation shown beside the status.",
-      "example": "Cart totalled correctly after adding two items"
+      "example": "The page behaved as expected"
      }
     ],
     "returns": [
@@ -364,14 +379,14 @@
       "type": "string",
       "json_path": "/capabilities/alwaysMatch/bstack:options/projectName",
       "description": "Groups sessions on the dashboard.",
-      "example": "Checkout flows"
+      "example": "Web checkout"
      },
      {
       "name": "build_name",
       "type": "string",
       "json_path": "/capabilities/alwaysMatch/bstack:options/buildName",
       "description": "Build the session is filed under.",
-      "example": "agent-exploration"
+      "example": "nightly"
      },
      {
       "name": "session_name",
@@ -379,7 +394,7 @@
       "maxLength": 255,
       "json_path": "/capabilities/alwaysMatch/bstack:options/sessionName",
       "description": "Name shown for this session.",
-      "example": "cart totals"
+      "example": "sign in and add to basket"
      }
     ],
     "returns": [
@@ -425,7 +440,7 @@
       "required": true,
       "format": "uri",
       "description": "Absolute URL including the scheme.",
-      "example": "https://www.bstackdemo.com/"
+      "example": "https://www.example.com/products"
      }
     ],
     "returns": [
@@ -624,7 +639,7 @@
     "entity": "browser_session",
     "intent": "Get the current page's HTML \u2014 use this to find selectors, or to read content a screenshot cannot show.",
     "guidance": [
-     "A real page runs to tens of kilobytes or more, so search it for what is needed rather than reading all of it. get_title and get_element_text answer most questions far more cheaply.",
+     "A real page runs to tens of kilobytes or more, so search it for what is needed rather than reading all of it. get_title answers most questions far more cheaply.",
      "This is the page as the browser has it now, including anything scripts have changed, not the HTML the server sent.",
      "Inside a frame this returns that frame's document; switch_to_frame with a null id first to get the top-level page back."
     ],
@@ -691,7 +706,7 @@
       "type": "string",
       "required": true,
       "description": "The selector itself, interpreted according to using.",
-      "example": ".shelf-item__buy-btn"
+      "example": "#add-to-cart"
      }
     ],
     "returns": [
@@ -748,7 +763,7 @@
       "type": "string",
       "required": true,
       "description": "The selector itself, interpreted according to using.",
-      "example": ".shelf-item__buy-btn"
+      "example": ".product-card"
      }
     ],
     "returns": [
@@ -791,7 +806,7 @@
       "type": "string",
       "required": true,
       "description": "Element id from find_element.",
-      "example": "f.31006BCEEF25A5A489371DAD0726B51F.d.B5F92408.e.13"
+      "example": "f.00000000000000000000000000000000.d.0000000000000000.e.1"
      }
     ],
     "returns": [
@@ -819,7 +834,7 @@
     "intent": "Type into a field \u2014 use this to fill a search box, a login form or any editable input.",
     "guidance": [
      "APPENDS to whatever the field already holds. Call clear_element first to replace the value rather than adding to it.",
-     "Read the result back with get_element_property on \"value\", not get_element_text, which is empty for an input.",
+     "Read the result back with get_element_property on \"value\": a field's current contents are a property, not text.",
      "A \\n at the end submits the form on a desktop browser and on Chrome for Android, and is quicker than finding the submit button. IT DOES NOT SUBMIT ON SAFARI FOR iOS \u2014 the text lands in the field and the page stays where it is, whether the newline is sent with the text or on its own. There, click the form's submit button, or call arguments[0].form.submit() through execute_script with the field as the argument.",
      "The element must be editable; typing into anything else answers \"element not interactable\".",
      "A site's own autocomplete or dropdown may swallow the keystrokes and require a click on a suggestion instead."
@@ -836,7 +851,7 @@
       "type": "string",
       "required": true,
       "description": "Element id from find_element.",
-      "example": "f.31006BCEEF25A5A489371DAD0726B51F.d.B5F92408.e.13"
+      "example": "f.00000000000000000000000000000000.d.0000000000000000.e.1"
      }
     ],
     "body": [
@@ -845,7 +860,7 @@
       "type": "string",
       "required": true,
       "description": "The characters to type. End with \\n to submit.",
-      "example": "BrowserStack"
+      "example": "hello"
      }
     ],
     "returns": [
@@ -888,7 +903,7 @@
       "type": "string",
       "required": true,
       "description": "Element id from find_element.",
-      "example": "f.31006BCEEF25A5A489371DAD0726B51F.d.B5F92408.e.13"
+      "example": "f.00000000000000000000000000000000.d.0000000000000000.e.1"
      }
     ],
     "returns": [
@@ -931,7 +946,7 @@
       "type": "string",
       "required": true,
       "description": "Element id from find_element.",
-      "example": "f.31006BCEEF25A5A489371DAD0726B51F.d.B5F92408.e.13"
+      "example": "f.00000000000000000000000000000000.d.0000000000000000.e.1"
      }
     ],
     "returns": [
@@ -958,7 +973,7 @@
     "entity": "browser_session",
     "intent": "Read a live DOM property of an element \u2014 use this for what a field currently holds, or whether a box is checked right now.",
     "guidance": [
-     "THIS IS THE ONE THAT READS A FIELD'S CURRENT VALUE. get_element_text is empty for an input, and the \"value\" attribute is the markup's initial value rather than what is in the box now.",
+     "THIS IS THE ONE THAT READS A FIELD'S CURRENT VALUE. The \"value\" attribute is the markup's initial value rather than what is in the box now, and an input carries no text.",
      "Useful names: value, checked, selected, disabled, innerText, href.",
      "A property the element does not have comes back null, not an error."
     ],
@@ -974,7 +989,7 @@
       "type": "string",
       "required": true,
       "description": "Element id from find_element.",
-      "example": "f.31006BCEEF25A5A489371DAD0726B51F.d.B5F92408.e.13"
+      "example": "f.00000000000000000000000000000000.d.0000000000000000.e.1"
      },
      {
       "name": "name",
@@ -1023,14 +1038,14 @@
       "type": "string",
       "required": true,
       "description": "Element id from find_element.",
-      "example": "f.31006BCEEF25A5A489371DAD0726B51F.d.B5F92408.e.13"
+      "example": "f.00000000000000000000000000000000.d.0000000000000000.e.1"
      },
      {
       "name": "name",
       "type": "string",
       "required": true,
       "description": "The attribute to read.",
-      "example": "class"
+      "example": "href"
      }
     ],
     "returns": [
@@ -1072,7 +1087,7 @@
       "type": "string",
       "required": true,
       "description": "Element id from find_element.",
-      "example": "f.31006BCEEF25A5A489371DAD0726B51F.d.B5F92408.e.13"
+      "example": "f.00000000000000000000000000000000.d.0000000000000000.e.1"
      }
     ],
     "returns": [
@@ -1154,7 +1169,7 @@
     "guidance": [
      "Returned inline as base64 and typically tens of kilobytes, so take one when the picture is needed rather than after every step.",
      "The VIEWPORT only, not the whole page: anything below the fold needs scrolling into view first with execute_script.",
-     "get_element_text and get_title answer most checks far more cheaply than reading an image."
+     "get_title and get_element_property answer most checks far more cheaply than reading an image."
     ],
     "path_params": [
      {
@@ -1379,7 +1394,7 @@
       "type": "string",
       "required": true,
       "description": "Handle from list_window_handles.",
-      "example": "2FFCF2904DC789DD82BACEF48E43AE93"
+      "example": "00000000000000000000000000000000"
      }
     ],
     "returns": [
@@ -2064,4 +2079,4 @@
    }
   }
  }
-}
+}

package/capability/{appautomate.capability-index.json → mobiledevicecontrol.capability-index.json}

@@ -1,9 +1,9 @@
 {
  "schema_version": 1,
- "version": "0.1",
- "build_id": "appautomate-demo",
- "appautomate": {
-  "summary": "BrowserStack App Automate: run a real Android or iOS device and drive the app on it step by step. The account side lists the devices this account can use, including private ones, uploads and lists app builds, reports parallel-session capacity, and keeps each session's record \u2014 status, shareable link and video \u2014 after the device is released. The session side starts a device with an installed build and drives it: read the UI tree, find and tap elements, type, swipe, screenshot, press keys, rotate, switch between the native app and a web view, push and pull files, move the simulated GPS, change the network profile, launch, close and uninstall apps, answer biometric prompts and feed images to the camera. Apps are RUN here \u2014 unlike Test Management, which authors cases, and Test Reporting, which records results pushed in from a runner. Web browsers are not here, and neither is App Live: it has no API an agent can drive, so agent sessions run on App Automate and consume its minutes. A build must exist before a session starts and can only be uploaded from a public link, never a file on disk \u2014 so media for camera injection must come from elsewhere. The default Appium server is 1.x and rejects every `mobile:` command; ask for 2.19.0.",
+ "version": "1.0",
+ "build_id": "6782f7e_2026-10-16T13:54:22Z",
+ "mobiledevicecontrol": {
+  "summary": "Mobile device control: run a real Android or iOS device and drive the app on it step by step. The account side lists the devices this account can use, including private ones, uploads and lists app builds, reports parallel-session capacity, and keeps each session's record \u2014 status, shareable link and video \u2014 after the device is released. The session side starts a device with an installed build and drives it: read the UI tree, find and tap elements, type, swipe, screenshot, press keys, rotate, switch between the native app and a web view, move between the native app and a web view, and launch or close apps. Apps are RUN here \u2014 unlike Test Management, which authors cases, and Test Reporting, which records results pushed in from a runner. Browsers are not here \u2014 those are device control, which drives a page rather than an installed app \u2014 and neither is App Live: it has no API an agent can drive, so agent sessions run on App Automate and consume its minutes. A build must exist before a session starts and can only be uploaded from a public link, never a file on disk \u2014 so media for camera injection must come from elsewhere. The default Appium server is 1.x and rejects every `mobile:` command; ask for 2.19.0.",
   "routing_terms": [
    "app automate",
    "appium",
@@ -51,7 +51,10 @@
    "os build",
    "upload apk",
    "upload ipa",
-   "local build"
+   "local build",
+   "mobile device control",
+   "device control",
+   "drive a device"
   ],
   "base_url": "https://hub-cloud.browserstack.com",
   "auth": {
@@ -69,10 +72,10 @@
     "guidance": [
      "The app must already be uploaded: pass the bs:// URL from upload_app_build or list_app_builds, or the custom_id it was uploaded under, which always resolves to the newest build with that id.",
      "Allocation and app install usually take 20\u201330 seconds; the response carries the new session id at value.sessionId \u2014 carry it into every other app_session call.",
-     "The session ends itself after idle_timeout seconds with no command (90 by default, 300 at most) and after 2 hours in total. Keep calling, or call get_window_rect as a cheap keep-alive, while deciding the next step.",
-     "Every session occupies a device and consumes App Automate minutes until it ends: always finish with execute_script setSessionStatus and then delete_session.",
+     "The session ends itself after idle_timeout seconds with no command (90 by default, 900 at most) and after 2 hours in total. Keep calling, or call get_window_rect as a cheap keep-alive, while deciding the next step.",
+     "Every session occupies a device and consumes App Automate minutes until it ends: always finish with set_session_status and then delete_session.",
      "To let a person watch the device live while the agent drives it, set interactive_debugging true and leave video on; they then open the running session on the App Automate dashboard and start the interactive session there. That window is two-way: a person's taps and scrolls reach the same device, so ask them to watch only, or re-read the page source before every action.",
-     "device_name and platform_version must be a combination App Automate offers; an unknown pair fails with a session-not-created error naming the capability.",
+     "device_name and platform_version must be a combination mobile device control offers; an unknown pair fails with a session-not-created error naming the capability.",
      "Set appium_version to 2.19.0 for any session that will use execute_script with a `mobile:` command; the default server is 1.x and answers those with a 404 listing the commands it does know.",
      "enable_biometric, enable_camera_image_injection and upload_media only take effect when set here \u2014 none of them can be turned on once the session is running.",
      "Credentials belong in the Authorization header, never inside bstack:options: capabilities are echoed back in session-not-created errors.",
@@ -145,21 +148,21 @@
       "type": "string",
       "json_path": "/capabilities/alwaysMatch/bstack:options/projectName",
       "description": "Groups sessions on the App Automate dashboard.",
-      "example": "Checkout flows"
+      "example": "Mobile checkout"
      },
      {
       "name": "build_name",
       "type": "string",
       "json_path": "/capabilities/alwaysMatch/bstack:options/buildName",
       "description": "Build the session is filed under on the dashboard.",
-      "example": "agent-exploration"
+      "example": "nightly"
      },
      {
       "name": "session_name",
       "type": "string",
       "json_path": "/capabilities/alwaysMatch/bstack:options/sessionName",
       "description": "Name shown for this session on the dashboard.",
-      "example": "Add a product to the cart"
+      "example": "sign in and add to basket"
      },
      {
       "name": "interactive_debugging",
@@ -387,7 +390,7 @@
       "type": "string",
       "required": true,
       "description": "The selector itself, interpreted according to using.",
-      "example": "nav-cart"
+      "example": "cart-button"
      }
     ],
     "returns": [
@@ -483,7 +486,7 @@
       "type": "string",
       "required": true,
       "description": "The characters to type.",
-      "example": "Galaxy S20"
+      "example": "hello"
      }
     ],
     "returns": [
@@ -612,8 +615,8 @@
     "entity": "app_session",
     "intent": "Run an Appium mobile command or a BrowserStack session command \u2014 scroll a list, press a hardware key, launch or close an app, or mark the session passed or failed.",
     "guidance": [
-     "Mark the result before ending the session: script 'browserstack_executor: {\"action\":\"setSessionStatus\",\"arguments\":{\"status\":\"passed\",\"reason\":\"Cart shows one item\"}}' with args []. status is passed or failed; a later call overwrites an earlier one, and the status survives delete_session.",
-     "Keep the setSessionStatus reason to one plain line under 256 characters with no escape sequences such as newlines.",
+     "set_session_status is the capability for marking a session passed or failed, and works after the session has ended too. Only reach for the browserstack_executor setSessionStatus action here when something has to happen from inside the running session.",
+     "Keep any executor reason to one plain line under 256 characters with no escape sequences such as newlines.",
      "Android scroll: script \"mobile: scrollGesture\" with args [{\"left\":100,\"top\":500,\"width\":880,\"height\":1500,\"direction\":\"down\",\"percent\":0.8}] \u2014 value true means more content remains below.",
      "Which mobile: commands exist depends on the Appium version the session runs. The default Android version is Appium 1.x, which supports scrollGesture, swipeGesture, flingGesture, dragGesture, longClickGesture, doubleClickGesture and pinch gestures, but NOT mobile: pressKey \u2014 that needs a session started with appium_version 2.x or later.",
      "An unsupported command fails with 404 \"unknown command\", and the message lists every mobile: command the session does support \u2014 read it rather than retrying variants."
@@ -1121,7 +1124,7 @@
       "type": "string",
       "maxLength": 255,
       "description": "Short explanation shown beside the status.",
-      "example": "Checkout completed and the cart showed the right total"
+      "example": "The app behaved as expected"
      }
     ],
     "returns": [
@@ -1747,7 +1750,7 @@
     "intent": "Find out which app is in the foreground right now \u2014 use this to confirm the app under test is showing and not the home screen or another app.",
     "guidance": [
      "Returns the Android package name; it answers with the launcher's package when the app has been sent to the background.",
-     "This is the quickest way to learn the app under test's own package id, which launch_app, terminate_app and uninstall_app all need.",
+     "This is the quickest way to learn the app under test's own package id, which launch_app and terminate_app both need.",
      "Android only; get_active_app_info is the iOS equivalent and returns an object rather than a string.",
      "Called on iOS this is a 405 \"unknown method\" rather than a silent no-op; use 'mobile: activeAppInfo' there."
     ],
@@ -2681,7 +2684,7 @@
       "type": "string",
       "required": true,
       "description": "The selector itself, interpreted according to using.",
-      "example": "nav-cart"
+      "example": "cart-button"
      }
     ],
     "returns": [
@@ -3308,4 +3311,4 @@
    "api": "https://api-cloud.browserstack.com"
   }
  }
-}
+}

package/dist/lib/error.d.ts

@@ -1,4 +1,14 @@
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Returns the most specific human-readable text for an error raised by an
+ * API call, capped at 500 characters. For an AxiosError with a response body
+ * it prefers the body's `message`, `error` or `errors` field, serialising
+ * objects, and uses the whole body when none of those fields exist. An empty,
+ * whitespace-only or HTML-document body falls back to the error's own message.
+ * @param err - The error object to describe
+ * @param defaultText - The fallback error message
+ */
+export declare function errorText(err: unknown, defaultText: string): string;
 /**
  * Formats an AxiosError into a CallToolResult with an appropriate message.
  * @param err - The error object to format

package/dist/lib/error.js

@@ -1,23 +1,75 @@
 import { AxiosError } from "axios";
+const MAX_ERROR_TEXT = 500;
+const BODY_FIELDS = ["message", "error", "errors"];
+function clip(text) {
+    return text.length > MAX_ERROR_TEXT ? text.slice(0, MAX_ERROR_TEXT) : text;
+}
+const HTML_DOCUMENT = /^\s*<(!doctype|html)\b/i;
+function stringify(value) {
+    if (typeof value === "string") {
+        return HTML_DOCUMENT.test(value) ? "" : value.trim();
+    }
+    if (value === undefined || value === null)
+        return "";
+    try {
+        const json = JSON.stringify(value);
+        return json === "{}" || json === "[]" ? "" : (json ?? "");
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Text taken from an API error body: the first non-empty `message`, `error`
+ * or `errors` field when any of them is present, otherwise the whole body.
+ * Returns undefined when the body carries no usable text.
+ */
+function bodyText(data) {
+    if (typeof data !== "object" || data === null) {
+        const text = stringify(data);
+        return text ? clip(text) : undefined;
+    }
+    const record = data;
+    const named = BODY_FIELDS.filter((key) => key in record);
+    if (named.length > 0) {
+        for (const key of named) {
+            const text = stringify(record[key]);
+            if (text)
+                return clip(text);
+        }
+        return undefined;
+    }
+    const text = stringify(record);
+    return text ? clip(text) : undefined;
+}
+/**
+ * Returns the most specific human-readable text for an error raised by an
+ * API call, capped at 500 characters. For an AxiosError with a response body
+ * it prefers the body's `message`, `error` or `errors` field, serialising
+ * objects, and uses the whole body when none of those fields exist. An empty,
+ * whitespace-only or HTML-document body falls back to the error's own message.
+ * @param err - The error object to describe
+ * @param defaultText - The fallback error message
+ */
+export function errorText(err, defaultText) {
+    if (err instanceof AxiosError) {
+        const text = bodyText(err.response?.data);
+        if (text)
+            return text;
+        return clip(err.message || defaultText);
+    }
+    if (err instanceof Error)
+        return clip(err.message || defaultText);
+    return defaultText;
+}
 /**
  * Formats an AxiosError into a CallToolResult with an appropriate message.
  * @param err - The error object to format
  * @param defaultText - The fallback error message
  */
 export function formatAxiosError(err, defaultText) {
-    let text = defaultText;
-    if (err instanceof AxiosError && err.response?.data) {
-        const message = err.response.data.message ||
-            err.response.data.error ||
-            err.message ||
-            defaultText;
-        text = message;
-    }
-    else if (err instanceof Error) {
-        text = err.message;
-    }
     return {
-        content: [{ type: "text", text }],
+        content: [{ type: "text", text: errorText(err, defaultText) }],
         isError: true,
     };
 }

package/dist/lib/utils.js

@@ -7,6 +7,9 @@ export function sanitizeUrlParam(param) {
     return param.replace(/[;&|`$(){}[\]<>]/g, "");
 }
 const ONE_MB = 1048576;
+// sharp's default (~268M px) lets one image decode to ~1 GB of RGBA; 25M px caps it near 100 MB.
+const MAX_INPUT_PIXELS = 25_000_000;
+const MAX_IMAGE_DIMENSION = 1920;
 let sharpConfigured = false;
 //Compresses a base64 image intelligently to keep it under 1 MB if needed.
 export async function maybeCompressBase64(base64) {
@@ -25,11 +28,19 @@ export async function maybeCompressBase64(base64) {
             sharp.concurrency(1);
             sharpConfigured = true;
         }
-        const compressedBuffer = await sharp(buffer).png({ quality }).toBuffer();
+        const image = globalConfig.REMOTE_MCP
+            ? sharp(buffer, { limitInputPixels: MAX_INPUT_PIXELS }).resize({
+                width: MAX_IMAGE_DIMENSION,
+                height: MAX_IMAGE_DIMENSION,
+                fit: "inside",
+                withoutEnlargement: true,
+            })
+            : sharp(buffer);
+        const compressedBuffer = await image.png({ quality }).toBuffer();
         return compressedBuffer.toString("base64");
     }
     catch (err) {
-        logger.warn("Image compression unavailable (sharp failed to load); returning the uncompressed image. %s", err instanceof Error ? err.message : String(err));
+        logger.warn("Image compression failed; returning the uncompressed image. %s", err instanceof Error ? err.message : String(err));
         return base64;
     }
 }

package/dist/tools/automate-utils/fetch-screenshots.d.ts

@@ -1,6 +1,10 @@
 import { SessionType } from "../../lib/constants.js";
 import { BrowserStackConfig } from "../../lib/types.js";
-export declare function fetchAutomationScreenshots(sessionId: string, sessionType: SessionType | undefined, config: BrowserStackConfig): Promise<{
+export declare const MAX_SCREENSHOT_BYTES: number | undefined;
+export declare function parseScreenshotUrls(text: string): string[];
+export type Screenshot = {
     url: string;
     base64: string;
-}[]>;
+    mimeType: string;
+};
+export declare function fetchAutomationScreenshots(sessionId: string, sessionType: SessionType | undefined, config: BrowserStackConfig): Promise<Screenshot[]>;

package/dist/tools/automate-utils/fetch-screenshots.js

@@ -3,6 +3,10 @@ import { SessionType } from "../../lib/constants.js";
 import { getBrowserStackAuth } from "../../lib/get-auth.js";
 import { apiClient } from "../../lib/apiClient.js";
 import globalConfig from "../../config.js";
+import { MAX_LOG_BYTES } from "../failurelogs-utils/utils.js";
+export const MAX_SCREENSHOT_BYTES = globalConfig.REMOTE_MCP
+    ? 10 * 1024 * 1024
+    : undefined;
 async function extractScreenshotUrls(sessionId, sessionType, config) {
     const authString = getBrowserStackAuth(config);
     const auth = Buffer.from(authString).toString("base64");
@@ -14,47 +18,112 @@ async function extractScreenshotUrls(sessionId, sessionType, config) {
             "Content-Type": "application/json",
             Authorization: `Basic ${auth}`,
         },
+        maxContentLength: MAX_LOG_BYTES,
         raise_error: false,
     });
+    if (response.status === 413) {
+        throw new Error("The logs for this session are too large (over 5 MB) to find screenshots here. Open the session in the BrowserStack dashboard to view them.");
+    }
     await assertOkResponse(response, "Session");
     const text = typeof response.data === "string"
         ? response.data
         : JSON.stringify(response.data);
+    return parseScreenshotUrls(text);
+}
+const LOG_PREFIX = String.raw `^\d{4}-\d{2}-\d{2} \d{1,2}:\d{1,2}:\d{1,2}:\d{1,3} `;
+const LINE_TYPE_PATTERN = new RegExp(`${LOG_PREFIX}([A-Z_]+) `);
+const SCREENSHOT_REQUEST_PATTERN = new RegExp(String.raw `${LOG_PREFIX}REQUEST \[[^\]]+\] GET /session/[^/\s]+/screenshot(\s|$)`);
+const RESPONSE_VALUE_PATTERN = new RegExp(String.raw `${LOG_PREFIX}RESPONSE \{"value"\s*:\s*"(https://[^"]+)"`);
+const DEBUG_SCREENSHOT_PATTERN = new RegExp(String.raw `${LOG_PREFIX}DEBUG (https://\S+)$`);
+const TRUSTED_HOST_PATTERN = /(^|\.)browserstack\.com$|\.s3([.-][a-z0-9-]+)*\.amazonaws\.com$|\.backblazeb2\.com$/;
+function isTrustedScreenshotUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" && TRUSTED_HOST_PATTERN.test(url.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+export function parseScreenshotUrls(text) {
     const urls = [];
-    const SCREENSHOT_PATTERN = /REQUEST.*GET.*\/screenshot/;
-    const RESPONSE_VALUE_PATTERN = /"value"\s*:\s*"([^"]+)"/;
-    // Split logs into lines and process them
-    const lines = text.split("\n");
-    for (let i = 0; i < lines.length - 1; i++) {
-        const currentLine = lines[i];
-        const nextLine = lines[i + 1];
-        if (SCREENSHOT_PATTERN.test(currentLine)) {
-            const match = nextLine.match(RESPONSE_VALUE_PATTERN);
-            if (match && match[1]) {
-                urls.push(match[1]);
+    const lines = text.split("\n").map((line) => line.trimEnd());
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const debugMatch = line.match(DEBUG_SCREENSHOT_PATTERN);
+        if (debugMatch) {
+            urls.push(debugMatch[1]);
+            continue;
+        }
+        if (!SCREENSHOT_REQUEST_PATTERN.test(line)) {
+            continue;
+        }
+        for (let j = i + 1; j < lines.length; j++) {
+            const lineType = lines[j].match(LINE_TYPE_PATTERN)?.[1];
+            if (lineType === "REQUEST") {
+                break;
+            }
+            if (lineType === "RESPONSE") {
+                const valueMatch = lines[j].match(RESPONSE_VALUE_PATTERN);
+                if (valueMatch) {
+                    urls.push(valueMatch[1]);
+                }
+                break;
             }
         }
     }
-    return urls;
+    return [...new Set(urls)].filter(isTrustedScreenshotUrl);
+}
+function detectImageMimeType(buffer) {
+    if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
+        return "image/jpeg";
+    }
+    return "image/png";
 }
+// Returns null for a screenshot over MAX_SCREENSHOT_BYTES so the rest still load.
 async function fetchAndCompress(url) {
-    const response = await apiClient.get({ url, responseType: "arraybuffer" });
+    const response = await apiClient.get({
+        url,
+        responseType: "arraybuffer",
+        maxContentLength: MAX_SCREENSHOT_BYTES,
+        raise_error: false,
+    });
+    if (response.status === 413) {
+        return null;
+    }
+    if (!response.ok) {
+        throw new Error(`Failed to download screenshot: ${response.status} ${response.statusText}`);
+    }
     // Axios returns response.data as a Buffer for binary data
-    const base64 = Buffer.from(response.data).toString("base64");
-    return { url, base64: await maybeCompressBase64(base64) };
+    const buffer = Buffer.from(response.data);
+    const base64 = await maybeCompressBase64(buffer.toString("base64"));
+    // Detect AFTER compression: sharp re-encodes anything over 1 MB to PNG, so
+    // reading the original bytes would label a large JPEG with the wrong type.
+    return {
+        url,
+        base64,
+        mimeType: detectImageMimeType(Buffer.from(base64, "base64")),
+    };
 }
 //Converts screenshot URLs to base64 encoded images
 async function convertUrlsToBase64(urls) {
+    let results;
     // Hosted pods are memory-constrained: process one image at a time. Local runs
     // keep the concurrent path.
     if (globalConfig.REMOTE_MCP) {
-        const screenshots = [];
+        results = [];
         for (const url of urls) {
-            screenshots.push(await fetchAndCompress(url));
+            results.push(await fetchAndCompress(url));
         }
-        return screenshots;
     }
-    return Promise.all(urls.map(fetchAndCompress));
+    else {
+        results = await Promise.all(urls.map(fetchAndCompress));
+    }
+    const screenshots = results.filter((s) => s !== null);
+    if (urls.length > 0 && screenshots.length === 0) {
+        throw new Error("The screenshots in this session are too large (over 10 MB each) to fetch here. Open the session in the BrowserStack dashboard to view them.");
+    }
+    return screenshots;
 }
 //Fetches and converts screenshot URLs to base64 encoded images
 export async function fetchAutomationScreenshots(sessionId, sessionType = SessionType.Automate, config) {

package/dist/tools/automate.js

@@ -14,7 +14,7 @@ export async function fetchAutomationScreenshotsTool(args, config) {
                 content: [
                     {
                         type: "text",
-                        text: "No screenshots found in the session or some unexpected error occurred",
+                        text: "No screenshots found in the session logs. Run with browserstack.debug: true to capture visual-log screenshots.",
                     },
                 ],
                 isError: true,
@@ -23,7 +23,7 @@ export async function fetchAutomationScreenshotsTool(args, config) {
         const results = screenshots.map((screenshot, index) => ({
             type: "image",
             data: screenshot.base64,
-            mimeType: "image/png",
+            mimeType: screenshot.mimeType,
             _meta: { url: screenshot.url, index: index + 1 },
         }));
         return {

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

@@ -0,0 +1,68 @@
+/**
+ * Narrowing a response the product will not narrow itself.
+ *
+ * invokeCapability makes one request and hands back what came off the wire. That is the
+ * right default and it stays the default: a caller reasoning about a product's answer
+ * should be reasoning about the product's answer. This is the declared exception.
+ *
+ * It exists because of `list_browsers`. `/automate/browsers.json` returns every operating
+ * system, browser and version combination the account can run — 5,251 rows and 604 KB —
+ * and accepts no parameters at all: `?os=Windows`, `?browser=chrome` and `?zzz=1` all come
+ * back byte-identical to the bare call. Its guidance told the caller to "narrow it
+ * yourself", which it had no means to do; the only way to use the capability was to not be
+ * an agent, because 604 KB of JSON is most of a context window spent to learn that Chrome
+ * runs on Windows 11.
+ *
+ * WHAT KEEPS THIS FROM BECOMING A SECOND API. Three rules, and they are the whole design:
+ *
+ *  1. A capability must declare `narrowable` before any of this is reachable. Nothing is
+ *     applied to a capability that did not ask for it, so the untouched-response promise
+ *     is intact everywhere it was intact before.
+ *  2. Only the fields it names may be used, and a field outside that set is refused BY
+ *     NAME with the set listed — the same way an unknown host is refused. A caller that
+ *     guesses `platform` learns what the fields are instead of silently getting everything.
+ *  3. The result says it was narrowed, from how many rows, and by what. A smaller answer
+ *     that does not announce itself is indistinguishable from a product that returned less
+ *     than it has, which is the failure this must not introduce.
+ *
+ * It is NOT a query language and should not grow into one. Equality, membership, distinct
+ * tuples, projection, a cap. Anything a caller cannot express here is a reason to look for
+ * a product endpoint that filters, not a reason to add an operator.
+ */
+import { Capability } from "./types.js";
+/** What the caller asked for. Every field is optional; an empty selection narrows nothing. */
+export interface Selection {
+    /**
+     * Field → the value it must take, or any of several.
+     *
+     * Strings compare case-insensitively. The product's own spellings are not consistent —
+     * `Windows` and `OS X` are capitalised, `android` and `ios` are not, in the same column
+     * of the same response — so an exact match would refuse half the corpus on a technicality
+     * the caller cannot see from the field name.
+     */
+    where?: Record<string, unknown>;
+    /** Return one row per distinct combination of these fields, and nothing else. */
+    distinct?: string[];
+    /** Keep only these fields on each row. */
+    fields?: string[];
+    /** At most this many rows, applied last. */
+    limit?: number;
+}
+export interface Narrowing {
+    /** Rows the product sent. */
+    from: number;
+    /** Rows being handed back. */
+    to: number;
+    /** Echoed so the answer carries the question — a narrowed body is not self-describing. */
+    by: Selection;
+}
+/**
+ * Apply a selection to a response, or refuse it.
+ *
+ * Returns `undefined` when there is nothing to do — no selection, or a capability that
+ * declares none — so the caller hands back the original body and the default holds.
+ */
+export declare function narrowResponse(capability: Capability, body: unknown, selection: Selection | undefined): {
+    body: unknown;
+    narrowing: Narrowing;
+} | undefined;

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

@@ -0,0 +1,140 @@
+/**
+ * Narrowing a response the product will not narrow itself.
+ *
+ * invokeCapability makes one request and hands back what came off the wire. That is the
+ * right default and it stays the default: a caller reasoning about a product's answer
+ * should be reasoning about the product's answer. This is the declared exception.
+ *
+ * It exists because of `list_browsers`. `/automate/browsers.json` returns every operating
+ * system, browser and version combination the account can run — 5,251 rows and 604 KB —
+ * and accepts no parameters at all: `?os=Windows`, `?browser=chrome` and `?zzz=1` all come
+ * back byte-identical to the bare call. Its guidance told the caller to "narrow it
+ * yourself", which it had no means to do; the only way to use the capability was to not be
+ * an agent, because 604 KB of JSON is most of a context window spent to learn that Chrome
+ * runs on Windows 11.
+ *
+ * WHAT KEEPS THIS FROM BECOMING A SECOND API. Three rules, and they are the whole design:
+ *
+ *  1. A capability must declare `narrowable` before any of this is reachable. Nothing is
+ *     applied to a capability that did not ask for it, so the untouched-response promise
+ *     is intact everywhere it was intact before.
+ *  2. Only the fields it names may be used, and a field outside that set is refused BY
+ *     NAME with the set listed — the same way an unknown host is refused. A caller that
+ *     guesses `platform` learns what the fields are instead of silently getting everything.
+ *  3. The result says it was narrowed, from how many rows, and by what. A smaller answer
+ *     that does not announce itself is indistinguishable from a product that returned less
+ *     than it has, which is the failure this must not introduce.
+ *
+ * It is NOT a query language and should not grow into one. Equality, membership, distinct
+ * tuples, projection, a cap. Anything a caller cannot express here is a reason to look for
+ * a product endpoint that filters, not a reason to add an operator.
+ */
+import { InvocationError } from "./index-loader.js";
+function isSelectionEmpty(selection) {
+    return (!selection.where &&
+        !selection.distinct &&
+        !selection.fields &&
+        selection.limit === undefined);
+}
+/** The array inside a body, by the capability's declared path. */
+function rowsAt(body, path) {
+    let here = body;
+    for (const step of (path ?? "").split(".").filter(Boolean)) {
+        if (typeof here !== "object" || here === null)
+            return undefined;
+        here = here[step];
+    }
+    return Array.isArray(here) ? here : undefined;
+}
+/** The body with its array replaced, leaving every sibling key as the product sent it. */
+function withRows(body, path, rows) {
+    const steps = (path ?? "").split(".").filter(Boolean);
+    if (steps.length === 0)
+        return rows;
+    const clone = {
+        ...body,
+    };
+    let here = clone;
+    for (const step of steps.slice(0, -1)) {
+        here[step] = { ...here[step] };
+        here = here[step];
+    }
+    here[steps[steps.length - 1]] = rows;
+    return clone;
+}
+function sameValue(cell, wanted) {
+    if (typeof cell === "string" && typeof wanted === "string")
+        return cell.toLowerCase() === wanted.toLowerCase();
+    // `real_mobile` is true or null, and a caller who writes "true" means true.
+    if (typeof cell === "boolean" && typeof wanted === "string")
+        return String(cell) === wanted.toLowerCase();
+    if (cell === null || cell === undefined)
+        return wanted === null || wanted === "null";
+    return cell === wanted;
+}
+function assertKnownFields(used, allowed, what) {
+    const unknown = used.filter((field) => !allowed.includes(field));
+    if (unknown.length > 0)
+        throw new InvocationError(`${what} names ${unknown.map((f) => `'${f}'`).join(", ")}, which this capability ` +
+            `cannot be narrowed on. The fields it accepts are: ${allowed.join(", ")}.`);
+}
+/**
+ * Apply a selection to a response, or refuse it.
+ *
+ * Returns `undefined` when there is nothing to do — no selection, or a capability that
+ * declares none — so the caller hands back the original body and the default holds.
+ */
+export function narrowResponse(capability, body, selection) {
+    if (!selection || isSelectionEmpty(selection))
+        return undefined;
+    const declared = capability.narrowable;
+    if (!declared)
+        throw new InvocationError("that capability does not support `select`: it returns the product's response as " +
+            "sent. describeCapability names the ones that do, under `narrowable`.");
+    const allowed = declared.fields;
+    assertKnownFields(Object.keys(selection.where ?? {}), allowed, "`where`");
+    assertKnownFields(selection.distinct ?? [], allowed, "`distinct`");
+    assertKnownFields(selection.fields ?? [], allowed, "`fields`");
+    const rows = rowsAt(body, declared.path);
+    // A body that is not the shape the capability promised is handed back whole. Narrowing
+    // an error payload, or a response that changed shape, would hide exactly the thing the
+    // caller needs to see.
+    if (!rows)
+        return undefined;
+    let out = rows;
+    for (const [field, wanted] of Object.entries(selection.where ?? {})) {
+        const wantedValues = Array.isArray(wanted) ? wanted : [wanted];
+        out = out.filter((row) => {
+            const cell = row?.[field];
+            return wantedValues.some((value) => sameValue(cell, value));
+        });
+    }
+    if (selection.distinct?.length) {
+        const seen = new Set();
+        const unique = [];
+        for (const row of out) {
+            const picked = Object.fromEntries(selection.distinct.map((field) => [
+                field,
+                row?.[field],
+            ]));
+            const key = JSON.stringify(picked);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            unique.push(picked);
+        }
+        out = unique;
+    }
+    else if (selection.fields?.length) {
+        out = out.map((row) => Object.fromEntries(selection.fields.map((field) => [
+            field,
+            row?.[field],
+        ])));
+    }
+    if (selection.limit !== undefined)
+        out = out.slice(0, Math.max(0, selection.limit));
+    return {
+        body: withRows(body, declared.path, out),
+        narrowing: { from: rows.length, to: out.length, by: selection },
+    };
+}

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

@@ -21,6 +21,7 @@ import { indexPaths, isEnabled, resolveBaseUrl } from "./config.js";
 import { redact } from "./redact.js";
 import { fetchTransport } from "./egress.js";
 import { CapabilityRegistry, InvocationError, resolveResponses, } from "./index-loader.js";
+import { narrowResponse } from "./narrow.js";
 import { invoke } from "./resolve.js";
 import { ambiguousProducts, productAnchors, isBrowseQuery, searchCapabilities, singular, terms, vocabularyOf, } from "./search.js";
 export const PERMISSION_VALUES = ["not_asked", "granted", "denied"];
@@ -793,8 +794,27 @@ export function addCapabilityRegistryTools(server, deps, config) {
             // Dropped rather than overwritten: the raw field holds `{"$response": …}` pointers,
             // and spreading the capability would leak them through whenever the resolved value
             // is absent.
-            const { responses: unresolved, method, path, ...contract } = capability;
+            //
+            // THE WIRE FIELDS GO WITH IT, for the same reason the route does: they describe how
+            // WE reach the product, not anything the caller supplies or acts on. `host` names
+            // which of the product's origins serves this one capability; `encoding` and
+            // `send_empty_body` say how the request body is framed; `local_only` and `disabled`
+            // are claims about which surface publishes it, already answered by the capability
+            // being present at all. A contract that shows them invites a caller to reason about
+            // plumbing it cannot influence — and `host: "api"` was doing exactly that in a
+            // shipped describe response.
+            //
+            // `invocable` STAYS, and is the one of these that is not plumbing. Presence says the
+            // capability is published, which is not the same as callable: a reference-only entry
+            // is published precisely so search can still find it and say what to do instead.
+            // Stripping the flag would leave that fact only in a prose guidance line.
+            const { responses: unresolved, method, path, host, encoding, send_empty_body, local_only, disabled, ...contract } = capability;
             void unresolved;
+            void host;
+            void encoding;
+            void send_empty_body;
+            void local_only;
+            void disabled;
             return ok({
                 // No build_id here either, same reason. `product` stays: describeCapability
                 // resolves by NAME and its product argument is optional, so the answer has to
@@ -826,7 +846,9 @@ export function addCapabilityRegistryTools(server, deps, config) {
         "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 " +
+        "makes exactly one request and returns the product's own response as sent — unless " +
+        "you pass `select`, which only capabilities whose contract carries `narrowable` " +
+        "accept, and which reports what it narrowed. 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 " +
@@ -870,6 +892,29 @@ export function addCapabilityRegistryTools(server, deps, config) {
             .string()
             .optional()
             .describe("What will change. Required for writes."),
+        select: z
+            .object({
+            where: z
+                .record(z.string(), z.any())
+                .optional()
+                .describe("Field -> the value it must take, or an array of accepted values. Strings " +
+                "match case-insensitively."),
+            distinct: z
+                .array(z.string())
+                .optional()
+                .describe("Return one row per distinct combination of these fields and nothing else — " +
+                "the cheapest way to ask what values exist."),
+            fields: z
+                .array(z.string())
+                .optional()
+                .describe("Keep only these fields on each row."),
+            limit: z.number().optional().describe("At most this many rows."),
+        })
+            .optional()
+            .describe("ONLY for a capability whose contract carries `narrowable`, which names the " +
+            "fields this may use; on any other capability it is refused. Those endpoints " +
+            "take no filtering parameters of their own, so this is applied to the response " +
+            "here, and the result reports what it narrowed and from how many rows."),
     }, {
         title: "Invoke Capability",
         // Not read-only: this is the one tool that writes. Never destructive, because
@@ -949,6 +994,20 @@ export function addCapabilityRegistryTools(server, deps, config) {
                 }
             }
             const result = await invoke(capability, args, await deps.baseUrlFor(product, capability.host), deps.credentialsFor(), transport, registry.index.products[product]?.auth, product);
+            // NARROWING IS APPLIED TO A SUCCESS ONLY. A 4xx body is the diagnosis the caller
+            // needs whole, and a selection that happened to match none of its keys would
+            // quietly empty it. `narrowResponse` refuses an unsupported `select` by throwing,
+            // which lands in the InvocationError branch below with the accepted fields listed.
+            const narrowed = result.ok
+                ? narrowResponse(capability, result.http_response.body, input.select)
+                : undefined;
+            const answer = narrowed
+                ? {
+                    ...result,
+                    http_response: { ...result.http_response, body: narrowed.body },
+                    narrowed: narrowed.narrowing,
+                }
+                : result;
             // The one row for a completed invoke. invoke() returns a 4xx/5xx rather than
             // throwing, so `success` keeps its tool-level meaning and these two fields carry
             // whether the product call worked. Status 0 means it could not be reached.
@@ -957,8 +1016,14 @@ export function addCapabilityRegistryTools(server, deps, config) {
                 upstream_ok: result.ok,
                 upstream_status: result.http_response.status,
                 change_summary: redact(input.change_summary),
+                ...(narrowed
+                    ? {
+                        narrowed_from: narrowed.narrowing.from,
+                        narrowed_to: narrowed.narrowing.to,
+                    }
+                    : {}),
             });
-            return ok(result);
+            return ok(answer);
         }
         catch (error) {
             if (error instanceof InvocationError)

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

@@ -117,24 +117,6 @@ export interface ProductAmbiguity {
     /** 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 {

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

@@ -122,11 +122,32 @@ export function isBrowseQuery(query) {
     const q = (query || "").trim().toLowerCase();
     return q === "*" || q === "all";
 }
+/**
+ * OUR OWN NAME, WHICH IS NOT ROUTING VOCABULARY.
+ *
+ * Every product here is BrowserStack's, so the word distinguishes none of them — it is a
+ * stopword in the strict sense. It could not be spelled as one, because the camelCase
+ * split above runs first and turns "BrowserStack" into `browser` + `stack`, two words that
+ * ARE vocabulary: `browser` is a devicecontrol entity and an alias on a tm configuration.
+ *
+ * So the company's name claimed a product's noun. "Which Android apps have I uploaded to
+ * BrowserStack?" clashed over `browser` across four products, and the question put to the
+ * user — devicecontrol or mobiledevicecontrol or tm or tra — was unanswerable, because no
+ * word in the request was really about browsers at all. It reached further than queries
+ * that name us: the tm and tra summaries say "BrowserStack", so those two became claimants
+ * of `browser` permanently, and "what browsers can I use" clashed four ways on a word only
+ * devicecontrol models.
+ *
+ * Matched after the split and the fold, so one pattern covers "BrowserStack", "browserstack"
+ * and "browser stack". `bstack` is the same name in the shorthand the logs and repos use.
+ */
+const BRAND = /\bbrowser\s*stack\b|\bbstack\b/g;
 export function terms(text) {
     return [
         ...(text || "")
             .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
             .toLowerCase()
+            .replace(BRAND, " ")
             .matchAll(WORD),
     ]
         .map((match) => match[0])
@@ -530,6 +551,22 @@ const GENERIC_ANCHORS = new Set(["test", "tests", "testing"]);
  * answered the question and there is nothing to ask. Only queries whose every recognised
  * word is shared are genuinely undecided.
  */
+/**
+ * The words that do disclaiming work in a product summary.
+ *
+ * Deliberately a list of markers rather than anything resembling negation parsing: the
+ * sentences this has to catch are written to one pattern ("X is not here", "neither is Y",
+ * "unlike Test Management", "rather than a browser"), and a looser rule would start
+ * discarding prose that claims.
+ */
+const DISCLAIMS = /\b(?:not|never|neither|nor|unlike|rather than|instead of|except)\b/i;
+/** A summary with its disclaiming sentences removed, for the claimant pass only. */
+function claimingSentences(summary) {
+    return (summary ?? "")
+        .split(/(?<=[.!?])\s+/)
+        .filter((sentence) => !DISCLAIMS.test(sentence))
+        .join(" ");
+}
 export function ambiguousProducts(products, query) {
     const none = { products: [], terms: [] };
     if (terms(query).length === 0)
@@ -580,9 +617,20 @@ export function ambiguousProducts(products, query) {
     // product already models catches that, and refusing to mine NEW terms out of it is what
     // keeps the prose from taking over: a summary is a paragraph of verbs and nouns written
     // to sell the product, and every word in it would otherwise become routing vocabulary.
+    //
+    // AND ONLY FROM A SENTENCE THAT CLAIMS. These summaries route deliberately — each one
+    // carries a sentence saying what is NOT in it and where to go instead, which is the most
+    // useful sentence in the paragraph and was being read as the opposite of what it says.
+    // "Browsers are not here — those are device control" made mobiledevicecontrol a claimant
+    // of `browser`, and "Mobile APPS are not here" made devicecontrol a claimant of `app`.
+    // Both products were then offered to the user for a word their own summary disowns.
+    //
+    // Dropping a sentence can only ever narrow a clash, never misdirect one: prose cannot
+    // introduce a term, so the worst case is a clash that goes unreported — and a product
+    // that genuinely handles something does not say so in a negated sentence.
     const summaries = Object.fromEntries(Object.entries(products).map(([product, index]) => [
         product,
-        ` ${fold(index.summary ?? "")} `,
+        ` ${fold(claimingSentences(index.summary))} `,
     ]));
     for (const [key, claimants] of owners) {
         for (const [product, text] of Object.entries(summaries)) {

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

@@ -229,6 +229,32 @@ export interface Capability {
      * something this can verify.
      */
     send_empty_body?: boolean;
+    /**
+     * This capability's array response may be narrowed by the server, on these fields.
+     *
+     * THE PRODUCT CANNOT DO IT. Declaring this is a statement that the endpoint offers no
+     * filtering of its own — not that ours is more convenient. `/automate/browsers.json`
+     * returns 5,251 rows and ignores every query parameter it is given, so a caller asking
+     * which browsers run on Windows had to receive 604 KB and find out itself.
+     *
+     * Where the wire DOES filter, declare the parameters and let the product filter: a
+     * server-side pass still transfers the whole response and still costs the round trip,
+     * and it moves the contract off the product and onto us.
+     *
+     * Unset — which is every other capability — means `select` is refused outright and the
+     * response is handed back exactly as sent.
+     */
+    narrowable?: {
+        /** The only fields `select` may name. Anything else is refused with this list. */
+        fields: string[];
+        /**
+         * Dotted path to the array inside the body; omitted when the body IS the array.
+         * Siblings of the array are preserved, so an envelope survives the narrowing.
+         */
+        path?: string;
+        /** One line for the contract: why this is here rather than on the wire. */
+        note?: string;
+    };
     paginated?: boolean;
     /** The largest page the operation declares. */
     max_page_size?: number;

package/dist/tools/testmanagement-utils/update-testcase.js

@@ -1,6 +1,6 @@
 import { apiClient } from "../../lib/apiClient.js";
 import { z } from "zod";
-import { formatAxiosError } from "../../lib/error.js";
+import { errorText } from "../../lib/error.js";
 import { fetchFormFields, normalizeDefaultFields as normalizeDefaultFieldsFromForm, projectIdentifierToId, } from "./TCG-utils/api.js";
 import { getTMBaseURL } from "../../lib/tm-base-url.js";
 import { getBrowserStackAuth } from "../../lib/get-auth.js";
@@ -218,12 +218,14 @@ Error details: ${JSON.stringify(err.response?.data || err.message)}`,
                 isError: true,
             };
         }
-        const errorMessage = formatAxiosError(err, "Failed to update test case");
+        const status = err.response?.status;
+        const detail = errorText(err, "unknown error");
+        const hint = status === 401 ? " Check the BrowserStack credentials in use." : "";
         return {
             content: [
                 {
                     type: "text",
-                    text: `Failed to update test case: ${errorMessage}. Please verify your credentials and try again.`,
+                    text: `Failed to update test case${status ? ` (HTTP ${status})` : ""}: ${detail}.${hint}`,
                 },
             ],
             isError: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserstack/mcp-server",
-  "version": "2.3.0-beta.2",
+  "version": "2.3.0-beta.4",
   "description": "BrowserStack's Official MCP Server",
   "mcpName": "io.github.browserstack/mcp-server",
   "main": "dist/index.js",