slimbrowser-mcp 0.1.1 → 0.1.4

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 +568 -55
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,105 +1,618 @@
1
- # slimbrowser-mcp
1
+ <p align="center">
2
+ <h1 align="center">SlimBrowser MCP</h1>
3
+ <p align="center">
4
+ <strong>Token-efficient browser automation for AI agents</strong>
5
+ </p>
6
+ <p align="center">
7
+ A Model Context Protocol (MCP) server that gives AI agents full browser control —<br/>
8
+ navigate, click, type, extract data, capture sessions, and debug — all through a<br/>
9
+ clean, structured tool interface optimized for minimal token overhead.
10
+ </p>
11
+ <p align="center">
12
+ <a href="#quickstart">Quickstart</a> &nbsp;&bull;&nbsp;
13
+ <a href="#client-integrations">Client Integrations</a> &nbsp;&bull;&nbsp;
14
+ <a href="#arguments">Arguments</a> &nbsp;&bull;&nbsp;
15
+ <a href="#remote-chrome">Remote Chrome</a> &nbsp;&bull;&nbsp;
16
+ <a href="#mcp-tool-catalog">Tool Catalog</a>
17
+ </p>
18
+ </p>
19
+
20
+ ---
21
+
22
+ ## Why SlimBrowser MCP?
23
+
24
+ Most browser MCP servers dump full DOM trees and bloated HTML into your context window. That means **more tokens, higher cost, and slower agents**. SlimBrowser takes a fundamentally different approach — structured observations with three resolution modes, compact element IDs for surgical interactions, and delta-based updates that only send what changed.
25
+
26
+ ### Token Usage Comparison
27
+
28
+ > Real-world benchmark: scraping 85 posts from the same website.
2
29
 
3
- A token-efficient browser MCP server for AI agents.
30
+ ```
31
+ ┌───────────────────────┬───────────┬─────────────┬────────────┐
32
+ │ Tool │ Same task │ Tokens used │ Savings │
33
+ ├───────────────────────┼───────────┼─────────────┼────────────┤
34
+ │ Chrome DevTools MCP │ 85 posts │ ~290,000 │ baseline │
35
+ ├───────────────────────┼───────────┼─────────────┼────────────┤
36
+ │ Claude in Chrome │ 85 posts │ ~100,000 │ 65% │
37
+ ├───────────────────────┼───────────┼─────────────┼────────────┤
38
+ │ SlimBrowser MCP │ 85 posts │ ~44,000 │ 85% │
39
+ └───────────────────────┴───────────┴─────────────┴────────────┘
40
+ ```
41
+
42
+ **SlimBrowser uses 85% fewer tokens** than Chrome DevTools MCP and **56% fewer** than Claude in Chrome — for the exact same task.
43
+
44
+ ### Key Advantages
45
+
46
+ - **85% token reduction** — proven in real-world benchmarks against leading alternatives
47
+ - **3 observation modes** — SUMMARY, REGION, and FULL let agents choose the right level of detail
48
+ - **42 specialized tools** — from one-click form fills to paginated network request inspection
49
+ - **Session capture & replay** — every action is recorded; generate visual playback HTML automatically
50
+ - **Remote Chrome support** — connect to Chrome instances running on remote machines, Docker containers, or cloud VMs
51
+ - **Multi-tab orchestration** — open, switch, pin, and close tabs with full state tracking
52
+ - **Built-in diagnostics** — console logs, network requests, performance metrics, and execution traces
53
+ - **AI prompt templates** — pre-built workflows for scraping, testing, security audits, and more
54
+ - **MCP resources** — subscribe to live session state via the `ab://` URI scheme
4
55
 
5
- - Chrome-only, CDP-first
6
- - Low-token observation model (`SUMMARY` by default)
7
- - Auto session capture/playback
8
- - Screenshot export with file paths returned to the agent
56
+ ---
9
57
 
10
- ## Quickstart (End Users)
58
+ ## Quickstart
11
59
 
12
- ### 1) Run doctor
60
+ **Prerequisites:** Node.js >= 18, Chrome/Chromium installed locally (or a remote Chrome instance).
61
+
62
+ Run the diagnostic check:
13
63
 
14
64
  ```bash
15
- npx -y slimbrowser-mcp doctor
65
+ npx -y slimbrowser-mcp@latest doctor
16
66
  ```
17
67
 
18
- ### 2) Start MCP server
68
+ Start the MCP server:
19
69
 
20
70
  ```bash
21
- npx -y slimbrowser-mcp
71
+ npx -y slimbrowser-mcp@latest
72
+ ```
73
+
74
+ Verify it works — ask your AI agent to run:
75
+
22
76
  ```
77
+ 1. browser_create_session
78
+ 2. browser_navigate → url: "https://example.com"
79
+ 3. browser_observe → mode: "SUMMARY"
80
+ 4. browser_screenshot
81
+ ```
82
+
83
+ ---
23
84
 
24
- No `.env` is required for default usage.
85
+ ## Client Integrations
25
86
 
26
- ## Connect to Claude Code
87
+ Supported clients: **Codex** / **Claude Code** / **Gemini CLI** / **Claude Desktop** / **Cursor** / **Windsurf**
27
88
 
28
- Add server:
89
+ <details>
90
+ <summary><strong>Codex</strong></summary>
29
91
 
30
92
  ```bash
31
- claude mcp add --scope local slimbrowser -- npx -y slimbrowser-mcp
93
+ # Add
94
+ codex mcp add slimbrowser -- npx -y slimbrowser-mcp@latest
95
+
96
+ # List / Remove
97
+ codex mcp list
98
+ codex mcp remove slimbrowser
32
99
  ```
33
100
 
34
- Check status:
101
+ </details>
102
+
103
+ <details>
104
+ <summary><strong>Claude Code</strong></summary>
35
105
 
36
106
  ```bash
37
- /mcp
107
+ # Add (user scope)
108
+ claude mcp add --scope user slimbrowser -- npx -y slimbrowser-mcp@latest
109
+
110
+ # List / Remove
111
+ claude mcp list --scope user
112
+ claude mcp remove --scope user slimbrowser
38
113
  ```
39
114
 
40
- Remove server:
115
+ </details>
116
+
117
+ <details>
118
+ <summary><strong>Gemini CLI</strong></summary>
41
119
 
42
120
  ```bash
43
- claude mcp remove --scope local slimbrowser
121
+ # Add
122
+ gemini mcp add slimbrowser npx -y slimbrowser-mcp@latest
123
+
124
+ # List / Remove
125
+ gemini mcp list
126
+ gemini mcp remove slimbrowser
44
127
  ```
45
128
 
46
- ## What the Agent Can Do
129
+ </details>
47
130
 
48
- Core tools include:
131
+ <details>
132
+ <summary><strong>Claude Desktop</strong></summary>
49
133
 
50
- - Session: `browser_create_session`, `browser_get_session`, `browser_close_session`
51
- - Observe/Navigate: `browser_observe`, `browser_navigate`, `browser_back`, `browser_forward`, `browser_reload`
52
- - Interact: `browser_click`, `browser_type`, `browser_select`, `browser_scroll`, `browser_wait_for`
53
- - Tabs: `browser_open_tab`, `browser_list_tabs`, `browser_switch_tab`, `browser_close_tab`
54
- - Data/Artifacts: `browser_extract`, `browser_screenshot`, `browser_list_artifacts`
55
- - Diagnostics: `browser_list_console_messages`, `browser_list_network_requests`, `browser_get_performance`
134
+ Add to your Claude Desktop MCP configuration:
56
135
 
57
- Full catalog: [docs/MCP_TOOL_CATALOG.md](docs/MCP_TOOL_CATALOG.md)
136
+ ```json
137
+ {
138
+ "mcpServers": {
139
+ "slimbrowser": {
140
+ "command": "npx",
141
+ "args": ["-y", "slimbrowser-mcp@latest"]
142
+ }
143
+ }
144
+ }
145
+ ```
58
146
 
59
- ## Screenshots and Playback
147
+ </details>
60
148
 
61
- - `browser_screenshot` returns artifact metadata and saved file path.
62
- - Session capture starts with session creation (if enabled).
63
- - When the task ends, the agent should call `browser_finalize_session_capture`.
64
- - Final playback file path is returned, so it can be used in reports.
149
+ <details>
150
+ <summary><strong>Cursor</strong></summary>
65
151
 
66
- Default capture directory:
152
+ Edit `~/.cursor/mcp.json` (Windows: `%USERPROFILE%\.cursor\mcp.json`):
153
+
154
+ ```json
155
+ {
156
+ "mcpServers": {
157
+ "slimbrowser": {
158
+ "command": "npx",
159
+ "args": ["-y", "slimbrowser-mcp@latest"]
160
+ }
161
+ }
162
+ }
163
+ ```
164
+
165
+ </details>
166
+
167
+ <details>
168
+ <summary><strong>Windsurf</strong></summary>
169
+
170
+ Edit `~/.codeium/windsurf/mcp_config.json` (Windows: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`):
171
+
172
+ ```json
173
+ {
174
+ "mcpServers": {
175
+ "slimbrowser": {
176
+ "command": "npx",
177
+ "args": ["-y", "slimbrowser-mcp@latest"]
178
+ }
179
+ }
180
+ }
181
+ ```
182
+
183
+ </details>
184
+
185
+ ---
186
+
187
+ ## Arguments
188
+
189
+ All flags can be passed directly as command arguments — no `.env` file required. Append them after the base command in any client.
190
+
191
+ **CLI example:**
67
192
 
68
193
  ```bash
69
- /tmp/slimbrowser-mcp-playbacks
194
+ codex mcp add slimbrowser -- npx -y slimbrowser-mcp@latest --headless=false --enable-session-capture=true
195
+ ```
196
+
197
+ **JSON example:**
198
+
199
+ ```json
200
+ {
201
+ "mcpServers": {
202
+ "slimbrowser": {
203
+ "command": "npx",
204
+ "args": [
205
+ "-y",
206
+ "slimbrowser-mcp@latest",
207
+ "--headless=false",
208
+ "--enable-session-capture=true",
209
+ "--session-capture-dir=/tmp/slimbrowser-mcp-playbacks"
210
+ ]
211
+ }
212
+ }
213
+ }
70
214
  ```
71
215
 
72
- ## Minimal Configuration (Optional)
216
+ ### Transport & Runtime
217
+
218
+ | Flag | Values | Default | Description |
219
+ |------|--------|---------|-------------|
220
+ | `--transport` | `stdio`, `http`, `both` | `stdio` | MCP transport mode |
221
+ | `--runtime-mode` | `embedded`, `gateway` | `embedded` | Run browser engine in-process or connect to a gateway |
222
+ | `--config` | `<path>` | — | Path to a TOML config file |
223
+
224
+ ### Browser Control
225
+
226
+ | Flag | Values | Default | Description |
227
+ |------|--------|---------|-------------|
228
+ | `--headless` | `true`, `false` | `true` | Run Chrome in headless or headed mode |
229
+ | `--autostart` | `auto`, `drivers`, `none` | `auto` | Browser autostart behavior |
230
+ | `--chrome-launch-on-start` | `true`, `false` | `true` | Auto-launch Chrome when server starts |
231
+ | `--chrome-binary-path` | `<path>` | — | Path to Chrome/Chromium binary |
232
+ | `--chrome-debugger-address` | `<host:port>` | — | Connect to an existing Chrome DevTools Protocol endpoint |
233
+ | `--chrome-user-data-dir` | `<path>` | — | Chrome user data directory (profile) |
234
+
235
+ ### Session Capture
73
236
 
74
- Set only if you want overrides:
237
+ | Flag | Values | Default | Description |
238
+ |------|--------|---------|-------------|
239
+ | `--enable-session-capture` | `true`, `false` | `true` | Record screenshots after each tool call |
240
+ | `--session-capture-dir` | `<path>` | `/tmp/slimbrowser-mcp-playbacks` | Output directory for capture frames |
241
+
242
+ ---
243
+
244
+ ## Remote Chrome
245
+
246
+ SlimBrowser supports connecting to **remote Chrome/Chromium instances** — run the browser on a remote server, Docker container, CI runner, or cloud VM, and control it from anywhere.
247
+
248
+ ### Connect to a Remote Chrome Instance
249
+
250
+ Use the `--chrome-debugger-address` flag to point SlimBrowser at a Chrome instance exposing its DevTools protocol:
251
+
252
+ ```bash
253
+ npx -y slimbrowser-mcp@latest \
254
+ --chrome-debugger-address=192.168.1.100:9222
255
+ ```
256
+
257
+ ### Launch Chrome with Remote Debugging
258
+
259
+ On the remote machine, start Chrome with debugging enabled:
260
+
261
+ ```bash
262
+ # Linux / macOS
263
+ google-chrome \
264
+ --remote-debugging-port=9222 \
265
+ --remote-debugging-address=0.0.0.0 \
266
+ --no-first-run \
267
+ --no-default-browser-check \
268
+ --user-data-dir=/tmp/chrome-remote
269
+
270
+ # Docker
271
+ docker run -d \
272
+ -p 9222:9222 \
273
+ --name chrome-remote \
274
+ chromedp/headless-shell:latest \
275
+ --remote-debugging-address=0.0.0.0 \
276
+ --remote-debugging-port=9222
277
+ ```
278
+
279
+ ### Client Configuration for Remote Chrome
280
+
281
+ **CLI agents (Codex, Claude Code, Gemini CLI):**
282
+
283
+ ```bash
284
+ codex mcp add slimbrowser -- \
285
+ npx -y slimbrowser-mcp@latest \
286
+ --chrome-debugger-address=your-server:9222
287
+ ```
288
+
289
+ **JSON-based clients (Claude Desktop, Cursor, Windsurf):**
290
+
291
+ ```json
292
+ {
293
+ "mcpServers": {
294
+ "slimbrowser": {
295
+ "command": "npx",
296
+ "args": [
297
+ "-y",
298
+ "slimbrowser-mcp@latest",
299
+ "--chrome-debugger-address=your-server:9222"
300
+ ]
301
+ }
302
+ }
303
+ }
304
+ ```
305
+
306
+ ### Custom Chrome Binary & Profile
307
+
308
+ For environments with non-standard Chrome installations:
75
309
 
76
310
  ```bash
77
- # MCP transport/runtime
78
- MCP_TRANSPORT=stdio
79
- MCP_RUNTIME_MODE=embedded
311
+ npx -y slimbrowser-mcp@latest \
312
+ --chrome-binary-path=/opt/google/chrome/chrome \
313
+ --chrome-user-data-dir=/home/user/.config/chromium
314
+ ```
315
+
316
+ ### Common Remote Scenarios
317
+
318
+ | Scenario | Flags |
319
+ |----------|-------|
320
+ | Chrome on another machine | `--chrome-debugger-address=<host>:9222` |
321
+ | Chrome in Docker | `--chrome-debugger-address=localhost:9222` (with `-p 9222:9222`) |
322
+ | Chrome on a cloud VM | `--chrome-debugger-address=<vm-ip>:9222` (ensure port is open) |
323
+ | Skip auto-launch, use existing Chrome | `--chrome-launch-on-start=false --chrome-debugger-address=localhost:9222` |
324
+ | Custom Chrome binary | `--chrome-binary-path=/path/to/chrome` |
325
+ | Custom Chrome profile | `--chrome-user-data-dir=/path/to/profile` |
326
+
327
+ ---
328
+
329
+ ## MCP Tool Catalog
330
+
331
+ SlimBrowser exposes **42 tools** organized into 9 categories. Every tool follows consistent conventions:
332
+
333
+ - `session_id` is **always optional** — omit it to use the default session
334
+ - `tab_id` is **optional** — omit it to target the active tab
335
+ - `timeout_ms` is **optional** — override the default wait timeout
336
+ - Tools marked **read-only** make no mutations; tools marked **idempotent** are safe to retry
337
+
338
+ ---
339
+
340
+ ### Session Management
341
+
342
+ Create, inspect, and close browser sessions with optional session capture for full playback.
343
+
344
+ | Tool | Description | Key Parameters |
345
+ |------|-------------|----------------|
346
+ | `browser_create_session` | Create a new browser session | `tenant_id?`, `profile?`, `browser?`, `policy?` |
347
+ | `browser_get_session` | Get session details | `session_id?` |
348
+ | `browser_close_session` | Close a session (auto-finalizes capture) | `session_id?`, `final_feedback?` |
349
+ | `browser_set_default_session` | Set the default session for this client | `session_id` |
350
+ | `browser_get_session_capture` | Get capture/playback metadata | `session_id?` |
351
+ | `browser_finalize_session_capture` | Finalize recording and generate playback HTML | `session_id?`, `final_feedback?` |
352
+
353
+ <details>
354
+ <summary><strong>Session profiles & policies</strong></summary>
80
355
 
81
- # Chrome mode
82
- CHROME_HEADLESS=false
356
+ **Profiles** control default behavior presets:
83
357
 
84
- # Session capture
85
- MCP_ENABLE_SESSION_CAPTURE=true
86
- MCP_SESSION_CAPTURE_DIR=/tmp/slimbrowser-mcp-playbacks
358
+ | Profile | Use Case |
359
+ |---------|----------|
360
+ | `agent` | General-purpose AI agent browsing (default) |
361
+ | `test` | E2E test automation |
362
+ | `security` | Security auditing and passive crawling |
363
+ | `scrape` | Data extraction and scraping |
364
+
365
+ **Policies** control security boundaries:
366
+
367
+ | Policy | Behavior |
368
+ |--------|----------|
369
+ | `strict` | Restricted navigation, no script eval |
370
+ | `configurable` | Balanced defaults with overrides (default) |
371
+ | `unrestricted` | Full access, no guardrails |
372
+
373
+ </details>
374
+
375
+ <details>
376
+ <summary><strong>Session capture output</strong></summary>
377
+
378
+ When session capture is enabled, each tool call produces a frame:
379
+
380
+ ```
381
+ /tmp/slimbrowser-mcp-playbacks/
382
+ {session_id}/
383
+ playback/
384
+ 001_browser_navigate.png
385
+ 002_browser_click.png
386
+ 003_browser_type.png
387
+ ...
388
+ manifest.json
389
+ playback.html ← open this to replay visually
87
390
  ```
88
391
 
89
- Config resolution order:
392
+ </details>
393
+
394
+ ---
395
+
396
+ ### Observation & Navigation
397
+
398
+ Read page state and navigate between URLs. The observation system is the core of SlimBrowser's token efficiency.
399
+
400
+ | Tool | Description | Key Parameters | Traits |
401
+ |------|-------------|----------------|--------|
402
+ | `browser_observe` | Read current page state | `mode?`, `region?` | Read-only, Idempotent |
403
+ | `browser_snapshot` | Capture a point-in-time observation | `mode?`, `region?` | Read-only, Idempotent |
404
+ | `browser_navigate` | Navigate to a URL | `url`, `timeout_ms?` | |
405
+ | `browser_back` | Go back in history | `timeout_ms?` | |
406
+ | `browser_forward` | Go forward in history | `timeout_ms?` | |
407
+ | `browser_reload` | Reload current page | `timeout_ms?` | |
408
+
409
+ <details>
410
+ <summary><strong>Observation modes — the core of token efficiency</strong></summary>
411
+
412
+ The observation system is what makes SlimBrowser dramatically more token-efficient than alternatives. Instead of dumping the entire DOM, you choose exactly how much detail you need:
413
+
414
+ | Mode | Token Cost | What You Get | When to Use |
415
+ |------|-----------|--------------|-------------|
416
+ | `SUMMARY` | **~50-200 tokens** | Page title, URL, interactable elements with compact EIDs, state hints | Default — use for 90% of interactions |
417
+ | `REGION` | **~200-500 tokens** | Focused observation of a specific page region | When you need detail on a specific area |
418
+ | `FULL` | **~500-2000 tokens** | Complete page content with all elements | Last resort when SUMMARY isn't enough |
419
+
420
+ Compare this to other tools that send **5,000-30,000 tokens per page observation** regardless of what you need.
421
+
422
+ The observation payload includes:
423
+ - **Interactables** — clickable/typeable elements with compact `eid`, `role`, `name`, `hint`, `state`, and `bbox`
424
+ - **Delta** — only what changed since the last observation (subsequent calls are even cheaper)
425
+ - **Budget** — remaining token/screenshot/retry budgets to prevent runaway context growth
426
+
427
+ **Pro tip:** Start with `SUMMARY` mode. Only escalate to `REGION` or `FULL` if the agent needs more context. This single practice can cut your token usage by 80%+ compared to full-DOM approaches.
428
+
429
+ </details>
430
+
431
+ ---
432
+
433
+ ### Interaction
434
+
435
+ Click, type, select, scroll, and wait. All interaction tools return a normalized action response.
436
+
437
+ | Tool | Description | Key Parameters |
438
+ |------|-------------|----------------|
439
+ | `browser_click` | Click an element by EID | `eid`, `timeout_ms?` |
440
+ | `browser_type` | Type text into an element | `eid`, `text`, `timeout_ms?` |
441
+ | `browser_select` | Select a dropdown option | `eid`, `option`, `timeout_ms?` |
442
+ | `browser_scroll` | Scroll the page | `dx?`, `dy?`, `timeout_ms?` |
443
+ | `browser_wait_for` | Wait for a condition to be true | `predicate`, `timeout_ms?` |
444
+
445
+ <details>
446
+ <summary><strong>Action response format</strong></summary>
447
+
448
+ Every interaction tool returns:
449
+
450
+ ```json
451
+ {
452
+ "action_id": "act_abc123",
453
+ "status": "OK | FAILED | AMBIGUOUS | BLOCKED",
454
+ "message": "Human-readable result",
455
+ "evidence": [],
456
+ "delta": { "...changes since last observation..." },
457
+ "budget": { "...remaining budgets..." }
458
+ }
459
+ ```
460
+
461
+ | Status | Meaning |
462
+ |--------|---------|
463
+ | `OK` | Action completed successfully |
464
+ | `FAILED` | Action could not be performed |
465
+ | `AMBIGUOUS` | Multiple matches found — refine your selector |
466
+ | `BLOCKED` | Action blocked by policy or page state |
467
+
468
+ </details>
469
+
470
+ ---
471
+
472
+ ### Tab Management
473
+
474
+ Open, switch, pin, and close tabs. Full multi-tab orchestration for complex workflows.
475
+
476
+ | Tool | Description | Key Parameters | Traits |
477
+ |------|-------------|----------------|--------|
478
+ | `browser_open_tab` | Open a new tab | `url?` (defaults to `about:blank`) | |
479
+ | `browser_list_tabs` | List all tabs in session | | Read-only, Idempotent |
480
+ | `browser_switch_tab` | Switch the active tab | `tab_id` | |
481
+ | `browser_close_tab` | Close a tab | `tab_id` | |
482
+ | `browser_pin_tab` | Pin or unpin a tab | `tab_id`, `pinned?` | |
483
+
484
+ ---
485
+
486
+ ### Macro & Discovery Tools
487
+
488
+ High-level tools that combine multiple primitives for common operations.
90
489
 
91
- 1. `--config <path>`
92
- 2. `MCP_CONFIG=<path>`
93
- 3. `./configs/mcp.toml`
94
- 4. `./mcp.toml`
95
- 5. `$HOME/.config/slimbrowser-mcp/mcp.toml`
96
- 6. Built-in defaults
490
+ | Tool | Description | Key Parameters |
491
+ |------|-------------|----------------|
492
+ | `browser_fill_form` | Fill multiple form fields at once | `fields` (object: `label -> value`) |
493
+ | `browser_click_by_text` | Click the first element matching text | `text`, `timeout_ms?` |
494
+ | `browser_type_by_label` | Type into an input matching a label | `label`, `text`, `timeout_ms?` |
495
+ | `browser_find_interactables` | Search for interactive elements | `query` |
496
+
497
+ <details>
498
+ <summary><strong>Example: fill a login form in one call</strong></summary>
499
+
500
+ ```json
501
+ {
502
+ "tool": "browser_fill_form",
503
+ "arguments": {
504
+ "fields": {
505
+ "Email": "user@example.com",
506
+ "Password": "••••••••"
507
+ }
508
+ }
509
+ }
510
+ ```
511
+
512
+ This finds each field by label and types the value — replacing what would be 4+ separate tool calls.
513
+
514
+ </details>
515
+
516
+ ---
517
+
518
+ ### Data Extraction & Artifacts
519
+
520
+ Extract structured data from pages, capture screenshots, and manage session artifacts.
521
+
522
+ | Tool | Description | Key Parameters | Traits |
523
+ |------|-------------|----------------|--------|
524
+ | `browser_extract` | Extract structured data using a JSON schema | `schema?` | Read-only, Idempotent |
525
+ | `browser_screenshot` | Capture a screenshot | `output_dir?`, `file_name?` | Idempotent |
526
+ | `browser_list_artifacts` | List all session artifacts | | Read-only, Idempotent |
527
+
528
+ <details>
529
+ <summary><strong>Screenshot output</strong></summary>
530
+
531
+ ```json
532
+ {
533
+ "artifact": {
534
+ "id": "art_xyz",
535
+ "path": "/internal/path/screenshot.png",
536
+ "size_bytes": 45320,
537
+ "created_at": "2025-01-15T10:30:00Z"
538
+ },
539
+ "artifact_path": "/internal/path/screenshot.png",
540
+ "saved_path": "/tmp/my-dir/screenshot.png",
541
+ "exported_path": "/tmp/my-dir/screenshot.png"
542
+ }
543
+ ```
544
+
545
+ </details>
546
+
547
+ ---
548
+
549
+ ### Diagnostics & Performance
550
+
551
+ Inspect console logs, network traffic, dialogs, and performance metrics — all through paginated, structured APIs.
552
+
553
+ | Tool | Description | Key Parameters | Traits |
554
+ |------|-------------|----------------|--------|
555
+ | `browser_evaluate_script` | Execute JavaScript in the page | `script`, `args?` | |
556
+ | `browser_list_console_messages` | Read console logs (paginated) | `cursor?`, `limit?` | Read-only, Idempotent |
557
+ | `browser_get_console_message` | Get a single console message | `message_id` | Read-only, Idempotent |
558
+ | `browser_list_network_requests` | Read network requests (paginated) | `cursor?`, `limit?` | Read-only, Idempotent |
559
+ | `browser_get_network_request` | Get a single network request | `request_id` | Read-only, Idempotent |
560
+ | `browser_list_dialogs` | Read alert/confirm/prompt dialogs | `cursor?`, `limit?` | Read-only, Idempotent |
561
+ | `browser_handle_dialog` | Accept or dismiss a dialog | `dialog_id`, `action?`, `text?` | |
562
+ | `browser_get_performance` | Get navigation & resource timing | | Read-only, Idempotent |
563
+
564
+ ---
565
+
566
+ ### Tracing & Replay
567
+
568
+ Record execution traces and replay them for debugging and reproducibility.
569
+
570
+ | Tool | Description | Traits |
571
+ |------|-------------|--------|
572
+ | `browser_get_trace` | Get all trace events for a session | Read-only, Idempotent |
573
+ | `browser_replay_trace` | Replay recorded trace events | Idempotent |
574
+
575
+ ---
576
+
577
+ ### Capability & Mode
578
+
579
+ Query and configure runtime capabilities.
580
+
581
+ | Tool | Description | Key Parameters | Traits |
582
+ |------|-------------|----------------|--------|
583
+ | `browser_capabilities` | Get supported browsers, modes, and features | | Read-only, Idempotent |
584
+ | `browser_get_headless_mode` | Check current headless/headed mode | | Read-only, Idempotent |
585
+ | `browser_set_headless_mode` | Switch between headless and headed | `headless` (boolean) | |
586
+
587
+ ---
97
588
 
98
589
  ## Troubleshooting
99
590
 
100
- - If `/mcp` shows `connecting` or `failed`, run: `npx -y slimbrowser-mcp doctor`
101
- - If Chrome cannot be controlled, confirm Chrome is installed and retry.
102
- - If a tool fails, use `browser_get_trace` and `browser_list_artifacts` for debugging evidence.
591
+ **Server won't connect or shows `connecting` / `failed`:**
592
+
593
+ ```bash
594
+ npx -y slimbrowser-mcp@latest doctor
595
+ ```
596
+
597
+ **Chrome not found:**
598
+ - Ensure Chrome/Chromium is installed locally, or
599
+ - Point to it with `--chrome-binary-path=/path/to/chrome`
600
+
601
+ **Remote Chrome not reachable:**
602
+ - Verify the remote Chrome was started with `--remote-debugging-port=9222 --remote-debugging-address=0.0.0.0`
603
+ - Check firewall rules allow traffic on the debugging port
604
+ - Test connectivity: `curl http://<host>:9222/json/version`
605
+
606
+ **Action failures:**
607
+ - Use `browser_get_trace` to inspect the execution trace
608
+ - Use `browser_list_artifacts` to find screenshots and other evidence
609
+ - Use the `triage_failed_action_with_artifacts` prompt for AI-assisted diagnosis
610
+
611
+ **Session capture not working:**
612
+ - Ensure `--enable-session-capture=true` is set
613
+ - Check that `--session-capture-dir` points to a writable directory
614
+
615
+ ---
103
616
 
104
617
  ## License
105
618
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "slimbrowser-mcp",
3
- "version": "0.1.1",
3
+ "version": "0.1.4",
4
4
  "description": "npx bootstrap launcher for slimbrowser-mcp",
5
5
  "publishConfig": {
6
6
  "access": "public"