junso-browser 0.2.12 → 0.3.0

package/README.md

@@ -66,7 +66,60 @@ Open `http://<host>:8790/view/<profile>?token=<token>` in any browser to **watch
 
 ## Optional browser MCP
 
-junso-browser also ships an **MCP server** (`src/mcp.ts`, bin `junso-browser-mcp`) — the way to give any MCP client (Jun, Codex, Claude Desktop) browser tools without a local browser. It resolves a profile's CDP URL from the API and drives it via `agent-browser --cdp`, so it works whether junso-browser is local or remote.
+junso-browser ships the **same browser MCP** over two transports — the way to give any MCP client (Jun, Codex, Claude Desktop) browser tools without a local browser. It drives profiles through the host's CDP gateway, so it works whether junso-browser is local or remote.
+
+### HTTP transport — no local install (recommended)
+
+Since 0.3.0 the host exposes the MCP at **`POST /mcp`** (Streamable HTTP), so a client adds junso-browser as a plain URL with nothing installed locally. Token-authed via `Authorization: Bearer <token>` (also accepts `x-junso-token: <token>` or `?token=<token>` in the URL).
+
+**The auth header config differs per client** — this is the #1 setup gotcha:
+
+**Claude Code** (`.mcp.json` at the repo root, or `~/.claude.json` for user scope) — uses a `headers` object:
+
+```json
+{
+  "mcpServers": {
+    "junso-browser": {
+      "type": "http",
+      "url": "http://<host>:8790/mcp",
+      "headers": { "Authorization": "Bearer <token>" }
+    }
+  }
+}
+```
+
+**Codex / Jun** (`config.toml`) — uses **`http_headers`** (NOT `headers` — Codex silently ignores a `headers` block, connects with no auth, gets a 401, and hangs at `startupState:"starting"`):
+
+```toml
+# may also require this at the top level on some builds:
+experimental_use_rmcp_client = true
+
+[mcp_servers.junso-browser]
+url = "http://<host>:8790/mcp"
+
+[mcp_servers.junso-browser.http_headers]
+Authorization = "Bearer <token>"
+```
+
+Codex also supports `bearer_token_env_var = "MY_TOKEN_ENV"` and `env_http_headers` to source the token/headers from env vars instead of hardcoding.
+
+Common to all clients:
+- Append `?profile=<id>` to the URL to set the session's initial profile (else `default`, auto-created).
+- Behind the Caddy TLS front, use `https://<host>:8443/mcp` (or whatever subdomain reverse-proxies to `127.0.0.1:8790`).
+- The MCP runs in-process on the host, one isolated server per session (`Mcp-Session-Id` header), idle-reaped after 10 min. A plain `GET /mcp` → **405** (the bridge is request/response only, no server→client SSE) — that's expected, not an error.
+- `browser_solve_captcha`'s 2captcha key is supplied **by the connector**: `x-twocaptcha-key` header or `?twocaptcha=` (keeps the secret with the client).
+
+**Troubleshooting:** if the client hangs on "loading" / shows a "Connect"/OAuth button / sits at `authStatus:"unsupported"`, the token isn't reaching the host (wrong header key — see Codex `http_headers` above) → it 401s and never completes the handshake. Verify the host independently with a raw POST:
+```bash
+curl -i -X POST http://<host>:8790/mcp \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
+```
+A working host returns **200** with an `mcp-session-id` header and `serverInfo: junso-browser`. If curl works but the client doesn't, the problem is the client's auth-key syntax, not the host. Also confirm you're hitting an actual junso-browser host: `GET /health` returns JSON `{"name":"junso-browser",…}` — if it returns HTML, that hostname is serving a different app (e.g. the Jun web UI) and junso-browser isn't routed there.
+
+### stdio transport — `junso-browser-mcp` bin
 
 Add it to a client's MCP config (once `junso-browser` is installed globally):
 
@@ -79,7 +132,11 @@ Add it to a client's MCP config (once `junso-browser` is installed globally):
 
 (or `"command": "bunx", "args": ["-y", "junso-browser-mcp"]` without a global install).
 
-Tools: `browser_status`, `browser_navigate`, `browser_snapshot`, `browser_click`, `browser_fill`, `browser_type`, `browser_press`, `browser_select`, `browser_scroll`, `browser_wait`, `browser_read`, `browser_eval`, `browser_screenshot`, `browser_exec`, `browser_list_profiles`, `browser_switch_profile`. The active profile (env `JUNSO_BROWSER_PROFILE`, default `default`) is auto-created on the host if missing; `browser_switch_profile` changes identity at runtime.
+### Tools
+
+Drive: `browser_status`, `browser_navigate`, `browser_snapshot`, `browser_click`, `browser_fill`, `browser_type`, `browser_press`, `browser_select`, `browser_scroll`, `browser_wait`, `browser_read`, `browser_eval`, `browser_screenshot`, `browser_exec`. Identity: `browser_list_profiles`, `browser_switch_profile`, `browser_create_profile`. Proxy/IP: `browser_get_proxy`, `browser_set_proxy`, `browser_exit_ip`, `browser_rotate_proxy`, `browser_probe_ip`. CAPTCHA: `browser_solve_captcha`.
+
+The active profile (env `JUNSO_BROWSER_PROFILE` for stdio / `?profile=` for HTTP, default `default`) is auto-created on the host if missing; `browser_switch_profile` changes identity at runtime. `browser_exit_ip` returns the live exit IP + geo health (`kind`, `tzMismatch`); `browser_rotate_proxy` draws a fresh sticky IP and re-syncs the fingerprint — the host carries standing login `instructions` so clients follow the residential-IP → health-check → one-attempt-per-IP recipe automatically.
 
 ## Status
 

package/bin/junso-browser.js

@@ -18,9 +18,19 @@ if (cmd === "version" || cmd === "--version" || cmd === "-v") {
   console.log(require(path.join(root, "package.json")).version);
 } else if (cmd === "mcp") {
   await import(path.join(root, "dist", "mcp.js")); // also available as `junso-browser-mcp`
+} else if (cmd === "setup" || cmd === "install") {
+  // Run the installer (Chromium libs, cloak prefetch, token, optional systemd) against
+  // THIS already-installed package. Forwards flags, e.g. `junso-browser setup --systemd
+  // --host 0.0.0.0 --public-url ws://IP:8790`. See scripts/install.sh for flags.
+  const script = path.join(root, "scripts", "install.sh");
+  const proc = Bun.spawn(["bash", script, "--no-install", ...process.argv.slice(3)], {
+    cwd: root,
+    stdio: ["inherit", "inherit", "inherit"],
+  });
+  process.exit(await proc.exited);
 } else if (cmd === "start" || cmd === undefined) {
   await import(path.join(root, "dist", "server.js"));
 } else {
-  console.error(`Unknown command: ${cmd}\nUsage: junso-browser [start|mcp|version]`);
+  console.error(`Unknown command: ${cmd}\nUsage: junso-browser [start|mcp|setup|version]`);
   process.exit(1);
 }