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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +320 -0
  2. package/package.json +1 -1
package/README.md ADDED
@@ -0,0 +1,320 @@
1
+ # Agent Browser MCP
2
+
3
+ MCP server for [agent-browser](https://agent-browser.dev) — a fast, Rust-based browser automation CLI built on Playwright.
4
+
5
+ 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.
6
+
7
+ ## Requirements
8
+
9
+ - **Node.js** >= 20.0.0
10
+ - **agent-browser** 0.26.0（其余版本未做测试）
11
+
12
+ Install agent-browser:
13
+
14
+ ```bash
15
+ # macOS / Linux
16
+ curl -fsSL https://agent-browser.dev/install.sh | bash
17
+
18
+ # npm
19
+ npm install -g agent-browser
20
+ ```
21
+
22
+ Verify installation:
23
+
24
+ ```bash
25
+ agent-browser --version
26
+ ```
27
+
28
+ ## Quick Start
29
+
30
+ ### npx (no install)
31
+
32
+ ```bash
33
+ npx @rabbitai-lab/agent-browser-mcp
34
+ ```
35
+
36
+ ### Global install
37
+
38
+ ```bash
39
+ npm install -g @rabbitai-lab/agent-browser-mcp
40
+ agent-browser-mcp
41
+ ```
42
+
43
+ The server starts on `http://localhost:12347/mcp` by default. Use `--port <number>` or the `PORT` environment variable to change it.
44
+
45
+ ### MCP Client Configuration
46
+
47
+ Add to your MCP client config file (e.g. `.mcp.json` or `claude_desktop_config.json`):
48
+
49
+ ```json
50
+ {
51
+ "mcpServers": {
52
+ "agent-browser": {
53
+ "command": "npx",
54
+ "args": ["@rabbitai-lab/agent-browser-mcp"]
55
+ }
56
+ }
57
+ }
58
+ ```
59
+
60
+ Or connect via URL (Streamable HTTP transport):
61
+
62
+ ```json
63
+ {
64
+ "mcpServers": {
65
+ "agent-browser": {
66
+ "url": "http://localhost:12347/mcp"
67
+ }
68
+ }
69
+ }
70
+ ```
71
+
72
+ ## Tools Reference
73
+
74
+ ### Navigation
75
+
76
+ | Tool | Description |
77
+ |------|-------------|
78
+ | `open` | Navigate to a URL |
79
+ | `back` | Go back to the previous page |
80
+ | `forward` | Go forward to the next page |
81
+ | `reload` | Reload the current page |
82
+ | `close` | Close the browser session |
83
+ | `connect` | Connect to a browser via CDP |
84
+
85
+ ### Interaction
86
+
87
+ | Tool | Description |
88
+ |------|-------------|
89
+ | `click` | Click an element by selector or @ref |
90
+ | `dblclick` | Double-click an element |
91
+ | `type` | Type text into an element (appends) |
92
+ | `fill` | Clear and fill an element with text |
93
+ | `press` | Press a keyboard key |
94
+ | `hover` | Hover over an element |
95
+ | `focus` | Focus an element |
96
+ | `check` | Check a checkbox |
97
+ | `uncheck` | Uncheck a checkbox |
98
+ | `select` | Select dropdown option(s) |
99
+ | `drag` | Drag and drop |
100
+ | `upload` | Upload file(s) to an element |
101
+ | `download` | Download a file by clicking an element |
102
+ | `scroll` | Scroll the page or a scrollable container |
103
+ | `scroll_into_view` | Scroll an element into view |
104
+ | `wait` | Wait for an element, timeout, or condition |
105
+
106
+ ### Query
107
+
108
+ | Tool | Description |
109
+ |------|-------------|
110
+ | `snapshot` | Capture accessibility tree with element refs |
111
+ | `get` | Get element information (text, html, value, attr, title, URL, etc.) |
112
+ | `is` | Check element state (visible, enabled, checked) |
113
+ | `find` | Find elements by locator and perform an action |
114
+ | `eval` | Run JavaScript in the browser page |
115
+
116
+ ### Visual
117
+
118
+ | Tool | Description |
119
+ |------|-------------|
120
+ | `screenshot` | Take a screenshot of the current page |
121
+ | `pdf` | Save the current page as PDF |
122
+ | `diff_snapshot` | Compare current accessibility snapshot vs last snapshot |
123
+ | `diff_screenshot` | Compare current screenshot vs baseline image |
124
+ | `diff_url` | Compare two URLs side by side |
125
+ | `highlight` | Highlight an element on the page |
126
+
127
+ ### Tabs & Frames
128
+
129
+ | Tool | Description |
130
+ |------|-------------|
131
+ | `tab_list` | List all browser tabs |
132
+ | `tab_new` | Open a new tab |
133
+ | `tab_close` | Close a tab |
134
+ | `tab_switch` | Switch to a tab by reference or label |
135
+ | `frame` | Switch frame context (iframe or main) |
136
+ | `window_new` | Open a new browser window |
137
+
138
+ ### Network
139
+
140
+ | Tool | Description |
141
+ |------|-------------|
142
+ | `network_route` | Intercept network requests by URL pattern |
143
+ | `network_unroute` | Remove a network route |
144
+ | `network_requests` | List network requests |
145
+ | `network_request_detail` | Get full details of a network request |
146
+ | `network_har` | Start or stop HAR recording |
147
+
148
+ ### Storage
149
+
150
+ | Tool | Description |
151
+ |------|-------------|
152
+ | `cookies_get` | Get all cookies |
153
+ | `cookies_set` | Set a cookie |
154
+ | `cookies_clear` | Clear all cookies |
155
+ | `storage_get` | Get web storage value(s) |
156
+ | `storage_set` | Set a web storage value |
157
+ | `storage_clear` | Clear web storage |
158
+
159
+ ### Browser Settings
160
+
161
+ | Tool | Description |
162
+ |------|-------------|
163
+ | `set_viewport` | Set browser viewport size |
164
+ | `set_device` | Emulate a device |
165
+ | `set_geolocation` | Set geolocation |
166
+ | `set_offline` | Toggle offline mode |
167
+ | `set_headers` | Set HTTP headers |
168
+ | `set_credentials` | Set HTTP authentication credentials |
169
+ | `set_color_scheme` | Set color scheme preference |
170
+
171
+ ### Keyboard
172
+
173
+ | Tool | Description |
174
+ |------|-------------|
175
+ | `keyboard_type` | Type text with real keystrokes (no selector needed) |
176
+ | `keyboard_insert` | Insert text without key events |
177
+ | `keydown` | Press and hold a key |
178
+ | `keyup` | Release a previously held key |
179
+
180
+ ### Mouse
181
+
182
+ | Tool | Description |
183
+ |------|-------------|
184
+ | `mouse_move` | Move mouse to coordinates |
185
+ | `mouse_down` | Press a mouse button |
186
+ | `mouse_up` | Release a mouse button |
187
+ | `mouse_wheel` | Scroll the mouse wheel |
188
+
189
+ ### Auth & State
190
+
191
+ | Tool | Description |
192
+ |------|-------------|
193
+ | `auth_save` | Save an authentication profile |
194
+ | `auth_login` | Login using a saved auth profile |
195
+ | `auth_list` | List saved auth profiles |
196
+ | `auth_show` | Show auth profile metadata |
197
+ | `auth_delete` | Delete a saved auth profile |
198
+ | `state_save` | Save browser auth state to a file |
199
+ | `state_load` | Load browser auth state from a file |
200
+ | `state_list` | List saved state files |
201
+ | `state_show` | Show state file summary |
202
+ | `state_rename` | Rename a state file |
203
+ | `state_clear` | Clear saved states |
204
+ | `state_clean` | Delete old state files |
205
+
206
+ ### Dialog & Confirmation
207
+
208
+ | Tool | Description |
209
+ |------|-------------|
210
+ | `dialog_accept` | Accept a dialog (alert/confirm/prompt) |
211
+ | `dialog_dismiss` | Dismiss a dialog |
212
+ | `dialog_status` | Check if a dialog is currently open |
213
+ | `confirm` | Approve a pending confirmation action |
214
+ | `deny` | Deny a pending confirmation action |
215
+
216
+ ### Debug & Recording
217
+
218
+ | Tool | Description |
219
+ |------|-------------|
220
+ | `console` | View console logs |
221
+ | `errors` | View page errors |
222
+ | `trace` | Record Chrome DevTools trace |
223
+ | `profiler` | Record Chrome DevTools profile |
224
+ | `record` | Record browser session as video (WebM) |
225
+ | `clipboard` | Read or write the clipboard |
226
+ | `inspect` | Open Chrome DevTools for the active page |
227
+
228
+ ### Sessions & Dashboard
229
+
230
+ | Tool | Description |
231
+ |------|-------------|
232
+ | `session_list` | List active browser sessions |
233
+ | `stream_enable` | Start runtime WebSocket streaming |
234
+ | `stream_disable` | Stop runtime WebSocket streaming |
235
+ | `stream_status` | Show streaming status and active port |
236
+ | `dashboard_start` | Start the observability dashboard server |
237
+ | `dashboard_stop` | Stop the dashboard server |
238
+
239
+ ### React DevTools
240
+
241
+ | Tool | Description |
242
+ |------|-------------|
243
+ | `react_tree` | Show full React component tree |
244
+ | `react_inspect` | Inspect a single React component by fiber ID |
245
+ | `react_renders` | Start or stop React fiber render recording |
246
+ | `react_suspense` | List React Suspense boundaries |
247
+
248
+ ### Batch & Misc
249
+
250
+ | Tool | Description |
251
+ |------|-------------|
252
+ | `batch` | Execute multiple browser commands sequentially |
253
+ | `doctor` | Diagnose agent-browser installation and configuration |
254
+ | `chat` | Send a natural language instruction to the AI agent |
255
+ | `pushstate` | SPA client-side navigation via history.pushState |
256
+ | `profiles` | List available Chrome profiles |
257
+ | `session` | Show current session name |
258
+ | `vitals` | Measure Web Vitals (LCP / CLS / TTFB / FCP / INP) |
259
+ | `addinitscript` | Register an init script at runtime |
260
+ | `removeinitscript` | Remove a previously registered init script |
261
+
262
+ ## Development
263
+
264
+ ```bash
265
+ # Install dependencies
266
+ npm install
267
+
268
+ # Build
269
+ npm run build
270
+
271
+ # Dev mode (hot reload)
272
+ npm run dev
273
+
274
+ # Type check
275
+ npm run typecheck
276
+
277
+ # Unit tests
278
+ npm run test:unit
279
+
280
+ # E2E tests (requires agent-browser running)
281
+ npm run test:e2e
282
+ ```
283
+
284
+ ## Architecture
285
+
286
+ ```
287
+ src/
288
+ ├── index.ts # Entry point, CLI argument parsing
289
+ ├── server.ts # HTTP server + MCP Streamable HTTP transport
290
+ ├── executor.ts # CLI subprocess executor (agent-browser)
291
+ ├── utils.ts # Shell escaping, arg builders
292
+ └── tools/
293
+ ├── index.ts # Tool registration hub
294
+ ├── navigation.ts
295
+ ├── interaction.ts
296
+ ├── query.ts
297
+ ├── visual.ts
298
+ ├── tabs.ts
299
+ ├── network.ts
300
+ ├── storage.ts
301
+ ├── browser-settings.ts
302
+ ├── keyboard.ts
303
+ ├── mouse.ts
304
+ ├── auth.ts
305
+ ├── state.ts
306
+ ├── dialog.ts
307
+ ├── confirmation.ts
308
+ ├── debug.ts
309
+ ├── sessions.ts
310
+ ├── dashboard.ts
311
+ ├── react.ts
312
+ ├── batch.ts
313
+ └── misc.ts
314
+ ```
315
+
316
+ 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.
317
+
318
+ ## License
319
+
320
+ [Apache-2.0](LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rabbitai-lab/agent-browser-mcp",
3
- "version": "0.1.0",
3
+ "version": "0.1.3",
4
4
  "description": "MCP server for agent-browser CLI - fast browser automation for AI agents",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",