smooth-operator-mcp 3.2.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,90 +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 three focused questions: browser profile ownership,
-browser display, and the Chromium executable. Run `smooth-operator install`
-without a harness to choose one interactively (TTY only; piped and 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 port `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.
 
-SmoothOperator requires Node.js 22.23.2 or newer and an installed
-Chromium-based browser. The default managed profile is
-`~/.smooth-operator/browser`; sign in once and reuse that private profile.
+```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. The preferred loop is `browser_navigate`/`browser_snapshot` → one mutation → verify. Element actions accept exactly one current `target`, `ref` (`e5`/`ref:e5`), CSS `selector`, or zero-based `index`; refresh these after navigation or DOM changes. Set `includeSnapshot: true` on a mutation to combine the mutation and its trailing verification snapshot. `browser_batch` is useful for short independent sequences; its `timeoutMs` is a whole-batch deadline (120 seconds by default, 600 seconds maximum).
-
-Prefer canonical tools such as `browser_tabs`, `browser_snapshot`, `browser_input`, `browser_back`, `browser_close`, and `browser_extract`. Browser-use compatibility aliases remain available and are labeled as aliases in `tools/list`. Deterministic stale-reference, frame, dialog, element, and browser-recovery errors include a compact recovery tool suggestion.
-
-For a challenge, `browser_solve_challenge` returns fresh bounded visual and
-state evidence with an attempt budget. The connected AI uses ordinary browser
-actions and calls it again until a fresh classification reports the challenge
-absent or the automation 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.
+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)