@vibebrowser/mcp 0.2.5 → 0.2.7

package/README.md

@@ -47,6 +47,7 @@ Claude Desktop       Cursor          VS Code         OpenCode
 - **Fast & Local** - Automation happens on your machine, no cloud latency
 - **Private** - Your browsing data never leaves your device
 - **Stable** - Content script based, no flaky CDP connections
+- **Chrome DevTools Fallback** - Extension tools stay primary by default; use `--devtools` to force chrome-devtools-only mode
 
 ## Quick Start
 
@@ -210,6 +211,15 @@ Add to your Codex configuration:
 3. Go to Settings and enable "MCP External Control"
 4. The status should show "Connected"
 
+If the extension is not connected, `vibebrowser-mcp` can optionally fall back to
+`chrome-devtools-mcp` (started in `--autoConnect` mode) when that package is installed.
+This fallback runs once in the shared local relay daemon (multi-agent safe), so
+both `vibebrowser-mcp` and `vibebrowser-cli` use the same backend instance.
+When extension is connected, extension tools are authoritative. Chrome DevTools
+fallback tools are exposed only when extension is unavailable/disconnected.
+Pass `--devtools` to either CLI to bypass relay/extension routing and use only
+the chrome-devtools backend.
+
 ## Available Tools
 
 | Tool | Description |
@@ -266,6 +276,12 @@ npx -y --package @vibebrowser/mcp vibebrowser-mcp start --transport http --remot
 
 This exposes a local MCP endpoint at `http://127.0.0.1:8788/mcp` by default.
 
+When OpenClaw runs on a different machine (for example cloud-hosted), provide a reachable URL:
+
+```bash
+npx -y --package @vibebrowser/mcp vibebrowser-mcp openclaw --remote <extension-uuid> --public-url https://<reachable-host>/mcp
+```
+
 You can print the exact OpenClaw-friendly setup with:
 
 ```bash
@@ -279,12 +295,14 @@ For the full walkthrough, see `docs/openclaw-local-browser.md`.
 `vibebrowser-cli` mirrors the OpenClaw browser CLI shape for the real local-browser path:
 
 ```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> open https://example.com
 npx -y --package @vibebrowser/mcp vibebrowser-cli --remote <extension-uuid> snapshot
 npx -y --package @vibebrowser/mcp vibebrowser-cli --remote <extension-uuid> click 12
 npx -y --package @vibebrowser/mcp vibebrowser-cli --remote <extension-uuid> type 23 "hello" --submit
+npx -y --package @vibebrowser/mcp vibebrowser-cli --devtools status
 ```
 
 The package now exposes two executables:
@@ -294,6 +312,53 @@ The package now exposes two executables:
 
 `vibebrowser-cli` accepts the OpenClaw-style `--browser-profile` flag for compatibility and supports `--json` for machine-readable output. Unlike OpenClaw's managed `openclaw` browser profile, this CLI always targets the real Vibe-connected browser session.
 
+Local-session selection:
+
+- `vibebrowser-cli sessions` lists connected local browser sessions.
+- `vibebrowser-cli --session <id> ...` targets a specific local session.
+- If `--session` is omitted in local mode, the CLI uses the first connected session.
+- In remote mode, `--remote <extension-uuid>` remains the explicit browser selector.
+
+Snapshot behavior is tool-only (no legacy snapshot RPC shortcut):
+
+- `snapshot` (default, `--format ai`) resolves via `take_md_snapshot` — uses the content script's in-page markdown extractor. Fast and readable, but **may return empty for background tabs or complex SPAs** (Notion, Gmail) where the content script is unreachable or layout is not computed.
+- `snapshot --format aria` resolves via `take_a11y_snapshot` — uses Chrome DevTools Protocol `Accessibility.getFullAXTree` directly. **Reliable for all tabs including background tabs and SPAs.** Use this as a fallback when the default format returns empty or only a page title.
+
+This keeps CLI behavior aligned with extension-supported tools and ensures page targeting works consistently with `--page-id`/`--pageId`.
+
+For navigation-style operations, responses now include page content when page state changes:
+
+- CLI `open` / `navigate` include `pageContent` in JSON output.
+- MCP tool calls for navigation-style tools return text content that includes current page state (with snapshot fallback when needed).
+
+### OpenClaw Integration
+
+There are two ways to use Vibe with OpenClaw:
+
+**Option A: Cloud OpenClaw controlling local browser**
+
+If OpenClaw runs in the cloud but you want it to control your local browser:
+
+1. Install the Vibe extension and enable **Remote** mode (see [docs/openclaw-local-browser.md](docs/openclaw-local-browser.md))
+2. Start the local HTTP bridge: `vibebrowser-mcp openclaw --remote <extension-uuid> [--public-url <url>]`
+3. Register the MCP URL in OpenClaw
+
+**Option B: OpenClaw skill for local agents**
+
+For OpenClaw agents that need your real browser context (logged-in sessions, existing tabs):
+
+1. Copy the Vibe skill from this package to your OpenClaw skills folder
+2. Set `VIBE_EXTENSION_UUID` environment variable
+3. Use `vibebrowser-cli` commands in your agent prompts
+
+The skill is located at [`openclaw/vibebrowser/SKILL.md`](openclaw/vibebrowser/SKILL.md) and provides:
+- Full OpenClaw-compatible CLI commands (`status`, `tabs`, `snapshot`, `click`, `type`, etc.)
+- Fallback-safe commands for DevTools-backed flows (`resize`, `upload`, `dialog`)
+- `--json` output for machine parsing
+- Environment-based configuration
+
+See [docs/openclaw-local-browser.md](docs/openclaw-local-browser.md) for the complete walkthrough.
+
 ## Local LLM: `serve` Command
 
 Run a local LLM with one command — no cloud API keys required. Automatically installs [Ollama](https://ollama.com), downloads the model, and starts serving an OpenAI-compatible API.
@@ -355,17 +420,20 @@ npx -y --package @vibebrowser/mcp vibebrowser-mcp [start] [options]
   --http-path <path>   Path for streamable HTTP MCP transport (default: /mcp)
   --allow-host <host>  Allowed host header for HTTP transport (repeatable)
   -r, --remote <uuid>  Connect to a remote extension via public relay
+  --devtools           Use only chrome-devtools backend (bypasses extension relay)
   --relay-url <url>    Custom relay server URL
 
 # OpenClaw helper
-npx -y --package @vibebrowser/mcp vibebrowser-mcp openclaw --remote <extension-uuid>
+npx -y --package @vibebrowser/mcp vibebrowser-mcp openclaw --remote <extension-uuid> [--public-url <url>]
 
 # OpenClaw-compatible browser CLI
 npx -y --package @vibebrowser/mcp vibebrowser-cli --remote <extension-uuid> status
+npx -y --package @vibebrowser/mcp vibebrowser-cli --remote <extension-uuid> status --wait-for-extension --wait-timeout 10000
 npx -y --package @vibebrowser/mcp vibebrowser-cli --remote <extension-uuid> tabs
 npx -y --package @vibebrowser/mcp vibebrowser-cli --remote <extension-uuid> snapshot --json
 npx -y --package @vibebrowser/mcp vibebrowser-cli --remote <extension-uuid> click 12
 npx -y --package @vibebrowser/mcp vibebrowser-cli --remote <extension-uuid> type 23 "hello" --submit
+npx -y --package @vibebrowser/mcp vibebrowser-cli --devtools tabs
 
 # Local LLM server
 npx -y --package @vibebrowser/mcp vibebrowser-mcp serve <model> [options]
@@ -387,7 +455,7 @@ npx -y --package @vibebrowser/mcp vibebrowser-mcp serve <model> [options]
 1. Start `vibebrowser-mcp` in HTTP mode instead of stdio
 2. Make sure the bridge process is still running on the user's machine
 3. Confirm the extension is in `Remote` mode and connected
-4. Verify the MCP URL in OpenClaw matches the bridge URL, usually `http://127.0.0.1:8788/mcp`
+4. Verify the MCP URL in OpenClaw matches the bridge URL. If OpenClaw is cloud-hosted, do not use `127.0.0.1`; use `openclaw --public-url` with a reachable host.
 
 ### Debug mode
 

package/dist/browser-cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-cli.d.ts","sourceRoot":"","sources":["../src/browser-cli.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsEpC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAK7D;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAGnE"}
+{"version":3,"file":"browser-cli.d.ts","sourceRoot":"","sources":["../src/browser-cli.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmGpC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAK7D;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAGnE"}