@raultov/browser-control-mcp 0.1.1-beta.1 → 0.2.0-beta.1

package/CHANGELOG.md

@@ -10,6 +10,90 @@ from a copy of its code: entries describe the differences from that release.
 
 ## [Unreleased]
 
+## [0.2.0-beta.1] - 2026-10-13
+
+Public **BETA**. Chrome and Firefox now answer the same replies; several are
+incompatible with 0.1.x (marked **Breaking**; see the README's "Migration
+from 0.1.x to 0.2.0").
+
+### Changed
+
+- **Breaking:** `navigate` and `reload` answer the same shape on Chrome and
+  Firefox once the page fired `load` (at most 30 s): `{url, tab_id, browser,
+  notes?}`, `url` being the final URL after redirects and `browser` the
+  protocol's ids (Chrome used to answer the raw `Page.navigate` reply without
+  waiting, and `{}` on reload). `open_tab` reports the final URL too, and on
+  Firefox it now creates the tab blank and navigates once it is registered,
+  as on Chrome, so the page's first events are captured.
+- **Breaking:** a network error fails `navigate` and `open_tab` on both
+  browsers with `Navigation failed: <browser's code> (<url>)` (Chrome used to
+  report success with `errorText` inside, or a tab on `chrome-error://`); from
+  `open_tab` the error names the tab, which stays open.
+- **Breaking:** `evaluate_js` answers `{value, type, subtype?, description?}`
+  on both browsers (Chrome used to wrap the value in the CDP `RemoteObject`,
+  Firefox to return the bare value). Values without a JSON form (functions,
+  DOM nodes, symbols, `NaN`, bigints, maps...) have `value: null` and a
+  `description`; on Chrome they no longer fail with "Object couldn't be
+  returned by value" or answer `{}` (array-likes such as `NodeList` are
+  described, e.g. `NodeList(6)`, as on Firefox). A thrown exception fails
+  with the same wording on both: what was thrown plus its 1-based line and
+  column.
+- **Breaking:** the debugger tools answer the same shapes on both browsers,
+  with 0-based lines everywhere: `set_breakpoint` returns an MCP id
+  (`bp-N`, also on Chrome instead of the CDP id) with the bound location and
+  `resolved`; `remove_breakpoint` takes that id and answers `{removed}`;
+  `step_over` and `resume` answer `{paused, location}` (Firefox's step
+  location was 1-based; Chrome reported none); `evaluate_on_call_frame`
+  answers the `evaluate_js` shape, and an exception in the frame is an error
+  on Chrome too (`Evaluation threw: ...`; it used to be a success carrying
+  `exceptionDetails`). `step_over` without a pause fails with "the debugger
+  is not paused" on both.
+- **Breaking:** `get_console_logs` answers `{messages, total, truncated,
+  notes?}` instead of a bare array, returns at most `limit` messages (new
+  argument, default 200, the most recent ones), and `clear` removes only the
+  returned messages (it used to empty the whole buffer, even messages a
+  `level_filter` had hidden).
+
+### Added
+
+- Partial `get_performance_metrics` and `profile_page_performance` on
+  Firefox, from the standard Web Performance APIs: `Nodes`, `Frames`,
+  `Resources` and `TransferSize`; FCP, LCP, DCL and Load (optionally after a
+  reload, cache bypassed with `disable_cache`). What Firefox cannot give (JS
+  heap, layout counts, long tasks, total blocking time) is `null` or listed
+  in a note, never a silent empty value.
+- Firefox WebSocket frames in `get_network_logs`, and the console messages
+  WebDriver BiDi does not report (script errors with file and line, cookie
+  and security warnings, CSS warnings, platform messages) in
+  `get_console_logs`, from the RDP watcher of each tab's debugger, in the
+  same shapes as Chrome. Each tab's debugger is attached when the session
+  starts, when `open_tab` creates the tab, or at the first log call on a tab
+  the page opened, matched by its position in BiDi's and RDP's tab lists
+  (checked against their URLs), without bringing it to the front. Needs the
+  Firefox debugger port (default for a launched Firefox). Messages both feeds report are kept once; console
+  `source` labels say what a Firefox message is (`javascript`, `css`,
+  `security`, `network`, `other`).
+- `--window-size <W>x<H>` (default `1920x1080`): launched Chrome and Firefox
+  get the same window size, headless too (they used to pick 921x648 and
+  1280x887). Attached browsers keep their window.
+- A tab's console buffer is cleared when the tab moves to another site
+  (registrable domain, via the `psl` crate's embedded Public Suffix List)
+  and kept across subdomains of one site, reloads and same-page
+  navigations; the next `get_console_logs` says what was cleared.
+
+- Lifecycle crates bumped: `cdp-browser-lite` 0.4.2 and `bidi-browser-lite`
+  0.1.4 (`bidi-lite` 0.1.2). Their mocks now record wire parameters, so the
+  Firefox page, input, network and debugger tools and the Chrome domain
+  setup are covered by hermetic tests instead of only by the E2E smoke.
+
+### Fixed
+
+- Chrome `get_performance_metrics` returned `{}`: every tab now enables the
+  Performance domain when it is registered, the tool enables it on a session
+  that missed it, and an empty metric list is an error instead of `{}`.
+- The "Chrome not found, use Firefox?" hint no longer ends the library's
+  sentence with two periods.
+
 ## [0.1.1-beta.1] - 2026-10-12
 
 Public **BETA**: known bugs and Chrome/Firefox differences are listed in the

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.1.1-beta.1).** This version contains known bugs and differences
+> **Status: BETA (0.2.0-beta.1).** 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
@@ -54,11 +54,11 @@ see the note.
 | `click_element` | ✓ | ✓ | |
 | `fill_input` | ✓ | ✓ | |
 | `evaluate_js` | ✓ | ✓ | |
-| `get_console_logs` | ✓ | ✓ | |
-| `get_network_logs` | ✓ | partial | Firefox: HTTP requests and response bodies, no WebSocket frames |
+| `get_console_logs` | ✓ | ✓ | Firefox: page errors, CSS warnings and platform messages need the debugger port |
+| `get_network_logs` | ✓ | ✓ | Firefox: WebSocket frames need the debugger port |
 | `get_custom_events` | ✓ | partial | Firefox: events of the modules subscribed with `send_bidi_command` |
-| `get_performance_metrics` | ✓ | ✗ | Firefox has no equivalent of CDP's Performance domain |
-| `profile_page_performance` | ✓ | ✗ | Firefox has no equivalent of CDP's Tracing domain |
+| `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` |
 | `set_breakpoint` | ✓ | partial | Firefox: by URL only (no `script_id` / `script_hash`) |
 | `remove_breakpoint` | ✓ | ✓ | |
 | `resume` | ✓ | ✓ | |
@@ -76,7 +76,18 @@ see the note.
 | `webmcp_list_invocations` | ✓ | ✗ | needs `--enable-webmcp` |
 
 The JavaScript debugger tools on Firefox need its debugger (RDP) port: on by
-default for a launched Firefox, `--firefox-rdp-port` for an attached one.
+default for a launched Firefox, `--firefox-rdp-port` for an attached one. The
+same port gives Firefox's WebSocket frames and the console messages BiDi does
+not report (script errors with their file and line, cookie and security
+warnings, CSS warnings, platform messages), in the same shapes as Chrome.
+Each tab's debugger watches them: the session's first tabs are attached when
+the session starts and `open_tab` attaches its tab before loading the URL; a
+tab the page opened is attached by the first `get_console_logs` or
+`get_network_logs` on it. Tabs are matched by their position in BiDi's and
+RDP's tab lists (checked against their URLs), never by activating them; a
+tab that cannot be matched that way (tabs opening or closing at that moment)
+is attached by its first debugger tool, which brings it to the front. Frames
+are captured from the moment a tab is attached.
 
 ## 📦 Installation
 
@@ -262,8 +273,34 @@ claude mcp add browser-control-mcp -- npx -y @raultov/browser-control-mcp
 - **Tabs.** `open_tab`, `list_tabs`, `switch_tab`, `close_tab`. Every tool
   takes `instance_id` and `tab_id`; without them it targets the default
   instance and its active tab.
+- **Same replies on both browsers.** `navigate` and `reload` answer once the
+  page fired `load` (at most 30 s, else with a note): a first line
+  (`Navigated to <final URL>.` / `Page reloaded.`), then
+  `{"url": "<final URL, after redirects>", "tab_id": "tab-N", "browser": {...}}`,
+  where `browser` holds the protocol's ids (CDP `frameId`/`loaderId`, BiDi
+  `navigation`). `open_tab` answers `{tab_id, target_id, url, label}` with the
+  final URL. A network error (unknown host, refused connection...) fails with
+  `Navigation failed: <browser's code> (<url>)`, e.g.
+  `net::ERR_NAME_NOT_RESOLVED` on Chrome and `NS_ERROR_UNKNOWN_HOST` on
+  Firefox; from `open_tab` the error names the tab, which stays open.
+  `evaluate_js` answers `{"value", "type", "subtype"?, "description"?}`:
+  `type` is JavaScript's `typeof`, `subtype` refines objects (`array`,
+  `null`, `node`, `date`, `map`...), `value` is the JSON form and is `null`
+  when there is none (functions, DOM nodes, symbols, `NaN`, bigints,
+  maps...), `description` then says what it was (Chrome describes functions
+  by their source, Firefox only as `function`). A thrown exception or a
+  rejected promise fails with what was thrown and its 1-based line and
+  column, e.g. `ReferenceError: x is not defined (line 1, column 1)`.
 - **Per-tab state.** Console logs, network traffic, breakpoints and custom
-  events are kept per tab, in bounded buffers.
+  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
+  domain from the Public Suffix List: `www.knot.kz` and `docs.knot.kz` are
+  one site, `a.github.io` and `b.github.io` two) and kept across reloads and
+  same-page navigations. `get_console_logs` answers
+  `{"messages": [...], "total", "truncated", "notes"?}`: at most `limit`
+  (default 200) of the most recent matching messages, oldest first; `clear`
+  removes only the returned ones; a note says when a site change cleared
+  messages.
 - **Firefox allows a single automation session.** Each Firefox instance holds
   one WebDriver BiDi session shared by its tabs; `close_instance`,
   `stop_browser` and every server shutdown path end it, so the next run can
@@ -276,6 +313,7 @@ claude mcp add browser-control-mcp -- npx -y @raultov/browser-control-mcp
 | `--browser <chrome\|firefox>` | `chrome` | browser of the default instance | browser of the default instance |
 | `--local` | off | navigation limited to local addresses | same |
 | `--headless` | off | headless Chrome | headless Firefox |
+| `--window-size <W>x<H>` | `1920x1080` | window of launched Chrome (`--window-size`) | window of launched Firefox (`--width`/`--height`) |
 | `--host <HOST>` | `127.0.0.1` | debugging host | debugging host |
 | `--port <PORT>` | `9222` | debugging port of the default instance | ignored (use `--firefox-port`) |
 | `--max-instances <N>` | `8` | instance cap | shared with Chrome |
@@ -334,6 +372,17 @@ Chrome and Firefox take the same calls:
    moves one statement; `resume` continues.
 6. `remove_breakpoint` with the id `set_breakpoint` returned.
 
+Both browsers answer the same replies, with 0-based lines everywhere:
+
+| Tool | Reply |
+| --- | --- |
+| `set_breakpoint` | `{"breakpoint_id": "bp-N", "url", "line_number", "column_number", "resolved"}`: where the browser bound it; `resolved` is false until a script with that URL loads |
+| `remove_breakpoint` | `{"removed": "bp-N"}`; an unknown id fails listing the tab's ids |
+| `step_over`, `resume` | `{"paused", "location": {"url", "line_number", "column_number"} \| null}`: where the thread stopped next (`step_over` waits up to 2 s; `resume` reports a pause only if one follows within 250 ms) |
+| `evaluate_on_call_frame` | the `evaluate_js` shape; an exception fails with `Evaluation threw: <what was thrown>` |
+
+Breakpoint ids are per tab and MCP-level (`bp-1`, `bp-2`...), like tab ids.
+
 Chrome also offers `pause_on_load` (pause on the first statement of the next
 load). Firefox notes: breakpoints by URL only; the column is snapped to the
 nearest breakable position automatically; the debugger needs the RDP port.
@@ -356,47 +405,39 @@ In client configurations replace the command `chrome-debug-mcp` with
 `browser-control-mcp` (or the npm package name). The old tool names answer an
 error that names the new ones.
 
+### Migration from 0.1.x to 0.2.0
+
+0.2.0 makes the replies the same on Chrome and Firefox; these changes are
+incompatible:
+
+| Tool | 0.1.x | 0.2.0 |
+| --- | --- | --- |
+| `navigate`, `reload` | Chrome: raw `Page.navigate` reply (`frameId`, `loaderId`, `errorText`) without waiting, `{}` on reload; Firefox: `{navigation, url}` | `{url, tab_id, browser, notes?}` after `load`; `url` is the final URL; protocol ids under `browser` |
+| `navigate`, `open_tab` to an unreachable host | Chrome: success (`errorText` inside, or a `chrome-error://` tab) | error `Navigation failed: <code> (<url>)`; `open_tab` names the tab, which stays open |
+| `evaluate_js` | Chrome: `{"result": {type, value, ...}}`; Firefox: the bare value | `{value, type, subtype?, description?}` |
+| `set_breakpoint` | Chrome: CDP id (`1:3:0:http://…`) and `locations`; Firefox: `{breakpointId, url, lineNumber, columnNumber}` | `{breakpoint_id: "bp-N", url, line_number, column_number, resolved}` |
+| `remove_breakpoint` | Chrome: CDP id, reply `{}` | `bp-N` id, reply `{removed}` |
+| `step_over`, `resume` | Chrome: text only; Firefox `step_over`: `{paused, location: {line (1-based), column}}` | `{paused, location: {url, line_number, column_number} \| null}`, 0-based |
+| `evaluate_on_call_frame` | Chrome: raw `RemoteObject` (exceptions as success); Firefox: bare value | the `evaluate_js` shape; exceptions are errors (`Evaluation threw: ...`) |
+| `get_console_logs` | a JSON array; `clear` emptied the whole buffer | `{messages, total, truncated, notes?}`, at most `limit` (200) messages; `clear` removes the returned ones; the buffer is cleared on cross-site navigation |
+
 ## Limitations and TODO
 
-- **TODO (priority)** Unified `navigate` response: Chrome returns the CDP ids
-  (`frameId`, `loaderId`) and Firefox `{navigation, url}`; both will return
-  the final URL in the same shape.
-- **TODO (priority)** Unified `evaluate_js` result: Chrome wraps the value in
-  the CDP `RemoteObject` (`{"result": {"type", "value"}}`) and Firefox
-  returns the bare value; both will return the same shape.
-- **TODO (priority)** Navigation errors: on Chrome, `navigate` and `open_tab`
-  to an unreachable host report success (the network error is only inside
-  the reply, or absent); both browsers will fail with the network error.
-- **TODO (priority)** Console buffer per navigation: `get_console_logs` will
-  clear a tab's buffer when it navigates to a different site (kept across
-  subdomains of the same site) and gain a limit, so one call cannot flood
-  the client.
-- **TODO (priority)** Unified debugger replies: `set_breakpoint`,
-  `remove_breakpoint` and `step_over` answer differently on Chrome and
-  Firefox (and Firefox's `step_over` location uses a 1-based line); both
-  will return the same shape with 0-based lines.
-- **TODO (priority)** Known bug: on Chrome `get_performance_metrics` returns
-  `{}` because the Performance domain is never enabled. Workaround:
-  `send_cdp_command` with `Performance.enable` first.
-- **TODO (priority)** Partial performance on Firefox from the standard Web
-  Performance APIs (navigation timings, FCP, LCP), stating what Firefox
-  cannot give (long tasks, CLS, JS heap).
-- **TODO (priority)** Same default window size on both browsers (today
-  Chrome 921x648, Firefox 1280x887): the screen size when known, else
-  1920x1080.
-- **TODO (priority)** Firefox WebSocket frames and the full console natively
-  over the Firefox debugger (RDP watcher `websocket`, `error-message` and
-  `css-message` resources), so both browsers return the same shape without
-  any page injection.
+- **TODO** Default window size from the screen size: launched browsers use
+  `--window-size` (default 1920x1080 on both); reading the screen size needs
+  native APIs per OS, left out of the server.
 - **TODO** `pause_on_load` on Firefox: neither a preload `debugger;`
   statement nor an RDP interrupt pauses a reloading page (spike verdict).
 - **TODO** `rust-mcp-sdk` 2.0: the server stays on 1.1.0 (MCP protocol
   2025-11-25). 2.0 moves to the stateless MCP protocol (2026-07-28), which
   today's MCP clients probably do not speak yet; upgrade once the clients do.
-- `get_performance_metrics` and `profile_page_performance` are Chrome only:
-  Firefox has no Performance or Tracing domain.
-- WebSocket frames in `get_network_logs` are Chrome only: WebDriver BiDi has
-  no WebSocket frame events.
+- `get_performance_metrics` and `profile_page_performance` are partial on
+  Firefox: it has no Performance or Tracing domain, so they read what the
+  Web Performance APIs give and say what is missing (JS heap, layout and
+  style counts, long tasks, total blocking time).
+- Firefox WebSocket frames and page errors need the Firefox debugger port
+  (WebDriver BiDi has no WebSocket frame events); binary frames are reported
+  as Firefox gives them, not base64 as on Chrome.
 - `webmcp_list_tools`, `webmcp_invoke_tool`, `webmcp_get_invocation` and
   `webmcp_list_invocations` are Chrome only (a Chrome testing feature).
 - `send_cdp_command` is Chrome only; `send_bidi_command` and
@@ -410,9 +451,12 @@ error that names the new ones.
 - Firefox: after a lost connection a launched Firefox gets a new session on
   the next tool call; an attached Firefox keeps its orphan session, so
   restart that Firefox.
-- Firefox debugger: it attaches to the tab Firefox has selected right after
-  activating the requested one; switching tabs at that very moment can bind
-  it to the wrong page.
+- Firefox debugger: a tab is matched to its debugger by its position in
+  BiDi's and RDP's tab lists, checked against the tabs' web URLs; tabs
+  showing no web page (`about:blank`, error pages) cannot be checked, so a
+  tab opening or closing elsewhere at that very moment could still bind the
+  debugger to the wrong page. When the lists differ the debugger attaches by
+  activating the tab, as before.
 - `get_network_logs` with response bodies has no total size limit (each
   Firefox body is capped at 2 MB): use `url_filter` on busy pages.
 - The Docker image is amd64 only.

package/npm-shrinkwrap.json

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

package/package.json

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