@raultov/browser-control-mcp 0.3.6-beta.6 → 0.4.0-beta.7

package/CHANGELOG.md

@@ -10,6 +10,147 @@ from a copy of its code: entries describe the differences from that release.
 
 ## [Unreleased]
 
+## [0.4.0-beta.7] - 2026-10-31
+
+Public **BETA**. Closes the gaps a comparison with Playwright MCP showed:
+`snapshot` and `find_in_snapshot` outline the page with refs every
+selector accepts, selectors reach into shadow roots and iframes with `>>>`,
+and new tools wait for content (`wait_for`), fill forms (`fill_form`),
+upload files, press keys, hover, read and change cookies and web storage,
+and emulate viewports. A click into a breakpoint or a dialog answers at once.
+Some behaviour changes: the `raw`, `perf`, `storage`, `files` and
+`emulation` tools are listed only with the new `--tool-groups` (start the
+server with `--tool-groups raw,perf` or `all` to keep `send_cdp_command`,
+`get_custom_events` and the performance tools), tool descriptions are about
+half as long, and `click_element` succeeds (noting it) when the click opens
+a dialog or hits a breakpoint.
+
+### Added
+
+- `--tool-groups` lists opt-in tool groups, comma separated: `storage`
+  (`cookies`, `web_storage`), `files` (`upload_file`), `raw`
+  (`send_cdp_command`, `send_bidi_command`, `send_rdp_request`,
+  `get_custom_events`), `perf` (`get_performance_metrics`,
+  `profile_page_performance`), `emulation` (`emulate`), or `all`. A tool of
+  a group that is off fails naming the flag. The tool list stays fixed for
+  the server's life (MCP 2026-07-28 forbids it to change as a side effect of
+  a call), so there is no tool to switch groups on during a session.
+
+- `emulate`: the tab's viewport (`width`, `height`, `device_scale_factor`,
+  and on Chrome `mobile` with touch) and, on Chrome, CSS media features
+  (`color_scheme`, `reduced_motion`, `forced_colors`, `media: print`);
+  `reset` removes them. It answers what the page now sees, measured in it
+  (size, pixel ratio, media queries). Firefox emulates the viewport and
+  pixel ratio through `browsingContext.setViewport`; its WebDriver BiDi has
+  no media or touch emulation yet, so those options fail there naming
+  them. Responsive and dark-mode checks needed raw protocol commands. (#9)
+
+- `cookies` and `web_storage` (Chrome and Firefox). `cookies` gets, sets
+  and deletes cookies: those the page's URL (or `url`) would be sent, or
+  those of a `domain`, optionally by `name` (Chrome `Network.*Cookie*`,
+  Firefox BiDi `storage.*` in the tab's partition, with the same filters
+  and replies). `web_storage` gets, sets, deletes and clears the page's
+  `localStorage` or `sessionStorage`. Both hide values (often session
+  tokens), giving their length, unless `show_values: true`. Cookies could
+  only be imported from your Chrome before. (#8)
+
+- `press_key` and `hover` (Chrome and Firefox), and `button`,
+  `click_count` and `modifiers` for `click_element`. `press_key` presses
+  one key (a character, Enter, Tab, Escape, Backspace, Delete, the arrows,
+  Home, End, PageUp, PageDown, Insert, Space, F1 to F12) with Control,
+  Shift, Alt or Meta held, in `selector` (focused first) or the focused
+  element, as a user (Chrome `Input.dispatchKeyEvent`, Firefox key
+  actions); a shortcut types nothing, and a dialog or debugger pause the key
+  causes is noted like for a click. `hover` moves the mouse over an element
+  after the same visibility checks as `click_element`. A right click opens
+  context menus and `click_count: 2` double-clicks. These needed raw
+  protocol commands or synthetic JavaScript events, which many pages
+  ignore. (#7)
+
+- `upload_file` (Chrome and Firefox): sets the files of an
+  `<input type=file>` as a user picking them (Chrome
+  `DOM.setFileInputFiles`, Firefox `input.setFiles`); the page gets `input`
+  and `change`. Only files under the upload roots are accepted: the
+  server's working directory and the system temp directory, or the
+  directories of the new repeatable `--upload-root` flag, checked once `..`
+  and symlinks are resolved, so the agent cannot hand a page any file of
+  the machine. Uploads needed three raw CDP commands, on Chrome only. (#6)
+
+- `fill_form` (Chrome and Firefox): fills several fields in one call, in
+  order. Text fields, textareas, contenteditable elements and `<select>`s
+  go through `fill_input`; a checkbox or radio takes `true` or `false` and
+  is clicked only when its state differs. It answers
+  `Filled N fields.` with each field's outcome (`filled`, `selected`,
+  `checked`, `unchecked`, `unchanged`), never the values, and stops at the
+  first field that fails, naming it and what was done before. A login form
+  took one call per field. (#5)
+
+- `snapshot` and `find_in_snapshot` (Chrome and Firefox): an outline of the
+  page with one line per element with a role (`button "Sign in" [ref=e7]`,
+  `textbox "Username" [ref=e3]`, `heading "Cart" [level=2] [ref=e1]`...),
+  its name, states and value, indented under its parent, through open
+  shadow roots and same-origin iframes, hidden elements left out; and a
+  search over that outline that returns only the matching lines under their
+  ancestors (a 1500-row page: 143 characters to find a button instead of a
+  50 000-character snapshot). The `selector` of `click_element`,
+  `fill_input`, `scroll` and `wait_for` accepts the refs, so agents no
+  longer write CSS from raw HTML. Computed in the page with the same
+  JavaScript on both browsers (one outline, refs that resolve the same
+  way); refs are kept per element while it is in the page and end when the
+  page navigates; password values are never shown. (#4)
+
+- Selectors of `click_element`, `fill_input`, `scroll` and `wait_for` reach
+  into open shadow roots and same-origin iframes with `>>>`
+  (`my-widget >>> button`, `#frame >>> #email`, chainable), on both
+  browsers. `inspect_dom` showed those elements but no tool could act on
+  them. A click inside iframes is checked for overlays in each document and
+  lands at the right point of the top window; a part that is neither an
+  open shadow host nor a same-origin iframe fails naming it. `fill_input`
+  also recognises fields of another frame (they failed as "not an input").
+  (#3)
+
+- `wait_for` (Chrome and Firefox): waits until the page's visible text
+  contains `text` or no longer contains `text_gone`, the first element
+  matching `selector` is `visible`, `hidden`, `attached` or `detached`
+  (`state`), and/or the tab's URL contains `url`, checking every 100 ms up
+  to `timeout_ms` (default 5000, at most 30000). It answers
+  `Waited N ms for ...` with `{elapsed_ms, url}`, or fails naming what is
+  still missing and where the page is. Text includes open shadow roots and
+  same-origin iframes; a check the page did not answer (a navigation) is
+  retried; a JavaScript dialog or a debugger pause ends the wait at once.
+  Agents no longer have to write polling promises in `evaluate_js`. (#2)
+
+### Changed
+
+- The `raw`, `perf`, `storage`, `files` and `emulation` tools are no longer
+  listed by default: 33 tools are (plus `enable_proxy_auth` and the WebMCP
+  tools behind their flags). Start the server with `--tool-groups raw,perf`
+  (or `all`) to keep `send_cdp_command`, `get_custom_events` and the
+  performance tools.
+- Tool and argument descriptions are about half as long (the tool list of
+  every tool went from 72 986 to 35 568 characters, about 18 000 to 9 000
+  tokens; the 33 default tools take 23 555), and `instance_id` / `tab_id` no longer say "Chrome".
+
+- `click_element` succeeds when the click opens a JavaScript dialog or its
+  handler pauses in the debugger: the click happened, so the reply says so
+  (`... The page opened a JavaScript confirm dialog ("Delete?"), which
+  blocks it: call handle_dialog ...`), followed by `{"dialog": {...}}` or
+  `{"paused": true, "location": ...}`. It was an error, which invited
+  agents to click again. Calls whose answer is missing (`evaluate_js`) or
+  that may have stopped half way (`fill_input`) still fail. (#11)
+
+### Fixed
+
+- A call whose own code hits a breakpoint (`click_element` on a button whose
+  handler has one, `fill_input`, `scroll`, `evaluate_js`, `navigate`,
+  `reload`) fails at once on both browsers with where the page paused and
+  how to go on (`evaluate_on_call_frame`, `resume`, `step_over`). It waited
+  for the 10 s command timeout and failed with `Input.dispatchMouseEvent`
+  (Chrome) or `input.performActions` (Firefox) "timed out". On Chrome a
+  pause must last 200 ms to count, so a page's own `debugger;` the server
+  resumes does not fail the call. A Chrome click interrupted on the press
+  still sends the release, so the button is not left held. (#1)
+
 ## [0.3.6-beta.6] - 2026-10-29
 
 Public **BETA**. `fill_input` types the same way on both browsers,

package/README.md

@@ -11,7 +11,7 @@ It is the successor of
 from a copy of its code) and complements Playwright MCP or
 chrome-devtools-mcp with runtime JavaScript debugging on both browsers.
 
-> **Status: BETA (0.3.6-beta.6).** This version contains known bugs and differences
+> **Status: BETA (0.4.0-beta.7).** This version contains known bugs and differences
 > between Chrome and Firefox (see [Limitations and TODO](#limitations-and-todo))
 > and parts that have not been verified (see [Untested](#untested)). Tool
 > replies may change in incompatible ways before 1.0. Please report problems
@@ -29,6 +29,25 @@ life: start the server with `--browser firefox`, or pass
 `"browser": "firefox"` to `open_instance`. If Chrome is not installed but Firefox
 is, the launch error says so and tells the agent to ask you before switching.
 
+## Tool groups
+
+Every tool listed costs the agent context on every turn, so niche and risky
+tools are off by default and listed only with `--tool-groups`:
+
+| Group | Tools | Why it is opt-in |
+| --- | --- | --- |
+| `storage` | `cookies`, `web_storage` | reads and changes session tokens |
+| `files` | `upload_file` | hands a page files of the machine |
+| `raw` | `send_cdp_command`, `send_bidi_command`, `send_rdp_request`, `get_custom_events` | anything the protocol allows |
+| `perf` | `get_performance_metrics`, `profile_page_performance` | niche |
+| `emulation` | `emulate` | niche |
+
+`--tool-groups all` lists every group. The page, input, observation and
+debugger tools are always listed (33 tools), plus `enable_proxy_auth` with
+`--proxy-server` and the WebMCP tools with `--enable-webmcp`. A tool of a
+group that is off fails naming the flag. The list is fixed for the server's
+life: it never changes during a session, so clients can cache it.
+
 ## Feature matrix
 
 ✓ supported, ✗ not available (the tool answers a capability error naming the
@@ -49,17 +68,27 @@ see the note.
 | `navigate` | ✓ | ✓ | |
 | `reload` | ✓ | ✓ | |
 | `scroll` | ✓ | ✓ | reports the window positions before and after |
+| `emulate` | ✓ | partial | `emulation` group; `width`/`height`, `device_scale_factor`, `mobile` (touch), `color_scheme`, `reduced_motion`, `forced_colors`, `media` (`print`), `reset`; answers what the page now sees; Firefox: viewport and device pixel ratio only (BiDi has no media or touch emulation yet; those options fail naming them) |
+| `wait_for` | ✓ | ✓ | waits (checking every 100 ms, at most 30 s) until a visible text appears or is gone, a selector is `visible` / `hidden` / `attached` / `detached`, or the URL contains a text; a dialog or debugger pause ends the wait at once |
 | `inspect_dom` | ✓ | ✓ | includes open shadow roots and same-origin iframes (cross-origin ones are noted); at most 100 000 characters without `query` (cut in the page) |
+| `snapshot` | ✓ | ✓ | outline of the page: role, name, states, value and a ref (`e12`) per element, through open shadow roots and same-origin iframes; at most 50 000 characters (`selector` and `depth` narrow it); the same JavaScript on both browsers |
+| `find_in_snapshot` | ✓ | ✓ | `text` (case-insensitive) or `regex` over the whole outline; matching lines under their ancestors, at most 20 |
 | `capture_screenshot` | ✓ | ✓ | `format` `png`, `jpeg` (or `jpg`) or `webp`; `full_page` at most 16 384 px per side (a text note says when cut) |
-| `click_element` | ✓ | ✓ | scrolls the element into view; fails without clicking when it is hidden or covered |
+| `click_element` | ✓ | ✓ | scrolls the element into view; `button` (left/right/middle), `click_count` (2 = double click) and `modifiers`; fails without clicking when it is hidden or covered; `host >>> inner` selectors reach open shadow roots and same-origin iframes (also in `fill_input`, `scroll`, `wait_for`); a dialog or debugger pause the click causes is noted in a successful reply (`{dialog}` or `{paused, location}`) |
 | `fill_input` | ✓ | ✓ | picks `<select>` options; fails without typing on elements that cannot take the text; types key by key on both (key handlers run; newlines and tabs inserted as text), about 1 ms per character; `change` on leaving the field, or at the end when the window has no focus |
+| `press_key` | ✓ | ✓ | one key (a character, Enter, Tab, Escape, arrows, F1–F12...) with Control / Shift / Alt / Meta held, in `selector` (focused first) or the focused element; a shortcut types nothing |
+| `hover` | ✓ | ✓ | moves the mouse over the element (scrolled into view; fails when hidden or covered) |
+| `fill_form` | ✓ | ✓ | several fields in one call: text and `<select>` as `fill_input`, a checkbox or radio takes `true`/`false` and is clicked only when its state differs; stops at the first failing field naming what was done; never echoes values |
+| `upload_file` | ✓ | ✓ | `files` group; sets the files of an `<input type=file>` (Chrome `DOM.setFileInputFiles`, Firefox `input.setFiles`); files must be under the upload roots (`--upload-root`, default the working and temp directories) |
 | `handle_dialog` | ✓ | ✓ | accepts or dismisses the open `alert` / `confirm` / `prompt` / `beforeunload` dialog |
 | `evaluate_js` | ✓ | ✓ | `value` at most 100 000 characters (`truncated: true`); Chrome stops a script after 8 s, Firefox cannot (a looping tab is closed with `close_tab`) |
+| `cookies` | ✓ | ✓ | `storage` group; `get` / `set` / `delete`: the cookies sent to the page (or `url`) or of a `domain`; values hidden unless `show_values: true` (Chrome `Network.*Cookie*`, Firefox BiDi `storage.*` in the tab's partition) |
+| `web_storage` | ✓ | ✓ | `storage` group; `get` / `set` / `delete` / `clear` on the page's `localStorage` or `sessionStorage`; values hidden unless `show_values: true` |
 | `get_console_logs` | ✓ | ✓ | a message keeps at most 10 000 characters; Firefox: page errors, CSS warnings and platform messages need the debugger port |
 | `get_network_logs` | ✓ | ✓ | a failed request has `error`, a binary body `response_body_encoding: "base64"`; bodies at most 64 000 characters, none over 2 MB; a WebSocket payload keeps 64 000 (`payload_len` is the whole); Firefox: WebSocket frames need the debugger port |
-| `get_custom_events` | ✓ | partial | `{events, total, truncated}`, the newest `limit` events; `clear` removes the returned ones; params over 64 000 characters of JSON are replaced by `{truncated, characters}`; Firefox: events of the modules subscribed with `send_bidi_command` |
-| `get_performance_metrics` | ✓ | partial | Firefox: `Nodes`, `Frames`, `Resources`, `TransferSize` from the Web Performance APIs (no Performance domain), plus a note |
-| `profile_page_performance` | ✓ | partial | Firefox: FCP, LCP, DCL and Load from the Web Performance APIs; no trace, so `total_blocking_time_ms` and `top_long_tasks` are `null` |
+| `get_custom_events` | ✓ | partial | `raw` group; `{events, total, truncated}`, the newest `limit` events; `clear` removes the returned ones; params over 64 000 characters of JSON are replaced by `{truncated, characters}`; Firefox: events of the modules subscribed with `send_bidi_command` |
+| `get_performance_metrics` | ✓ | partial | `perf` group; Firefox: `Nodes`, `Frames`, `Resources`, `TransferSize` from the Web Performance APIs (no Performance domain), plus a note |
+| `profile_page_performance` | ✓ | partial | `perf` group; Firefox: FCP, LCP, DCL and Load from the Web Performance APIs; no trace, so `total_blocking_time_ms` and `top_long_tasks` are `null` |
 | `set_breakpoint` | ✓ | partial | Firefox: by URL only (no `script_id` / `script_hash`) |
 | `remove_breakpoint` | ✓ | ✓ | |
 | `resume` | ✓ | ✓ | |
@@ -68,9 +97,9 @@ see the note.
 | `search_scripts` | ✓ | ✓ | a long line's preview is 100 characters on each side of the match |
 | `pause_on_load` | ✓ | ✗ | TODO on Firefox, see [Limitations and TODO](#limitations-and-todo) |
 | `enable_proxy_auth` | ✓ | partial | needs `--proxy-server`; a request the proxy rejects twice is cancelled; untested on Firefox against a real proxy |
-| `send_cdp_command` | ✓ | ✗ | raw Chrome DevTools Protocol; refuses `Network`/`Page`/`Runtime`/`Log`/`Debugger.disable` and `Browser.close`; `Fetch.enable` comes with a note |
-| `send_bidi_command` | ✗ | ✓ | raw WebDriver BiDi; refuses `session.new`, `session.end`, `browser.close` |
-| `send_rdp_request` | ✗ | ✓ | raw Firefox RDP request to an actor (`thread`, `console`, `root` shortcuts) |
+| `send_cdp_command` | ✓ | ✗ | `raw` group; raw Chrome DevTools Protocol; refuses `Network`/`Page`/`Runtime`/`Log`/`Debugger.disable` and `Browser.close`; `Fetch.enable` comes with a note |
+| `send_bidi_command` | ✗ | ✓ | `raw` group; raw WebDriver BiDi; refuses `session.new`, `session.end`, `browser.close` |
+| `send_rdp_request` | ✗ | ✓ | `raw` group; raw Firefox RDP request to an actor (`thread`, `console`, `root` shortcuts) |
 | `webmcp_list_tools` | ✓ | ✗ | needs `--enable-webmcp`; WebMCP is a Chrome testing feature; every annotation Chrome reports is listed (`readOnly`, `consequential`, `untrustedContent`, `debugging`, `autosubmit`, newer ones as they are) |
 | `webmcp_invoke_tool` | ✓ | ✗ | needs `--enable-webmcp`; the output of an `untrustedContent` tool comes with a note to treat it as data |
 | `webmcp_get_invocation` | ✓ | ✗ | needs `--enable-webmcp` |
@@ -305,6 +334,18 @@ claude mcp add browser-control-mcp -- npx -y @raultov/browser-control-mcp
   A `value` over 100 000 characters is not returned whole: a string keeps
   its first 100 000, an object or array is measured in the page and only
   described; the reply then carries `"truncated": true`.
+- **Acting on elements.** `snapshot` outlines the page, one line per
+  element with a role, e.g. `textbox "Username" [ref=e3]`,
+  `button "Sign in" [ref=e7]`, `iframe [ref=e9]` with the frame's elements
+  under it; `find_in_snapshot` returns only the lines that match, under
+  their ancestors. The `selector` of `click_element`, `fill_input`,
+  `scroll` and `wait_for` takes such a ref, a CSS selector, or
+  `host >>> inner` to reach into an open shadow root or a same-origin
+  iframe (`#checkout >>> #card-number`, chainable). An element keeps its ref
+  in later snapshots while it is in the page; refs end when the page
+  navigates (a stale ref fails saying so). Roles and names are computed in
+  the page, an approximation of the browser's accessibility tree that is
+  the same on both browsers; password values never appear.
 - **Per-tab state.** Console logs, network traffic, breakpoints and custom
   events are kept per tab, in bounded buffers. A tab's console buffer (last
   1000 messages) is cleared when the tab moves to another site (registrable
@@ -338,6 +379,8 @@ claude mcp add browser-control-mcp -- npx -y @raultov/browser-control-mcp
 | `--enable-automation` | off | shows the automation infobar | ignored; `list_instances` shows a warning |
 | `--user-profile` | off | your default profile (no `--user-data-dir`) | only with `--firefox-port` (attach to your running Firefox) |
 | `--allow-cookie-import` | off | exposes `copy_cookies` | capability error |
+| `--tool-groups <GROUPS>` | none | lists the opt-in tool groups, comma separated: `storage`, `files`, `raw`, `perf`, `emulation` or `all` (see [Tool groups](#tool-groups)) | same |
+| `--upload-root <DIR>` | working + temp dir | directory `upload_file` may read files from (repeatable; replaces the defaults) | same |
 | `--enable-webmcp` | off | WebMCP switches and `webmcp_*` tools | capability error |
 | `--proxy-server <URL>` | none | proxy for every instance; exposes `enable_proxy_auth` | `http://` and `socks5://` proxies |
 | `--proxy-username <USER>` | none | answers proxy (407) challenges | same (untested) |
@@ -390,7 +433,13 @@ Chrome and Firefox take the same calls:
 2. `search_scripts` with a needle to find the script URL and line.
 3. `set_breakpoint` with `url` and `line_number` (0-based).
 4. Trigger the code (`click_element`, `evaluate_js` with a `setTimeout`, a
-   reload...). The page pauses.
+   reload...). The page pauses. A `click_element` whose handler hits the
+   breakpoint answers at once, as a success: the click happened, and the
+   reply adds `The page paused in the debugger at <url> line N, column M
+   (0-based)` (the URL when the browser gives it) and
+   `{"paused": true, "location": ...}`. Any other call the pause leaves
+   unfinished (`evaluate_js`, `fill_input`, `navigate`...) fails at once
+   with that location.
 5. `evaluate_on_call_frame` reads locals of the paused frame; `step_over`
    moves one statement; `resume` continues.
 6. `remove_breakpoint` with the id `set_breakpoint` returned.
@@ -503,6 +552,12 @@ incompatible:
 
 - `--allow-cookie-import` copies your real Chrome cookies into an isolated
   profile; the agent must ask you before using `copy_cookies`.
+- `cookies` and `web_storage` hide values (often session tokens) unless
+  `show_values: true`; values never reach the logs.
+- `upload_file` hands the page a file's contents: it only reads files under
+  the upload roots (the server's working directory and the system temp
+  directory, or the `--upload-root` directories), resolved so `..` and
+  symlinks cannot leave them. Paths are never logged.
 - The proxy password is never logged and is given only to proxy (407)
   challenges, never to a site's own authentication.
 - The Firefox debugger port needs `devtools.chrome.enabled`: any local

package/npm-shrinkwrap.json

@@ -19,7 +19,7 @@
       "hasInstallScript": true,
       "license": "MIT",
       "name": "@raultov/browser-control-mcp",
-      "version": "0.3.6-beta.6"
+      "version": "0.4.0-beta.7"
     },
     "node_modules/detect-libc": {
       "engines": {
@@ -48,5 +48,5 @@
     }
   },
   "requires": true,
-  "version": "0.3.6-beta.6"
+  "version": "0.4.0-beta.7"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "artifactDownloadUrls": [
-    "https://github.com/raultov/browser-control-mcp/releases/download/v0.3.6-beta.6"
+    "https://github.com/raultov/browser-control-mcp/releases/download/v0.4.0-beta.7"
   ],
   "author": "raultov <raultov@protonmail.com>",
   "bin": {
@@ -92,7 +92,7 @@
       "zipExt": ".tar.xz"
     }
   },
-  "version": "0.3.6-beta.6",
+  "version": "0.4.0-beta.7",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"