Standalone build, stability fixes, and dependency updates (v0.2.0)

README-STABILITY.md

@@ -0,0 +1,46 @@
+# Browser MCP stability fix (0.2.1)
+
+## Problem
+
+Cursor restarts the MCP server process often. The old server called `killProcessOnPort(9009)` on every start, which killed the WebSocket the browser extension was connected to. That caused random `Not connected` errors.
+
+## Fix
+
+1. **Persistent bridge daemon** (`dist/ws-daemon.js`) keeps the extension WebSocket alive on port `9009`.
+2. **MCP control channel** on port `9010` lets Cursor reconnect without dropping the browser tab.
+3. **WebSocket ping keepalive** every 25s prevents idle disconnects.
+4. **No port killing** on startup.
+5. **Bridge token auth** on the control channel (`~/.browsermcp/bridge.token`, mode `0600`) blocks other local processes from driving your browser.
+6. **Input validation** blocks `javascript:`, `file:`, and `data:` navigation URLs and caps wait/text payload sizes.
+
+The MCP server auto-starts the daemon if it is not already running.
+
+## One-click pairing
+
+Install Browser MCP in your editor and get Cursor / VS Code deeplinks:
+
+```bash
+npx @browsermcp/mcp pair --open cursor
+```
+
+Or from a local build:
+
+```bash
+node dist/index.js pair --open cursor
+```
+
+This writes `browsermcp` to `~/.cursor/mcp.json` (and other supported clients), starts the bridge daemon, and prints one-click install links.
+
+After pairing: **Cursor Settings → MCP → restart browsermcp**.
+
+The MCP server auto-restarts a stale bridge daemon if the control port is occupied but authentication fails (for example after upgrading to token auth).
+
+Then in Chrome: open the Browser MCP extension → **Connect** on your Cloudflare tab.
+
+## Manual daemon (optional)
+
+```bash
+node /Users/misha/nocursor/browsermcp/mcp/dist/ws-daemon.js
+```
+
+Ports: extension `9009`, MCP bridge `9010`.

README.md

@@ -1,32 +1,87 @@
-<a href="https://browsermcp.io">
-  <img src="./.github/images/banner.png" alt="Browser MCP banner">
-</a>
+# Browser MCP (community fork)
 
-<h3 align="center">Browser MCP</h3>
+A maintained fork of [Browser MCP](https://github.com/BrowserMCP/mcp), the MCP server and Chrome extension that lets AI tools automate your existing browser.
 
-<p align="center">
-  Automate your browser with AI.
-  <br />
-  <a href="https://browsermcp.io"><strong>Website</strong></a> 
-  •
-  <a href="https://docs.browsermcp.io"><strong>Docs</strong></a>
-</p>
+Upstream development has slowed, so this repository exists to keep the project usable, fix regressions, and ship improvements without waiting on the original maintainers.
 
 ## About
 
-Browser MCP is an MCP server + Chrome extension that allows you to automate your browser using AI applications like VS Code, Claude, Cursor, and Windsurf.
+Browser MCP connects an MCP server to a Chrome extension so applications like Cursor, VS Code, Claude, and Windsurf can drive the browser you already use: your profile, your logins, your tabs.
+
+This fork keeps that model and focuses on reliability for day-to-day agent workflows.
+
+## Why this fork
+
+- Upstream activity and issue response have been limited for some time.
+- Cursor and other clients restart MCP processes frequently; the original server could drop the extension connection on every restart.
+- We wanted standalone builds, clearer pairing, and hardening without depending on upstream release cadence.
+
+If upstream becomes active again, we are happy to contribute fixes back. Until then, this repo is the maintained line.
+
+## What is different here
+
+Compared to upstream `0.1.x`, this fork (`0.2.x`) includes:
+
+- **Persistent bridge daemon** — keeps the extension WebSocket alive across MCP restarts.
+- **Separate control channel** — the editor reconnects without killing the browser tab connection.
+- **No port killing on startup** — avoids random `Not connected` errors.
+- **Bridge token auth** — local control traffic requires a token in `~/.browsermcp/bridge.token`.
+- **Input validation** — blocks dangerous navigation schemes and caps payload sizes.
+- **One-click pairing** — `browsermcp pair` writes client config and starts the daemon.
+- **Standalone build** — ships a self-contained `dist/` without fragile monorepo assumptions.
+
+See [README-STABILITY.md](./README-STABILITY.md) for implementation details and pairing steps.
+
+The [`extension/`](../extension/) directory tracks popup UI fixes (for example, disconnecting from any tab). See [extension/README.md](../extension/README.md).
 
 ## Features
 
-- ⚡ Fast: Automation happens locally on your machine, resulting in better performance without network latency.
-- 🔒 Private: Since automation happens locally, your browser activity stays on your device and isn't sent to remote servers.
-- 👤 Logged In: Uses your existing browser profile, keeping you logged into all your services.
-- 🥷🏼 Stealth: Avoids basic bot detection and CAPTCHAs by using your real browser fingerprint.
+- **Fast** — automation runs locally; no remote browser latency.
+- **Private** — browser activity stays on your machine.
+- **Logged in** — uses your existing profile and sessions.
+- **Stealth** — uses your real browser fingerprint to reduce basic bot detection.
+
+## Quick start
+
+From a local build:
 
-## Contributing
+```bash
+npm install
+npm run build
+node dist/index.js pair --open cursor
+```
 
-This repo contains all the core MCP code for Browser MCP, but currently cannot yet be built on its own due to dependencies on utils and types from the monorepo where it's developed.
+After pairing, restart the `browsermcp` MCP server in your editor. In Chrome, open the Browser MCP extension and click **Connect** on the tab you want to automate.
+
+Published installs can use:
+
+```bash
+npx @browsermcp/mcp pair --open cursor
+```
+
+## Development
+
+Requires Node.js 18+.
+
+```bash
+npm install
+npm run build
+npm run typecheck
+npm run test
+```
+
+Run the MCP inspector:
+
+```bash
+npm run inspector
+```
 
 ## Credits
 
-Browser MCP was adapted from the [Playwright MCP server](https://github.com/microsoft/playwright-mcp) in order to automate the user's browser rather than creating new browser instances. This allows using the user's existing browser profile to use logged-in sessions and avoid bot detection mechanisms that commonly block automated browser use.
+Browser MCP was created by the [BrowserMCP](https://github.com/BrowserMCP) project and adapted from the [Playwright MCP server](https://github.com/microsoft/playwright-mcp) to automate the user's browser rather than spawning new browser instances.
+
+This fork is maintained independently. Upstream website and docs remain at [browsermcp.io](https://browsermcp.io) and [docs.browsermcp.io](https://docs.browsermcp.io) for reference.
+
+## License
+
+Apache-2.0. See [LICENSE](./LICENSE).