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

package/.gitignore

@@ -0,0 +1,2 @@
+/node_modules
+

package/CHANGELOG.md

@@ -0,0 +1,215 @@
+# Changelog
+
+All notable changes to `browser-control-mcp` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+`browser-control-mcp` is the successor of `chrome-debug-mcp` 1.5.6 and starts
+from a copy of its code: entries describe the differences from that release.
+
+## [Unreleased]
+
+## [0.1.1-beta.1] - 2026-10-12
+
+Public **BETA**: known bugs and Chrome/Firefox differences are listed in the
+README ("Limitations and TODO"). The GitHub Release, the shell/PowerShell
+installers, the MSI and the npm package start with this version (0.1.0 was
+only published to crates.io).
+
+### Changed
+- README: per-platform installation section (shell and PowerShell
+  installers, npm/npx, Homebrew, MSI, Cargo/binstall, manual download,
+  Docker, source) and a one-prompt install for AI agents.
+- Releases of beta versions are published as the latest GitHub Release and
+  with the npm `latest` tag, so `releases/latest/download/...` installers
+  and `npm install -g @raultov/browser-control-mcp` get them.
+
+### Fixed
+- A Windows-only unit test failure (path separator in the cookie-import
+  error assertion).
+
+## [0.1.0] - 2026-10-12
+
+First public release, **BETA**: known bugs and Chrome/Firefox differences are
+listed in the README ("Limitations and TODO").
+
+### Added
+- When Chrome is not installed and a Firefox is, the launch error says so
+  and tells the agent to ask the user before using `"browser": "firefox"`.
+- E2E smoke over stdio MCP against real, visible Chrome and Firefox
+  (`make e2e`: launched and attach modes, SIGTERM and relaunch), with
+  `tests/chrome.sh` and `tests/firefox.sh` for dedicated test browsers.
+- Project scaffolding: quality gates (`make check`: format, clippy with
+  warnings as errors, tests, docs, duplication, packaging and version
+  consistency), CI on Linux, macOS and Windows, `AGENTS.md`, MIT licence.
+- The server code of chrome-debug-mcp 1.5.6 (35 tools, Chrome over CDP),
+  copied without its history and renamed: crate and binary
+  `browser-control-mcp`, server title "Browser Control MCP".
+
+- `--browser <chrome|firefox>` selects the browser of the default instance
+  and `open_instance` takes a `browser` argument (Firefox lands in later
+  tasks; until then a Firefox instance answers "not implemented yet").
+- Every tool declares what it needs; a tool an instance's browser cannot
+  serve fails with an error naming the tool and the browser, before anything
+  is sent. `list_instances` shows each instance's `browser` and
+  `capabilities`.
+- On exit (end of stdin, Ctrl-C, SIGTERM on Unix) the server stops every
+  browser it started; the exit code reports instances that did not stop.
+
+- **Firefox support** over WebDriver BiDi (`--browser firefox`, or
+  `open_instance` with `browser: "firefox"`): tabs, `navigate`, `reload`,
+  `evaluate_js` (values as plain JSON), `inspect_dom`, `scroll`,
+  `click_element` (real pointer input), `fill_input` (real key input),
+  `capture_screenshot`, `get_console_logs`, `get_network_logs` (with response
+  bodies; no WebSocket frames) and `get_custom_events`; instance tools
+  (`open_instance`, `close_instance`, `restart_browser`, `stop_browser`,
+  `list_instances` with the Firefox version). Events of iframes are kept with
+  their tab. Firefox instances are launched with an ephemeral profile, or
+  attached with `--firefox-port`.
+- **JavaScript debugging on Firefox** over the Firefox Remote Debugging
+  Protocol: `set_breakpoint` (by `url`), `remove_breakpoint`, `resume`,
+  `step_over` (reports the new location), `evaluate_on_call_frame` and
+  `search_scripts`. The debugger port is on by default for launched Firefox
+  instances; `--no-firefox-debugger` turns it off. `pause_on_load` is Chrome
+  only for now.
+- Firefox flags: `--firefox-path`, `--firefox-port`, `--firefox-rdp-port`,
+  `--no-firefox-debugger`. `--enable-automation` is reported as ignored on
+  Firefox instances by `list_instances`.
+
+- `send_bidi_command` (raw WebDriver BiDi; refuses `session.new`,
+  `session.end`, `browser.close` and removing the server's own subscription;
+  its `session.subscribe` events feed `get_custom_events`) and
+  `send_rdp_request` (raw Firefox RDP, with `thread`/`console`/`root`
+  shortcuts). Firefox only.
+- `enable_proxy_auth` on Firefox (`network.authRequired` →
+  `network.continueWithAuth`, credentials only for 407). **Untested against a
+  real authenticating proxy.**
+
+- Distribution: cargo-dist release workflow (shell, PowerShell, npm
+  `@raultov/browser-control-mcp`, Homebrew, MSI with its own GUIDs) behind a
+  preflight that refuses a tag not matching `Cargo.toml`/`package.json` or
+  without a CHANGELOG section; release notes are that section. Docker image
+  with Google Chrome and Firefox (amd64). glama.json exposes `--browser`.
+
+### Changed
+- `cdp-browser-lite`'s test mocks are no longer linked into the binary.
+- Dependencies updated to their latest releases; unused test dependencies
+  (`hyper`, `hyper-util`, `http-body-util`, `futures-util`,
+  `tokio-tungstenite`) removed.
+- `rust-mcp-sdk` stays on 1.x (MCP 2025-11-25) with only its `server`,
+  `macros` and `stdio` features: the binary no longer links the SDK's HTTP,
+  SSE and OAuth client stack.
+
+- `navigate`, `reload`, `evaluate_js`, `evaluate_on_call_frame`,
+  `set_breakpoint`, `remove_breakpoint` and `send_cdp_command` return the
+  protocol reply as pretty JSON after their usual prefix, instead of the Rust
+  `Debug` of the whole message (`WsResponse { .. }`).
+
+- **Renamed tools:** `restart_chrome` → `restart_browser`, `stop_chrome` →
+  `stop_browser`. Calling an old name returns an error naming the new one.
+- Generated instance ids carry the browser name (`chrome-2`, `firefox-3`).
+- Server title "Browser Control MCP"; new description and instructions that
+  cover both browsers.
+
+- Tool descriptions say which tools are Chrome only and no longer mention
+  tools that do not exist (`pause_on_exceptions`, `step_out`);
+  `remove_breakpoint` no longer claims the page must be paused.
+
+### Fixed
+- `stop_browser` / `restart_browser` on Chrome could deadlock with a tool
+  making the instance's first connection (two locks taken in opposite order).
+- Chrome `open_instance` checks the instance limit and the label before
+  launching: a refused instance no longer leaves an untracked Chrome running.
+- No instance can take the id `default` (it hijacked the default instance).
+- `open_tab` checks the tab limit and the label before creating the page,
+  keeps labels unique when target discovery registered the page first, and
+  closes the page if it still cannot register it (Chrome and Firefox).
+- `close_tab` forgets a tab only once the browser closed it (Chrome and
+  Firefox).
+- Firefox: a lost WebSocket no longer leaves a dead event pump (empty console
+  and network logs): the next tool starts a new session.
+- Firefox: tab ids are not reused after `restart_browser`; the iframe map
+  forgets a destroyed context's whole subtree; debuggers of tabs closed by the
+  page are dropped.
+- Firefox `enable_proxy_auth` subscribes to `network.authRequired` before the
+  intercept exists, so no challenge is missed (and lags are logged).
+- Firefox `set_breakpoint` with `line_number` 4294967295 is an argument error
+  instead of an overflow.
+- Shutdown: tool calls are refused once the server is stopping, and a
+  debugger tool in flight no longer delays stopping Firefox past its budget.
+- The server exits on SIGTERM/Ctrl-C: it used to stop its browsers and then
+  hang, waiting for a stdin read that only returns on input.
+- Chrome `profile_page_performance` no longer times out at random on tabs
+  opened with `open_tab`: when target discovery and `open_tab` both attached
+  the page, the second registration replaced the tab's listeners with ones on
+  a session nobody sent commands to.
+- Chrome `open_tab` with a URL records the page's first requests: the tab is
+  created blank and navigated once its domains are enabled.
+- `profile_page_performance` reports a failed `Tracing.end` instead of a
+  timeout.
+- `reload` right after `navigate` on Chrome no longer fails with "Not attached
+  to an active page": the transient error is retried once after 500 ms.
+- `inspect_dom` no longer crashes the server when the context window around a
+  match falls inside a multi-byte character.
+
+- The server can no longer panic on a poisoned lock or an unexpected value:
+  every `unwrap`/`expect` outside tests was removed; the instance registry
+  uses a single lock (two locks taken in different orders could deadlock).
+- Custom-domain listeners started by `send_cdp_command` on a tab are stopped
+  when the tab closes (a reference cycle kept them running forever), and no
+  longer leak one static string per domain name.
+- Per-tab state fed by the browser is bounded: at most 2,000 parsed scripts,
+  100 WebSocket connections (with their frames) and 1,000 WebMCP
+  invocations; the oldest are forgotten first.
+
+- `search_scripts` / script cache: Chrome's numeric `startLine`/`startColumn`
+  were read as strings and always stored as 0.
+- `evaluate_on_call_frame` no longer uses a stale frame after the page
+  resumed (`Debugger.resumed` clears it).
+- `pause_on_load` pauses once: the injected `debugger;` script is removed on
+  the next `resume` instead of pausing every later navigation.
+- `get_custom_events` with `limit: 0` returns every event (it returned none).
+- `get_network_logs`: a redirect keeps one entry per request id, with the
+  final URL and a `redirects` list.
+- `profile_page_performance` restores the cache and its completion channel
+  when tracing fails or times out, and keeps the top 5 long tasks its
+  description promises (it kept 10).
+- `fill_input` replaces the field's content, as its description says.
+- Closing the active tab activates the most recently used tab (it picked an
+  arbitrary one); `list_tabs` reports each tab's current URL; a tab opened
+  with `open_tab` can no longer be registered twice.
+- The session-level WebMCP listener starts before `WebMCP.enable`, so the
+  initial tool list is not missed.
+
+- A Firefox launched by the server no longer starts on `about:home`, where
+  BiDi refuses page scripts: its first tab is moved to `about:blank`.
+
+### Security
+- `--local` treats `192.168.x.x` only as an IP address: a domain name such
+  as `192.168.attacker.com` is no longer accepted as local.
+- `--local` also covers RDP `navigateTo` in `send_rdp_request`.
+- `send_bidi_command` refuses `session.unsubscribe` of the events the server
+  listens to (by event or module name), not only of its subscription id.
+- The start-up log no longer prints the proxy password, username or a
+  `user:pass@` embedded in `--proxy-server` (chrome-debug-mcp printed every
+  argument). Logs now go through `tracing` to stderr (`RUST_LOG`, default
+  `info`) and carry ids, method names and error kinds, never payloads;
+  `cdp-lite`'s payload logging is capped at `info` whatever `RUST_LOG` says.
+- `enable_proxy_auth` answers only proxy (407) challenges; a site's 401 gets
+  the browser's default handling instead of the proxy credentials.
+- `enable_proxy_auth` checks the credentials and `--local` (pre-warm URL)
+  before enabling Fetch, so a refused call no longer leaves every request
+  paused; enabling it again replaces the previous handler instead of stacking
+  a second one; the pre-warm URL is logged as scheme and host only.
+- `scroll`, `click_element` and `fill_input` embed the CSS selector as a JSON
+  string literal; a selector with a backslash could break out of the
+  JavaScript string before.
+- `--local` also blocks `Target.createTarget` sent through `send_cdp_command`
+  (only `Page.navigate` was checked).
+- Cookie import refuses a `source_profile` that is not a single profile
+  directory name (`../..` could read outside the browser's user-data root).
+- `get_network_logs` returns `Authorization`, `Proxy-Authorization`, `Cookie`
+  and `Set-Cookie` header values as `<redacted>` unless the new
+  `include_sensitive_headers: true` is passed.
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 raultov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,467 @@
-# Temporary Holding Version
+# browser-control-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Browser Control MCP** lets an AI agent control **and debug** real browsers
+at runtime: breakpoints, pause on load, call frames, evaluation in a paused
+frame, stepping and script search on **Chrome (CDP)** and **Firefox
+(WebDriver BiDi + Firefox RDP)**, plus navigation, DOM, input, screenshots,
+console and network capture.
+
+It is the successor of
+[chrome-debug-mcp](https://github.com/raultov/chrome-debug-mcp) (it starts
+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
+> 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
+> in the [issues](https://github.com/raultov/browser-control-mcp/issues).
+
+## Supported browsers
+
+| Browser | Protocol | Validated with |
+| --- | --- | --- |
+| Chrome / Chromium | Chrome DevTools Protocol | Google Chrome 155.0.8059.39 (Linux) |
+| Firefox | WebDriver BiDi, plus the Firefox Remote Debugging Protocol (RDP) for the JavaScript debugger | Firefox 157.0.1 (Linux, snap) |
+
+The default browser is Chrome. Every instance runs one browser for its whole
+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.
+
+## Feature matrix
+
+✓ supported, ✗ not available (the tool answers a capability error naming the
+tool, the browser and the reason; nothing is sent to the browser), partial:
+see the note.
+
+| Tool | Chrome | Firefox | Notes |
+| --- | --- | --- | --- |
+| `open_instance` | ✓ | partial | `features`, `copy_cookies` and `source_profile` are Chrome only |
+| `close_instance` | ✓ | ✓ | |
+| `list_instances` | ✓ | ✓ | each instance reports its `browser` and `capabilities` |
+| `restart_browser` | ✓ | ✓ | was `restart_chrome` |
+| `stop_browser` | ✓ | ✓ | was `stop_chrome`; on an attached Firefox it ends the session, the browser keeps running |
+| `open_tab` | ✓ | ✓ | |
+| `close_tab` | ✓ | ✓ | |
+| `list_tabs` | ✓ | ✓ | |
+| `switch_tab` | ✓ | ✓ | |
+| `navigate` | ✓ | ✓ | |
+| `reload` | ✓ | ✓ | |
+| `scroll` | ✓ | ✓ | |
+| `inspect_dom` | ✓ | ✓ | |
+| `capture_screenshot` | ✓ | ✓ | |
+| `click_element` | ✓ | ✓ | |
+| `fill_input` | ✓ | ✓ | |
+| `evaluate_js` | ✓ | ✓ | |
+| `get_console_logs` | ✓ | ✓ | |
+| `get_network_logs` | ✓ | partial | Firefox: HTTP requests and response bodies, no WebSocket frames |
+| `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 |
+| `set_breakpoint` | ✓ | partial | Firefox: by URL only (no `script_id` / `script_hash`) |
+| `remove_breakpoint` | ✓ | ✓ | |
+| `resume` | ✓ | ✓ | |
+| `step_over` | ✓ | ✓ | |
+| `evaluate_on_call_frame` | ✓ | ✓ | |
+| `search_scripts` | ✓ | ✓ | |
+| `pause_on_load` | ✓ | ✗ | TODO on Firefox, see [Limitations and TODO](#limitations-and-todo) |
+| `enable_proxy_auth` | ✓ | partial | needs `--proxy-server`; untested on Firefox against a real proxy |
+| `send_cdp_command` | ✓ | ✗ | raw Chrome DevTools Protocol |
+| `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) |
+| `webmcp_list_tools` | ✓ | ✗ | needs `--enable-webmcp`; WebMCP is a Chrome testing feature |
+| `webmcp_invoke_tool` | ✓ | ✗ | needs `--enable-webmcp` |
+| `webmcp_get_invocation` | ✓ | ✗ | needs `--enable-webmcp` |
+| `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.
+
+## 📦 Installation
+
+Every method installs the **same pre-compiled binaries** published on each
+[GitHub Release](https://github.com/raultov/browser-control-mcp/releases); a Rust toolchain is only needed for the Cargo and
+source routes. The npm package is a small wrapper whose `postinstall` fetches
+the pre-compiled binary for your platform from GitHub Releases: no compiling,
+no Rust toolchain. Install Chrome and/or Firefox yourself: the server launches
+them, it does not ship them (except the Docker image).
+
+> ⚠️ **Always use the scoped npm name `@raultov/browser-control-mcp`.** The
+> unscoped `browser-control-mcp` on npm is a different, unrelated project.
+
+Prefer zero effort? The one-prompt route below lets your AI agent do all of
+it. Otherwise, methods are grouped by platform and ordered by popularity.
+
+### 🤖 One-Prompt Install (any platform)
+
+Paste this prompt into any AI coding agent's chat (Claude Code, opencode,
+Cursor, Codex CLI, Copilot, ...) and let it install the server and register
+it with every MCP-capable client it detects on your machine:
+
+```text
+Install and set up the browser-control-mcp MCP server on this machine. Do not launch Chrome or Firefox yourself: the server launches and manages them.
+
+1. Install the server binary with the first method that works on this OS:
+   - Homebrew available (macOS/Linux): brew install raultov/tap/browser-control-mcp
+   - Node.js >= 14 available (any OS): npm install -g @raultov/browser-control-mcp
+   - macOS/Linux fallback: curl --proto '=https' --tlsv1.2 -LsSf https://github.com/raultov/browser-control-mcp/releases/latest/download/browser-control-mcp-installer.sh | sh
+   - Windows fallback: download and run the .msi from https://github.com/raultov/browser-control-mcp/releases/latest
+   Verify with: browser-control-mcp --version (add the install dir to PATH if it is not found).
+
+2. Register the MCP server with every AI client you detect on this machine:
+   - Claude Code: claude mcp add --scope user browser-control-mcp browser-control-mcp
+   - opencode: merge into ~/.config/opencode/opencode.json —
+     "mcp": { "browser-control-mcp": { "type": "local", "command": ["browser-control-mcp"] } }
+   - Codex CLI: append to ~/.codex/config.toml —
+     [mcp_servers.browser-control-mcp]
+     command = "browser-control-mcp"
+   - Any other MCP-capable client (Cursor, Windsurf, VS Code, ...): add it with its own MCP settings, command "browser-control-mcp" with no arguments.
+
+3. Report what you installed and which clients you configured, and remind me to restart each client so the MCP server loads. Do not enable --user-profile or --allow-cookie-import unless I ask for them.
+```
+
+### macOS
+
+**1. Homebrew**, the natural option on macOS:
+```bash
+brew install raultov/tap/browser-control-mcp
+```
+The formula fetches the pre-compiled binary (Apple Silicon and Intel) from
+GitHub Releases, and `brew upgrade` keeps you current.
+
+**2. npm / npx**, the MCP-client convention (requires Node.js >= 14):
+```bash
+npm install -g @raultov/browser-control-mcp   # installs the `browser-control-mcp` command
+npx -y @raultov/browser-control-mcp           # ...or just run it once, nothing to install
+```
+
+**3. Shell installer**, a one-liner that installs to `~/.cargo/bin`:
+```bash
+curl --proto '=https' --tlsv1.2 -LsSf https://github.com/raultov/browser-control-mcp/releases/latest/download/browser-control-mcp-installer.sh | sh
+```
+
+**4. Cargo**, if you already have Rust:
+```bash
+cargo install browser-control-mcp     # compiles from crates.io
+cargo binstall browser-control-mcp    # with cargo-binstall: fetches the pre-compiled binary, no compile
+```
+
+**5. Manual download**: the `aarch64-apple-darwin` or `x86_64-apple-darwin`
+`.tar.xz` archive from the [Releases](https://github.com/raultov/browser-control-mcp/releases) page.
+
+### Linux
+
+**1. npm / npx** (requires Node.js >= 14):
+```bash
+npm install -g @raultov/browser-control-mcp   # installs the `browser-control-mcp` command
+npx -y @raultov/browser-control-mcp           # ...or just run it once, nothing to install
+```
+
+**2. Shell installer**, a one-liner that installs to `~/.cargo/bin`:
+```bash
+curl --proto '=https' --tlsv1.2 -LsSf https://github.com/raultov/browser-control-mcp/releases/latest/download/browser-control-mcp-installer.sh | sh
+```
+The Linux binaries require glibc >= 2.35 (Ubuntu 22.04+, Debian 12+, Fedora 36+).
+
+**3. Homebrew (Linuxbrew)**, if you already use
+[Homebrew on Linux](https://docs.brew.sh/Homebrew-on-Linux):
+```bash
+brew install raultov/tap/browser-control-mcp
+```
+
+**4. Cargo**, if you already have Rust:
+```bash
+cargo install browser-control-mcp     # compiles from crates.io
+cargo binstall browser-control-mcp    # with cargo-binstall: fetches the pre-compiled binary, no compile
+```
+
+**5. Manual download**: the `x86_64-unknown-linux-gnu` or
+`aarch64-unknown-linux-gnu` `.tar.xz` archive from the [Releases](https://github.com/raultov/browser-control-mcp/releases) page.
+
+### Windows
+
+**1. npm / npx** (requires Node.js >= 14):
+```powershell
+npm install -g @raultov/browser-control-mcp   # installs the `browser-control-mcp` command
+npx -y @raultov/browser-control-mcp           # ...or just run it once, nothing to install
+```
+
+**2. MSI installer**, the native Windows experience: download
+`browser-control-mcp-x86_64-pc-windows-msvc.msi` from the [Releases](https://github.com/raultov/browser-control-mcp/releases)
+page and double-click it.
+
+**3. PowerShell installer**, a one-liner:
+```powershell
+powershell -ExecutionPolicy Bypass -c "irm https://github.com/raultov/browser-control-mcp/releases/latest/download/browser-control-mcp-installer.ps1 | iex"
+```
+
+**4. Cargo**, if you already have Rust:
+```powershell
+cargo install browser-control-mcp     # compiles from crates.io
+cargo binstall browser-control-mcp    # with cargo-binstall: fetches the pre-compiled binary, no compile
+```
+
+**5. Manual download**: the `x86_64-pc-windows-msvc` `.zip` archive from the
+[Releases](https://github.com/raultov/browser-control-mcp/releases) page.
+
+### Docker (amd64)
+
+```bash
+docker build -t browser-control-mcp .
+docker run -i --rm browser-control-mcp --headless   # Chrome and Firefox inside
+```
+
+### From source
+
+```bash
+git clone https://github.com/raultov/browser-control-mcp && cd browser-control-mcp
+make install   # release build copied to ~/.cargo/bin (or cargo install --path . --locked)
+```
+
+### Browser discovery
+
+`CHROME_PATH`, then `google-chrome`, `chromium` and the usual install paths;
+`--firefox-path`, then `FIREFOX_PATH`, then `firefox` and the usual install
+paths.
+
+## MCP client configuration
+
+Universal JSON:
+
+```json
+{
+  "mcpServers": {
+    "browser-control-mcp": { "command": "browser-control-mcp", "args": [] },
+    "browser-control-firefox": {
+      "command": "browser-control-mcp",
+      "args": ["--browser", "firefox"]
+    },
+    "browser-control-docker": {
+      "command": "docker",
+      "args": ["run", "-i", "--rm", "browser-control-mcp", "--headless"]
+    }
+  }
+}
+```
+
+Claude Code:
+
+```bash
+claude mcp add browser-control-mcp browser-control-mcp
+claude mcp add browser-control-firefox -- browser-control-mcp --browser firefox
+claude mcp add browser-control-mcp -- npx -y @raultov/browser-control-mcp
+```
+
+## Usage concepts
+
+- **Instances.** A `default` instance always exists and uses the `--browser`
+  flag. `open_instance` with a `label` starts another one (its id is the
+  label), with `browser` to pick Chrome or Firefox. Browsers are launched
+  lazily, on the first tool that needs them, with an ephemeral profile.
+- **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.
+- **Per-tab state.** Console logs, network traffic, breakpoints and custom
+  events are kept per tab, in bounded buffers.
+- **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
+  attach again.
+
+## CLI flags
+
+| Flag | Default | Chrome | Firefox |
+| --- | --- | --- | --- |
+| `--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 |
+| `--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 |
+| `--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 |
+| `--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) |
+| `--proxy-password <PASS>` | none | never logged | same |
+| `--firefox-path <PATH>` | discovered | — | Firefox binary to launch |
+| `--firefox-port <PORT>` | none (launch) | — | attach to a running Firefox's BiDi port |
+| `--firefox-rdp-port <PORT>` | none | — | debugger port of the attached Firefox (needs `--firefox-port`) |
+| `--no-firefox-debugger` | off | — | launch Firefox without its debugger port (no debugger tools) |
+
+`--proxy` and `--webmcp` are aliases. To attach to your own Firefox, start it
+with `--remote-debugging-port <port>` (and `--start-debugger-server ws:<rdp>`
+plus `devtools.debugger.remote-enabled` and `devtools.chrome.enabled` for the
+debugger), then pass `--browser firefox --firefox-port <port>
+--firefox-rdp-port <rdp>`.
+
+## Architecture
+
+```
+ MCP client (agent)
+     │  JSON-RPC over stdio (tools/list, tools/call)
+     ▼
+ browser-control-mcp ── tool table: flag gate → capability check → per-browser handler
+     │                                   │
+     │ Chrome instance                   │ Firefox instance
+     ▼                                   ▼
+ cdp-browser-lite / cdp-lite         bidi-browser-lite / bidi-lite
+ (launch, ports, profiles,           (launch, prefs, one BiDi session,
+  CDP over WebSocket)                 RDP client for the debugger)
+     │  CDP commands/events              │  BiDi commands/events   │  RDP packets
+     ▼                                   ▼                         ▼
+   Chrome                              Firefox ◄───────────────────┘
+```
+
+A tool call resolves the instance (`instance_id`, default `default`) and the
+tab (`tab_id`, default active), checks the instance can serve it, then runs
+the implementation for that instance's browser. Events are pumped into
+per-tab state: on Chrome, one listener per CDP domain and tab; on Firefox,
+one subscription per session, routed by browsing context id.
+
+## Debugging JavaScript
+
+Chrome and Firefox take the same calls:
+
+1. `navigate` to the page (or `open_tab` + `switch_tab`).
+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.
+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.
+
+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.
+
+## Migration from chrome-debug-mcp
+
+| chrome-debug-mcp 1.5.6 | browser-control-mcp |
+| --- | --- |
+| binary / crate `chrome-debug-mcp` | `browser-control-mcp` |
+| npm `@raultov/chrome-debug-mcp` | `@raultov/browser-control-mcp` |
+| tool `restart_chrome` | `restart_browser` |
+| tool `stop_chrome` | `stop_browser` |
+| replies printed as Rust `Debug` (`WsResponse { .. }`) | prefix + pretty JSON of the reply |
+| `get_network_logs` returned credential headers | `<redacted>` unless `include_sensitive_headers: true` |
+| `enable_proxy_auth` answered every auth challenge | answers proxy (407) challenges only |
+
+All command-line flags are kept; `--browser`, `--firefox-path`,
+`--firefox-port`, `--firefox-rdp-port` and `--no-firefox-debugger` are new.
+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.
+
+## 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** `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.
+- `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
+  `send_rdp_request` are Firefox only.
+- Cookie import (`--allow-cookie-import`) and launch presets (`features`) are
+  Chrome only.
+- Firefox breakpoints are set by URL only.
+- `--local` checks the URLs the server navigates to and the known navigation
+  methods of the raw tools; JavaScript running in the page can still navigate
+  anywhere.
+- 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.
+- `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.
+
+## Untested
+
+- Proxy authentication on Firefox against a real proxy.
+- macOS and Windows with real browsers (CI builds and unit-tests them; the
+  E2E smoke ran on Linux only).
+- Firefox ESR.
+- The Docker image on arm64.
+- The Windows clippy cross-check (`make clippy-windows`) on a machine with
+  mingw.
+
+## Security notes
+
+- `--allow-cookie-import` copies your real Chrome cookies into an isolated
+  profile; the agent must ask you before using `copy_cookies`.
+- 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
+  process that reaches that port gets chrome (privileged) access to the
+  browser. Use `--no-firefox-debugger` when you do not need the debugger.
+- Credential headers (`Authorization`, `Cookie`, `Set-Cookie`, ...) are
+  redacted in `get_network_logs` unless `include_sensitive_headers: true`.
+- Logs carry tool names, ids, protocol method names and sizes, never
+  payloads, cookies or URLs with queries.
+
+## Development
+
+```sh
+make check        # fmt, clippy -D warnings, tests, docs, duplication, packaging, version
+make e2e          # E2E smoke against real, visible Chrome and Firefox (Linux, macOS)
+make check-all    # both
+```
+
+`make check` is hermetic: it never starts a browser or touches the network.
+`make e2e` runs `tests/run_all_e2e.sh`: the launched-mode smoke for both
+browsers, then the attach mode against browsers started by `tests/chrome.sh`
+and `tests/firefox.sh`. See [AGENTS.md](AGENTS.md) for the conventions.
+
+## Releasing
+
+For the maintainer: bump the version in `Cargo.toml` and `package.json`,
+close the `[Unreleased]` section of `CHANGELOG.md`, run `make check-all`,
+tag `vX.Y.Z` and push the tag (the release workflow builds the installers and
+publishes npm and Homebrew; it needs the `NPM_TOKEN` and
+`HOMEBREW_TAP_TOKEN` secrets), then `cargo publish` by hand.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

package/binary-install.js

@@ -0,0 +1,348 @@
+const {
+  createWriteStream,
+  existsSync,
+  mkdirSync,
+  mkdtemp,
+  rmSync,
+} = require("fs");
+const { join, sep } = require("path");
+const { spawnSync } = require("child_process");
+const { tmpdir } = require("os");
+
+const https = require("node:https");
+const http = require("node:http");
+
+const tmpDir = tmpdir();
+
+const error = (msg) => {
+  console.error(msg);
+  process.exit(1);
+};
+
+function getProxyForUrl(urlString) {
+  const url = new URL(urlString);
+  const isHttps = url.protocol === "https:";
+
+  const noProxy = process.env.NO_PROXY || process.env.no_proxy || "";
+  if (noProxy === "*") return null;
+  if (noProxy) {
+    const hostname = url.hostname.toLowerCase();
+    const noProxyList = noProxy.split(",").map((s) => s.trim().toLowerCase());
+    for (const entry of noProxyList) {
+      if (hostname === entry || hostname.endsWith("." + entry)) {
+        return null;
+      }
+    }
+  }
+
+  const proxyEnv = isHttps
+    ? process.env.HTTPS_PROXY || process.env.https_proxy
+    : process.env.HTTP_PROXY || process.env.http_proxy;
+
+  if (!proxyEnv) return null;
+
+  const proxyUrl = new URL(proxyEnv);
+
+  let auth = null;
+  if (proxyUrl.username || proxyUrl.password) {
+    auth = `${proxyUrl.username}:${proxyUrl.password}`;
+  }
+
+  return {
+    hostname: proxyUrl.hostname,
+    port: proxyUrl.port || (proxyUrl.protocol === "https:" ? 443 : 80),
+    auth: auth,
+  };
+}
+
+function connectThroughProxy(proxy, target) {
+  return new Promise((resolve, reject) => {
+    const headers = {};
+    if (proxy.auth) {
+      headers["Proxy-Authorization"] =
+        "Basic " + Buffer.from(proxy.auth).toString("base64");
+    }
+
+    const connectReq = http.request({
+      hostname: proxy.hostname,
+      port: proxy.port,
+      method: "CONNECT",
+      path: `${target.hostname}:${target.port || 443}`,
+      headers,
+    });
+    connectReq.on("connect", (res, socket) => {
+      if (res.statusCode === 200) {
+        resolve(socket);
+      } else {
+        reject(new Error(`Proxy CONNECT failed with status ${res.statusCode}`));
+      }
+    });
+    connectReq.on("error", reject);
+    connectReq.end();
+  });
+}
+
+function download(urlString, maxRedirects) {
+  if (maxRedirects === undefined) maxRedirects = 5;
+  return new Promise((resolve, reject) => {
+    if (maxRedirects < 0) {
+      return reject(new Error("Too many redirects"));
+    }
+
+    const parsed = new URL(urlString);
+    const isHttps = parsed.protocol === "https:";
+    const mod = isHttps ? https : http;
+    const proxy = getProxyForUrl(urlString);
+
+    const doRequest = (extraOptions) => {
+      const options = Object.assign(
+        {
+          hostname: parsed.hostname,
+          port: parsed.port || (isHttps ? 443 : 80),
+          path: parsed.pathname + parsed.search,
+          method: "GET",
+          headers: { "User-Agent": "cargo-dist-npm-installer" },
+        },
+        extraOptions || {},
+      );
+
+      if (proxy && !isHttps) {
+        // HTTP through HTTP proxy: request the full URL via the proxy
+        options.hostname = proxy.hostname;
+        options.port = proxy.port;
+        options.path = urlString;
+        if (proxy.auth) {
+          options.headers["Proxy-Authorization"] =
+            "Basic " + Buffer.from(proxy.auth).toString("base64");
+        }
+      }
+
+      const req = mod.request(options, (res) => {
+        if (
+          res.statusCode >= 300 &&
+          res.statusCode < 400 &&
+          res.headers.location
+        ) {
+          res.resume();
+          const nextUrl = new URL(res.headers.location, urlString).toString();
+          return download(nextUrl, maxRedirects - 1).then(resolve, reject);
+        }
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          res.resume();
+          return reject(new Error(`HTTP ${res.statusCode} from ${urlString}`));
+        }
+        resolve(res);
+      });
+      req.on("error", reject);
+      req.end();
+    };
+
+    if (proxy && isHttps) {
+      connectThroughProxy(proxy, parsed).then(
+        (socket) => doRequest({ socket, agent: false }),
+        reject,
+      );
+    } else {
+      doRequest();
+    }
+  });
+}
+
+class Package {
+  constructor(platform, name, url, filename, zipExt, binaries) {
+    let errors = [];
+    if (typeof url !== "string") {
+      errors.push("url must be a string");
+    } else {
+      try {
+        new URL(url);
+      } catch (e) {
+        errors.push(e);
+      }
+    }
+    if (name && typeof name !== "string") {
+      errors.push("package name must be a string");
+    }
+    if (!name) {
+      errors.push("You must specify the name of your package");
+    }
+    if (binaries && typeof binaries !== "object") {
+      errors.push("binaries must be a string => string map");
+    }
+    if (!binaries) {
+      errors.push("You must specify the binaries in the package");
+    }
+
+    if (errors.length > 0) {
+      let errorMsg =
+        "One or more of the parameters you passed to the Binary constructor are invalid:\n";
+      errors.forEach((error) => {
+        errorMsg += error;
+      });
+      errorMsg +=
+        '\n\nCorrect usage: new Package("my-binary", "https://example.com/binary/download.tar.gz", {"my-binary": "my-binary"})';
+      error(errorMsg);
+    }
+
+    this.platform = platform;
+    this.url = url;
+    this.name = name;
+    this.filename = filename;
+    this.zipExt = zipExt;
+    this.installDirectory = join(__dirname, "node_modules", ".bin_real");
+    this.binaries = binaries;
+
+    if (!existsSync(this.installDirectory)) {
+      mkdirSync(this.installDirectory, { recursive: true });
+    }
+  }
+
+  exists() {
+    for (const binaryName in this.binaries) {
+      const binRelPath = this.binaries[binaryName];
+      const binPath = join(this.installDirectory, binRelPath);
+      if (!existsSync(binPath)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  install(suppressLogs = false) {
+    if (this.exists()) {
+      if (!suppressLogs) {
+        console.error(
+          `${this.name} is already installed, skipping installation.`,
+        );
+      }
+      return Promise.resolve();
+    }
+
+    try {
+      rmSync(this.installDirectory, { recursive: true, force: true });
+    } catch {
+      // ignore - directory may not exist
+    }
+
+    mkdirSync(this.installDirectory, { recursive: true });
+
+    if (!suppressLogs) {
+      console.error(`Downloading release from ${this.url}`);
+    }
+
+    return download(this.url)
+      .then((res) => {
+        return new Promise((resolve, reject) => {
+          mkdtemp(`${tmpDir}${sep}`, (err, directory) => {
+            if (err) return reject(err);
+            let tempFile = join(directory, this.filename);
+            const sink = res.pipe(createWriteStream(tempFile));
+            sink.on("error", (err) => reject(err));
+            sink.on("close", () => {
+              if (/\.tar\.*/.test(this.zipExt)) {
+                const result = spawnSync("tar", [
+                  "xf",
+                  tempFile,
+                  // The tarballs are stored with a leading directory
+                  // component; we strip one component in the
+                  // shell installers too.
+                  "--strip-components",
+                  "1",
+                  "-C",
+                  this.installDirectory,
+                ]);
+                if (result.status == 0) {
+                  resolve();
+                } else if (result.error) {
+                  reject(result.error);
+                } else {
+                  reject(
+                    new Error(
+                      `An error occurred untarring the artifact: stdout: ${result.stdout}; stderr: ${result.stderr}`,
+                    ),
+                  );
+                }
+              } else if (this.zipExt == ".zip") {
+                let result;
+                if (this.platform.artifactName.includes("windows")) {
+                  // Windows does not have "unzip" by default on many installations, instead
+                  // we use Expand-Archive from powershell
+                  result = spawnSync("powershell.exe", [
+                    "-NoProfile",
+                    "-NonInteractive",
+                    "-Command",
+                    `& {
+                        param([string]$LiteralPath, [string]$DestinationPath)
+                        Expand-Archive -LiteralPath $LiteralPath -DestinationPath $DestinationPath -Force
+                    }`,
+                    tempFile,
+                    this.installDirectory,
+                  ]);
+                } else {
+                  result = spawnSync("unzip", [
+                    "-q",
+                    tempFile,
+                    "-d",
+                    this.installDirectory,
+                  ]);
+                }
+
+                if (result.status == 0) {
+                  resolve();
+                } else if (result.error) {
+                  reject(result.error);
+                } else {
+                  reject(
+                    new Error(
+                      `An error occurred unzipping the artifact: stdout: ${result.stdout}; stderr: ${result.stderr}`,
+                    ),
+                  );
+                }
+              } else {
+                reject(
+                  new Error(`Unrecognized file extension: ${this.zipExt}`),
+                );
+              }
+            });
+          });
+        });
+      })
+      .then(() => {
+        if (!suppressLogs) {
+          console.error(`${this.name} has been installed!`);
+        }
+      })
+      .catch((e) => {
+        error(`Error fetching release: ${e.message}`);
+      });
+  }
+
+  run(binaryName) {
+    const promise = !this.exists() ? this.install(true) : Promise.resolve();
+
+    promise
+      .then(() => {
+        const [, , ...args] = process.argv;
+
+        const options = { cwd: process.cwd(), stdio: "inherit" };
+
+        const binRelPath = this.binaries[binaryName];
+        if (!binRelPath) {
+          error(`${binaryName} is not a known binary in ${this.name}`);
+        }
+        const binPath = join(this.installDirectory, binRelPath);
+        const result = spawnSync(binPath, args, options);
+
+        if (result.error) {
+          error(result.error);
+        }
+
+        process.exit(result.status);
+      })
+      .catch((e) => {
+        error(e.message);
+      });
+  }
+}
+
+module.exports.Package = Package;

package/binary.js

@@ -0,0 +1,124 @@
+const { Package } = require("./binary-install");
+const os = require("os");
+const libc = require("detect-libc");
+
+const error = (msg) => {
+  console.error(msg);
+  process.exit(1);
+};
+
+const {
+  name,
+  artifactDownloadUrls,
+  supportedPlatforms,
+  glibcMinimum,
+} = require("./package.json");
+
+// FIXME: implement NPM installer handling of fallback download URLs
+const artifactDownloadUrl = artifactDownloadUrls[0];
+const builderGlibcMajorVersion = glibcMinimum.major;
+const builderGlibcMinorVersion = glibcMinimum.series;
+
+const getPlatform = () => {
+  const rawOsType = os.type();
+  const rawArchitecture = os.arch();
+
+  // We want to use rust-style target triples as the canonical key
+  // for a platform, so translate the "os" library's concepts into rust ones
+  let osType = "";
+  switch (rawOsType) {
+    case "Windows_NT":
+      osType = "pc-windows-msvc";
+      break;
+    case "Darwin":
+      osType = "apple-darwin";
+      break;
+    case "Linux":
+      osType = "unknown-linux-gnu";
+      break;
+  }
+
+  let arch = "";
+  switch (rawArchitecture) {
+    case "x64":
+      arch = "x86_64";
+      break;
+    case "arm64":
+      arch = "aarch64";
+      break;
+  }
+
+  if (rawOsType === "Linux") {
+    if (libc.familySync() == "musl") {
+      osType = "unknown-linux-musl-dynamic";
+    } else if (libc.isNonGlibcLinuxSync()) {
+      console.warn(
+        "Your libc is neither glibc nor musl; trying static musl binary instead",
+      );
+      osType = "unknown-linux-musl-static";
+    } else {
+      let libcVersion = libc.versionSync();
+      let splitLibcVersion = libcVersion.split(".");
+      let libcMajorVersion = splitLibcVersion[0];
+      let libcMinorVersion = splitLibcVersion[1];
+      if (
+        libcMajorVersion != builderGlibcMajorVersion ||
+        libcMinorVersion < builderGlibcMinorVersion
+      ) {
+        // We can't run the glibc binaries, but we can run the static musl ones
+        // if they exist
+        console.warn(
+          "Your glibc isn't compatible; trying static musl binary instead",
+        );
+        osType = "unknown-linux-musl-static";
+      }
+    }
+  }
+
+  // Assume the above succeeded and build a target triple to look things up with.
+  // If any of it failed, this lookup will fail and we'll handle it like normal.
+  let targetTriple = `${arch}-${osType}`;
+  let platform = supportedPlatforms[targetTriple];
+
+  if (!platform) {
+    error(
+      `Platform with type "${rawOsType}" and architecture "${rawArchitecture}" is not supported by ${name}.\nYour system must be one of the following:\n\n${Object.keys(
+        supportedPlatforms,
+      ).join(",")}`,
+    );
+  }
+
+  return platform;
+};
+
+const getPackage = () => {
+  const platform = getPlatform();
+  const url = `${artifactDownloadUrl}/${platform.artifactName}`;
+  let filename = platform.artifactName;
+  let ext = platform.zipExt;
+  let binary = new Package(platform, name, url, filename, ext, platform.bins);
+
+  return binary;
+};
+
+const install = (suppressLogs) => {
+  if (!artifactDownloadUrl || artifactDownloadUrl.length === 0) {
+    console.warn("in demo mode, not installing binaries");
+    return;
+  }
+  const pkg = getPackage();
+
+  return pkg.install(suppressLogs);
+};
+
+const run = (binaryName) => {
+  const pkg = getPackage();
+
+  pkg.run(binaryName);
+};
+
+module.exports = {
+  install,
+  run,
+  getPackage,
+};

package/install.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+const { install } = require("./binary");
+install(false);

package/npm-shrinkwrap.json

@@ -0,0 +1,52 @@
+{
+  "lockfileVersion": 3,
+  "name": "@raultov/browser-control-mcp",
+  "packages": {
+    "": {
+      "bin": {
+        "browser-control-mcp": "run-browser-control-mcp.js"
+      },
+      "dependencies": {
+        "detect-libc": "^2.1.2"
+      },
+      "devDependencies": {
+        "prettier": "^3.8.3"
+      },
+      "engines": {
+        "node": ">=14.14",
+        "npm": ">=6"
+      },
+      "hasInstallScript": true,
+      "license": "MIT",
+      "name": "@raultov/browser-control-mcp",
+      "version": "0.1.1-beta.1"
+    },
+    "node_modules/detect-libc": {
+      "engines": {
+        "node": ">=8"
+      },
+      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+      "license": "Apache-2.0",
+      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
+      "version": "2.1.2"
+    },
+    "node_modules/prettier": {
+      "bin": {
+        "prettier": "bin/prettier.cjs"
+      },
+      "dev": true,
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "url": "https://github.com/prettier/prettier?sponsor=1"
+      },
+      "integrity": "sha512-7igPTM53cGHMW8xWuVTydi2KO233VFiTNyF5hLJqpilHfmn8C8gPf+PS7dUT64YcXFbiMGZxS9pCSxL/Dxm/Jw==",
+      "license": "MIT",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.8.3.tgz",
+      "version": "3.8.3"
+    }
+  },
+  "requires": true,
+  "version": "0.1.1-beta.1"
+}

package/package.json

@@ -1,6 +1,100 @@
 {
+  "artifactDownloadUrls": [
+    "https://github.com/raultov/browser-control-mcp/releases/download/v0.1.1-beta.1"
+  ],
+  "author": "raultov <raultov@protonmail.com>",
+  "bin": {
+    "browser-control-mcp": "run-browser-control-mcp.js"
+  },
+  "dependencies": {
+    "detect-libc": "^2.1.2"
+  },
+  "description": "MCP server to control and debug Chrome and Firefox at runtime: breakpoints, call frames and stepping over CDP and WebDriver BiDi/RDP, plus navigation, DOM, input, screenshots, console and network capture.",
+  "devDependencies": {
+    "prettier": "^3.8.3"
+  },
+  "engines": {
+    "node": ">=14.14",
+    "npm": ">=6"
+  },
+  "glibcMinimum": {
+    "major": 2,
+    "series": 35
+  },
+  "homepage": "https://github.com/raultov/browser-control-mcp",
+  "keywords": [
+    "development-tools::debugging",
+    "web-programming",
+    "command-line-utilities",
+    "mcp",
+    "browser",
+    "debugging",
+    "devtools",
+    "firefox"
+  ],
+  "license": "MIT",
   "name": "@raultov/browser-control-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "preferUnplugged": true,
+  "repository": "https://github.com/raultov/browser-control-mcp",
+  "scripts": {
+    "fmt": "prettier --write **/*.js",
+    "fmt:check": "prettier --check **/*.js",
+    "postinstall": "node ./install.js"
+  },
+  "supportedPlatforms": {
+    "aarch64-apple-darwin": {
+      "artifactName": "browser-control-mcp-aarch64-apple-darwin.tar.xz",
+      "bins": {
+        "browser-control-mcp": "browser-control-mcp"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "aarch64-pc-windows-msvc": {
+      "artifactName": "browser-control-mcp-x86_64-pc-windows-msvc.zip",
+      "bins": {
+        "browser-control-mcp": "browser-control-mcp.exe"
+      },
+      "zipExt": ".zip"
+    },
+    "aarch64-unknown-linux-gnu": {
+      "artifactName": "browser-control-mcp-aarch64-unknown-linux-gnu.tar.xz",
+      "bins": {
+        "browser-control-mcp": "browser-control-mcp"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "x86_64-apple-darwin": {
+      "artifactName": "browser-control-mcp-x86_64-apple-darwin.tar.xz",
+      "bins": {
+        "browser-control-mcp": "browser-control-mcp"
+      },
+      "zipExt": ".tar.xz"
+    },
+    "x86_64-pc-windows-gnu": {
+      "artifactName": "browser-control-mcp-x86_64-pc-windows-msvc.zip",
+      "bins": {
+        "browser-control-mcp": "browser-control-mcp.exe"
+      },
+      "zipExt": ".zip"
+    },
+    "x86_64-pc-windows-msvc": {
+      "artifactName": "browser-control-mcp-x86_64-pc-windows-msvc.zip",
+      "bins": {
+        "browser-control-mcp": "browser-control-mcp.exe"
+      },
+      "zipExt": ".zip"
+    },
+    "x86_64-unknown-linux-gnu": {
+      "artifactName": "browser-control-mcp-x86_64-unknown-linux-gnu.tar.xz",
+      "bins": {
+        "browser-control-mcp": "browser-control-mcp"
+      },
+      "zipExt": ".tar.xz"
+    }
+  },
+  "version": "0.1.1-beta.1",
+  "volta": {
+    "node": "18.14.1",
+    "npm": "9.5.0"
+  }
 }

package/run-browser-control-mcp.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+const { run } = require("./binary");
+run("browser-control-mcp");