@bsbofmusic/agent-browser-mcp-opencode 2.0.0 → 2.0.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.
- package/README.md +145 -103
- package/package.json +1 -1
- package/src/tools/version.js +1 -1
- package/verify_init.txt +2 -0
- package/verify_tools.txt +4 -0
package/README.md
CHANGED
|
@@ -2,210 +2,252 @@
|
|
|
2
2
|
|
|
3
3
|
<div align="center">
|
|
4
4
|
|
|
5
|
-
**MCP Server for agent-browser**
|
|
6
|
-
<sub
|
|
7
|
-
|
|
8
|
-
[](https://
|
|
9
|
-
[](https://
|
|
10
|
-
[](https://
|
|
5
|
+
**MCP Server for Vercel agent-browser**
|
|
6
|
+
<sub>Browser automation for AI agents via Model Context Protocol</sub>
|
|
7
|
+
|
|
8
|
+
[](https://modelcontextprotocol.io/)
|
|
9
|
+
[](https://opensource.org/licenses/Apache-2.0)
|
|
10
|
+
[](https://nodejs.org/)
|
|
11
|
+
[](https://www.npmjs.com/package/@bsbofmusic/agent-browser-mcp-opencode)
|
|
12
|
+
[](https://www.npmjs.com/package/@bsbofmusic/agent-browser-mcp-opencode)
|
|
13
|
+
[]()
|
|
14
|
+
[]()
|
|
15
|
+
[]()
|
|
12
16
|
|
|
13
17
|
</div>
|
|
14
18
|
|
|
15
19
|
---
|
|
16
20
|
|
|
17
|
-
|
|
21
|
+
## Overview
|
|
18
22
|
|
|
19
|
-
|
|
23
|
+
This package is an **MCP (Model Context Protocol)** wrapper for [agent-browser](https://github.com/vercel-labs/agent-browser) by Vercel Labs. It provides browser automation capabilities to AI assistants like **OpenCode**, **Claude Code**, **Cursor**, and others through a standardized MCP interface.
|
|
20
24
|
|
|
21
|
-
|
|
25
|
+
### ✨ Key Features
|
|
26
|
+
|
|
27
|
+
| Feature | Description |
|
|
28
|
+
|---------|-------------|
|
|
29
|
+
| 🚀 **One-Click Enable** | Auto-installs all dependencies (agent-browser + Chromium) on first run |
|
|
30
|
+
| 🛠️ **Self-Healing** | Built-in `browser_ensure` and `browser_doctor` tools for auto-repair |
|
|
31
|
+
| 🔄 **Auto-Update** | `always-latest` mode with atomic update support |
|
|
32
|
+
| 📚 **Full Capability Coverage** | 15 MCP tools covering all core agent-browser functionality |
|
|
33
|
+
| ⚡ **Universal Passthrough** | `browser_exec` for executing any agent-browser CLI command |
|
|
34
|
+
| ♻️ **Idempotent** | Safe to run multiple times, no side effects |
|
|
35
|
+
| 🪟 **Windows Compatibility** | Auto-fallback to `npx` when global install fails |
|
|
36
|
+
| 📊 **Structured Output** | All tools return consistent `{ok, logs, stdout, stderr, nextSteps}` format |
|
|
22
37
|
|
|
23
38
|
---
|
|
24
39
|
|
|
25
|
-
## Quick Start
|
|
40
|
+
## 🚀 Quick Start
|
|
41
|
+
|
|
42
|
+
### Option 1: OpenCode Configuration (Recommended)
|
|
26
43
|
|
|
44
|
+
Add to your `opencode.json`:
|
|
45
|
+
```json
|
|
46
|
+
{
|
|
47
|
+
"mcp": {
|
|
48
|
+
"agent-browser-mcp-opencode": {
|
|
49
|
+
"command": ["npx", "-y", "@bsbofmusic/agent-browser-mcp-opencode"],
|
|
50
|
+
"enabled": true,
|
|
51
|
+
"type": "local"
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### Option 2: Direct Run
|
|
27
58
|
```bash
|
|
28
59
|
npx @bsbofmusic/agent-browser-mcp-opencode
|
|
29
60
|
```
|
|
30
61
|
|
|
31
|
-
|
|
62
|
+
### Option 3: Global Install
|
|
63
|
+
```bash
|
|
64
|
+
npm install -g @bsbofmusic/agent-browser-mcp-opencode
|
|
65
|
+
agent-browser-mcp-opencode
|
|
66
|
+
```
|
|
32
67
|
|
|
33
|
-
|
|
68
|
+
---
|
|
34
69
|
|
|
35
|
-
|
|
70
|
+
## 🛠️ MCP Tools
|
|
36
71
|
|
|
72
|
+
### Core Management Tools
|
|
37
73
|
| Tool | Description |
|
|
38
74
|
|------|-------------|
|
|
39
|
-
| `browser_ensure` |
|
|
40
|
-
| `browser_doctor` | Diagnose issues with
|
|
41
|
-
| `browser_help` | List all available commands |
|
|
42
|
-
| `browser_version` | Show version
|
|
43
|
-
| `browser_exec` | Execute any agent-browser CLI command |
|
|
44
|
-
|
|
45
|
-
### Action Tools
|
|
75
|
+
| `browser_ensure` | Manually trigger full repair (install/upgrade agent-browser and Chromium) |
|
|
76
|
+
| `browser_doctor` | Diagnose environment issues with actionable nextSteps |
|
|
77
|
+
| `browser_help` | List all available commands and capabilities |
|
|
78
|
+
| `browser_version` | Show version information for MCP and agent-browser |
|
|
79
|
+
| `browser_exec` | Execute any agent-browser CLI command (full passthrough) |
|
|
46
80
|
|
|
81
|
+
### Structured Action Tools
|
|
47
82
|
| Tool | Description |
|
|
48
83
|
|------|-------------|
|
|
49
|
-
| `browser_open` | Navigate to URL |
|
|
50
|
-
| `browser_snapshot` | Get accessibility tree with refs |
|
|
51
|
-
| `browser_click` | Click element |
|
|
52
|
-
| `browser_fill` |
|
|
53
|
-
| `browser_screenshot` | Take screenshot |
|
|
54
|
-
| `browser_close` | Close browser |
|
|
55
|
-
| `browser_get_text` | Get element
|
|
56
|
-
| `browser_find` |
|
|
57
|
-
| `browser_wait` | Wait for element/text/URL
|
|
58
|
-
| `browser_tab` | Manage tabs |
|
|
84
|
+
| `browser_open` | Navigate to a URL |
|
|
85
|
+
| `browser_snapshot` | Get accessibility tree with element refs (recommended for AI interaction) |
|
|
86
|
+
| `browser_click` | Click an element (@e1 ref or CSS selector) |
|
|
87
|
+
| `browser_fill` | Clear and fill a form field |
|
|
88
|
+
| `browser_screenshot` | Take a screenshot of the current page |
|
|
89
|
+
| `browser_close` | Close the browser and end the session |
|
|
90
|
+
| `browser_get_text` | Get text content from an element |
|
|
91
|
+
| `browser_find` | Find element by semantic locator (role/text/label/alt etc.) |
|
|
92
|
+
| `browser_wait` | Wait for element/text/URL to appear or specified time |
|
|
93
|
+
| `browser_tab` | Manage browser tabs (list/create/switch/close) |
|
|
59
94
|
|
|
60
95
|
---
|
|
61
96
|
|
|
62
|
-
## Usage Examples
|
|
97
|
+
## 💡 Usage Examples
|
|
63
98
|
|
|
64
99
|
### Basic Workflow
|
|
65
|
-
|
|
66
100
|
```json
|
|
67
|
-
// 1. Navigate
|
|
101
|
+
// 1. Navigate to page
|
|
68
102
|
{"name": "browser_open", "arguments": {"url": "https://example.com"}}
|
|
69
103
|
|
|
70
|
-
// 2. Get interactive elements
|
|
71
|
-
{"name": "browser_snapshot", "arguments": {"interactive": true}}
|
|
104
|
+
// 2. Get interactive elements with refs
|
|
105
|
+
{"name": "browser_snapshot", "arguments": {"interactive": true, "compact": true}}
|
|
72
106
|
|
|
73
|
-
// 3. Click element
|
|
107
|
+
// 3. Click the first interactive element
|
|
74
108
|
{"name": "browser_click", "arguments": {"selector": "@e1"}}
|
|
109
|
+
|
|
110
|
+
// 4. Fill a form field
|
|
111
|
+
{"name": "browser_fill", "arguments": {"selector": "@e2", "value": "test@example.com"}}
|
|
112
|
+
|
|
113
|
+
// 5. Take a screenshot
|
|
114
|
+
{"name": "browser_screenshot", "arguments": {"fullPage": true}}
|
|
75
115
|
```
|
|
76
116
|
|
|
77
117
|
### Semantic Locator
|
|
78
|
-
|
|
79
118
|
```json
|
|
80
|
-
{
|
|
81
|
-
"
|
|
82
|
-
"
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
"name": "Submit"
|
|
87
|
-
}
|
|
88
|
-
}
|
|
119
|
+
{"name": "browser_find", "arguments": {
|
|
120
|
+
"type": "role",
|
|
121
|
+
"value": "button",
|
|
122
|
+
"action": "click",
|
|
123
|
+
"name": "Submit Form"
|
|
124
|
+
}}
|
|
89
125
|
```
|
|
90
126
|
|
|
91
|
-
### Using browser_exec
|
|
92
|
-
|
|
127
|
+
### Using browser_exec (Advanced)
|
|
93
128
|
```json
|
|
94
|
-
{
|
|
95
|
-
"
|
|
96
|
-
|
|
97
|
-
"command": "open example.com && snapshot -i && click #submit"
|
|
98
|
-
}
|
|
99
|
-
}
|
|
129
|
+
{"name": "browser_exec", "arguments": {
|
|
130
|
+
"command": "open example.com && snapshot -i && find role button click --name \"Submit\""
|
|
131
|
+
}}
|
|
100
132
|
```
|
|
101
133
|
|
|
102
134
|
---
|
|
103
135
|
|
|
104
|
-
##
|
|
136
|
+
## ⚙️ Configuration
|
|
105
137
|
|
|
138
|
+
### Environment Variables
|
|
106
139
|
| Variable | Default | Description |
|
|
107
140
|
|----------|---------|-------------|
|
|
108
|
-
| `ALWAYS_LATEST` | `1` | Check for updates before each call |
|
|
109
|
-
| `UPDATE_STRATEGY` | `simple` | `atomic` or `simple` |
|
|
110
|
-
| `LOG_LEVEL` | `info` | `error`, `warn`, `info`, `debug` |
|
|
141
|
+
| `ALWAYS_LATEST` | `1` | Check for agent-browser updates before each call |
|
|
142
|
+
| `UPDATE_STRATEGY` | `simple` | Update strategy: `atomic` (with rollback) or `simple` (direct overwrite) |
|
|
143
|
+
| `LOG_LEVEL` | `info` | Log level: `error`, `warn`, `info`, `debug` |
|
|
144
|
+
| `RUNTIME_DIR` | `~/.agent-browser/mcp` | Runtime directory for MCP state |
|
|
145
|
+
|
|
146
|
+
### Update Strategies
|
|
147
|
+
| Strategy | Description |
|
|
148
|
+
|----------|-------------|
|
|
149
|
+
| **Simple** (default) | Direct overwrite installation, no rollback capability |
|
|
150
|
+
| **Atomic** | Uses dual `runtime_active/` + `runtime_staging/` directories, validates before switching, rolls back on failure |
|
|
111
151
|
|
|
112
152
|
---
|
|
113
153
|
|
|
114
|
-
## Runtime Directories
|
|
154
|
+
## 📁 Runtime Directories
|
|
115
155
|
|
|
116
|
-
| Directory | Location |
|
|
156
|
+
| Directory | Location | Purpose |
|
|
117
157
|
|-----------|----------|---------|
|
|
118
|
-
| Config | `~/.agent-browser/` | User configuration |
|
|
119
|
-
|
|
|
120
|
-
| Cache | System temp | Temporary files |
|
|
158
|
+
| Config | `~/.agent-browser/` | User configuration and saved sessions |
|
|
159
|
+
| MCP Runtime | `~/.agent-browser/mcp/` | MCP runtime state and update staging |
|
|
160
|
+
| Cache | System temp directory | Temporary files and screenshots |
|
|
161
|
+
|
|
162
|
+
All directories are auto-created on first run and are fully rebuildable.
|
|
121
163
|
|
|
122
164
|
---
|
|
123
165
|
|
|
124
|
-
## Troubleshooting
|
|
166
|
+
## 🔧 Troubleshooting
|
|
125
167
|
|
|
126
168
|
### Run Diagnostics
|
|
127
|
-
|
|
128
169
|
```json
|
|
129
170
|
{"name": "browser_doctor"}
|
|
130
171
|
```
|
|
172
|
+
Output includes:
|
|
173
|
+
- Issue categories: network/permissions/dependencies/system_libraries/executable/browser/auth
|
|
174
|
+
- Severity levels: critical/high/medium
|
|
175
|
+
- Actionable `nextSteps` for fixing issues
|
|
131
176
|
|
|
132
|
-
|
|
133
|
-
|
|
177
|
+
### Common Issues & Solutions
|
|
134
178
|
| Issue | Solution |
|
|
135
179
|
|-------|----------|
|
|
136
180
|
| agent-browser not installed | Run `browser_ensure` or `npx agent-browser install` |
|
|
137
181
|
| Chromium not installed | Run `npx agent-browser install` |
|
|
138
|
-
| Permission errors | Check npm global directory permissions |
|
|
182
|
+
| Permission errors | Check npm global directory permissions, or use npx |
|
|
183
|
+
| Windows daemon issues | Auto-falls back to npx, no manual action needed |
|
|
184
|
+
| Network issues | Set npm mirror: `npm config set registry https://registry.npmmirror.com` |
|
|
139
185
|
|
|
140
186
|
---
|
|
141
187
|
|
|
142
|
-
## Platform Compatibility
|
|
188
|
+
## 🖥️ Platform Compatibility
|
|
143
189
|
|
|
144
190
|
| Platform | Status | Notes |
|
|
145
|
-
|
|
146
|
-
| Windows |
|
|
191
|
+
|----------|--------|-------|
|
|
192
|
+
| Windows | ✅ Full | Auto-fallback to npx when PATH issues occur |
|
|
147
193
|
| macOS | ✅ Full | Native binary works perfectly |
|
|
148
194
|
| Linux | ✅ Full | Native binary works perfectly |
|
|
149
195
|
|
|
150
196
|
---
|
|
151
197
|
|
|
152
|
-
## Verification
|
|
198
|
+
## ✅ Verification
|
|
153
199
|
|
|
154
200
|
### 6.1 One-Click Deployment
|
|
155
|
-
|
|
156
201
|
```bash
|
|
157
202
|
npx @bsbofmusic/agent-browser-mcp-opencode
|
|
158
203
|
```
|
|
159
|
-
|
|
160
|
-
**Expected**: Auto-installs dependencies without manual steps.
|
|
204
|
+
**Expected**: Auto-installs all dependencies without manual steps.
|
|
161
205
|
|
|
162
206
|
### 6.2 Capability Coverage
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
-
|
|
166
|
-
-
|
|
207
|
+
All 15 tools are available:
|
|
208
|
+
- 5 core management tools
|
|
209
|
+
- 10 structured action tools
|
|
210
|
+
- Full CLI passthrough via `browser_exec`
|
|
167
211
|
|
|
168
212
|
### 6.3 Stability
|
|
169
|
-
|
|
170
213
|
- `browser_doctor` outputs 7 issue categories
|
|
171
|
-
- `browser_ensure` is idempotent
|
|
172
|
-
-
|
|
214
|
+
- `browser_ensure` is fully idempotent
|
|
215
|
+
- All errors include structured logs and actionable nextSteps
|
|
173
216
|
|
|
174
217
|
### 6.4 Auto-Update
|
|
175
|
-
|
|
176
|
-
- `
|
|
177
|
-
-
|
|
218
|
+
- `browser_version` shows current and latest available versions
|
|
219
|
+
- `ALWAYS_LATEST=1` checks for updates on every call
|
|
220
|
+
- Failed updates do not break existing working environment
|
|
178
221
|
|
|
179
222
|
### 6.5 Deployment Ready
|
|
180
|
-
|
|
181
|
-
No manual config after first enable. Survives MCP/Agent restart.
|
|
223
|
+
No manual configuration required after first enable. Survives MCP and AI agent restarts.
|
|
182
224
|
|
|
183
225
|
### 6.6 Failure Scenarios
|
|
184
|
-
|
|
185
226
|
| Scenario | Expected Output |
|
|
186
227
|
|----------|-----------------|
|
|
187
|
-
| No network | Network error +
|
|
188
|
-
| No
|
|
189
|
-
| Missing
|
|
228
|
+
| No network | Network error + repair steps |
|
|
229
|
+
| No write permissions | Permission error + npx fallback instructions |
|
|
230
|
+
| Missing dependencies | Dependency error + install instructions |
|
|
190
231
|
|
|
191
232
|
---
|
|
192
233
|
|
|
193
|
-
## Wrapper Declaration
|
|
234
|
+
## 📜 Wrapper Declaration
|
|
194
235
|
|
|
195
|
-
This project is a
|
|
236
|
+
This project is a wrapper for **agent-browser** by Vercel Labs.
|
|
196
237
|
|
|
197
|
-
- **Upstream**: https://github.com/vercel-labs/agent-browser
|
|
198
|
-
- **License**: Apache-2.0
|
|
238
|
+
- **Upstream Project**: https://github.com/vercel-labs/agent-browser
|
|
239
|
+
- **Upstream License**: Apache-2.0
|
|
199
240
|
- This is **NOT** an official upstream release
|
|
200
|
-
- Upstream trademarks
|
|
241
|
+
- Upstream trademarks, names, and copyrights belong to their respective owners
|
|
242
|
+
- This package follows all upstream license requirements
|
|
201
243
|
|
|
202
|
-
See [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) for license details.
|
|
244
|
+
See [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) for full license details.
|
|
203
245
|
|
|
204
246
|
---
|
|
205
247
|
|
|
206
|
-
## License
|
|
248
|
+
## 📄 License
|
|
207
249
|
|
|
208
|
-
[](https://
|
|
250
|
+
[](https://opensource.org/licenses/Apache-2.0)
|
|
209
251
|
|
|
210
252
|
Apache-2.0 License
|
|
211
253
|
|
|
@@ -213,7 +255,7 @@ Copyright (c) 2024-2025 bsbofmusic
|
|
|
213
255
|
|
|
214
256
|
---
|
|
215
257
|
|
|
216
|
-
## Support
|
|
258
|
+
## 🆘 Support
|
|
217
259
|
|
|
218
|
-
- **MCP
|
|
219
|
-
- **agent-browser
|
|
260
|
+
- **MCP Issues**: https://github.com/bsbofmusic/agent-browser-mcp-opencode/issues
|
|
261
|
+
- **Upstream agent-browser Issues**: https://github.com/vercel-labs/agent-browser/issues
|
package/package.json
CHANGED
package/src/tools/version.js
CHANGED
package/verify_init.txt
ADDED
package/verify_tools.txt
ADDED
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}
|
|
2
|
+
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"browser_version","arguments":{}}}
|
|
3
|
+
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"browser_help","arguments":{}}}
|
|
4
|
+
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"browser_doctor","arguments":{}}}
|