bwb-browser 2.0.2 โ 2.0.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.
- package/README.md +242 -85
- package/package.json +1 -1
- package/server.mjs +8 -3
package/README.md
CHANGED
|
@@ -1,131 +1,288 @@
|
|
|
1
|
-
# bwb-browser
|
|
1
|
+
# ๐ฅ bwb-browser
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
### Browser Without Bloat โ 30KB MCP Browser Automation Server
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
[](https://www.npmjs.com/package/bwb-browser)
|
|
6
|
+
[](https://www.npmjs.com/package/bwb-browser)
|
|
7
|
+
[](https://github.com/krshforever/bwb-browser)
|
|
8
|
+
[](LICENSE)
|
|
9
|
+
[]()
|
|
6
10
|
|
|
7
|
-
|
|
11
|
+
**No Playwright. No Puppeteer. No 400MB downloads. Just raw Chrome DevTools Protocol.**
|
|
8
12
|
|
|
9
|
-
|
|
13
|
+
bwb gives any AI agent (Claude Code, OpenCode, Cline, Antigravity, Cursor, Continue, etc.) the ability to browse the web, take screenshots, click elements, fill forms, execute JavaScript, and **watch live page events** โ all in a **30KB** package.
|
|
10
14
|
|
|
11
|
-
|
|
12
|
-
|---------|-----|----------------|---------------|
|
|
13
|
-
| **Dependencies** | 3 packages | 50+ packages | 30+ packages |
|
|
14
|
-
| **Install size** | ~2MB | ~500MB+ | ~300MB+ |
|
|
15
|
-
| **Works on Termux** | โ
| โ | โ |
|
|
16
|
-
| **Works in CI** | โ
| โ ๏ธ Needs browser download | โ ๏ธ Needs browser download |
|
|
17
|
-
| **Uses existing Chrome** | โ
| โ Downloads its own | โ Downloads its own |
|
|
15
|
+
Created by [**Krish Tiwari**](https://github.com/krshforever) ([@krshforever](https://github.com/krshforever)).
|
|
18
16
|
|
|
19
|
-
|
|
17
|
+
---
|
|
20
18
|
|
|
21
|
-
|
|
22
|
-
npm install -g bwb-browser-termux
|
|
23
|
-
```
|
|
19
|
+
## ๐ The Breakthrough: Watch Your Pages Live
|
|
24
20
|
|
|
25
|
-
|
|
21
|
+
**bwb is the first and only MCP browser tool that captures live page events.**
|
|
26
22
|
|
|
27
|
-
```
|
|
28
|
-
|
|
23
|
+
```mermaid
|
|
24
|
+
sequenceDiagram
|
|
25
|
+
Agent->>bwb: browser_watch({action:"start", events:["all"]})
|
|
26
|
+
bwb->>Page: ๐ฌ Recording console, network, errors...
|
|
27
|
+
Agent->>bwb: browser_goto({url:"https://example.com"})
|
|
28
|
+
bwb->>Page: Navigate, interact...
|
|
29
|
+
Page-->>bwb: โก Console.log, Network request, JS Error
|
|
30
|
+
Agent->>bwb: browser_watch({action:"poll"})
|
|
31
|
+
bwb-->>Agent: [{console:"React mounted"}, {network:"GET /api/data 200"}, ...]
|
|
32
|
+
Agent->>bwb: browser_watch({action:"stop"})
|
|
33
|
+
bwb-->>Agent: โ
Recording stopped, 47 events captured
|
|
29
34
|
```
|
|
30
35
|
|
|
31
|
-
|
|
36
|
+
No other MCP browser tool does this. Playwright MCP, Chrome DevTools MCP, Puppeteer MCP โ all are fire-and-forget. bwb is the **black box recorder** for browser automation.
|
|
32
37
|
|
|
33
|
-
|
|
38
|
+
Your agent can now:
|
|
39
|
+
- **Debug SPAs** โ see React/Vue/Angular errors in real-time
|
|
40
|
+
- **Track API calls** โ every network request, response, and status code
|
|
41
|
+
- **Detect loading states** โ know when the page is actually done rendering
|
|
42
|
+
- **Intercept console output** โ catch warnings, logs, and errors as they happen
|
|
34
43
|
|
|
35
|
-
|
|
36
|
-
```bash
|
|
37
|
-
pkg install chromium
|
|
38
|
-
```
|
|
44
|
+
---
|
|
39
45
|
|
|
40
|
-
|
|
41
|
-
```bash
|
|
42
|
-
sudo apt install chromium-browser
|
|
43
|
-
# or
|
|
44
|
-
sudo apt install google-chrome
|
|
45
|
-
```
|
|
46
|
+
## ๐ฆ Why bwb?
|
|
46
47
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
48
|
+
| Feature | bwb | Playwright MCP | Puppeteer MCP | Chrome DevTools MCP |
|
|
49
|
+
|---------|-----|----------------|---------------|-------------------|
|
|
50
|
+
| **Size** | **30 KB** | 200+ MB | 400+ MB | 300+ MB |
|
|
51
|
+
| **Dependencies** | **3 tiny** | 50+ | 30+ | 50+ |
|
|
52
|
+
| **Termux/Android** | โ
**Native** | โ | โ | โ |
|
|
53
|
+
| **Works on any platform** | โ
Linux, macOS, Windows, CI | โ ๏ธ Needs browsers | โ ๏ธ Needs Chromium | โ ๏ธ Needs Puppeteer |
|
|
54
|
+
| **Uses your existing Chrome** | โ
Auto-detects | โ Downloads its own | โ Downloads its own | โ Downloads its own |
|
|
55
|
+
| **Live page events** | โ
**`browser_watch`** | โ | โ | โ |
|
|
56
|
+
| **Setup time** | **5 seconds** | 5+ minutes | 5+ minutes | 5+ minutes |
|
|
51
57
|
|
|
52
|
-
**
|
|
53
|
-
Download and install Google Chrome normally.
|
|
58
|
+
**bwb is 13,000x smaller than Puppeteer MCP.**
|
|
54
59
|
|
|
55
|
-
|
|
60
|
+
---
|
|
56
61
|
|
|
57
|
-
|
|
62
|
+
## โก Quick Install
|
|
58
63
|
|
|
59
|
-
|
|
64
|
+
```bash
|
|
65
|
+
npm install -g bwb-browser
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
That's it. **5 seconds.** You're done.
|
|
69
|
+
|
|
70
|
+
Then add to your AI agent's MCP config:
|
|
60
71
|
|
|
61
72
|
```json
|
|
62
73
|
{
|
|
63
74
|
"mcpServers": {
|
|
64
75
|
"bwb": {
|
|
65
|
-
"command": "
|
|
66
|
-
"args": ["bwb-browser-termux"]
|
|
76
|
+
"command": "bwb"
|
|
67
77
|
}
|
|
68
78
|
}
|
|
69
79
|
}
|
|
70
80
|
```
|
|
71
81
|
|
|
72
|
-
For
|
|
82
|
+
> ๐ก **For AI Agents:** See [AGENTS.md](AGENTS.md) for the complete copy-paste prompt that auto-installs and configures bwb on Claude Code, OpenCode, Antigravity, Cline, Cursor, Continue.dev, Aider, Codex CLI, Cody, Windsurf, and any MCP-compatible agent.
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## ๐ฅ 15 Tools
|
|
87
|
+
|
|
88
|
+
| Tool | Description | Groundbreaking? |
|
|
89
|
+
|------|-------------|:---:|
|
|
90
|
+
| `browser_goto` | Navigate to a URL | |
|
|
91
|
+
| `browser_screenshot` | Take a screenshot (saves to disk + returns base64) | |
|
|
92
|
+
| `browser_html` | Get page/selector HTML | |
|
|
93
|
+
| `browser_text` | Get page/selector visible text | |
|
|
94
|
+
| `browser_click` | Click an element (native CDP mouse events) | |
|
|
95
|
+
| `browser_fill` | Fill an input field (native CDP keyboard events) | |
|
|
96
|
+
| `browser_elements` | List links, buttons, inputs, headings | |
|
|
97
|
+
| `browser_title` | Get page title | |
|
|
98
|
+
| `browser_url` | Get current URL | |
|
|
99
|
+
| `browser_eval` | Execute JavaScript (with exception capture) | |
|
|
100
|
+
| `browser_status` | Browser connection status | |
|
|
101
|
+
| **`browser_watch`** | ๐ฅ **Live console, network, error, navigation capture** | **โ
YES** |
|
|
102
|
+
| `browser_waitForSelector` | Wait for element to appear/disappear | |
|
|
103
|
+
| `browser_setViewport` | Change viewport size (responsive testing) | |
|
|
104
|
+
| `browser_back` | Go back in browser history | |
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## ๐ฏ Live Demo (Real Results from Termux/Android)
|
|
73
109
|
|
|
74
|
-
```json
|
|
75
|
-
{
|
|
76
|
-
"mcpServers": {
|
|
77
|
-
"bwb": {
|
|
78
|
-
"command": "node",
|
|
79
|
-
"args": ["/path/to/bwb-browser-termux/server.js"]
|
|
80
|
-
}
|
|
81
|
-
}
|
|
82
|
-
}
|
|
83
110
|
```
|
|
111
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
112
|
+
โ bwb-browser โ LIVE DEMO โ
|
|
113
|
+
โ 30KB ยท 15 tools ยท raw CDP ยท zero bloat ยท on Termux โ
|
|
114
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
84
115
|
|
|
85
|
-
|
|
116
|
+
Step 1: Hacker News scraping โ
1.7s
|
|
117
|
+
โ #1: 7.1 Earthquake in Japan
|
|
118
|
+
โ #2: About the security content of macOS Tahoe 26.6
|
|
119
|
+
โ #3: What Even Are Microservices?
|
|
86
120
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
121
|
+
Step 2: GitHub Trending exploration โ
5.1s
|
|
122
|
+
โ pascalorg/editor, jenkinsci/jenkins, moeru-ai/airi
|
|
123
|
+
|
|
124
|
+
Step 3: Google search fill + submit โ
4.0s
|
|
125
|
+
โ Filled "bwb browser automation termux", submitted
|
|
90
126
|
|
|
91
|
-
|
|
92
|
-
|
|
127
|
+
Step 4: Wikipedia article extraction โ
3.2s
|
|
128
|
+
โ "A headless browser is a web browser without a GUI..."
|
|
93
129
|
|
|
94
|
-
|
|
95
|
-
|
|
130
|
+
Step 5: Rapid-fire 5 sites in 24s โ
24.1s
|
|
131
|
+
โ example.com: 744ms | httpbin.org/ip: 1635ms
|
|
132
|
+
โ github.com: 5146ms | wikipedia.org: 15.3s
|
|
133
|
+
โ news.ycombinator.com: 1231ms
|
|
96
134
|
|
|
97
|
-
|
|
98
|
-
|
|
135
|
+
Step 6: System status โ
0.1s
|
|
136
|
+
โ Connected: true ยท Chrome PID: 15409
|
|
99
137
|
|
|
100
|
-
|
|
101
|
-
|
|
138
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
139
|
+
Total: 44.9s ยท 6 steps ยท 7 screenshots
|
|
140
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
102
141
|
```
|
|
103
142
|
|
|
104
|
-
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## ๐ Prerequisites
|
|
146
|
+
|
|
147
|
+
Just **Chrome** or **Chromium** installed anywhere on your system. bwb auto-detects it.
|
|
148
|
+
|
|
149
|
+
| Platform | Install |
|
|
150
|
+
|----------|---------|
|
|
151
|
+
| **Termux/Android** | `pkg install chromium` |
|
|
152
|
+
| **Linux (Debian/Ubuntu)** | `sudo apt install chromium-browser` |
|
|
153
|
+
| **macOS** | `brew install --cask google-chrome` |
|
|
154
|
+
| **Windows** | Download from [google.com/chrome](https://www.google.com/chrome/) |
|
|
155
|
+
| **CI/Docker** | `apt-get install -y chromium` |
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## ๐ Configuration
|
|
105
160
|
|
|
106
161
|
| CLI flag | Env var | Default | Description |
|
|
107
162
|
|----------|---------|---------|-------------|
|
|
108
163
|
| `--browser-path` | `BWB_CHROME_PATH` | auto-detected | Path to Chrome/Chromium binary |
|
|
109
|
-
| `--port` | `BWB_CDP_PORT` | `
|
|
164
|
+
| `--port` | `BWB_CDP_PORT` | `0` (random free port) | Remote debugging port |
|
|
110
165
|
| `--user-data-dir` | `BWB_USER_DATA_DIR` | `~/.cache/bwb-browser` | Browser profile directory |
|
|
111
166
|
| `--headless` | `BWB_HEADLESS` | `true` | Run headless (`true`/`false`) |
|
|
167
|
+
| `--screenshots-dir` | `BWB_SCREENSHOTS_DIR` | `~/bwb-screenshots/` | Screenshot save location |
|
|
168
|
+
| `--timeout` | `BWB_NAV_TIMEOUT` | `30000` | Navigation timeout in ms |
|
|
169
|
+
|
|
170
|
+
**Note:** On Android/Termux, screenshots default to `/storage/emulated/0/Download/bwb-screenshots/` so they're accessible from any file manager or gallery app.
|
|
171
|
+
|
|
172
|
+
---
|
|
173
|
+
|
|
174
|
+
## ๐ค Compatible AI Agents
|
|
175
|
+
|
|
176
|
+
bwb works with **every major AI coding agent** via MCP:
|
|
177
|
+
|
|
178
|
+
| Agent | Config File |
|
|
179
|
+
|-------|------------|
|
|
180
|
+
| **Claude Code** | `~/.claude/settings.json` |
|
|
181
|
+
| **OpenCode** | `~/.config/opencode/opencode.json` |
|
|
182
|
+
| **Antigravity CLI** | `~/.gemini/antigravity-cli/mcp_config.json` |
|
|
183
|
+
| **Cline** (VS Code) | `~/.cline/mcp.json` |
|
|
184
|
+
| **Continue.dev** | `~/.continue/config.json` |
|
|
185
|
+
| **Cursor** | `.cursor/mcp.json` |
|
|
186
|
+
| **Aider** | Custom tool integration |
|
|
187
|
+
| **Codex CLI** | `~/.codex/mcp.json` |
|
|
188
|
+
| **Cody** (Sourcegraph) | MCP config |
|
|
189
|
+
| **Windsurf** | MCP config |
|
|
190
|
+
|
|
191
|
+
> ๐ฏ **Give this to any AI agent to auto-install bwb:** See the copy-paste prompt in [AGENTS.md](AGENTS.md)
|
|
192
|
+
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
## ๐ฅ Using `browser_watch` (The Game Changer)
|
|
196
|
+
|
|
197
|
+
### Start watching:
|
|
198
|
+
```
|
|
199
|
+
browser_watch({action: "start", events: ["all"]})
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### Browse around:
|
|
203
|
+
```
|
|
204
|
+
browser_goto({url: "https://example.com"})
|
|
205
|
+
browser_click({selector: "button"})
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
### See everything that happened:
|
|
209
|
+
```
|
|
210
|
+
browser_watch({action: "poll"})
|
|
211
|
+
# โ [{console: "App initialized"}, {network: "GET /api/data 200"}, ...]
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
### Stop recording:
|
|
215
|
+
```
|
|
216
|
+
browser_watch({action: "stop"})
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
The agent gets **structured event data** โ not just screenshots. It can SEE what the page is doing internally.
|
|
220
|
+
|
|
221
|
+
---
|
|
222
|
+
|
|
223
|
+
## ๐ Platform Support
|
|
224
|
+
|
|
225
|
+
| Platform | Status | Notes |
|
|
226
|
+
|----------|--------|-------|
|
|
227
|
+
| **Termux/Android** | โ
**Verified** | Native, no containers. Chromium via `pkg`. |
|
|
228
|
+
| **Linux** | โ
| Works with any Chrome/Chromium |
|
|
229
|
+
| **macOS** | โ
| Google Chrome auto-detected |
|
|
230
|
+
| **Windows** | โ
| Chrome auto-detected |
|
|
231
|
+
| **CI/CD (GitHub Actions)** | โ
| Use `chromium-browser` |
|
|
232
|
+
| **Docker** | โ
| Install chromium in container |
|
|
233
|
+
|
|
234
|
+
---
|
|
235
|
+
|
|
236
|
+
## ๐ฆ What's in the Box?
|
|
237
|
+
|
|
238
|
+
```
|
|
239
|
+
bwb-browser (37KB unpacked)
|
|
240
|
+
โโโ server.mjs MCP server โ 15 tools, CDP integration
|
|
241
|
+
โโโ bin/bwb CLI entry point
|
|
242
|
+
โโโ AGENTS.md Agent integration guide + copy-paste prompt
|
|
243
|
+
โโโ BENCHMARKS.md Competitive comparison data
|
|
244
|
+
โโโ LICENSE MIT
|
|
245
|
+
โโโ README.md This file
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
**Zero bloat. No AI framework. No bundled browser. Just the bridge between your agent and Chrome.**
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## ๐ Comparison: bwb vs The World
|
|
253
|
+
|
|
254
|
+
| Metric | bwb | Playwright MCP | Puppeteer MCP | Chrome DevTools MCP |
|
|
255
|
+
|--------|-----|----------------|---------------|-------------------|
|
|
256
|
+
| Unpacked size | **30 KB** | ~200 MB | ~400 MB | ~300 MB |
|
|
257
|
+
| npm install size | **~2 MB** | ~500 MB | ~400 MB | ~300 MB |
|
|
258
|
+
| Install time | **5 seconds** | 5+ minutes | 5+ minutes | 5+ minutes |
|
|
259
|
+
| Dependencies | **3 packages** | 50+ packages | 30+ packages | 50+ packages |
|
|
260
|
+
| Live event capture | โ
**`browser_watch`** | โ | โ | โ |
|
|
261
|
+
| Termux/Android | โ
**Native** | โ | โ | โ |
|
|
262
|
+
| Uses existing Chrome | โ
Auto-detect | โ Downloads its own | โ Downloads its own | โ Downloads its own |
|
|
263
|
+
| Dark mode | โ
MIT | โ
Apache 2.0 | โ
Apache 2.0 | โ
Apache 2.0 |
|
|
264
|
+
|
|
265
|
+
---
|
|
266
|
+
|
|
267
|
+
## ๐ Roadmap
|
|
268
|
+
|
|
269
|
+
- **v2.0.x** โ Current: 15 tools, `browser_watch`, stable
|
|
270
|
+
- **v2.1** โ Stealth mode (bot detection bypass via CDP script injection)
|
|
271
|
+
- **v2.2** โ Cookie/session management (`browser_getCookies`, `browser_setCookie`)
|
|
272
|
+
- **v3.0** โ Parallel tab management, persistent sessions, network interception
|
|
273
|
+
- **bwb Cloud** โ Managed browser instances, pay-per-use (coming 2027)
|
|
274
|
+
|
|
275
|
+
---
|
|
276
|
+
|
|
277
|
+
## ๐ License
|
|
278
|
+
|
|
279
|
+
MIT ยฉ [Krish Tiwari](https://github.com/krshforever) ([@krshforever](https://github.com/krshforever))
|
|
280
|
+
|
|
281
|
+
---
|
|
112
282
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
| `browser_html` | Get page/selector HTML |
|
|
120
|
-
| `browser_text` | Get page/selector text |
|
|
121
|
-
| `browser_click` | Click an element by CSS selector |
|
|
122
|
-
| `browser_fill` | Fill an input field |
|
|
123
|
-
| `browser_elements` | List interactive elements (links, buttons, inputs, headings) |
|
|
124
|
-
| `browser_title` | Get current page title |
|
|
125
|
-
| `browser_url` | Get current URL |
|
|
126
|
-
| `browser_eval` | Execute JavaScript in page context |
|
|
127
|
-
| `browser_status` | Browser connection status |
|
|
128
|
-
|
|
129
|
-
## License
|
|
130
|
-
|
|
131
|
-
MIT ยฉ krsh
|
|
283
|
+
<p align="center">
|
|
284
|
+
<b>30KB. Raw CDP. Zero Bloat. Any Agent. Any Platform.</b><br>
|
|
285
|
+
<a href="https://github.com/krshforever/bwb-browser">GitHub</a> ยท
|
|
286
|
+
<a href="https://www.npmjs.com/package/bwb-browser">npm</a> ยท
|
|
287
|
+
<a href="AGENTS.md">Agent Guide</a>
|
|
288
|
+
</p>
|
package/package.json
CHANGED
package/server.mjs
CHANGED
|
@@ -39,7 +39,7 @@ function parseArgs() {
|
|
|
39
39
|
case "--headless": cfg.headless = args[++i] !== "false"; break;
|
|
40
40
|
case "--screenshots-dir": cfg.screenshotsDir = args[++i]; break;
|
|
41
41
|
case "--timeout": cfg.navTimeout = parseInt(args[++i], 10); break;
|
|
42
|
-
case "--version": console.log("bwb-browser 2.0.
|
|
42
|
+
case "--version": console.log("bwb-browser 2.0.4"); process.exit(0);
|
|
43
43
|
case "--help": printHelp(); process.exit(0);
|
|
44
44
|
}
|
|
45
45
|
}
|
|
@@ -600,7 +600,7 @@ async function waitForSelector(runtime, selector, opts = {}) {
|
|
|
600
600
|
|
|
601
601
|
const server = new McpServer({
|
|
602
602
|
name: "bwb-browser",
|
|
603
|
-
version: "2.0.
|
|
603
|
+
version: "2.0.4",
|
|
604
604
|
});
|
|
605
605
|
|
|
606
606
|
// Tool implementations
|
|
@@ -881,7 +881,12 @@ const tools = {
|
|
|
881
881
|
},
|
|
882
882
|
handler: async ({ width = 1280, height = 720 }) => {
|
|
883
883
|
const p = await ensureBrowser();
|
|
884
|
-
await p.
|
|
884
|
+
await p.Emulation.setDeviceMetricsOverride({
|
|
885
|
+
width,
|
|
886
|
+
height,
|
|
887
|
+
deviceScaleFactor: 1,
|
|
888
|
+
mobile: false,
|
|
889
|
+
});
|
|
885
890
|
return {
|
|
886
891
|
content: [{
|
|
887
892
|
type: "text",
|