@browserstack/mcp-server 2.3.0-beta.1 → 2.3.0-beta.3

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

@@ -2,8 +2,8 @@
  "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.",
+ "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 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 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": {
@@ -204,7 +206,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": [
@@ -246,7 +248,8 @@
      "A session starts in seconds rather than the tens of seconds a device session takes, but it still holds a browser and consumes Automate minutes until it ends: always finish with set_session_status and then delete_session.",
      "The session ends itself after idle_timeout seconds without a command, and after 2 hours in total.",
      "console_logs and network_logs must be asked for here; they cannot be turned on once the session is running, and get_session only links to them when they were.",
-     "Credentials belong in the Authorization header, never inside bstack:options: capabilities are echoed back in session-not-created errors."
+     "Credentials belong in the Authorization header, never inside bstack:options: capabilities are echoed back in session-not-created errors.",
+     "resolution takes one of a fixed set of values per operating system, not any width and height: an unsupported pair is refused outright rather than rounded to the nearest one. The browser window is well short of the screen it sits on \u2014 1920x1080 gives a viewport around 930x860 \u2014 so measure it rather than assuming the request was honoured."
     ],
     "body": [
      {
@@ -317,7 +320,7 @@
       "name": "resolution",
       "type": "string",
       "json_path": "/capabilities/alwaysMatch/bstack:options/resolution",
-      "description": "Desktop screen resolution. The browser window is smaller than this; read the real size from get_window_rect.",
+      "description": "Desktop screen resolution, from a fixed set the chosen OS supports \u2014 an unsupported value is refused with \"The specified screen resolution is not compatible with the chosen OS version\" and no session starts. 1920x1080 is accepted on Windows 11; 2560x1440 is not. The browser window is much smaller than the screen either way, so read the real size rather than assuming it.",
       "example": "1920x1080"
      },
      {
@@ -363,14 +366,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",
@@ -378,7 +381,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": [
@@ -424,7 +427,7 @@
       "required": true,
       "format": "uri",
       "description": "Absolute URL including the scheme.",
-      "example": "https://www.bstackdemo.com/"
+      "example": "https://www.example.com/products"
      }
     ],
     "returns": [
@@ -648,8 +651,7 @@
      "404": {
       "$response": "WebDriverError"
      }
-    },
-    "disabled": true
+    }
    },
    {
     "name": "find_element",
@@ -691,7 +693,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 +750,7 @@
       "type": "string",
       "required": true,
       "description": "The selector itself, interpreted according to using.",
-      "example": ".shelf-item__buy-btn"
+      "example": ".product-card"
      }
     ],
     "returns": [
@@ -791,7 +793,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": [
@@ -820,7 +822,7 @@
     "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.",
-     "A \\n at the end submits the form, which is usually quicker than finding and clicking the submit button.",
+     "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 +838,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 +847,7 @@
       "type": "string",
       "required": true,
       "description": "The characters to type. End with \\n to submit.",
-      "example": "BrowserStack"
+      "example": "hello"
      }
     ],
     "returns": [
@@ -888,7 +890,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 +933,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": [
@@ -974,7 +976,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 +1025,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 +1074,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": [
@@ -1213,8 +1215,7 @@
      "404": {
       "$response": "WebDriverError"
      }
-    },
-    "disabled": true
+    }
    },
    {
     "name": "set_window_rect",
@@ -1380,7 +1381,7 @@
       "type": "string",
       "required": true,
       "description": "Handle from list_window_handles.",
-      "example": "2FFCF2904DC789DD82BACEF48E43AE93"
+      "example": "00000000000000000000000000000000"
      }
     ],
     "returns": [

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

@@ -2,8 +2,8 @@
  "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.",
+ "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, 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. 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": {
@@ -72,7 +75,7 @@
      "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.",
      "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",
@@ -342,8 +345,7 @@
      "404": {
       "$response": "WebDriverError"
      }
-    },
-    "disabled": true
+    }
    },
    {
     "name": "find_element",
@@ -356,7 +358,8 @@
      "The element id comes back under the W3C key value[\"element-6066-11e4-a52e-4f735466cecf\"]; pass that string as element_id.",
      "Take the selector from get_page_source rather than guessing: resource-id \u2192 \"id\", content-desc (Android) or name (iOS) \u2192 \"accessibility id\".",
      "No match is a 404 with error \"no such element\" \u2014 re-read the page source; the screen may have changed or the element may be off-screen and need a scroll first.",
-     "\"-android uiautomator\" accepts a UiSelector expression, which can scroll an element into view: new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(new UiSelector().text(\"Checkout\"))."
+     "\"-android uiautomator\" accepts a UiSelector expression, which can scroll an element into view: new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(new UiSelector().text(\"Checkout\")).",
+     "find_elements answers the same query with a list and never a 404, which is how to ask whether something is present without treating absence as a failure."
     ],
     "path_params": [
      {
@@ -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": [
@@ -703,8 +706,7 @@
      "404": {
       "$response": "WebDriverError"
      }
-    },
-    "disabled": true
+    }
    },
    {
     "name": "delete_session",
@@ -1122,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": [
@@ -1808,7 +1810,7 @@
      "Android takes appId and iOS takes bundleId \u2014 send exactly the one for the platform. The wrong name is refused with a 400 \"invalid argument\" that names the parameter it wanted, and no action is taken.",
      "Launching an app that is already in the foreground does nothing and still reports success.",
      "To restart an app from a clean state, call terminate_app first and then this.",
-     "Succeeding means the app was activated, not that it finished drawing; read the page source before acting.",
+     "Succeeding means the app was activated, not that it finished drawing, so give it a moment and confirm before acting. An app that cannot be brought forward at all answers 400 rather than reporting success, and get_app_state reads 4 once it really is in front \u2014 sampled too early it can still report the home screen mid-switch.",
      "The app must be installed \u2014 a package that is not there fails rather than installing it."
     ],
     "path_params": [
@@ -1953,7 +1955,7 @@
      "Android takes appId and iOS takes bundleId \u2014 send exactly the one for the platform. The wrong name is refused with a 400 \"invalid argument\" that names the parameter it wanted, and no action is taken.",
      "The value is a number: 0 not installed, 1 installed but not running, 2 running in the background and suspended, 3 running in the background, 4 running in the foreground.",
      "4 is the only state in which the app is on screen and can be driven.",
-     "The same scale applies on both platforms. Sending an app to the background with press_button home leaves it at 2, and launching it again returns it to 4."
+     "The same scale applies on both platforms. Sending an app to the background leaves it at 3 or 2 \u2014 the system suspends it a moment after it stops being visible \u2014 so treat anything below 4 as not on screen rather than waiting for one number. Launching it again returns it to 4."
     ],
     "path_params": [
      {
@@ -2638,6 +2640,67 @@
      }
     },
     "unavailable_note": "This server does not run on your own machine, so it cannot read a file you name \u2014 a path sent here would point at the machine hosting the server. Upload the build yourself with a multipart request carrying the file to the same endpoint, which the asset-upload helper will write out for you, and then use the bs:// url it returns as the app for create_session. upload_app_build does the same thing from a public download link, if the build is reachable at one."
+   },
+   {
+    "name": "find_elements",
+    "method": "POST",
+    "path": "/wd/hub/session/{session_id}/elements",
+    "mode": "read",
+    "entity": "app_session",
+    "intent": "Find every element matching a selector \u2014 use this to count matches, work through a list, or check whether something is present at all.",
+    "guidance": [
+     "No match is an EMPTY LIST and a 200, where find_element answers 404. That makes this the way to test whether something is there without handling an error.",
+     "An empty list can be trusted to mean absent: a strategy this surface does not accept is refused before the request is sent, and an iOS strategy aimed at an Android screen comes back as a 400 \"invalid selector\" rather than as nothing found.",
+     "Each entry carries the same element-6066-11e4-a52e-4f735466cecf key as find_element, and the ids go stale when the screen changes just as readily.",
+     "The order is the UI tree's own, so it follows the screen's layout rather than anything meaningful to the app.",
+     "Use find_element when exactly one match is expected: its 404 says plainly that the screen is not what you thought."
+    ],
+    "path_params": [
+     {
+      "name": "session_id",
+      "type": "string",
+      "required": true,
+      "example": "0123456789abcdef0123456789abcdef01234567"
+     }
+    ],
+    "body": [
+     {
+      "name": "using",
+      "type": "string",
+      "required": true,
+      "values": [
+       "id",
+       "accessibility id",
+       "xpath",
+       "class name",
+       "-android uiautomator",
+       "-ios predicate string",
+       "-ios class chain"
+      ],
+      "example": "accessibility id"
+     },
+     {
+      "name": "value",
+      "type": "string",
+      "required": true,
+      "description": "The selector itself, interpreted according to using.",
+      "example": "cart-button"
+     }
+    ],
+    "returns": [
+     "value"
+    ],
+    "responses": {
+     "200": {
+      "description": "Every matching element, possibly none.",
+      "schema": {
+       "$schema": "ElementListResponse"
+      }
+     },
+     "404": {
+      "$response": "WebDriverError"
+     }
+    }
    }
   ],
   "schemas": {
@@ -3065,6 +3128,23 @@
       }
      }
     }
+   },
+   "ElementListResponse": {
+    "type": "object",
+    "properties": {
+     "value": {
+      "type": "array",
+      "items": {
+       "type": "object",
+       "properties": {
+        "element-6066-11e4-a52e-4f735466cecf": {
+         "type": "string",
+         "description": "The element id to pass as element_id."
+        }
+       }
+      }
+     }
+    }
    }
   },
   "responses": {
@@ -3139,7 +3219,8 @@
      "press_button",
      "get_simulated_location",
      "get_active_app_info",
-     "read_device_property"
+     "read_device_property",
+     "find_elements"
     ]
    },
    "device": {

package/package.json

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