smooth-operator-mcp 3.1.0 → 3.3.0

package/README.md

@@ -1,13 +1,15 @@
 # SmoothOperator
 
-Give your AI a real Chrome. SmoothOperator is a lightweight, production-grade MCP server for secure, reliable browser control. Your harness supplies the reasoning; SmoothOperator handles navigation, interaction, extraction, and browser lifecycle. No model keys. No hidden planner.
+Give your AI a real Chrome. SmoothOperator is a production MCP server for
+secure browser control. Your harness supplies the reasoning; SmoothOperator
+handles navigation, interaction, extraction, and browser lifecycle. No model
+keys. No hidden planner.
 
-## Install — directly to your harness
-
-Choose your harness, add SmoothOperator directly to it, and restart the harness.
+## Install
 
 **From npm** (`smooth-operator-mcp`):
-~~~sh
+
+```sh
 npm install -g smooth-operator-mcp && smooth-operator install opencode
 npm install -g smooth-operator-mcp && smooth-operator install claude-code
 npm install -g smooth-operator-mcp && smooth-operator install copilot
@@ -17,99 +19,86 @@ npm install -g smooth-operator-mcp && smooth-operator install vscode
 npm install -g smooth-operator-mcp && smooth-operator install cursor
 npm install -g smooth-operator-mcp && smooth-operator install windsurf
 npm install -g smooth-operator-mcp && smooth-operator install claude-desktop
-~~~
+```
+
+The plain-npm name `smooth-operator` is an unrelated library. Do **not** run
+`npm install -g smooth-operator`.
 
-> Note: the plain-npm name `smooth-operator` is an unrelated library on the registry.
-> Do NOT use `npm install -g smooth-operator`.
+From GitHub:
 
-Or straight from GitHub:
-~~~sh
+```sh
 npm install -g github:Gitshop77/Smooth-Operator && smooth-operator install opencode
-~~~
+```
+
+The wizard asks exactly three questions: browser profile ownership, browser
+display, and the Chromium executable. `smooth-operator install` without a
+harness chooses one on a TTY (piped/CI prints usage). `--yes` applies
+recommended defaults: `smooth-operator install opencode --yes`.
+
+Managed mode owns one private persistent profile
+(`~/.smooth-operator/browser`). Wizard Personal Chrome launches a dedicated
+debugging profile on port `9222` and derives `browserUrl`; it does not take
+over daily Chrome. Connect mode attaches to the configured `browserURL` /
+`wsEndpoint`.
 
-The wizard asks exactly 3 focused questions: browser profile ownership, browser display, and the Chromium executable. Run `smooth-operator install` with no harness to pick one interactively (TTY only; piped/CI runs print usage and exit). `--yes` applies the recommended defaults, so give it a target: `smooth-operator install opencode --yes`. Personal Chrome mode launches a dedicated debugging profile on `9222` and derives `browserUrl` automatically. Managed mode owns one private persistent profile; connected mode launches and attaches to a dedicated debugging profile and does not claim ownership of an operator's daily browser.
+Requires Node.js 22.23.2+ and an installed Chromium-based browser.
 
-Requires Node 22.23.2+ and an installed Chromium-based browser. Profile at `~/.smooth-operator/browser` — sign in once.
+```sh
+smooth-operator --help
+smooth-operator doctor
+```
 
-Verify: `smooth-operator --help` and `server_health` / `browser_doctor` appear after restart. `server_health` reports `ok` when the runtime is ready, `degraded` when browser recovery is required or its managed profile lease is not held, and `shutting_down` during teardown; an idle lazy browser is healthy.
+After restart, ask the harness to run `server_health` and `browser_doctor`.
+`server_health` reports `ok` when ready, `degraded` when recovery or the
+profile lease is needed, and `shutting_down` during teardown. An idle lazy
+browser is healthy.
 
-For a local release check, run `npm run verify`; it covers lint, type safety,
-tests, dead-code analysis, and the package smoke test.
+Local check: `npm run verify` (lint, typecheck, coverage tests, knip, package
+smoke/build). `npm test` and coverage exclude `tests/browser-live.test.ts`.
+Live Chrome is only `npm run test:browser:live`.
 
 ## What it does
 
-- Navigate and interact with real websites: click, type, select, scroll, hover, and key input
-- Inspect pages with snapshots, accessibility trees, HTML, styles, text search, and bounded extraction
-- Work across tabs, frames, popups, shadow DOM, dialogs, cookies, storage, downloads, screenshots, and PDFs
-- Search the web through bounded DuckDuckGo retrieval
-- Search a bounded metadata-only network journal by request ID, URL, method, status, and resource type
-- Block page-scoped image, stylesheet, font, media, and script subresources; document and navigation requests are never selectable
-- Inspect a selected element's safe attributes, styles, animations, and shallow children without returning scripts, event source, form values, or arbitrary data attributes
-- Upload one file or up to 20 files from allowed roots; each file is capped at 50 MiB and the aggregate at 100 MiB
-- Read, set, and delete URL-scoped cookies with validated SameSite settings; cookie values are omitted from reads
-
-The MCP registry exposes 64 public tools. The surface includes bounded network
-search, safe element inspection, page-scoped resource blocking, and file and
-cookie controls alongside the navigation, extraction, and lifecycle tools.
-
-Ask: *“Scrape pricing into a table”*, *“Fill this form with ~/resume.pdf”*, or *“Download the monthly report as a PDF.”*
-
-## How to use
-
-Talk to your harness normally. It can call `browser_navigate` → `browser_snapshot` → `browser_click` and the rest of the MCP surface as needed. For a challenge, `browser_solve_challenge` returns fresh bounded visual/state evidence and an attempt budget; the connected AI keeps using ordinary browser actions and calls it again until the final classification is clear or the budget is exhausted. Human handoff remains available only as an explicit final option.
-
-Browser identity remains native, page JavaScript is available by default, and
-behavioral timing is off for fast deterministic input. Set the explicit
-environment flags to change those choices. See the [browser compatibility guide](docs/STEALTH-GUIDE.md) for
-details and responsible use.
-
-For the fastest supported operation, keep behavioral timing off with
-`SMOOTH_OPERATOR_BEHAVIOR_ENABLED=false`; the native browser remains bounded and
-cancellable. All local browser tools and page features are available by default;
-remote HTTP, private-network access, and file roots remain explicitly gated.
-Faster calls do not bypass challenges or grant permission to automate a site.
-
-Managed mode preflights a regular executable when it needs to launch, and
-launch mode does so before invoking Chromium. Both wait for browser launch
-readiness and a target-guard acknowledgement before returning a usable
-connection. The loopback DevTools `/json/version` probe is bounded to 64 KiB
-before JSON parsing. There is no arbitrary CDP or host-code tool; page
-evaluation remains an explicit page capability.
-
-## Why
-
-- Zero setup — managed, headed, persistent browser by default
-- Secure by default — domain and file policy, bounded outputs, redaction, and explicit safety boundaries
-- Reliable — private profiles, stale-reference recovery, reconnect handling, and structured errors
-- Flexible — stdio by default, Streamable HTTP when you need it, plus connect and disabled modes
-
-For HTTP deployments, the configured MCP path also has a bounded readiness
-endpoint at `<path>/healthz` (normally `/mcp/healthz`), subject to the same
-HTTP authentication policy as the MCP endpoint.
-
-## Benchmarks
-
-Compared with [Browser Use MCP](https://github.com/browser-use/browser-use) · [![Browser Use GitHub stars](https://img.shields.io/github/stars/browser-use/browser-use?style=social)](https://github.com/browser-use/browser-use) 
-
-Tested: 26 August 2026
-
-| Benchmark | Metric | SmoothOperator | Browser Use MCP |
-| --- | --- | ---: | ---: |
-| Live Web (8 sites, 32 episodes) | URL success | **32/32** | 23/32 |
-| Live Web | Page-text quality | **26/32** | 21/32 |
-| Live Web | Combined success | **26/32** | 18/32 |
-| Live Web | Task latency mean / p95 | **1,358 / 2,957 ms** | 4,604 / 30,780 ms |
-| Live Web | Navigation p95 | **2,130 ms** | 4,320 ms |
-| Live Web | Click p95 | 920 ms | **142 ms** |
-| Live Web | MCP call p95 | **943 ms** | 2,095 ms |
-| Live Web | Trace errors | **0** | 10 |
-| MiniWoB++ 0.14.3 (125 tasks) | Reward = 1 | **124/125** | 89/125 |
-| MiniWoB++ | Attempts | **125** | 125 |
-| MiniWoB++ | MCP errors | **0** | 29 |
-| MiniWoB++ | Transport errors | **0** | **0** |
-| MiniWoB++ | Timeouts | **0** | **0** |
-| Browser Use benchmark | Muse Spark 1.2 · score | **64% · 100 tasks** | 12% · 60 tasks |
-
-*Task counts and scoring rules differ; comparison is directional.*
-
-[View the Browser Use benchmark](https://github.com/browser-use/benchmark)
+The MCP registry exposes **57 public tools**. Each listed name does one job.
+Navigate and interact; inspect with snapshots, accessibility, HTML, styles,
+and bounded extraction; work across tabs, frames, popups, shadow DOM,
+dialogs, cookies, storage, downloads, screenshots, and PDFs; search the web
+through bounded DuckDuckGo retrieval; search a metadata-only network journal;
+block page-scoped subresources; inspect elements without scripts, event
+source, or form values; upload up to 20 files from allowed roots (50 MiB
+each, 100 MiB aggregate). Cookie values are omitted from reads. Operations:
+cookies `get`/`set`/`delete`; storage and resource-blocking `get`/`set`/`clear`;
+network and console logs `enable`/`disable`/`read`/`clear`/`read_and_clear`;
+dialogs `get_text`/`accept`/`dismiss`/`send_keys`.
+
+Preferred loop: `browser_navigate` / `browser_snapshot` → one mutation →
+verify. Element actions accept exactly one of `target`, `ref`
+(`e5`/`ref:e5`), CSS `selector`, or zero-based `index`. `browser_click`,
+`browser_move`, and `browser_press_and_hold` also accept
+`coordinateX`/`coordinateY` (hold also start/end coordinates or a path).
+Set `includeSnapshot: true` to combine a mutation with its trailing snapshot.
+
+Canonical tools: `browser_tabs`, `browser_snapshot`, `browser_input`,
+`browser_back`, `browser_close`, `browser_extract`, `browser_wait`,
+`browser_network_log`, `browser_challenge`, `browser_batch`. Compatibility
+aliases are not listed.
+
+`browser_solve_challenge` returns fresh bounded evidence. The connected AI
+uses ordinary browser actions until a fresh classification reports the
+challenge **absent** or the attempt budget is exhausted. Human handoff
+(`browser_wait_for_human`) is an explicit last option. There is no captcha
+solver. Identity stays native: launch args do not fabricate UA,
+platform, WebGL, canvas, client hints, or `navigator.webdriver`.
+
+HTTP deployments expose `<path>/healthz` (normally `/mcp/healthz`) with the
+same Host, Origin, and bearer policy as `/mcp`.
+
+## Docs
+
+- [Architecture](docs/architecture.md)
+- [Security](docs/security.md)
+- [Tools](docs/tools.md)
+- [Config](docs/config.md)
+- [Harnesses](docs/harnesses.md)
+- [Browser compatibility](docs/STEALTH-GUIDE.md)
+- [MCP server operations](docs/mcp-server.md)