@vibebrowser/mcp 0.2.4 → 0.2.6

package/docs/eval.md

@@ -0,0 +1,294 @@
+# 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 26, 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 |
+| Live browser CLI regression | `npm run test:e2e:browser-cli-live` | local | real extension session | validates `open`/`snapshot` behavior on a real URL against the connected Vibe extension |
+| 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. Published npm CLI validation
+
+```bash
+cd /Users/engineer/workspace/vibebrowser/vibe-mcp
+npx -y --package @vibebrowser/mcp@latest vibebrowser-mcp --version
+npx -y --package @vibebrowser/mcp@latest vibe-mcp --version
+npx -y --package @vibebrowser/mcp@latest vibebrowser-cli --version
+E2E_BROWSER_CLI_SOURCE=npm node scripts/e2e-browser-cli.mjs
+```
+
+Pass signal:
+
+- all three binaries print the published version
+- `browser cli e2e ok` proves `vibebrowser-cli` works from the npm registry package, not only from a local tarball
+
+### 5. 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
+- default Codex settings are tuned for current CLI compatibility:
+  - `E2E_CODEX_MODEL=gpt-5`
+  - `E2E_CODEX_REASONING_EFFORT=low`
+  - `E2E_CODEX_TIMEOUT_MS=480000`
+
+### 5a. Live browser CLI regression (real extension)
+
+```bash
+cd /Users/engineer/workspace/vibebrowser/vibe-mcp
+npm run test:e2e:browser-cli-live
+```
+
+Optional env overrides:
+
+- `BROWSER_LIVE_URL` (default: X search URL from issue repro)
+- `BROWSER_LIVE_TIMEOUT_MS` (default: `60000`)
+- `BROWSER_LIVE_MIN_CONTENT_CHARS` (default: `200`)
+
+Pass signal:
+
+- output contains `live browser cli e2e ok`
+- output prints measured `open latency`, content lengths, and matched `pageId`
+- test proves real-extension `open` + page-content + `snapshot --page-id` flow (not mocked)
+
+### 5b. Latest built extension eval via Chrome for Testing
+
+Build the dev extension first:
+
+```bash
+cd /Users/engineer/workspace/vibebrowser/vibe
+npm run build:extension:dev
+```
+
+Use the direct script form when debugging the isolated path, especially from a detached worktree where `../vibe` discovery may not point at the intended sibling repo:
+
+```bash
+cd /Users/engineer/workspace/vibebrowser/vibe-mcp
+E2E_DEBUG=1 \
+E2E_TEST_BROWSER=1 \
+E2E_VIBE_REPO_ROOT=/Users/engineer/workspace/vibebrowser/vibe \
+E2E_TEST_EXTENSION_PATH=/Users/engineer/workspace/vibebrowser/vibe/dist/extension/dev \
+E2E_MCP_SOURCE=npm \
+node scripts/e2e-mcp-agents.mjs
+```
+
+Use the package-script entrypoint for the canonical repo-level check:
+
+```bash
+cd /Users/engineer/workspace/vibebrowser/vibe-mcp
+E2E_TEST_BROWSER=1 \
+E2E_VIBE_REPO_ROOT=/Users/engineer/workspace/vibebrowser/vibe \
+E2E_TEST_EXTENSION_PATH=/Users/engineer/workspace/vibebrowser/vibe/dist/extension/dev \
+E2E_MCP_SOURCE=npm \
+npm run test:e2e:agents
+```
+
+Pass signal:
+
+- output contains `e2e ok`
+- the eval launches a separate Chrome for Testing instance
+- the loaded extension comes from `../vibe/dist/extension/dev`, not the user’s daily Chrome profile
+
+### 6. 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 |
+| `gh workflow run "Publish to npm" --ref release/vibebrowser-cli-0.2.5` | PASS | GitHub publish workflow completed successfully |
+| `npm view @vibebrowser/mcp version dist-tags.latest bin --json` | PASS | npm `latest` is now `0.2.5` and includes `vibebrowser-mcp`, `vibe-mcp`, and `vibebrowser-cli` |
+| `npx -y --package @vibebrowser/mcp@latest vibebrowser-mcp --version` | PASS | published npm binary resolves to `0.2.5` |
+| `npx -y --package @vibebrowser/mcp@latest vibe-mcp --version` | PASS | legacy alias still resolves to `0.2.5` |
+| `npm run test:e2e:agents` | PASS | local `dist/cli.js` path completed all three MiniWoB tasks with Codex + OpenCode against the live extension session |
+| `E2E_MCP_SOURCE=npm npm run test:e2e:agents` | PASS | published npm binary path completed the same three MiniWoB tasks end to end |
+| `E2E_DEBUG=1 E2E_TEST_BROWSER=1 E2E_VIBE_REPO_ROOT=/Users/engineer/workspace/vibebrowser/vibe E2E_TEST_EXTENSION_PATH=/Users/engineer/workspace/vibebrowser/vibe/dist/extension/dev E2E_MCP_SOURCE=npm node scripts/e2e-mcp-agents.mjs` | PASS | debug run against a separate Chrome for Testing instance with the unpacked extension build |
+| `E2E_TEST_BROWSER=1 E2E_VIBE_REPO_ROOT=/Users/engineer/workspace/vibebrowser/vibe E2E_TEST_EXTENSION_PATH=/Users/engineer/workspace/vibebrowser/vibe/dist/extension/dev E2E_MCP_SOURCE=npm npm run test:e2e:agents` | PASS | canonical repo entrypoint passed against the latest built extension in isolated browser mode |
+| `npx -y --package @vibebrowser/mcp@latest vibebrowser-cli --version` | PASS | standalone CLI is now available from npm `latest` |
+| `E2E_BROWSER_CLI_SOURCE=npm node scripts/e2e-browser-cli.mjs` | PASS | npm-installed `vibebrowser-cli` passed end to end |
+| `npm run test:e2e:browser-cli-live` | PASS | real extension run against X search URL; reported open latency `60718ms`, open content `9119` chars, snapshot content `9564` chars |
+| `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 |
+
+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 now updated to `0.2.5` with all intended 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 bin --json` returns `0.2.5`
+- `@latest` now includes:
+  - `vibebrowser-mcp`
+  - `vibe-mcp`
+  - `vibebrowser-cli`
+- publish succeeded via GitHub Actions workflow `Publish to npm`
+
+Consequences:
+
+- the new `vibebrowser-mcp` / `vibebrowser-cli` binaries are published to npm and verified from the registry
+- the remaining non-green item is the real-extension agent eval, which still requires a live Vibe extension session on the relay path
+
+## Tracking
+
+- Tracking issue: `VibeTechnologies/vibe-mcp#22`
+- Release PR: `VibeTechnologies/vibe-mcp#23`

package/docs/openclaw-local-browser.md

@@ -0,0 +1,264 @@
+---
+title: "Use Vibe Co-Pilot to Let Cloud OpenClaw Control Your Local Browser"
+description: "How to connect a cloud OpenClaw agent to a user's local browser with the Vibe Co-Pilot extension, remote relay mode, and the new vibebrowser-mcp HTTP bridge."
+date: "2026-03-15"
+author: "Dzianis Vashchuk"
+published: true
+---
+
+If you are running OpenClaw in the cloud, one of the most useful upgrades is giving it access to a real browser.
+
+But there are actually two different browser problems hiding inside that sentence:
+
+- **tenant browser**: a browser that lives inside the hosted OpenClaw runtime
+- **local browser**: the user's actual Chrome or Chromium profile on their own machine
+
+Those are not the same product problem, and they should not use the same architecture.
+
+For the tenant browser, the right answer is still the hosted browser stack inside the tenant.
+
+For the user's local browser, the right answer is the Vibe Co-Pilot extension plus `vibebrowser-mcp` in remote relay mode.
+
+That is what this setup enables.
+
+## The architecture that works
+
+The flow looks like this:
+
+```text
+Cloud OpenClaw agent
+        |
+        | MCP over HTTP
+        v
+  local vibebrowser-mcp bridge
+        |
+        | secure outbound relay connection
+        v
+   Vibe remote relay
+        |
+        v
+Vibe Co-Pilot browser extension
+        |
+        v
+User's local Chrome / Chromium browser
+```
+
+The important point is that the browser still stays on the user's machine.
+
+The cloud runtime does not need direct access to the user's laptop, an exposed CDP port, or a custom reverse tunnel into Chrome. The Vibe extension connects outward to the relay, and `vibebrowser-mcp` exposes a local MCP HTTP endpoint that OpenClaw can attach to.
+
+## Why we added HTTP mode to `vibebrowser-mcp`
+
+Before this change, `vibebrowser-mcp` worked well for local MCP clients such as Claude Desktop, Cursor, OpenCode, and VS Code because they can launch an MCP server over stdio.
+
+Cloud OpenClaw is different.
+
+In OpenClawBot and similar hosted deployments, MCP servers are configured as URLs. That means a stdio-only MCP bridge is not enough. We needed `vibebrowser-mcp` to expose a proper network MCP endpoint.
+
+So the missing piece was a streamable HTTP MCP transport.
+
+That is what `vibebrowser-mcp start --transport http` now provides.
+
+## Prerequisites
+
+You need:
+
+1. **Node.js 18+** - `vibebrowser-mcp` requires Node.js
+2. **Chrome/Brave/Chromium** with the Vibe extension installed
+3. **OpenClaw** configured with an MCP server URL
+
+## What gets installed
+
+The user needs three pieces:
+
+1. the Vibe Co-Pilot browser extension
+2. `vibebrowser-mcp` on the same machine as the browser
+3. an OpenClaw MCP server entry pointing to the local `vibebrowser-mcp` HTTP endpoint
+
+## Step 1: Install the Vibe extension
+
+1. Install the Vibe Co-Pilot extension from [Chrome Web Store](https://chromewebstore.google.com/detail/vibe-ai-browser-co-pilot/djodpgokbmobeclicaicnnidccoinado)
+2. Open Chrome and click the Vibe extension icon
+3. Go to **Settings** (gear icon)
+4. Find **MCP External** (or "MCP External Control")
+5. Enable it and select **Remote** mode
+6. Copy the **Extension UUID** shown - you'll need this for the next step
+
+> **Note**: The Extension UUID is a unique identifier that allows `vibebrowser-mcp` to connect to your specific browser session through the Vibe relay.
+
+## Step 2: Start the local HTTP bridge
+
+On the same machine where the browser extension is installed, run:
+
+**Option A: Using the helper command (recommended)**
+
+```bash
+npx -y --package @vibebrowser/mcp vibebrowser-mcp openclaw --remote <extension-uuid>
+```
+
+This prints the exact commands and MCP URL you need.
+
+**Option B: Manual command**
+
+```bash
+npx -y --package @vibebrowser/mcp vibebrowser-mcp start --transport http --remote <extension-uuid>
+```
+
+By default this starts a local MCP endpoint at:
+
+```
+http://127.0.0.1:8788/mcp
+```
+
+Keep this terminal open - the bridge must stay running for OpenClaw to connect.
+
+For operator workflows and OpenClaw skills, you can also use the OpenClaw-compatible browser CLI surface directly:
+
+```bash
+npx -y --package @vibebrowser/mcp vibebrowser-cli sessions
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote <extension-uuid> status
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote <extension-uuid> tabs
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote <extension-uuid> snapshot --json
+```
+
+`snapshot` in `vibebrowser-cli` is tool-only and maps directly to extension snapshot tools:
+
+- default (`--format ai`) -> `take_md_snapshot`
+- ARIA (`--format aria`) -> `take_a11y_snapshot`
+
+Use `--page-id <id>` (or `--pageId <id>`) to target a specific tab without switching user focus.
+
+For local relay mode with multiple connected browsers/profiles:
+
+- run `vibebrowser-cli sessions` to list available local session IDs
+- pass `--session <id>` to target one explicitly
+- if omitted, the CLI uses the first connected local session
+
+`open` and `navigate` responses include extracted page content in JSON output (`pageContent`) when page state is modified, so agents can continue without an immediate extra snapshot call.
+
+That CLI accepts the same style of verbs and flags OpenClaw operators expect, but it still targets the Vibe real-browser path rather than an isolated OpenClaw-managed browser profile.
+
+## Step 3: add the MCP server to OpenClaw
+
+Register the bridge URL in OpenClaw:
+
+```json
+{
+  "mcpServers": {
+    "vibe": {
+      "url": "http://127.0.0.1:8788/mcp"
+    }
+  }
+}
+```
+
+Once that is configured, the cloud OpenClaw agent can use the Vibe browser tools through the local bridge.
+
+## Optional: Use the OpenClaw skill for local agents
+
+For OpenClaw agents running locally (not in the cloud) that need access to your real browser, you can use the Vibe skill instead of configuring an MCP server URL.
+
+### Install the skill
+
+Copy `openclaw/vibebrowser/SKILL.md` from this package to your OpenClaw skills directory. The skill provides OpenClaw-compatible CLI commands that target your Vibe-connected browser.
+
+### Configure environment
+
+Set the extension UUID in your shell:
+
+```bash
+export VIBE_EXTENSION_UUID="<your-extension-uuid>"
+```
+
+### Available commands
+
+```bash
+# Check status
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json status
+
+# List tabs
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json tabs
+
+# Open a page
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json open https://example.com
+
+# Click element by index
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json click 12
+
+# Type into element
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json type 23 "hello"
+```
+
+See [`openclaw/vibebrowser/SKILL.md`](../openclaw/vibebrowser/SKILL.md) for the full command reference.
+
+## When to use this setup
+
+This architecture is the right fit when the agent needs the **user's own browser context**, for example:
+
+- websites where the user is already logged in locally
+- workflows that depend on cookies or browser extensions
+- tasks on tabs the user already opened
+- browsing in the exact local profile the user uses every day
+
+## When not to use this setup
+
+Do **not** use this as a replacement for the hosted tenant browser.
+
+If the user wants a browser that lives inside the OpenClaw tenant itself, keep using the existing tenant browser stack. That remains the correct architecture for hosted cloud browsing because it is reproducible, self-contained, and lives entirely inside the tenant runtime.
+
+So the rule is simple:
+
+- **tenant browser in cloud** -> tenant `/browser` stack
+- **user's real local browser** -> Vibe extension + relay + `vibebrowser-mcp` HTTP bridge
+
+## Why this split matters
+
+Trying to force one model to solve both cases creates product confusion.
+
+The tenant browser is about a cloud runtime having its own browser environment.
+
+The Vibe extension path is about letting a cloud agent borrow the user's real browser safely and intentionally.
+
+They sound similar from the outside, but they optimize for different things:
+
+- tenant browser -> repeatability, isolation, hosted runtime control
+- local browser bridge -> real sessions, real profile, real user context
+
+That distinction is what made the implementation plan finally click.
+
+## What this unlocks
+
+With this bridge, OpenClaw users can keep the intelligence and orchestration in the cloud while still letting the agent act inside the browser they already use.
+
+That is a much better fit than asking users to move their life into a fresh cloud browser profile just to get browser automation.
+
+The end result is simple:
+
+**OpenClaw stays in the cloud. The browser stays local. Vibe MCP connects them cleanly.**
+
+## Troubleshooting
+
+### "Extension UUID not found"
+
+Make sure you've enabled **Remote** mode in the Vibe extension settings. The UUID only appears when Remote mode is active.
+
+### "Connection refused" errors
+
+1. Ensure the `vibebrowser-mcp` process is still running
+2. Check the terminal for error messages
+3. Verify the MCP URL matches exactly (including the `/mcp` path)
+
+### "No extension connected"
+
+1. Open Chrome and click the Vibe extension icon
+2. Verify MCP External is enabled in Settings
+3. Check the extension shows "Connected" status
+
+### MCP URL format
+
+The correct format is:
+```
+http://127.0.0.1:8788/mcp
+```
+
+Not `http://127.0.0.1:8788` (missing `/mcp` path).