smooth-operator-mcp 2.4.10 → 3.0.0

package/docs/harnesses.md

@@ -1,12 +1,33 @@
 # Harness installation
 
-## Interactive wizard (one-command)
-
-`smooth-operator install <harness>` is interactive by default — it asks 7 curated questions (browser mode, browser executable, headless, allowed domains, blocked domains, page JavaScript, and data directory) with recommended defaults in brackets. Omitting `<harness>` is allowed too: on a TTY the installer prompts for the target first (default `opencode`), while piped or CI environments print usage and exit instead. Use `smooth-operator install opencode --yes` to skip prompts and use recommended defaults. The wizard saves its choices to `~/.smooth-operator/config.json` (0600, symlink-safe) — mode, executable path, headless, domains, and allowEval are written exactly as answered on every run — and then registers the harness. Personal-Chrome mode derives `browserUrl` after launching the helper on port 9222; it is not a separate prompt.
+## Interactive wizard (directly to your harness)
+
+`smooth-operator install <harness>` is interactive by default — it asks exactly 3
+curated questions (browser mode/profile, browser executable, and
+security/data-directory settings) with recommended defaults in brackets.
+Omitting `<harness>` is allowed too: on a TTY the installer prompts for the
+target first (default `opencode`), while piped or CI environments print usage
+and exit instead. Use `smooth-operator install opencode --yes` to skip prompts
+and use recommended defaults. The wizard normalizes and validates its choices
+before saving them to `~/.smooth-operator/config.json` (0600, bounded,
+owner-only, and symlink-safe). Managed mode owns one private persistent profile;
+connect mode attaches to an operator-owned browser and does not own or close
+its profile/process. Personal-Chrome mode derives `browserUrl` after launching
+the helper on port 9222; it is not a separate prompt.
 
 ### Personal Chrome (connect) helper
 
-When you pick “personal Chrome” (mode `connect`), the wizard finds Chrome via `discovery.ts`, spawns `chrome --remote-debugging-port=9222 --user-data-dir=~/.smooth-operator/personal-chrome --no-first-run --no-default-browser-check` detached, and polls `http://127.0.0.1:9222/json/version` (300ms × 33, ~10s) until `live`. On success it writes `SMOOTH_OPERATOR_BROWSER_MODE=connect` and `SMOOTH_OPERATOR_BROWSER_URL=http://127.0.0.1:9222` for you. No manual `9222` knowledge needed. Non-interactive environments (no TTY or `CI` set) skip prompts entirely and apply the same recommended defaults as `--yes`. The `chrome://inspect` toggle remains as an advanced opt-in (see `docs/mcp-server.md`).
+When you pick “connected browser” (mode `connect`), the wizard finds Chromium via
+`discovery.ts`, launches a dedicated debugging profile under
+`~/.smooth-operator/personal-chrome` with port `9222`, and polls the loopback
+endpoint until it is live. On success it writes
+`SMOOTH_OPERATOR_BROWSER_MODE=connect` and
+`SMOOTH_OPERATOR_BROWSER_URL=http://127.0.0.1:9222` for you. This does not
+attach to or take ownership of an operator's daily browser profile. No manual
+`9222` knowledge is needed. Non-interactive environments (no TTY or `CI` set)
+skip prompts entirely and apply the same recommended defaults as `--yes`. The
+`chrome://inspect` toggle remains as an advanced opt-in (see
+`docs/mcp-server.md`).
 
 SmoothOperator speaks MCP over stdio. The `smooth-operator install <target>`
 command registers that stdio server with a supported client. It uses

package/docs/mcp-server.md

@@ -43,6 +43,16 @@ smooth-operator --help
 
 (The registry package is `smooth-operator-mcp`; plain `smooth-operator` is an unrelated library. You can also install straight from GitHub: `npm install -g github:Gitshop77/Smooth-Operator`.)
 
+The interactive installer asks exactly three questions: (1) browser profile
+ownership, (2) headed or headless display, and (3) which Chromium executable to
+use. Its recommended defaults are a managed private persistent profile, headed
+display, and the first detected Chromium executable. It also enables page eval,
+balanced stealth, and short behavioral timing in the native profile; pass the
+corresponding environment flags as `false` when those capabilities are not
+wanted. Managed mode owns its profile. Connected mode launches and attaches to
+a dedicated debugging profile and does not claim ownership of an operator's
+daily browser.
+
 From a checkout:
 
 ```sh
@@ -145,18 +155,23 @@ are answered only after the same Host and Origin checks.
 
 ## Browser lifecycle
 
-The server manages one headed, persistent private agent-Chrome session by
-default. On the first browser tool call it discovers an installed Google Chrome,
+The server manages one headed, persistent private Chromium-based browser session
+by default. On the first browser tool call it discovers an installed browser,
 launches it with `${SMOOTH_OPERATOR_DATA_DIR}/browser` as a non-default profile,
 and records its loopback DevTools endpoint for later reattachment. Sign in once
 in the visible window; its sessions persist in that private profile. The
 `browser_doctor` tool reports executable resolution and endpoint state without
 evaluating page content.
 
-Managed Chrome is headed by default for sign-in and human handoff. On CI or a
+The managed browser is headed by default for sign-in and human handoff. On CI or a
 displayless host, explicitly set `SMOOTH_OPERATOR_BROWSER_HEADLESS=true` or use
-Xvfb. The server never adds fingerprint spoofing, CAPTCHA solving, proxy
-rotation, or other evasion behavior.
+Xvfb. If you set both `SMOOTH_OPERATOR_BROWSER_VIEWPORT_WIDTH` and
+`SMOOTH_OPERATOR_BROWSER_VIEWPORT_HEIGHT`, that explicit viewport is applied to
+the browser and any opt-in stealth page metrics. All local browser tools and
+features are available by default, including page evaluation and the balanced
+stealth/short-behavior profile. Set their environment flags to `false` for a
+stricter or faster profile. See `STEALTH-GUIDE.md` for challenge handling and
+the remaining boundaries.
 
 ### Managed mode (default)
 
@@ -283,18 +298,50 @@ variables include:
 | `SMOOTH_OPERATOR_BROWSER_MODE` | `managed` | `managed`, `disabled`, `connect`, or `launch` |
 | `SMOOTH_OPERATOR_BROWSER_URL` | `http://127.0.0.1:9222` | DevTools HTTP endpoint |
 | `SMOOTH_OPERATOR_BROWSER_EXECUTABLE` | unset | Managed-mode override; required for explicit launch mode |
-| `SMOOTH_OPERATOR_BROWSER_USER_DATA_DIR` | `${SMOOTH_OPERATOR_DATA_DIR}/browser` | Dedicated persistent agent-Chrome profile |
+| `SMOOTH_OPERATOR_BROWSER_USER_DATA_DIR` | `${SMOOTH_OPERATOR_DATA_DIR}/browser` | Dedicated persistent browser profile |
 | `SMOOTH_OPERATOR_BROWSER_HEADLESS` | `false` | Set `true` for CI/displayless managed or launch use |
+| `SMOOTH_OPERATOR_BROWSER_VIEWPORT_WIDTH` / `_HEIGHT` | unset | Set both to apply an explicit viewport |
+| `SMOOTH_OPERATOR_BROWSER_AUTO_LAUNCH` | `false` | Backward-compatible connect-mode recovery option |
+| `SMOOTH_OPERATOR_BROWSER_TIMEOUT_MS` | `15000` | Per-action deadline |
+| `SMOOTH_OPERATOR_BROWSER_CONNECT_TIMEOUT_MS` | `30000` | Browser connection deadline |
+| `SMOOTH_OPERATOR_BROWSER_CDP_TIMEOUT_MS` | `30000` | DevTools command deadline |
+| `SMOOTH_OPERATOR_MAX_SCREENSHOT_BYTES` | `8000000` | Screenshot byte cap |
+| `SMOOTH_OPERATOR_MAX_HTML_CHARS` | `200000` | HTML output cap |
 | `SMOOTH_OPERATOR_ALLOWED_DOMAINS` | unset | Comma-separated allowlist |
 | `SMOOTH_OPERATOR_BLOCKED_DOMAINS` | unset | Comma-separated denylist |
 | `SMOOTH_OPERATOR_ALLOWED_FILE_ROOTS` | data `files`, `downloads` | Explicit roots replace defaults |
 | `SMOOTH_OPERATOR_ALLOW_PRIVATE_NETWORK` | `false` | Allows non-loopback private targets when true |
-| `SMOOTH_OPERATOR_ALLOW_EVAL` | `false` | Required, with full policy, for page JavaScript |
+| `SMOOTH_OPERATOR_ALLOW_EVAL` | `true` | Set `false` to disable page JavaScript |
+| `SMOOTH_OPERATOR_STEALTH_ENABLED` | `true` | Set `false` to preserve raw automation signals |
+| `SMOOTH_OPERATOR_STEALTH_PROFILE` | `balanced` | `balanced` or `max` compatibility label |
+| `SMOOTH_OPERATOR_STEALTH_GPU` | `false` | Adds opt-in GPU launch flags |
+| `SMOOTH_OPERATOR_BEHAVIOR_ENABLED` | `true` | Set `false` for fastest raw interactions |
+| `SMOOTH_OPERATOR_HTTP_HOST` | `127.0.0.1` | HTTP bind host |
+| `SMOOTH_OPERATOR_HTTP_PORT` | `3344` | HTTP bind port |
+| `SMOOTH_OPERATOR_HTTP_PATH` | `/mcp` | HTTP endpoint path |
 | `SMOOTH_OPERATOR_HTTP_TOKEN` | unset | Required for HTTP; 32+ chars for remote mode |
 | `SMOOTH_OPERATOR_ALLOW_REMOTE_HTTP` | `false` | Allows non-loopback HTTP only with a strong token |
 | `SMOOTH_OPERATOR_HTTP_MAX_BODY_BYTES` | `2000000` | Bounded HTTP request body |
+| `SMOOTH_OPERATOR_ALLOWED_HOSTS` | `localhost,127.0.0.1,[::1]` | HTTP Host allowlist |
+| `SMOOTH_OPERATOR_ALLOWED_ORIGINS` | `localhost,127.0.0.1,[::1]` | HTTP Origin allowlist |
 | `SMOOTH_OPERATOR_LOG_LEVEL` | `info` | `debug`, `info`, `warn`, or `error` |
 
+### Fast operation mode
+
+The default configuration is a native managed browser with short bounded
+behavioral timing, the conservative stealth baseline, and page evaluation
+available. For the fastest raw interactions, set
+`SMOOTH_OPERATOR_BEHAVIOR_ENABLED=false` and, when appropriate,
+`SMOOTH_OPERATOR_STEALTH_ENABLED=false`; set `SMOOTH_OPERATOR_ALLOW_EVAL=false`
+when page JavaScript is not needed. Tool calls remain bounded and cancellable;
+no hidden planning loop is introduced.
+
+Raw MCP/tool-call speed is not the main bot-detection vector. Sites can score
+network and browser identity, IP reputation, session history, and interaction
+timing independently. A faster call does not bypass a challenge or make an
+automated session legitimate; use the internal AI workflow or human handoff
+only where the target permits automation.
+
 ## Security enforcement layers
 
 There are no client-selectable permissiveness tiers. The following controls
@@ -314,13 +361,15 @@ are always applied, with explicit opt-ins where documented:
   unknown schemes are rejected.
 - Upload and PDF destinations must stay within configured file roots after
   realpath and symlink checks. Download paths and generated files are bounded.
-- Page JavaScript is disabled by default. It is available only when the full
-  security policy and `SMOOTH_OPERATOR_ALLOW_EVAL=true` are configured; enabling it
-  lets page code observe and mutate page state with the browser's privileges.
+- Page JavaScript is available in the native profile by default and can be
+  disabled with `SMOOTH_OPERATOR_ALLOW_EVAL=false`; when enabled, page code can
+  observe and mutate page state with the browser's privileges.
 - Page text, HTML, titles, attributes, search snippets, cookies, and logs are
   treated as untrusted data, normalized, bounded, and redacted before output.
-- CAPTCHA and anti-bot markers are reported for human handoff. The server does
-  not bypass them, rotate identities, or solve challenges.
+- Challenge and anti-bot markers are reported from bounded evidence. The server
+  does not rotate identities or silently bypass challenges. The connected-AI
+  challenge loop collects fresh classification and visual/state evidence,
+  allows ordinary browser actions, and verifies with a subsequent call.
 
 Run the server with a dedicated browser profile and the smallest domain and
 file-root allowlists that fit the task. Browser automation can still perform
@@ -347,22 +396,28 @@ individual descriptions and limits are returned by `tools/list`.
 `browser_close_tab`, `browser_click`, `browser_input`, `browser_select`,
 `browser_scroll`, `browser_scroll_to_bottom`, `browser_key`,
 `browser_wait`, `browser_wait_for_element`, `browser_wait_for_text`, `browser_wait_for_url`,
-`browser_wait_for_network_idle`, `browser_hover`, `browser_press_and_hold`,
+`browser_wait_for_network_idle`, `browser_hover`, `browser_move`, `browser_press_and_hold`,
 `browser_type`, `browser_close`, and `browser_close_all`.
 
-**Explicitly gated capabilities:** `browser_screenshot`, `browser_pdf`,
+**Available local capabilities:** `browser_screenshot`, `browser_pdf`,
 `browser_upload`, `browser_downloads`, `browser_network_log`,
-`browser_console_log`, `browser_dialog`, `browser_cookies`,
-`browser_storage`, `browser_evaluate`, `browser_batch`,
-`browser_exec`, `browser_wait_for_human`, `browser_close_session`, and
-the explicit browser-session lifecycle controls.
-
-`browser_evaluate` is page JavaScript and is disabled by default. `browser_exec`
+`browser_console_log`, `browser_dialog`, `browser_cookies`, `browser_storage`,
+`browser_batch`, `browser_exec`, `browser_wait_for_human`,
+`browser_solve_challenge`, and all other browser tools are available by default.
+`browser_close_session` remains a local lifecycle control and does not change
+browser permissions. Page evaluation is available by default and can be
+disabled explicitly with `SMOOTH_OPERATOR_ALLOW_EVAL=false`.
+
+`browser_evaluate` is page JavaScript and is available by default (set
+`SMOOTH_OPERATOR_ALLOW_EVAL=false` when it is not wanted). `browser_exec`
 accepts only a JSON array of validated browser actions; it is not a shell,
 Python, or arbitrary code runner. Destructive batch actions require explicit
 confirmation. `browser_wait_for_human` pauses for an operator to complete a
-visible sign-in or challenge, and `browser_close_session` closes the one
-native browser session by its explicit session identifier.
+visible sign-in or challenge. `browser_solve_challenge` is an internal
+connected-AI observe/act/verify loop: it returns bounded evidence and is
+successful only when a fresh final classification explicitly reports the
+challenge absent. `browser_close_session` closes the one native browser session
+by its explicit session identifier.
 
 Actions that leave a usable page—navigation, click, input, select, scroll, key,
 back, forward, and reload—accept optional `includeSnapshot: true`. The action
@@ -398,7 +453,9 @@ schema) is one aggregate budget across the returned title and snippet text,
 not a per-result multiplier. URL fields and fixed untrusted-data wrapper
 markers are outside that text budget. The response body is bounded before
 parsing, redirects are rejected, cancellation and timeout are propagated, and
-credentials/query secret placeholders are removed from result URLs.
+credentials/query secret placeholders are removed from result URLs. Transient
+retrieval failures use at most three bounded attempts; anti-bot responses are
+reported without attempting a bypass.
 
 ### Resources
 
@@ -413,7 +470,10 @@ The server publishes read-only resources:
 - `smooth-operator://browser/logs/console`
 
 Resource output is bounded and follows the same redaction and policy rules as
-tool output.
+tool output. The capabilities resource also reports the native defaults and
+effective feature flags for local browser tools, page evaluation, stealth, and
+behavioral timing, plus whether challenge success requires an explicit absent
+classification.
 
 ### Prompts
 
@@ -436,7 +496,6 @@ mode remains under the operator's ownership.
 To clean up a local installation:
 
 ```sh
-smooth-operator install claude-desktop   # inspect config before removal
 npm uninstall -g smooth-operator-mcp
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smooth-operator-mcp",
-  "version": "2.4.10",
+  "version": "3.0.0",
   "type": "module",
   "packageManager": "npm@12.0.2",
   "description": "A lightweight, production-grade MCP server for secure browser automation.",
@@ -43,6 +43,7 @@
   "dependencies": {
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
+    "ghost-cursor": "^1.4.2",
     "puppeteer-core": "^25.9.0",
     "zod": "^4.4.3"
   },