@rabbitai-lab/agent-browser-mcp 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,320 @@
+# Agent Browser MCP
+
+MCP server for [agent-browser](https://agent-browser.dev) — a fast, Rust-based browser automation CLI built on Playwright.
+
+This package exposes **100 tools** across 18 categories, enabling any MCP-compatible AI client to automate web browsers: navigate pages, interact with elements, capture screenshots, intercept network traffic, manage authentication, record sessions, and more.
+
+## Requirements
+
+- **Node.js** >= 20.0.0
+- **agent-browser** CLI installed and available in `$PATH`
+
+Install agent-browser:
+
+```bash
+# macOS / Linux
+curl -fsSL https://agent-browser.dev/install.sh | bash
+
+# npm
+npm install -g agent-browser
+```
+
+Verify installation:
+
+```bash
+agent-browser --version
+```
+
+## Quick Start
+
+### npx (no install)
+
+```bash
+npx @rabbitai-lab/agent-browser-mcp
+```
+
+### Global install
+
+```bash
+npm install -g @rabbitai-lab/agent-browser-mcp
+agent-browser-mcp
+```
+
+The server starts on `http://localhost:12347/mcp` by default. Use `--port <number>` or the `PORT` environment variable to change it.
+
+### MCP Client Configuration
+
+Add to your MCP client config file (e.g. `.mcp.json` or `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "agent-browser": {
+      "command": "npx",
+      "args": ["@rabbitai-lab/agent-browser-mcp"]
+    }
+  }
+}
+```
+
+Or connect via URL (Streamable HTTP transport):
+
+```json
+{
+  "mcpServers": {
+    "agent-browser": {
+      "url": "http://localhost:12347/mcp"
+    }
+  }
+}
+```
+
+## Tools Reference
+
+### Navigation
+
+| Tool | Description |
+|------|-------------|
+| `open` | Navigate to a URL |
+| `back` | Go back to the previous page |
+| `forward` | Go forward to the next page |
+| `reload` | Reload the current page |
+| `close` | Close the browser session |
+| `connect` | Connect to a browser via CDP |
+
+### Interaction
+
+| Tool | Description |
+|------|-------------|
+| `click` | Click an element by selector or @ref |
+| `dblclick` | Double-click an element |
+| `type` | Type text into an element (appends) |
+| `fill` | Clear and fill an element with text |
+| `press` | Press a keyboard key |
+| `hover` | Hover over an element |
+| `focus` | Focus an element |
+| `check` | Check a checkbox |
+| `uncheck` | Uncheck a checkbox |
+| `select` | Select dropdown option(s) |
+| `drag` | Drag and drop |
+| `upload` | Upload file(s) to an element |
+| `download` | Download a file by clicking an element |
+| `scroll` | Scroll the page or a scrollable container |
+| `scroll_into_view` | Scroll an element into view |
+| `wait` | Wait for an element, timeout, or condition |
+
+### Query
+
+| Tool | Description |
+|------|-------------|
+| `snapshot` | Capture accessibility tree with element refs |
+| `get` | Get element information (text, html, value, attr, title, URL, etc.) |
+| `is` | Check element state (visible, enabled, checked) |
+| `find` | Find elements by locator and perform an action |
+| `eval` | Run JavaScript in the browser page |
+
+### Visual
+
+| Tool | Description |
+|------|-------------|
+| `screenshot` | Take a screenshot of the current page |
+| `pdf` | Save the current page as PDF |
+| `diff_snapshot` | Compare current accessibility snapshot vs last snapshot |
+| `diff_screenshot` | Compare current screenshot vs baseline image |
+| `diff_url` | Compare two URLs side by side |
+| `highlight` | Highlight an element on the page |
+
+### Tabs & Frames
+
+| Tool | Description |
+|------|-------------|
+| `tab_list` | List all browser tabs |
+| `tab_new` | Open a new tab |
+| `tab_close` | Close a tab |
+| `tab_switch` | Switch to a tab by reference or label |
+| `frame` | Switch frame context (iframe or main) |
+| `window_new` | Open a new browser window |
+
+### Network
+
+| Tool | Description |
+|------|-------------|
+| `network_route` | Intercept network requests by URL pattern |
+| `network_unroute` | Remove a network route |
+| `network_requests` | List network requests |
+| `network_request_detail` | Get full details of a network request |
+| `network_har` | Start or stop HAR recording |
+
+### Storage
+
+| Tool | Description |
+|------|-------------|
+| `cookies_get` | Get all cookies |
+| `cookies_set` | Set a cookie |
+| `cookies_clear` | Clear all cookies |
+| `storage_get` | Get web storage value(s) |
+| `storage_set` | Set a web storage value |
+| `storage_clear` | Clear web storage |
+
+### Browser Settings
+
+| Tool | Description |
+|------|-------------|
+| `set_viewport` | Set browser viewport size |
+| `set_device` | Emulate a device |
+| `set_geolocation` | Set geolocation |
+| `set_offline` | Toggle offline mode |
+| `set_headers` | Set HTTP headers |
+| `set_credentials` | Set HTTP authentication credentials |
+| `set_color_scheme` | Set color scheme preference |
+
+### Keyboard
+
+| Tool | Description |
+|------|-------------|
+| `keyboard_type` | Type text with real keystrokes (no selector needed) |
+| `keyboard_insert` | Insert text without key events |
+| `keydown` | Press and hold a key |
+| `keyup` | Release a previously held key |
+
+### Mouse
+
+| Tool | Description |
+|------|-------------|
+| `mouse_move` | Move mouse to coordinates |
+| `mouse_down` | Press a mouse button |
+| `mouse_up` | Release a mouse button |
+| `mouse_wheel` | Scroll the mouse wheel |
+
+### Auth & State
+
+| Tool | Description |
+|------|-------------|
+| `auth_save` | Save an authentication profile |
+| `auth_login` | Login using a saved auth profile |
+| `auth_list` | List saved auth profiles |
+| `auth_show` | Show auth profile metadata |
+| `auth_delete` | Delete a saved auth profile |
+| `state_save` | Save browser auth state to a file |
+| `state_load` | Load browser auth state from a file |
+| `state_list` | List saved state files |
+| `state_show` | Show state file summary |
+| `state_rename` | Rename a state file |
+| `state_clear` | Clear saved states |
+| `state_clean` | Delete old state files |
+
+### Dialog & Confirmation
+
+| Tool | Description |
+|------|-------------|
+| `dialog_accept` | Accept a dialog (alert/confirm/prompt) |
+| `dialog_dismiss` | Dismiss a dialog |
+| `dialog_status` | Check if a dialog is currently open |
+| `confirm` | Approve a pending confirmation action |
+| `deny` | Deny a pending confirmation action |
+
+### Debug & Recording
+
+| Tool | Description |
+|------|-------------|
+| `console` | View console logs |
+| `errors` | View page errors |
+| `trace` | Record Chrome DevTools trace |
+| `profiler` | Record Chrome DevTools profile |
+| `record` | Record browser session as video (WebM) |
+| `clipboard` | Read or write the clipboard |
+| `inspect` | Open Chrome DevTools for the active page |
+
+### Sessions & Dashboard
+
+| Tool | Description |
+|------|-------------|
+| `session_list` | List active browser sessions |
+| `stream_enable` | Start runtime WebSocket streaming |
+| `stream_disable` | Stop runtime WebSocket streaming |
+| `stream_status` | Show streaming status and active port |
+| `dashboard_start` | Start the observability dashboard server |
+| `dashboard_stop` | Stop the dashboard server |
+
+### React DevTools
+
+| Tool | Description |
+|------|-------------|
+| `react_tree` | Show full React component tree |
+| `react_inspect` | Inspect a single React component by fiber ID |
+| `react_renders` | Start or stop React fiber render recording |
+| `react_suspense` | List React Suspense boundaries |
+
+### Batch & Misc
+
+| Tool | Description |
+|------|-------------|
+| `batch` | Execute multiple browser commands sequentially |
+| `doctor` | Diagnose agent-browser installation and configuration |
+| `chat` | Send a natural language instruction to the AI agent |
+| `pushstate` | SPA client-side navigation via history.pushState |
+| `profiles` | List available Chrome profiles |
+| `session` | Show current session name |
+| `vitals` | Measure Web Vitals (LCP / CLS / TTFB / FCP / INP) |
+| `addinitscript` | Register an init script at runtime |
+| `removeinitscript` | Remove a previously registered init script |
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Dev mode (hot reload)
+npm run dev
+
+# Type check
+npm run typecheck
+
+# Unit tests
+npm run test:unit
+
+# E2E tests (requires agent-browser running)
+npm run test:e2e
+```
+
+## Architecture
+
+```
+src/
+├── index.ts          # Entry point, CLI argument parsing
+├── server.ts         # HTTP server + MCP Streamable HTTP transport
+├── executor.ts       # CLI subprocess executor (agent-browser)
+├── utils.ts          # Shell escaping, arg builders
+└── tools/
+    ├── index.ts      # Tool registration hub
+    ├── navigation.ts
+    ├── interaction.ts
+    ├── query.ts
+    ├── visual.ts
+    ├── tabs.ts
+    ├── network.ts
+    ├── storage.ts
+    ├── browser-settings.ts
+    ├── keyboard.ts
+    ├── mouse.ts
+    ├── auth.ts
+    ├── state.ts
+    ├── dialog.ts
+    ├── confirmation.ts
+    ├── debug.ts
+    ├── sessions.ts
+    ├── dashboard.ts
+    ├── react.ts
+    ├── batch.ts
+    └── misc.ts
+```
+
+Each tool module registers MCP tools via `server.tool(name, schema, handler)`. The handler constructs a CLI command string and delegates execution to `CliExecutor`, which spawns `agent-browser` as a subprocess.
+
+## License
+
+[Apache-2.0](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rabbitai-lab/agent-browser-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MCP server for agent-browser CLI - fast browser automation for AI agents",
   "type": "module",
   "main": "dist/index.js",