aipex-mcp-bridge 1.0.2 → 2.0.0

package/README.md

@@ -1,20 +1,32 @@
 # aipex-mcp-bridge
 
-MCP bridge that connects AI agents to the [AIPex](https://aipex.ai) browser extension via WebSocket.
+MCP bridge that connects AI agents to the [AIPex](https://aipex.ai) browser extension via Native Messaging.
 
-Works with **any** MCP client that supports stdio transport — Cursor, Claude Desktop, Claude Code, VS Code Copilot, Windsurf, Zed, and more.
+Works with **any** MCP client that supports stdio transport -- Cursor, Claude Desktop, Claude Code, VS Code Copilot, Windsurf, Zed, and more.
 
 ## How it works
 
 ```
-AI Agent (MCP client) ──stdio──▶ aipex-mcp-bridge ──WebSocket──▶ AIPex Chrome Extension
+AI Agent (MCP client) ──stdio──▶ aipex-mcp-bridge ──Native Messaging──▶ AIPex Chrome Extension
 ```
 
-The bridge starts a WebSocket server on `localhost:9223` (configurable) and communicates with your AI agent over stdio using the MCP protocol. The AIPex extension connects to the WebSocket server to expose browser control tools.
+The bridge communicates with the AIPex Chrome extension via Chrome's Native Messaging protocol (no WebSocket, no manual connection needed). It also exposes a Streamable HTTP endpoint on `localhost:12306` for HTTP-capable clients.
 
 ## Quick start
 
-### 1. Configure your AI agent
+### 1. Install and register the native messaging host
+
+```bash
+npm install -g aipex-mcp-bridge
+```
+
+The native messaging host is registered automatically during installation. If needed, you can register manually:
+
+```bash
+aipex-mcp-bridge register
+```
+
+### 2. Configure your AI agent
 
 Add the following to your agent's MCP configuration:
 
@@ -76,43 +88,76 @@ claude mcp add aipex-browser -- npx -y aipex-mcp-bridge
 }
 ```
 
-### 2. Connect AIPex extension
+### 3. Reload AIPex extension
 
-1. Open Chrome → AIPex extension → Options page
-2. Set WebSocket URL to `ws://localhost:9223`
-3. Click **Connect**
+After installing the bridge, reload the AIPex extension in Chrome. The extension will automatically connect to the native messaging host.
 
 Your AI agent can now control the browser through AIPex.
 
-## Options
+## CLI Commands
 
+### Register native messaging host
+
+```bash
+aipex-mcp-bridge register [options]
 ```
-npx aipex-mcp-bridge [--port <port>]
+
+| Option | Description |
+| --- | --- |
+| `--browser <name>` | Browser: `chrome`, `chromium`, `all`, `detect` (default: `detect`) |
+| `--system` | Register system-wide (requires admin) |
+| `--extension-id <id>` | Chrome extension ID (repeatable) |
+
+### Run diagnostics
+
+```bash
+aipex-mcp-bridge doctor [--fix]
 ```
 
-| Option            | Default | Description                        |
-| ----------------- | ------- | ---------------------------------- |
-| `--port <port>`   | `9223`  | WebSocket port for AIPex extension |
-| `--help`, `-h`    |         | Show help message                  |
-| `--version`, `-v` |         | Show version                       |
+### Fix file permissions (macOS/Linux)
 
-### Custom port example
+```bash
+aipex-mcp-bridge fix-permissions
+```
 
-```json
-{
-  "mcpServers": {
-    "aipex-browser": {
-      "command": "npx",
-      "args": ["-y", "aipex-mcp-bridge", "--port", "8080"]
-    }
-  }
-}
+### Remove registration
+
+```bash
+aipex-mcp-bridge unregister
 ```
 
+## Server Options
+
+```
+aipex-mcp-bridge [--port <port>] [--stdio-only]
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--port <port>` | `12306` | HTTP port for Streamable HTTP transport |
+| `--stdio-only` | | Only serve via stdio, skip HTTP server |
+| `--help`, `-h` | | Show help message |
+| `--version`, `-v` | | Show version |
+
 ## Requirements
 
 - Node.js >= 18
 - AIPex Chrome extension installed
+- Chrome or Chromium browser
+
+## Troubleshooting
+
+**"Specified native messaging host not found"**
+
+Run `aipex-mcp-bridge register` to register the native messaging host, then reload the Chrome extension.
+
+**"Permission denied" (macOS/Linux)**
+
+Run `aipex-mcp-bridge fix-permissions` to fix file permissions.
+
+**General diagnostics**
+
+Run `aipex-mcp-bridge doctor --fix` for automated diagnosis and repair.
 
 ## License