@vibebrowser/mcp 0.2.4 → 0.2.5

package/docs/chrome-devtools-relay.md

@@ -0,0 +1,351 @@
+# Chrome DevTools Relay — System Design
+
+## Problem
+
+Cloud AI agents (OpenClaw tenants, coding assistants, automation pipelines) need to
+control a user's **local Chrome browser** — the one with their cookies, bookmarks,
+logged-in sessions, and extensions. Today this requires the agent and browser to
+be on the same machine or network.
+
+The user's browser is behind NAT, on a laptop, on a home network. The agent runs
+in a cloud Kubernetes pod. There is no direct path.
+
+## Solution
+
+A **secure relay** that bridges the gap:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                         CLOUD                                    │
+│                                                                  │
+│  ┌─────────────────────┐        ┌──────────────────────────┐     │
+│  │  OpenClaw Skill      │        │  Vibe Relay Backend       │     │
+│  │  (or any REST caller)│──POST─▶│  relay.vibebrowser.com    │     │
+│  │                      │◀─resp──│                          │     │
+│  │  Authorization:      │        │  • authenticates bearer   │     │
+│  │  Bearer <token>      │        │  • routes by browser_uuid │     │
+│  └─────────────────────┘        │  • queues tool calls      │     │
+│                                  │  • returns results        │     │
+│                                  └────────────┬─────────────┘     │
+│                                               │                   │
+└───────────────────────────────────────────────│───────────────────┘
+                                                │ WSS (outbound
+                                                │  from user machine)
+┌───────────────────────────────────────────────│───────────────────┐
+│                        USER MACHINE           │                   │
+│                                               ▼                   │
+│  ┌────────────────────────────────────────────────────────────┐   │
+│  │  Relay Client (local process)                              │   │
+│  │  • connects outbound to wss://relay.vibebrowser.com        │   │
+│  │  • registers browser_uuid                                  │   │
+│  │  • receives tool calls from relay                          │   │
+│  │  • executes them via chrome-devtools-mcp tools             │   │
+│  │  • returns results through relay                           │   │
+│  └──────────────────────────┬─────────────────────────────────┘   │
+│                             │ CDP (localhost:9222)                 │
+│                             ▼                                     │
+│  ┌────────────────────────────────────────────────────────────┐   │
+│  │  Chrome (user's browser)                                   │   │
+│  │  --remote-debugging-port=9222                              │   │
+│  │  User's cookies, sessions, extensions, bookmarks           │   │
+│  └────────────────────────────────────────────────────────────┘   │
+│                                                                   │
+└───────────────────────────────────────────────────────────────────┘
+```
+
+### Key properties
+
+- **No inbound ports** on the user's machine. The relay client connects outbound.
+- **Bearer token auth** on every cloud API call. The browser UUID alone is not a secret.
+- **Full chrome-devtools-mcp toolset** — 27 tools: click, fill, navigate, screenshot,
+  snapshot, network interception, performance tracing, Lighthouse, etc.
+- **User stays in control** — they start/stop the relay client, they see their browser.
+- **Works with any cloud caller** — OpenClaw skills, CI pipelines, REST scripts.
+
+---
+
+## Components
+
+### 1. Relay Client (this repo, forked from chrome-devtools-mcp)
+
+A local CLI process the user runs. Based on a fork of
+[chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp)
+(Apache 2.0, by Google/ChromeDevTools team).
+
+**What chrome-devtools-mcp already provides:**
+
+- 27 browser automation tools (input, navigation, emulation, performance,
+  network, console, debugging, Lighthouse)
+- Puppeteer-based Chrome control via CDP
+- Connection to running Chrome via `--browser-url` or `--autoConnect`
+- WebSocket endpoint connection with custom headers
+- Slim mode (3 tools) for basic tasks
+- Requires Node.js v20.19+, Chrome stable+
+
+**What we add:**
+
+- Outbound WebSocket connection to cloud relay
+- Tool call receive/execute/respond loop
+- Auth handshake (browser_uuid + access_token)
+- Reconnection with backoff
+- Local config persistence (~/.vibe-relay/)
+
+**CLI interface:**
+
+```bash
+# First time: authenticate
+vibe-relay login --token <access_token>
+
+# Connect to relay (browser must be running with --remote-debugging-port)
+vibe-relay connect
+
+# Or with explicit browser URL
+vibe-relay connect --browser-url http://localhost:9222
+
+# Check status
+vibe-relay status
+```
+
+### 2. Vibe Relay Backend (cloud service)
+
+Stateless relay that authenticates callers and routes tool calls to connected
+browser sessions.
+
+**API endpoints:**
+
+```
+GET  /v1/browser-sessions/:uuid/status
+     → { connected: bool, tools: string[], connectedAt: ISO8601 }
+
+GET  /v1/browser-sessions/:uuid/tools
+     → { tools: [ { name, description, inputSchema } ] }
+
+POST /v1/browser-sessions/:uuid/tools/:toolName
+     → { result: ... }
+     Body: { arguments: { ... } }
+
+All require: Authorization: Bearer <token>
+```
+
+**Responsibilities:**
+
+- Validate bearer tokens (scope: user, session, optional tenant/workspace)
+- Maintain WebSocket connections to relay clients
+- Queue tool call requests, match to responses
+- Timeout handling (30s default, configurable)
+- Rate limiting per token
+
+**Not responsible for:**
+
+- Executing any browser commands (that's the relay client)
+- Storing browser state or screenshots
+- Managing Chrome processes
+
+### 3. OpenClaw Integration (skill + config)
+
+OpenClaw does not speak MCP. It uses skills that call CLI tools or REST APIs.
+
+**Skill definition:**
+
+```yaml
+name: vibe-browser
+description: Control the user's local Chrome browser through Vibe relay
+tools:
+  - navigate_page
+  - take_snapshot
+  - take_screenshot
+  - click
+  - fill
+  - press_key
+  - evaluate_script
+  - list_network_requests
+  - get_network_request
+  - lighthouse_audit
+  # ... all 27 chrome-devtools-mcp tools
+```
+
+Each tool in the skill calls the relay REST API:
+
+```bash
+curl -X POST \
+  -H "Authorization: Bearer $VIBE_ACCESS_TOKEN" \
+  -H "Content-Type: application/json" \
+  "https://relay.vibebrowser.com/v1/browser-sessions/$BROWSER_UUID/tools/navigate_page" \
+  -d '{"arguments": {"url": "https://example.com", "type": "url"}}'
+```
+
+---
+
+## Security Model
+
+### Identifiers vs Secrets
+
+| Value          | Purpose                        | Secret? | Rotatable? |
+|----------------|--------------------------------|---------|------------|
+| browser_uuid   | Identifies which browser       | No      | Yes        |
+| access_token   | Proves caller is authorized    | Yes     | Yes        |
+
+### Token Scoping
+
+Access tokens are scoped to:
+
+- **User** — which user owns this token
+- **Session** (optional) — which browser session(s) it can access
+- **Tenant/Workspace** (optional) — for multi-tenant scenarios
+- **Expiration** — TTL, default 24h
+- **Permissions** (future) — which tools are allowed
+
+### Auth Flow
+
+```
+1. User generates access_token via Vibe dashboard or CLI
+2. User starts relay client with token (stored in ~/.vibe-relay/config.json)
+3. Relay client connects to cloud relay, sends { browser_uuid, access_token }
+4. Cloud relay validates token, registers session
+5. Cloud caller (OpenClaw) sends tool call with Authorization: Bearer <token>
+6. Cloud relay validates caller's token, checks session access, forwards to client
+7. Client executes tool locally, returns result through relay
+```
+
+### Threat Model
+
+| Threat                           | Mitigation                                     |
+|----------------------------------|-------------------------------------------------|
+| Stolen browser_uuid              | UUID alone grants nothing; need valid token      |
+| Stolen access_token              | Scoped + expiring; revocable via dashboard       |
+| MITM on relay connection         | WSS (TLS) for client↔relay; HTTPS for API calls |
+| Relay client compromise          | Runs as user process; same trust as the browser  |
+| Cloud relay compromise           | No browser access stored; just routing + auth    |
+| Unauthorized tool execution      | Token scope + optional tool allowlists           |
+
+---
+
+## Why Not Other Approaches
+
+### Why not HTTP MCP bridge on vibebrowser-mcp?
+
+We explored adding `--transport http` to vibebrowser-mcp to expose a URL-addressable MCP
+endpoint. This doesn't work for OpenClaw because:
+
+1. **OpenClaw doesn't speak MCP** — it calls CLI tools and REST APIs from skills.
+2. **MCP HTTP still requires a reachable endpoint** — the user's machine is behind
+   NAT, so a localhost MCP server isn't reachable from cloud.
+3. **It solves the wrong problem** — the issue isn't MCP vs HTTP, it's
+   cloud-to-local connectivity.
+
+### Why not CDP shim over Vibe browser extension?
+
+The Vibe browser extension (`chrome.debugger` API) only exposes a restricted
+subset of CDP domains:
+
+- **Missing:** `Browser.*`, `SystemInfo.*`, `Security.*`, `ServiceWorker.*`,
+  `HeapProfiler`, `Memory`, `LayerTree`, `Media`
+- **Conflict:** Opening Chrome DevTools terminates the extension's debugger session
+- **Limited:** No `Browser.getWindowForTarget`, no full network interception
+
+The chrome-devtools-mcp approach via Puppeteer/CDP gives full access to all
+Chrome DevTools Protocol domains.
+
+### Why not tunnel/ngrok?
+
+- Requires the user to install and configure a separate tunneling tool
+- Exposes a raw CDP endpoint to the internet (massive attack surface)
+- No built-in auth, rate limiting, or tool-level access control
+- CDP is designed for localhost trust, not internet exposure
+
+### Why fork chrome-devtools-mcp instead of building from scratch?
+
+- **27 production-tested tools** with proper error handling and edge cases
+- **Apache 2.0 license** — fork-friendly, no copyleft concerns
+- **Active maintenance** by Google/ChromeDevTools team
+- **Puppeteer integration** — handles Chrome lifecycle, reconnection, tab management
+- We only need to add the relay transport layer; the tool implementations stay as-is
+
+---
+
+## Data Flow: Tool Execution
+
+```
+OpenClaw skill                    Cloud Relay                     Relay Client              Chrome
+     │                                │                               │                      │
+     │  POST /tools/take_snapshot     │                               │                      │
+     │  Authorization: Bearer xxx     │                               │                      │
+     │ ──────────────────────────────▶│                               │                      │
+     │                                │  validate token               │                      │
+     │                                │  lookup browser session       │                      │
+     │                                │                               │                      │
+     │                                │  WS: { call: take_snapshot }  │                      │
+     │                                │ ─────────────────────────────▶│                      │
+     │                                │                               │  CDP: getDocument    │
+     │                                │                               │ ────────────────────▶│
+     │                                │                               │                      │
+     │                                │                               │  CDP: a11y snapshot  │
+     │                                │                               │◀────────────────────│
+     │                                │                               │                      │
+     │                                │  WS: { result: snapshot }     │                      │
+     │                                │◀─────────────────────────────│                      │
+     │                                │                               │                      │
+     │  200 { result: snapshot }      │                               │                      │
+     │◀──────────────────────────────│                               │                      │
+     │                                │                               │                      │
+```
+
+---
+
+## Implementation Plan
+
+### Phase 1: Relay Client (fork + relay layer)
+
+1. Fork `chrome-devtools-mcp` → `vibe-relay-client`
+2. Add WebSocket client that connects outbound to relay backend
+3. Implement tool call receive → execute → respond loop
+4. Add `login`, `connect`, `status` CLI commands
+5. Add config persistence (~/.vibe-relay/)
+6. Test locally with a mock relay server
+
+### Phase 2: Relay Backend (cloud service)
+
+1. Minimal relay server (Node.js/Bun, deployable to Fly.io or AKS)
+2. WebSocket handler for relay client connections
+3. REST API for tool calls with bearer auth
+4. Token validation + session management
+5. Timeout + error handling
+6. Deploy behind `relay.vibebrowser.com`
+
+### Phase 3: OpenClaw Skill
+
+1. Write skill that wraps relay REST API calls
+2. Include setup instructions (install relay client, get token, connect)
+3. Test with real OpenClaw tenant
+4. Ship in OpenClawBot repo or as standalone installable skill
+
+### Phase 4: Polish
+
+1. Dashboard UI for token management
+2. Session monitoring (connected browsers, active tools)
+3. Tool-level permissions
+4. Usage analytics
+5. Documentation site / blog post
+
+---
+
+## Open Questions
+
+1. **Relay backend hosting** — Fly.io (simple, edge-deployed) vs AKS sidecar
+   (co-located with OpenClaw tenants, lower latency)?
+2. **Binary vs screenshot transport** — should screenshots go through the relay
+   as base64, or should the relay client upload to object storage and return a URL?
+3. **Multi-tab support** — should one relay client session expose all Chrome tabs,
+   or should users explicitly attach to specific tabs?
+4. **Extension integration** — should the Vibe browser extension be able to act
+   as a relay client directly (no separate process)?
+
+---
+
+## References
+
+- [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) — base for relay client
+- [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) — CDP spec
+- [Puppeteer](https://pptr.dev/) — Chrome automation library used by chrome-devtools-mcp
+- [OpenClaw Skills](https://github.com/openclaw/openclaw) — skill system documentation
+- [Vibe Browser Extension](https://github.com/AnomalyCo/AnomalyBrowser) — existing Vibe browser tools

package/docs/eval.md

@@ -0,0 +1,209 @@
+# vibebrowser-mcp Evaluation Process
+
+This document tracks the current validation matrix for the `vibebrowser-mcp` and `vibebrowser-cli` binaries, with an explicit split between:
+
+- local workspace validation
+- packed package artifact validation (`npm pack`)
+- published npm validation (`@vibebrowser/mcp@latest`)
+- real-extension browser evals versus fake-extension protocol evals
+
+Evaluation date: **March 25, 2026 (America/Los_Angeles)**.
+
+## Coverage Matrix
+
+| Surface | Harness | Source Modes | Backend | What It Proves |
+|---|---|---|---|---|
+| Relay race regression | `npm run test:e2e:relay-race` | local | fake extension socket | relay preserves in-flight tool calls across extension reconnects |
+| HTTP MCP transport | `npm run test:e2e:http` | local | fake extension socket | streamable HTTP MCP path works end to end |
+| OpenClaw-compatible browser CLI | `npm run test:e2e:browser-cli` | `local`, `pack`, `npm` | fake extension socket | `vibebrowser-cli` command shape, JSON output, and tool routing work end to end |
+| Codex + OpenCode MCP bridge | `npm run test:e2e:agents` | `local`, `pack`, `npm` | real extension session | packaged `vibebrowser-mcp` can be launched by Codex/OpenCode tooling and route MCP traffic to a real Vibe-connected browser |
+| OpenCode financial eval (`../vibe`) | `node tests/mcp-eval.test.js --skip-build --model github-copilot/gpt-4.1 --mcp-source ...` | `auto`, `local`, `pack`, `npm` | harness-managed browser + extension | full OpenCode browser task execution against the Vibe extension |
+
+Important scope note:
+- There is **not yet** a full hosted OpenClaw runtime eval in this repo.
+- Current OpenClaw coverage is the **OpenClaw-compatible CLI surface** (`vibebrowser-cli`) plus the `openclaw` helper and HTTP bridge docs.
+- Do not claim full hosted OpenClaw runtime parity based only on the CLI test.
+
+## Source Selectors
+
+### Browser CLI harness
+
+`scripts/e2e-browser-cli.mjs` now supports:
+
+- `E2E_BROWSER_CLI_SOURCE=local`
+- `E2E_BROWSER_CLI_SOURCE=pack`
+- `E2E_BROWSER_CLI_SOURCE=npm`
+
+Optional override:
+
+- `E2E_BROWSER_CLI_PACKAGE=/absolute/or/relative/path/to/package.tgz`
+
+`pack` mode creates a temporary tarball with `npm pack --json --pack-destination ...` and runs:
+
+```bash
+npx -y --package <local-tarball> vibebrowser-cli ...
+```
+
+### MCP agent harness
+
+`scripts/e2e-mcp-agents.mjs` now supports:
+
+- `E2E_MCP_SOURCE=local`
+- `E2E_MCP_SOURCE=pack`
+- `E2E_MCP_SOURCE=npm`
+
+Optional override:
+
+- `E2E_MCP_PACKAGE=/absolute/or/relative/path/to/package.tgz`
+
+`pack` mode creates a temporary tarball and runs:
+
+```bash
+npx -y --package <local-tarball> vibebrowser-mcp ...
+```
+
+### Cross-repo OpenCode eval
+
+`../vibe/tests/mcp-eval.test.js` now accepts:
+
+- `--mcp-source auto`
+- `--mcp-source local`
+- `--mcp-source pack`
+- `--mcp-source npm`
+- `--mcp-package <tarball-or-package-spec>`
+
+Use `--mcp-source pack` when validating a release candidate before publish.
+
+## Required Commands
+
+### 1. Local regression suite
+
+```bash
+cd /Users/engineer/workspace/vibebrowser/vibe-mcp
+npm run build
+npm test
+```
+
+Pass signal:
+
+- `npm test` exits `0`
+- output contains:
+  - `e2e ok`
+  - `http e2e ok`
+  - `browser cli e2e ok`
+
+### 2. Packaged CLI artifact validation
+
+```bash
+cd /Users/engineer/workspace/vibebrowser/vibe-mcp
+E2E_BROWSER_CLI_SOURCE=pack node scripts/e2e-browser-cli.mjs
+```
+
+Pass signal:
+
+- output contains `browser cli e2e ok`
+- `vibebrowser-cli` is installed from a `.tgz` package artifact, not from the workspace
+
+### 3. Packaged binary smoke check
+
+```bash
+cd /Users/engineer/workspace/vibebrowser/vibe-mcp
+TMP_DIR="$(mktemp -d)"
+npm pack --json --pack-destination "$TMP_DIR"
+npx -y --package "$TMP_DIR"/vibebrowser-mcp-*.tgz vibebrowser-mcp --help
+npx -y --package "$TMP_DIR"/vibebrowser-mcp-*.tgz vibebrowser-cli --help
+```
+
+Pass signal:
+
+- `vibebrowser-mcp --help` prints the branded CLI
+- `vibebrowser-cli --help` prints the standalone OpenClaw-compatible CLI
+
+### 4. Real-extension agent eval
+
+```bash
+cd /Users/engineer/workspace/vibebrowser/vibe-mcp
+E2E_MCP_SOURCE=pack node scripts/e2e-mcp-agents.mjs
+```
+
+Pass signal:
+
+- output contains `e2e ok`
+- Codex uses `vibe-browser.*` tools
+- OpenCode can resolve the same MCP config and report `vibe-browser connected`
+
+Hard requirement:
+
+- a live Vibe extension session must already be connected or connectable on the relay path
+- this harness does **not** prove anything if the extension is absent
+
+### 5. Full OpenCode browser eval in sibling repo
+
+```bash
+cd /Users/engineer/workspace/vibebrowser/vibe
+node tests/mcp-eval.test.js --skip-build --model github-copilot/gpt-4.1 --mcp-source pack
+```
+
+Pass criteria:
+
+- `MCP External enabled: PASS`
+- `Relay connected: PASS`
+- `MCP tools used: PASS`
+- `Tickers found: 6/6`
+- process exits `0`
+
+Note:
+
+- this harness launches its own browser test environment from the `vibe` repo
+- use it when you explicitly want the full browser-task eval, not just package smoke coverage
+
+## Latest Verification Snapshot
+
+Commands executed in this session:
+
+| Command | Result | Notes |
+|---|---|---|
+| `npm run build` | PASS | local TypeScript build succeeded |
+| `npm test` | PASS | relay race, HTTP, and local browser CLI e2e all passed |
+| `E2E_BROWSER_CLI_SOURCE=pack node scripts/e2e-browser-cli.mjs` | PASS | tarball-installed `vibebrowser-cli` passed end to end |
+| `npm pack --json --pack-destination <tmp>` | PASS | tarball includes both `dist/cli.js` and `dist/browser-main.js` plus docs/openclaw skill files |
+| `npx -y --package <local-tarball> vibebrowser-mcp --help` | PASS | branded `vibebrowser-mcp` binary available from package artifact |
+| `npx -y --package <local-tarball> vibebrowser-cli --help` | PASS | standalone `vibebrowser-cli` binary available from package artifact |
+| `E2E_MCP_SOURCE=pack node scripts/e2e-mcp-agents.mjs` | FAIL (environment) | timed out waiting for a live Vibe extension connection on the relay path |
+| `npx -y --package @vibebrowser/mcp@latest vibebrowser-mcp --help` | PASS, but stale | published npm has the `vibebrowser-mcp` alias, but not the full new standalone CLI release shape |
+| `npx -y --package @vibebrowser/mcp@latest vibebrowser-cli --help` | FAIL | `vibebrowser-cli` is not present in the current npm `latest` release |
+| `npm whoami` | FAIL | `ENEEDAUTH`; publish from this machine is currently blocked |
+
+Observed real-extension agent failure:
+
+```text
+Error: Extension did not connect to relay within 120000ms. Ensure Vibe extension has MCP External enabled in the active Chrome profile.
+```
+
+Interpretation:
+
+- packaged artifacts are valid locally
+- the standalone CLI branding and binaries are correct in the tarball
+- published npm `latest` is **not yet** updated to the new branded binaries
+- real-agent validation currently depends on a live extension session and was not satisfiable in this shell session
+
+## Publish Reality
+
+Current npm state:
+
+- `npm view @vibebrowser/mcp version dist-tags.latest --json` returned `0.2.4`
+- `@latest` still resolves to a partial older package surface
+- `npm whoami` failed with `ENEEDAUTH`
+
+Consequences:
+
+- the new `vibebrowser-mcp` / `vibebrowser-cli` binaries are verified in a local tarball artifact
+- they are **not yet published** to npm from this machine
+- do not claim npm end-to-end availability until:
+  - a new version is cut
+  - publish auth is configured
+  - `npx -y --package @vibebrowser/mcp@<new-version> vibebrowser-cli --help` succeeds
+
+## Tracking
+
+- Tracking issue: `VibeTechnologies/vibe-mcp#22`