@vibebrowser/mcp 0.2.4 → 0.2.6

package/README.md

@@ -24,7 +24,7 @@ Vibe MCP is the **only solution that allows multiple AI agents to control the sa
 Claude Desktop       Cursor          VS Code         OpenCode
      |                  |                |               |
      v                  v                v               v
- [vibe-mcp]        [vibe-mcp]       [vibe-mcp]      [vibe-mcp]
+ [vibebrowser-mcp] [vibebrowser-mcp] [vibebrowser-mcp] [vibebrowser-mcp]
      |                  |                |               |
      +------------------+----------------+---------------+
                         |
@@ -243,7 +243,7 @@ Claude / Cursor / VS Code (stdio)
 ```
 
 1. AI applications connect via MCP over stdio
-2. `vibebrowser-mcp` (or `vibe-mcp`) connects to the local relay on port `19888`
+2. `vibebrowser-mcp` connects to the local relay on port `19888`
 3. The relay forwards commands to the extension on port `19889`
 4. Results flow back to the agent
 
@@ -256,12 +256,97 @@ When multiple agents connect, Vibe MCP automatically spawns a relay daemon:
 - Relay multiplexes all agent requests to the single extension connection
 - Each agent receives only its own responses
 
+### Cloud OpenClaw -> Local Browser
+
+If your agent runs in the cloud but you want it to control the user's real local browser, run `vibebrowser-mcp` in HTTP mode and connect it to the Vibe extension in remote relay mode.
+
+```bash
+npx -y --package @vibebrowser/mcp vibebrowser-mcp start --transport http --remote <extension-uuid>
+```
+
+This exposes a local MCP endpoint at `http://127.0.0.1:8788/mcp` by default.
+
+You can print the exact OpenClaw-friendly setup with:
+
+```bash
+npx -y --package @vibebrowser/mcp vibebrowser-mcp openclaw --remote <extension-uuid>
+```
+
+For the full walkthrough, see `docs/openclaw-local-browser.md`.
+
+### OpenClaw-Compatible Browser CLI
+
+`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
+```
+
+The package now exposes two executables:
+
+- `vibebrowser-mcp` for MCP server, HTTP bridge, and helper commands
+- `vibebrowser-cli` for OpenClaw-inspired browser control against the real Vibe-connected session
+
+`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) resolves via `take_md_snapshot`
+- `snapshot --format aria` resolves via `take_a11y_snapshot`
+
+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>`
+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.)
+- `--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.
 
 ```bash
-npx @vibebrowser/mcp serve qwen3.5
+npx -y --package @vibebrowser/mcp vibebrowser-mcp serve qwen3.5
 ```
 
 That's it. Works on **macOS**, **Linux**, and **Windows**.
@@ -276,16 +361,16 @@ That's it. Works on **macOS**, **Linux**, and **Windows**.
 ### Recommended models
 
 ```bash
-npx @vibebrowser/mcp serve qwen3.5      # Best overall for agentic tasks
-npx @vibebrowser/mcp serve llama4        # Strong general reasoning
-npx @vibebrowser/mcp serve deepseek-r1   # Reasoning chains
-npx @vibebrowser/mcp serve mistral       # Lightweight & fast (7B)
+npx -y --package @vibebrowser/mcp vibebrowser-mcp serve qwen3.5      # Best overall for agentic tasks
+npx -y --package @vibebrowser/mcp vibebrowser-mcp serve llama4        # Strong general reasoning
+npx -y --package @vibebrowser/mcp vibebrowser-mcp serve deepseek-r1   # Reasoning chains
+npx -y --package @vibebrowser/mcp vibebrowser-mcp serve mistral       # Lightweight & fast (7B)
 ```
 
 ### Options
 
 ```bash
-npx @vibebrowser/mcp serve <model> [options]
+npx -y --package @vibebrowser/mcp vibebrowser-mcp serve <model> [options]
 
 Options:
   -p, --port <number>  Ollama API port (default: 11434)
@@ -304,15 +389,33 @@ The extension connects to `http://localhost:11434/v1` automatically.
 ## CLI Options
 
 ```bash
-npx @vibebrowser/mcp --help
+npx -y --package @vibebrowser/mcp vibebrowser-mcp --help
+npx -y --package @vibebrowser/mcp vibebrowser-cli --help
 
 # MCP server (default)
-npx @vibebrowser/mcp [start] [options]
+npx -y --package @vibebrowser/mcp vibebrowser-mcp [start] [options]
   -p, --port <number>  WebSocket port for local relay (agent) connection (default: 19888)
   -d, --debug          Enable debug logging
+  --transport <mode>   MCP transport to expose: stdio or http (default: stdio)
+  --host <host>        Host to bind the HTTP server to (default: 127.0.0.1)
+  --http-port <number> Port for streamable HTTP MCP transport (default: 8788)
+  --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
+  --relay-url <url>    Custom relay server URL
+
+# OpenClaw helper
+npx -y --package @vibebrowser/mcp vibebrowser-mcp openclaw --remote <extension-uuid>
+
+# 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> 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
 
 # Local LLM server
-npx @vibebrowser/mcp serve <model> [options]
+npx -y --package @vibebrowser/mcp vibebrowser-mcp serve <model> [options]
   -p, --port <number>  Ollama API port (default: 11434)
   -y, --yes            Skip confirmation prompts
   -d, --debug          Enable debug logging
@@ -326,6 +429,13 @@ npx @vibebrowser/mcp serve <model> [options]
 2. Click the extension icon and enable "MCP External Control" in Settings
 3. Check that no firewall is blocking localhost connections
 
+### "OpenClaw cannot reach my local browser bridge"
+
+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`
+
 ### Debug mode
 
 Enable debug logging to diagnose issues:
@@ -335,7 +445,7 @@ Enable debug logging to diagnose issues:
   "mcpServers": {
     "vibe": {
       "command": "npx",
-      "args": ["-y", "@vibebrowser/mcp", "--debug"]
+      "args": ["-y", "--package", "@vibebrowser/mcp", "vibebrowser-mcp", "--debug"]
     }
   }
 }

package/dist/browser-cli.d.ts

@@ -0,0 +1,4 @@
+import { Command } from 'commander';
+export declare function registerBrowserCommand(program: Command): void;
+export declare function registerStandaloneBrowserCli(program: Command): void;
+//# sourceMappingURL=browser-cli.d.ts.map

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

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