@vibebrowser/mcp 0.1.0 → 0.2.1

package/README.md

@@ -1,34 +1,73 @@
-# Vibe MCP
+# Vibe MCP - Browser Automation for AI Agents
 
-MCP server for [Vibe AI Browser](https://vibebrowser.app) - allows AI agents to control your browser.
+[![npm version](https://img.shields.io/npm/v/@vibebrowser/mcp.svg)](https://www.npmjs.com/package/@vibebrowser/mcp)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 
-## What is this?
+MCP server for [Vibe AI Browser](https://vibebrowser.app) - the **only browser automation tool that supports multiple AI agents simultaneously**.
 
-Vibe MCP connects AI applications like Claude Desktop, Cursor, VS Code, and others to your Chrome browser through the Vibe extension. This enables AI to:
+## Why Vibe MCP?
 
-- Navigate to websites
-- Click buttons and links
-- Fill out forms
-- Take screenshots
-- Extract page content
-- And much more
+| Feature | Vibe MCP | Playwright MCP | BrowserMCP |
+|---------|----------|----------------|------------|
+| **Multi-Agent Support** | Yes | No | No |
+| Uses Your Browser Profile | Yes | No | No |
+| Logged-In Sessions | Yes | No | No |
+| No Separate Browser | Yes | No | No |
+| Local & Private | Yes | Yes | Partial |
+| Content Script Based | Yes | No | No |
+
+### Multi-Agent Architecture
+
+Vibe MCP is the **only solution that allows multiple AI agents to control the same browser simultaneously**. Run Claude Desktop, Cursor, VS Code Copilot, and OpenCode all at once - they all share control of your browser through our relay architecture.
+
+```
+Claude Desktop       Cursor          VS Code         OpenCode
+     |                  |                |               |
+     v                  v                v               v
+ [vibe-mcp]        [vibe-mcp]       [vibe-mcp]      [vibe-mcp]
+     |                  |                |               |
+     +------------------+----------------+---------------+
+                        |
+                        v
+                  [Relay Daemon]  <-- Auto-spawned, handles multiplexing
+                        |
+                        v
+                 [Vibe Extension]
+                        |
+                        v
+                   [Your Chrome]
+```
+
+**Competitors like Playwright MCP and BrowserMCP fail when you try to run multiple agents** - they get port conflicts or connection errors. Vibe MCP just works.
 
 ## Features
 
-- **Fast** - Automation happens locally on your machine
-- **Private** - Your browser activity stays on your device
-- **Logged In** - Uses your existing browser profile with all your sessions
-- **Stable** - Uses content scripts instead of CDP, avoiding common disconnection issues
+- **Multi-Agent Ready** - Run Claude, Cursor, VS Code, and more simultaneously
+- **Uses Your Browser** - No separate browser instance, uses your existing Chrome with all your logins
+- **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
 
-## Installation
+## Quick Start
 
 ### 1. Install the Vibe Extension
 
-Install the Vibe AI Browser extension from [vibebrowser.app](https://vibebrowser.app) or the [Chrome Web Store](https://chrome.google.com/webstore).
+Install the Vibe AI Browser extension in Chrome, Brave, or any Chromium browser:
 
-### 2. Configure Your AI Application
+**Option A: Chrome Web Store (Recommended)**
+1. Visit the [Chrome Web Store](https://chromewebstore.google.com/detail/vibe-ai-browser-co-pilot/djodpgokbmobeclicaicnnidccoinado)
+2. Click "Add to Chrome"
+3. The Vibe icon will appear in your toolbar
+
+**Option B: Developer Version**
+1. Download the [latest release ZIP](https://github.com/VibeTechnologies/VibeWebAgent/releases/latest/download/vibe-ai-copilot-latest.zip)
+2. Extract to a permanent folder
+3. Go to `chrome://extensions`, enable Developer Mode
+4. Click "Load unpacked" and select the extracted folder
+
+For detailed instructions, see the [installation guide](https://docs.vibebrowser.app/getting-started/extension).
 
-Add the Vibe MCP server to your AI application's configuration:
+### 2. Configure Your AI Application
 
 <details>
 <summary><strong>Claude Desktop</strong></summary>
@@ -56,7 +95,7 @@ Restart Claude Desktop after saving.
 <summary><strong>Cursor</strong></summary>
 
 1. Open Cursor Settings (Cmd/Ctrl + ,)
-2. Go to "Features" → "MCP Servers"
+2. Go to "Features" -> "MCP Servers"
 3. Click "Add Server" and add:
 
 ```json
@@ -88,8 +127,6 @@ Add to your VS Code settings.json:
 }
 ```
 
-Or use the MCP extension settings UI.
-
 </details>
 
 <details>
@@ -170,91 +207,76 @@ Add to your Codex configuration:
 
 1. Open Chrome with the Vibe extension installed
 2. Click the Vibe extension icon in the toolbar
-3. Click "Connect to MCP" to enable external control
+3. Go to Settings and enable "MCP External Control"
 4. The status should show "Connected"
 
 ## Available Tools
 
-The MCP server exposes all Vibe browser tools:
-
 | Tool | Description |
 |------|-------------|
-| `navigate_to_url` | Navigate to a URL |
-| `go_back` | Go back in history |
-| `go_forward` | Go forward in history |
-| `click` | Click an element |
-| `type` | Type text into an element |
-| `fill` | Fill a form field |
+| `navigate_to_url` | Navigate to any URL |
+| `go_back` / `go_forward` | Browser history navigation |
+| `click` | Click elements on the page |
+| `type` / `fill` | Enter text into inputs |
 | `scroll` | Scroll the page |
-| `take_screenshot` | Capture a screenshot |
-| `get_page_content` | Get page text content |
-| `list_tabs` | List open browser tabs |
-| `create_new_tab` | Open a new tab |
-| `switch_to_tab` | Switch to a tab |
-| `close_tab` | Close a tab |
-| `keyboard_shortcut` | Press keyboard shortcuts |
+| `take_screenshot` | Capture screenshots |
+| `get_page_content` | Extract page text/HTML |
+| `get_tabs` / `create_new_tab` / `switch_to_tab` / `close_tab` | Tab management |
+| `keyboard_shortcut` | Press keyboard combinations |
 | `web_search` | Search the web |
 
-## CLI Options
-
-```bash
-npx @anthropic/vibe-mcp --help
-
-Options:
-  -p, --port <number>  WebSocket port for extension connection (default: 19989)
-  -d, --debug          Enable debug logging
-  -h, --help           Show help
-```
-
-## Architecture
+## How It Works
 
 ```
 ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
-│ AI Application  │────►│ Vibe MCP Server │────►│ Vibe Extension  │
-│ (Claude/Cursor) │stdio│ (this package)  │ WS  │ (Chrome)        │
+│ AI Application  │────>│  Vibe MCP       │────>│ Vibe Extension  │
+│ (Claude/Cursor) │stdio│  (this package) │ WS  │ (Chrome)        │
 └─────────────────┘     └─────────────────┘     └─────────────────┘
 ```
 
-The MCP server:
-1. Receives tool calls from AI applications via stdio (MCP protocol)
-2. Forwards them to the Vibe extension via WebSocket
-3. Returns results back to the AI application
+1. AI applications connect via MCP protocol (stdio)
+2. Vibe MCP forwards commands to the browser extension via WebSocket
+3. The extension executes actions in your actual browser
+4. Results flow back to the AI
 
-## Troubleshooting
+### Multi-Agent Mode
 
-### "No connection to Vibe extension"
+When multiple agents connect, Vibe MCP automatically spawns a relay daemon:
 
-1. Make sure the Vibe extension is installed in Chrome
-2. Click the extension icon and ensure "Connect to MCP" is enabled
-3. Check that no other application is using port 19989
+- First agent starts the relay (listens on ports 19988 and 19989)
+- Additional agents connect to the relay as clients
+- Relay multiplexes all agent requests to the single extension connection
+- Each agent receives only its own responses
 
-### Port already in use
+## CLI Options
 
-Use a different port:
+```bash
+npx @vibebrowser/mcp --help
 
-```json
-{
-  "mcpServers": {
-    "vibe": {
-      "command": "npx",
-      "args": ["-y", "@anthropic/vibe-mcp", "--port", "19990"]
-    }
-  }
-}
+Options:
+  -p, --port <number>  WebSocket port for extension (default: 19989)
+  -d, --debug          Enable debug logging
+  -h, --help           Show help
 ```
 
-Make sure to also update the port in the extension settings.
+## Troubleshooting
+
+### "No connection to Vibe extension"
+
+1. Ensure the Vibe extension is installed in Chrome
+2. Click the extension icon and enable "MCP External Control" in Settings
+3. Check that no firewall is blocking localhost connections
 
 ### Debug mode
 
-Enable debug logging to see what's happening:
+Enable debug logging to diagnose issues:
 
 ```json
 {
   "mcpServers": {
     "vibe": {
       "command": "npx",
-      "args": ["-y", "@anthropic/vibe-mcp", "--debug"]
+      "args": ["-y", "@vibebrowser/mcp", "--debug"]
     }
   }
 }
@@ -263,27 +285,25 @@ Enable debug logging to see what's happening:
 ## Development
 
 ```bash
-# Clone the repository
 git clone https://github.com/VibeTechnologies/vibe-mcp.git
 cd vibe-mcp
-
-# Install dependencies
 npm install
-
-# Build
 npm run build
-
-# Run locally
 node dist/cli.js --debug
 ```
 
+## Keywords
+
+browser automation, mcp server, model context protocol, ai browser control, claude desktop browser, cursor browser automation, web automation, chrome automation, ai agent browser, multi-agent browser control, playwright alternative, puppeteer alternative, browser mcp, web scraping ai, ai web agent
+
 ## License
 
 Apache-2.0
 
 ## Links
 
-- [Vibe AI Browser](https://vibebrowser.app)
-- [Documentation](https://docs.vibebrowser.app)
-- [GitHub](https://github.com/VibeTechnologies/vibe-mcp)
-- [Report Issues](https://github.com/VibeTechnologies/vibe-mcp/issues)
+- [Vibe AI Browser](https://vibebrowser.app) - Main product
+- [Documentation](https://docs.vibebrowser.app) - Full docs
+- [Chrome Extension](https://chromewebstore.google.com/detail/vibe-ai-web-agent/ajfjlohdpfgngdjfafhhcnpmijbbdgln) - Install extension
+- [GitHub Issues](https://github.com/VibeTechnologies/vibe-mcp/issues) - Report bugs
+- [npm Package](https://www.npmjs.com/package/@vibebrowser/mcp) - npm registry

package/dist/cli.js

@@ -1,19 +1,17 @@
 #!/usr/bin/env node
-"use strict";
 /**
  * Vibe MCP Server - CLI Entry Point
  *
  * Command-line interface for starting the MCP server.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-const commander_1 = require("commander");
-const server_js_1 = require("./server.js");
-const types_js_1 = require("./types.js");
-commander_1.program
+import { program } from 'commander';
+import { createServer } from './server.js';
+import { DEFAULT_WS_PORT } from './types.js';
+program
     .name('vibe-mcp')
     .description('MCP server for Vibe AI Browser - allows AI agents to control your browser')
     .version('0.1.0')
-    .option('-p, --port <number>', 'WebSocket port for extension connection', String(types_js_1.DEFAULT_WS_PORT))
+    .option('-p, --port <number>', 'WebSocket port for extension connection', String(DEFAULT_WS_PORT))
     .option('-d, --debug', 'Enable debug logging', false)
     .action(async (options) => {
     const port = parseInt(options.port, 10);
@@ -22,7 +20,7 @@ commander_1.program
         process.exit(1);
     }
     try {
-        await (0, server_js_1.createServer)({
+        await createServer({
             port,
             debug: options.debug,
         });
@@ -33,5 +31,5 @@ commander_1.program
         process.exit(1);
     }
 });
-commander_1.program.parse();
+program.parse();
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;AACA;;;;GAIG;;AAEH,yCAAoC;AACpC,2CAA2C;AAC3C,yCAA6C;AAE7C,mBAAO;KACJ,IAAI,CAAC,UAAU,CAAC;KAChB,WAAW,CAAC,2EAA2E,CAAC;KACxF,OAAO,CAAC,OAAO,CAAC;KAChB,MAAM,CAAC,qBAAqB,EAAE,yCAAyC,EAAE,MAAM,CAAC,0BAAe,CAAC,CAAC;KACjG,MAAM,CAAC,aAAa,EAAE,sBAAsB,EAAE,KAAK,CAAC;KACpD,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;IACxB,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAExC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;QAC/C,OAAO,CAAC,KAAK,CAAC,qDAAqD,CAAC,CAAC;QACrE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,IAAA,wBAAY,EAAC;YACjB,IAAI;YACJ,KAAK,EAAE,OAAO,CAAC,KAAK;SACrB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,OAAO,CAAC,KAAK,CAAC,2BAA2B,OAAO,EAAE,CAAC,CAAC;QACpD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,mBAAO,CAAC,KAAK,EAAE,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C,OAAO;KACJ,IAAI,CAAC,UAAU,CAAC;KAChB,WAAW,CAAC,2EAA2E,CAAC;KACxF,OAAO,CAAC,OAAO,CAAC;KAChB,MAAM,CAAC,qBAAqB,EAAE,yCAAyC,EAAE,MAAM,CAAC,eAAe,CAAC,CAAC;KACjG,MAAM,CAAC,aAAa,EAAE,sBAAsB,EAAE,KAAK,CAAC;KACpD,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;IACxB,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAExC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;QAC/C,OAAO,CAAC,KAAK,CAAC,qDAAqD,CAAC,CAAC;QACrE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,CAAC;QACH,MAAM,YAAY,CAAC;YACjB,IAAI;YACJ,KAAK,EAAE,OAAO,CAAC,KAAK;SACrB,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,OAAO,CAAC,KAAK,CAAC,2BAA2B,OAAO,EAAE,CAAC,CAAC;QACpD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/dist/connection.d.ts

@@ -1,15 +1,17 @@
 /**
- * Vibe MCP Server - Extension Connection
+ * Vibe MCP Server - Relay Connection
  *
- * Manages WebSocket connection to the Vibe browser extension.
+ * Connects to the relay server as a WebSocket client.
+ * The relay handles the actual extension connection.
  */
 import { EventEmitter } from 'events';
 import { ConnectionStatus, ToolDefinition, ToolResult, SnapshotResult } from './types.js';
 /**
- * Extension connection manager
+ * Relay connection manager
+ *
+ * Connects to the relay server instead of directly to the extension.
  */
 export declare class ExtensionConnection extends EventEmitter {
-    private wss;
     private ws;
     private status;
     private pendingRequests;
@@ -18,25 +20,39 @@ export declare class ExtensionConnection extends EventEmitter {
     private debug;
     private tools;
     private reconnectTimer;
+    private extensionConnected;
     constructor(port?: number, debug?: boolean);
     /**
-     * Start the WebSocket server and wait for extension connection
+     * Start connection to relay server
+     * Spawns relay daemon if not already running
      */
     start(): Promise<void>;
     /**
-     * Stop the WebSocket server
+     * Spawn relay daemon as detached process
      */
-    stop(): Promise<void>;
+    private spawnRelay;
+    /**
+     * Wait for relay to become available
+     */
+    private waitForRelay;
+    /**
+     * Connect to the relay server
+     */
+    private connectToRelay;
     /**
-     * Handle new WebSocket connection from extension
+     * Schedule reconnection attempt
      */
-    private handleConnection;
+    private scheduleReconnect;
     /**
-     * Handle message from extension
+     * Stop the connection
+     */
+    stop(): Promise<void>;
+    /**
+     * Handle message from relay
      */
     private handleMessage;
     /**
-     * Send a message to the extension and wait for response
+     * Send a message to the extension via relay and wait for response
      */
     private sendRequest;
     /**
@@ -56,13 +72,17 @@ export declare class ExtensionConnection extends EventEmitter {
      */
     getSnapshot(): Promise<SnapshotResult>;
     /**
-     * Check if extension is connected
+     * Check if extension is connected (via relay)
      */
     isConnected(): boolean;
     /**
      * Get connection status
      */
     getStatus(): ConnectionStatus;
+    /**
+     * Check if extension is connected to relay
+     */
+    isExtensionConnected(): boolean;
     /**
      * Log message if debug is enabled
      */

package/dist/connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAEL,gBAAgB,EAGhB,cAAc,EACd,UAAU,EACV,cAAc,EACf,MAAM,YAAY,CAAC;AAgBpB;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;IACnD,OAAO,CAAC,GAAG,CAAgC;IAC3C,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,MAAM,CAAoC;IAClD,OAAO,CAAC,eAAe,CAA0C;IACjE,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,KAAK,CAAU;IACvB,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,cAAc,CAA+B;gBAEzC,IAAI,GAAE,MAAwB,EAAE,KAAK,GAAE,OAAe;IAMlE;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAwB5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA6B3B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAuCxB;;OAEG;IACH,OAAO,CAAC,aAAa;IAoCrB;;OAEG;YACW,WAAW;IA6BzB;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAM/C;;OAEG;IACH,QAAQ,IAAI,cAAc,EAAE;IAI5B;;OAEG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;IAIhF;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,cAAc,CAAC;IAI5C;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,SAAS,IAAI,gBAAgB;IAI7B;;OAEG;IACH,OAAO,CAAC,GAAG;CAKZ"}
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAGtC,OAAO,EACL,gBAAgB,EAGhB,cAAc,EACd,UAAU,EACV,cAAc,EACf,MAAM,YAAY,CAAC;AAoBpB;;;;GAIG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;IACnD,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,MAAM,CAAoC;IAClD,OAAO,CAAC,eAAe,CAA0C;IACjE,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,KAAK,CAAU;IACvB,OAAO,CAAC,KAAK,CAAwB;IACrC,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,kBAAkB,CAAkB;gBAEhC,IAAI,GAAE,MAAmB,EAAE,KAAK,GAAE,OAAe;IAM7D;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAa5B;;OAEG;YACW,UAAU;IAaxB;;OAEG;YACW,YAAY;IAoC1B;;OAEG;YACW,cAAc;IA6C5B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAgBzB;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB3B;;OAEG;IACH,OAAO,CAAC,aAAa;IAmDrB;;OAEG;YACW,WAAW;IAiCzB;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAM/C;;OAEG;IACH,QAAQ,IAAI,cAAc,EAAE;IAI5B;;OAEG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;IAIhF;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,cAAc,CAAC;IAI5C;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,SAAS,IAAI,gBAAgB;IAI7B;;OAEG;IACH,oBAAoB,IAAI,OAAO;IAI/B;;OAEG;IACH,OAAO,CAAC,GAAG;CAKZ"}