slimbrowser-mcp 0.1.0 → 0.1.1

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 +50 -215
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,270 +1,105 @@
1
- <p align="center">
2
- <h1 align="center">slimbrowser-mcp</h1>
3
- <p align="center">A token-efficient browser MCP for AI agents. Minimal context, maximum visibility.</p>
4
- </p>
1
+ # slimbrowser-mcp
5
2
 
6
- <p align="center">
7
- <a href="#quickstart">Quickstart</a> &middot;
8
- <a href="#one-command-bootstrap">One-command Bootstrap</a> &middot;
9
- <a href="#packaging-for-distribution">Packaging</a> &middot;
10
- <a href="#why-slimbrowser-mcp">Why slimbrowser-mcp</a> &middot;
11
- <a href="#architecture">Architecture</a> &middot;
12
- <a href="#tool-catalog">Tools</a> &middot;
13
- <a href="#claude-code-integration">Claude Code</a> &middot;
14
- <a href="docs/MCP_TOOL_CATALOG.md">Full Tool Reference</a>
15
- </p>
3
+ A token-efficient browser MCP server for AI agents.
16
4
 
17
- <p align="center">
18
- <img src="https://img.shields.io/badge/rust-1.78+-orange?logo=rust" alt="Rust 1.78+">
19
- <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License">
20
- <img src="https://img.shields.io/badge/MCP-compatible-green" alt="MCP Compatible">
21
- <img src="https://img.shields.io/badge/browser-Chrome-yellow?logo=googlechrome" alt="Chrome">
22
- </p>
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
23
9
 
24
- ---
10
+ ## Quickstart (End Users)
25
11
 
26
- ## Why slimbrowser-mcp
27
-
28
- Browser automation for AI agents is expensive. A single page observation can consume **15,000-30,000 tokens** with traditional tools. Over a typical multi-step workflow, that adds up fast.
29
-
30
- slimbrowser-mcp takes a different approach:
31
-
32
- | Approach | Tokens per page read | 12-step workflow |
33
- |---|---|---|
34
- | Chrome DevTools MCP | 15,000 - 30,000 | ~200K - 380K |
35
- | Playwright MCP | 14,000 - 19,000 | ~180K - 250K |
36
- | Claude in Chrome | 4,000 - 8,000 | ~80K - 120K |
37
- | **slimbrowser-mcp** | **1,000 - 3,000** | **~30K - 50K** |
38
-
39
- **Up to 85% fewer tokens** than Chrome DevTools MCP. Up to 56% fewer than Claude in Chrome.
40
-
41
- ### How
42
-
43
- - **Compressed observations** &mdash; `browser_observe(SUMMARY)` returns only interactive elements, not the full DOM or accessibility tree
44
- - **Schema-based extraction** &mdash; `browser_extract` pulls exactly the data you ask for, nothing more
45
- - **Smart deltas** &mdash; only report what changed between actions, not the entire page state
46
- - **Budget tracking** &mdash; built-in token/screenshot budget per session so agents stay within limits
47
-
48
- ---
49
-
50
- ## Quickstart
51
-
52
- ```bash
53
- # Clone
54
- git clone git@github.com:Naresh084/slimbrowse.git
55
- cd slimbrowse
56
-
57
- # Run diagnostics
58
- cargo run -p slimbrowser-mcp -- doctor
59
-
60
- # Start the MCP server
61
- cargo run -p slimbrowser-mcp
62
- ```
63
-
64
- No `.env` required. Sensible defaults are built in. Use `.env` only to override (see [`.env.example`](.env.example)).
65
-
66
- ---
67
-
68
- ## One-command Bootstrap
69
-
70
- No manual install flow required:
12
+ ### 1) Run doctor
71
13
 
72
14
  ```bash
73
- ./scripts/slimbrowser-mcp-bootstrap.sh doctor
74
- ./scripts/slimbrowser-mcp-bootstrap.sh
15
+ npx -y slimbrowser-mcp doctor
75
16
  ```
76
17
 
77
- This auto-installs `slimbrowser-mcp` under `~/.slimbrowser-mcp/bin` on first run, then runs it directly.
78
-
79
- `npx`-style local launcher is also available:
18
+ ### 2) Start MCP server
80
19
 
81
20
  ```bash
82
- npx --yes /Users/naresh/Work/Personal/browser-test doctor
21
+ npx -y slimbrowser-mcp
83
22
  ```
84
23
 
85
- ---
24
+ No `.env` is required for default usage.
86
25
 
87
- ## Packaging for Distribution
26
+ ## Connect to Claude Code
88
27
 
89
- Build distributable artifacts:
28
+ Add server:
90
29
 
91
30
  ```bash
92
- ./scripts/package-release.sh
31
+ claude mcp add --scope local slimbrowser -- npx -y slimbrowser-mcp
93
32
  ```
94
33
 
95
- This creates platform-specific `.tar.gz` + `.zip` + checksum in `dist/`.
96
-
97
- Install from an unpacked package:
34
+ Check status:
98
35
 
99
36
  ```bash
100
- ./scripts/install-from-package.sh ./slimbrowser-mcp-<version>-<target>
37
+ /mcp
101
38
  ```
102
39
 
103
- Full distribution instructions: [docs/DISTRIBUTION.md](docs/DISTRIBUTION.md)
104
- Publish instructions: [docs/PUBLISH.md](docs/PUBLISH.md)
105
-
106
- ---
40
+ Remove server:
107
41
 
108
- ## Architecture
109
-
110
- slimbrowser-mcp is a Rust workspace with a modular crate structure:
111
-
112
- ```
113
- slimbrowse/
114
- ├── apps/
115
- │ ├── slimbrowser-mcp # MCP server binary (stdio + HTTP)
116
- │ ├── slimbrowser-cli # Standalone CLI
117
- │ └── slimbrowserd # Daemon mode
118
- ├── crates/
119
- │ ├── engine-chromium # Chrome CDP adapter
120
- │ ├── runtime-observe # Compressed page observations
121
- │ ├── runtime-extract # Schema-based data extraction
122
- │ ├── runtime-actions # Click, type, scroll, navigate
123
- │ ├── runtime-cost # Token budget tracking
124
- │ ├── runtime-artifacts # Screenshot & artifact storage
125
- │ ├── runtime-policy # Session policy (strict/unrestricted)
126
- │ ├── session-manager # Multi-session lifecycle
127
- │ ├── tab-graph # Tab state management
128
- │ ├── mcp-server # MCP protocol layer
129
- │ ├── mcp-types # MCP type definitions
130
- │ ├── sdk-rust # Rust SDK for embedding
131
- │ └── ... # 12 more internal crates
132
- ├── configs/ # Default MCP config (TOML)
133
- ├── examples/ # Smoke tests & usage scripts
134
- └── docs/ # Tool catalog & resource docs
42
+ ```bash
43
+ claude mcp remove --scope local slimbrowser
135
44
  ```
136
45
 
137
- ### Key design decisions
138
-
139
- - **Chrome-only, CDP-first** &mdash; No WebDriver. Direct Chrome DevTools Protocol for speed and reliability.
140
- - **Embedded auto-launch** &mdash; MCP server auto-launches Chrome on first session. Auto-stops on shutdown.
141
- - **Headed by default** &mdash; You see exactly what the agent sees. Switch to headless with one env var.
142
- - **Session capture** &mdash; Every session records a playback trace for debugging and demos.
143
-
144
- ---
46
+ ## What the Agent Can Do
145
47
 
146
- ## Tool Catalog
48
+ Core tools include:
147
49
 
148
- 40+ browser tools organized by category:
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`
149
56
 
150
- ### Session Management
151
- | Tool | Description |
152
- |---|---|
153
- | `browser_create_session` | Create a new browser session with profile & policy |
154
- | `browser_close_session` | Close session with optional feedback |
155
- | `browser_get_session` | Get session state |
57
+ Full catalog: [docs/MCP_TOOL_CATALOG.md](docs/MCP_TOOL_CATALOG.md)
156
58
 
157
- ### Observation & Navigation
158
- | Tool | Description |
159
- |---|---|
160
- | `browser_observe` | Compressed page state (SUMMARY / REGION / FULL) |
161
- | `browser_navigate` | Navigate to URL |
162
- | `browser_scroll` | Scroll page by delta |
163
- | `browser_back` / `browser_forward` | History navigation |
59
+ ## Screenshots and Playback
164
60
 
165
- ### Interaction
166
- | Tool | Description |
167
- |---|---|
168
- | `browser_click` | Click element by ID |
169
- | `browser_type` | Type text into element |
170
- | `browser_fill_form` | Fill multiple form fields at once |
171
- | `browser_select` | Select dropdown option |
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.
172
65
 
173
- ### Extraction & Artifacts
174
- | Tool | Description |
175
- |---|---|
176
- | `browser_extract` | Schema-based structured data extraction |
177
- | `browser_screenshot` | Capture screenshot with export options |
178
- | `browser_evaluate_script` | Execute JavaScript in page |
179
-
180
- ### Diagnostics
181
- | Tool | Description |
182
- |---|---|
183
- | `browser_list_console_messages` | Read console output |
184
- | `browser_list_network_requests` | Inspect network traffic |
185
- | `browser_get_performance` | Page performance metrics |
186
-
187
- [Full tool reference &rarr;](docs/MCP_TOOL_CATALOG.md)
188
-
189
- ---
190
-
191
- ## Claude Code Integration
192
-
193
- Install the binary:
194
-
195
- ```bash
196
- cargo install --path apps/slimbrowser-mcp
197
- ```
198
-
199
- Register with Claude Code:
200
-
201
- ```bash
202
- claude mcp add --scope local slimbrowser -- slimbrowser-mcp
203
- ```
204
-
205
- Verify:
206
-
207
- ```bash
208
- # Inside Claude Code, run:
209
- /mcp
210
- # Look for "slimbrowser" in the connected servers list
211
- ```
212
-
213
- Remove:
66
+ Default capture directory:
214
67
 
215
68
  ```bash
216
- claude mcp remove --scope local slimbrowser
69
+ /tmp/slimbrowser-mcp-playbacks
217
70
  ```
218
71
 
219
- ---
220
-
221
- ## Configuration
72
+ ## Minimal Configuration (Optional)
222
73
 
223
- slimbrowser-mcp works out of the box. Override defaults via `.env` or environment variables:
74
+ Set only if you want overrides:
224
75
 
225
76
  ```bash
226
- # Transport
227
- MCP_TRANSPORT=stdio # stdio | http | both
228
- MCP_RUNTIME_MODE=embedded # embedded | remote
77
+ # MCP transport/runtime
78
+ MCP_TRANSPORT=stdio
79
+ MCP_RUNTIME_MODE=embedded
229
80
 
230
- # Browser
231
- CHROME_HEADLESS=false # true for headless mode
232
- CHROME_LAUNCH_ON_START=true # auto-launch Chrome
81
+ # Chrome mode
82
+ CHROME_HEADLESS=false
233
83
 
234
84
  # Session capture
235
85
  MCP_ENABLE_SESSION_CAPTURE=true
236
86
  MCP_SESSION_CAPTURE_DIR=/tmp/slimbrowser-mcp-playbacks
237
-
238
- # HTTP mode (optional)
239
- MCP_HTTP_BIND=127.0.0.1:3100
240
- MCP_HTTP_ENDPOINT=/mcp
241
87
  ```
242
88
 
243
- Config file discovery order:
89
+ Config resolution order:
90
+
244
91
  1. `--config <path>`
245
92
  2. `MCP_CONFIG=<path>`
246
93
  3. `./configs/mcp.toml`
247
94
  4. `./mcp.toml`
248
95
  5. `$HOME/.config/slimbrowser-mcp/mcp.toml`
249
- 6. Built-in defaults + `.env`
250
-
251
- ---
96
+ 6. Built-in defaults
252
97
 
253
- ## Development
254
-
255
- ```bash
256
- # Check everything compiles
257
- cargo check --workspace
258
-
259
- # Run tests
260
- cargo test --workspace
261
-
262
- # Lint
263
- cargo fmt --all -- --check
264
- cargo clippy --workspace --all-targets -- -D warnings
265
- ```
98
+ ## Troubleshooting
266
99
 
267
- ---
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.
268
103
 
269
104
  ## License
270
105
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "slimbrowser-mcp",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "npx bootstrap launcher for slimbrowser-mcp",
5
5
  "publishConfig": {
6
6
  "access": "public"