@vibebrowser/mcp 0.2.3 → 0.2.5

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,15 +256,122 @@ 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
 
-## CLI Options
+### 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 @vibebrowser/mcp --help
+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 --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 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 -y --package @vibebrowser/mcp vibebrowser-mcp serve qwen3.5
+```
+
+That's it. Works on **macOS**, **Linux**, and **Windows**.
+
+### What it does
+
+1. **Detects Ollama** → installs it if missing (via `brew`, `curl`, or `winget`)
+2. **Starts the server** → launches `ollama serve` in the background
+3. **Downloads the model** → streams download progress to your terminal
+4. **Prints connection info** → ready to use with VibeBrowser or any OpenAI-compatible client
+
+### Recommended models
+
+```bash
+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 -y --package @vibebrowser/mcp vibebrowser-mcp serve <model> [options]
 
 Options:
+  -p, --port <number>  Ollama API port (default: 11434)
+  -y, --yes            Skip install confirmation prompts
+  -d, --debug          Enable debug logging
+```
+
+### Using with VibeBrowser extension
+
+After `serve` completes, configure the extension:
+- **Model provider** → `ollama`
+- **Model name** → the model you served (e.g., `qwen3.5`)
+
+The extension connects to `http://localhost:11434/v1` automatically.
+
+## CLI Options
+
+```bash
+npx -y --package @vibebrowser/mcp vibebrowser-mcp --help
+npx -y --package @vibebrowser/mcp vibebrowser-cli --help
+
+# MCP server (default)
+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
-  -h, --help           Show help
+  --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 -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
 ```
 
 ## Troubleshooting
@@ -275,6 +382,13 @@ 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:
@@ -284,7 +398,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;AAsEpC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAK7D;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAGnE"}