@vibebrowser/mcp 0.2.5 → 0.2.6

package/docs/openclaw-local-browser.md

@@ -59,56 +59,83 @@ So the missing piece was a streamable HTTP MCP transport.
 
 That is what `vibebrowser-mcp start --transport http` now provides.
 
-## What to install
+## 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 at the local `vibebrowser-mcp` HTTP endpoint
-
-## Step 1: install the Vibe extension
+3. an OpenClaw MCP server entry pointing to the local `vibebrowser-mcp` HTTP endpoint
 
-Install the Vibe Co-Pilot extension from `https://vibebrowser.app`.
+## Step 1: Install the Vibe extension
 
-Then open the extension settings and enable `MCP External`.
+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
 
-For cloud OpenClaw, choose **Remote** mode and copy the **Extension UUID**.
+> **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
+## 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 start --transport http --remote <extension-uuid>
+npx -y --package @vibebrowser/mcp vibebrowser-mcp openclaw --remote <extension-uuid>
 ```
 
-By default this starts a local MCP endpoint at:
+This prints the exact commands and MCP URL you need.
 
-```text
-http://127.0.0.1:8788/mcp
-```
-
-If you want the exact OpenClaw-friendly snippet, you can also run:
+**Option B: Manual command**
 
 ```bash
-npx -y --package @vibebrowser/mcp vibebrowser-mcp openclaw --remote <extension-uuid>
+npx -y --package @vibebrowser/mcp vibebrowser-mcp start --transport http --remote <extension-uuid>
 ```
 
-That prints:
+By default this starts a local MCP endpoint at:
 
-- the bridge command
-- the MCP URL to register in OpenClaw
-- a JSON snippet you can paste into config
+```
+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
@@ -127,6 +154,43 @@ Register the bridge URL in OpenClaw:
 
 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:
@@ -171,3 +235,30 @@ That is a much better fit than asking users to move their life into a fresh clou
 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).

package/openclaw/{vibe-local-browser → vibebrowser}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: vibe-local-browser
+name: vibebrowser
 description: Control the user's local browser through the Vibe Browser CLI bridge. Use this when the task must run against the user's real Vibe-connected browser session, tabs, cookies, or installed extensions.
 metadata:
   {
@@ -17,6 +17,21 @@ metadata:
 
 # Vibe Local Browser
 
+## Installation
+
+1. **Get the Extension UUID**:
+   - Install the Vibe extension in Chrome
+   - Open extension Settings → MCP External
+   - Enable Remote mode and copy the Extension UUID
+
+2. **Set environment variable**:
+   ```bash
+   export VIBE_EXTENSION_UUID="<your-extension-uuid>"
+   ```
+
+3. **Install the skill**:
+   Copy this file to your OpenClaw skills directory (typically `~/.openclaw/skills/` or your project's `openclaw/skills/` folder).
+
 Use the `vibebrowser-cli` command when the user wants OpenClaw to drive their real local browser through the Vibe extension.
 
 Prefer this skill when the task depends on:
@@ -64,7 +79,13 @@ If you set `VIBE_RELAY_URL`, append:
 
 ## Safe operating rules
 
+- **Never use `focus` or `tab select` unless explicitly asked.** The user may be actively working in the browser — switching their active tab is disruptive. Instead, pass `--page-id <id>` (or `--pageId <id>`) to target a specific tab without switching focus. Get the page ID from `tabs` output, then use it on any command:
+  ```bash
+  vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json --page-id 2 snapshot
+  vibebrowser-cli --remote "$VIBE_EXTENSION_UUID" --json --page-id 2 click 7
+  ```
 - Prefer `browser tabs` or `browser snapshot` before acting.
+- `snapshot` is tool-only and maps to extension snapshot tools (`take_md_snapshot` by default, `take_a11y_snapshot` for `--format aria`).
 - Use `browser open <url>` to create a fresh page when possible.
 - Use `browser evaluate --fn ...` only for simple compatibility-safe expressions such as:
   - `() => 21 + 21`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibebrowser/mcp",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "type": "module",
   "description": "MCP server for browser automation - the only solution supporting multiple AI agents (Claude, Cursor, VS Code) simultaneously controlling your Chrome browser",
   "main": "dist/index.js",
@@ -18,10 +18,13 @@
     "dev": "tsc --watch",
     "start": "node dist/cli.js",
     "prepublishOnly": "npm run build",
-    "test": "npm run test:e2e:relay-race && npm run test:e2e:http && npm run test:e2e:browser-cli",
+    "test": "npm run test:e2e:relay-race && npm run test:e2e:relay-roundtrip && npm run test:e2e:cli-relay && npm run test:e2e:http && npm run test:e2e:browser-cli",
     "test:e2e:browser-cli": "node scripts/e2e-browser-cli.mjs",
+    "test:e2e:cli-relay": "node scripts/e2e-cli-relay.mjs",
     "test:e2e:http": "node scripts/e2e-http-streamable.mjs",
+    "test:e2e:browser-cli-live": "node scripts/e2e-browser-cli-live.mjs",
     "test:e2e:relay-race": "node scripts/e2e-relay-fake-extension-race.mjs",
+    "test:e2e:relay-roundtrip": "node scripts/e2e-relay-roundtrip.mjs",
     "test:e2e:agents": "node scripts/e2e-mcp-agents.mjs"
   },
   "keywords": [