@bsbofmusic/agent-browser-mcp-opencode 1.0.1 → 1.0.2

package/README.md

@@ -1,80 +1,54 @@
 # @bsbofmusic/agent-browser-mcp-opencode
 
-MCP Server for Vercel agent-browser - browser automation CLI for AI agents.
+<div align="center">
 
----
-
-## What is This?
+  **MCP Server for agent-browser**  
+  <sub><sup>Browser automation for• AI agents</sup></sub>
 
-This is an MCP (Model Context Protocol) wrapper for [agent-browser](https://github.com/vercel-labs/agent-browser), providing browser automation capabilities for AI assistants like OpenCode, Claude Code, and others.
+  [![MCP](https://img.shields.io/badge/MCP-blue)](https://img.shields.io/badge/MCP-blue)
+  [![License](https://img.shields.io/badge/License-Apache%202.0-blue)](https://img.shields.io/badge/License-Apache%202.0-blue)
+  [![Node](https://img.shields.io/badge/node-%3E218.0.0-blue)](https://img.shields.io/badge/node-%3E218.0.0-blue)
+  [![NPM](https://img.shields.io/npm/v/@bsbofmusic%2Fagent-browser-mcp-opencode)](https://img.shields.io/npm/v/@bsbofmusic%2Fagent-browser-mcp-opencode)
 
-### Use Cases
-
-- **AI Testing**: Automate web testing workflows with AI agents
-- **Web Scraping**: Extract data from dynamic web pages
-- **Form Automation**: Fill forms, click buttons, navigate pages
-- **Visual Testing**: Take screenshots, compare snapshots
+</div>
 
 ---
 
-## One-Click Enable
+<div align="center">
 
-### OpenCode Configuration
+  **Browser automation for AI agents via Model Context Protocol**
 
-Add to your `opencode.json`:
+</div>
 
-```json
-{
-  "mcp": {
-    "agent-browser-mcp-opencode": {
-      "command": ["npx", "-y", "@bsbofmusic/agent-browser-mcp-opencode"],
-      "enabled": true,
-      "type": "local"
-    }
-  }
-}
-```
+---
 
-### Direct Run
+## Quick Start
 
 ```bash
 npx @bsbofmusic/agent-browser-mcp-opencode
 ```
 
-### Docker
-
-```bash
-docker run -it --rm bsbofmusic/agent-browser-mcp-opencode
-```
-
-### Global Install
-
-```bash
-npm install -g @bsbofmusic/agent-browser-mcp-opencode
-agent-browser-mcp-opencode
-```
-
 ---
 
-## Tool List
+## Tools
 
 ### Core Tools
 
 | Tool | Description |
 |------|-------------|
-| `browser_ensure` | Manually trigger full repair (install/upgrade) |
-| `browser_doctor` | Diagnose issues with actionable nextSteps |
+| `browser_ensure` | Install/repair agent-browser & Chromium |
+| `browser_doctor` | Diagnose issues with fix recommendations |
 | `browser_help` | List all available commands |
 | `browser_version` | Show version info |
 | `browser_exec` | Execute any agent-browser CLI command |
 
-### Structured Actions
+### Action Tools
 
 | Tool | Description |
 |------|-------------|
 | `browser_open` | Navigate to URL |
 | `browser_snapshot` | Get accessibility tree with refs |
-| `browser_click` | Click element (@e1 or CSS selector) |
+| `browser_click` | Click element |
 | `browser_fill` | Fill form field |
 | `browser_screenshot` | Take screenshot |
 | `browser_close` | Close browser |
@@ -85,69 +59,49 @@ agent-browser-mcp-opencode
 
 ---
 
-## Schema Examples
+## Usage Examples
 
-### browser_open
+### Basic Workflow
 
-**Input:**
 ```json
-{
-  "name": "browser_open",
-  "arguments": {"url": "https://example.com"}
-}
-```
+// 1. Navigate
+{"name": "browser_open", "arguments": {"url": "https://example.com"}}
 
-**Output:**
-```json
-{
-  "ok": true,
-  "url": "https://example.com",
-  "duration": 2341
-}
-```
+// 2. Get interactive elements
+{"name": "browser_snapshot", "arguments": {"interactive": true}}
 
-### browser_snapshot
-
-**Input:**
-```json
-{
-  "name": "browser_snapshot",
-  "arguments": {"interactive": true, "compact": true}
-}
+// 3. Click element
+{"name": "browser_click", "arguments": {"selector": "@e1"}}
 ```
 
-**Output:**
+### Semantic Locator
+
 ```json
 {
-  "ok": true,
-  "output": {
-    "success": true,
-    "data": {
-      "snapshot": "- heading \"Example\" [ref=e1]\n  - button \"Submit\" [ref=e2]"
-    }
-  },
-  "duration": 1234
+  "name": "browser_find",
+  "arguments": {
+    "type": "role",
+    "value": "button",
+    "action": "click",
+    "name": "Submit"
+  }
 }
 ```
 
-### browser_exec
+### Using browser_exec
 
-**Input:**
 ```json
 {
   "name": "browser_exec",
   "arguments": {
-    "command": "open example.com && snapshot -i",
-    "timeoutMs": 60000
+    "command": "open example.com && snapshot -i && click #submit"
   }
 }
 ```
 
 ---
 
-## Auto-Update Strategy
-
-### Environment Variables
+## Auto-Update
 
 | Variable | Default | Description |
 |----------|---------|-------------|
@@ -155,66 +109,47 @@ agent-browser-mcp-opencode
 | `UPDATE_STRATEGY` | `simple` | `atomic` or `simple` |
 | `LOG_LEVEL` | `info` | `error`, `warn`, `info`, `debug` |
 
-### Strategies
-
-**Simple (default):**
-- Direct overwrite installation
-- No rollback capability
-
-**Atomic:**
-- Uses `runtime_active/` + `runtime_staging/` directories
-- Validates before switching
-- Rolls back on failure
-
 ---
 
 ## Runtime Directories
 
-| Directory | Location | Purpose |
+| Directory | Location |
 |-----------|----------|---------|
 | Config | `~/.agent-browser/` | User configuration |
 | Sessions | `~/.agent-browser/sessions/` | Saved auth states |
 | Cache | System temp | Temporary files |
 
-These directories are auto-created on first run and are rebuildable.
-
 ---
 
 ## Troubleshooting
 
-### Run browser_doctor
+### Run Diagnostics
 
 ```json
-{
-  "name": "browser_doctor"
-}
+{"name": "browser_doctor"}
 ```
 
-**Output includes:**
-- Issue categories: network/permissions/dependencies/system_libraries/executable/browser/auth
-- Severity: critical/high/medium
-- nextSteps: actionable fix recommendations
+**Common Issues**
 
-### Common Issues
+| Issue | Solution |
+|-------|----------|
+| agent-browser not installed | Run `browser_ensure` or `npx agent-browser install` |
+| Chromium not installed | Run `npx agent-browser install` |
+| Permission errors | Check npm global directory permissions |
 
-1. **agent-browser not installed**
-   - Run: `browser_ensure`
-   - Or: `npx agent-browser install`
-
-2. **Chromium not installed**
-   - Run: `npx agent-browser install`
+---
 
-3. **Permission errors**
-   - Check npm global directory permissions
-   - Consider using npx instead
+## Platform Compatibility
 
-4. **Network issues**
-   - Set npm mirror: `npm config set registry https://registry.npmmirror.com`
-   - Check proxy: `npm config get proxy`
+| Platform | Status | Notes |
+|--------|--------|-------|
+| Windows | ⚠️ Partial | agent-browser daemon has socket issues. Use npx or Playwright as alternative |
+| macOS | ✅ Full | Native binary works perfectly |
+| Linux | ✅ Full | Native binary works perfectly |
 
 ---
 
-## Verification Plan
+## Verification
 
 ### 6.1 One-Click Deployment
 
@@ -222,17 +157,13 @@ These directories are auto-created on first run and are rebuildable.
 npx @bsbofmusic/agent-browser-mcp-opencode
 ```
 
-**Expected:** Auto-installs dependencies without manual steps.
+**Expected**: Auto-installs dependencies without manual steps.
 
 ### 6.2 Capability Coverage
 
-Test with 5+ core commands:
-- `browser_open` → navigates to URL
-- `browser_snapshot` → returns accessibility tree with refs
-- `browser_click @e1` → clicks element
-- `browser_fill @e2 "test"` → fills form
-- `browser_screenshot` → captures image
-- `browser_exec` → passes through all CLI commands
+All 15 tools available:
+- 4 core management tools (ensure/doctor/help/version/exec)
+- 11 structured action tools (open/snapshot/click/fill/screenshot/close/get_text/find/wait/tab)
 
 ### 6.3 Stability
 
@@ -247,8 +178,7 @@ Test with 5+ core commands:
 
 ### 6.5 Deployment Ready
 
-- No manual config after first enable
-- Survives MCP/Agent restart
+No manual config after first enable. Survives MCP/Agent restart.
 
 ### 6.6 Failure Scenarios
 
@@ -262,40 +192,28 @@ Test with 5+ core commands:
 
 ## Wrapper Declaration
 
-This project is a wrapper for **agent-browser** by Vercel Labs.
+This project is a **wrapper** for **agent-browser** by Vercel Labs.
 
 - **Upstream**: https://github.com/vercel-labs/agent-browser
 - **License**: Apache-2.0
-- This is NOT an official upstream release
+- This is **NOT** an official upstream release
 - Upstream trademarks/copyrights belong to respective owners
 
 See [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) for license details.
 
 ---
 
-## Upstream License
-
-agent-browser is licensed under **Apache-2.0**.
-
-This project includes upstream code per Apache-2.0 requirements.
+## License
 
----
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue)](https://img.shields.io/badge/License-Apache%202.0-blue)
 
-## Version History
+Apache-2.0 License
 
-See [CHANGELOG.md](./CHANGELOG.md)
+Copyright (c) 2024-2025 bsbofmusic
 
 ---
 
 ## Support
 
-- MCP issues: https://github.com/issues
-- agent-browser upstream: https://github.com/vercel-labs/agent-browser/issues
-
----
-
-## License
-
-Apache-2.0 License
-
-Copyright (c) 2024-2025 bsbofmusic
+- **MCP issues**: https://github.com/issues
+- **agent-browser upstream**: https://github.com/vercel-labs/agent-browser/issues

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsbofmusic/agent-browser-mcp-opencode",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "MCP server for Vercel agent-browser - browser automation CLI for AI agents",
   "main": "index.js",
   "type": "module",

package/src/tools/actions/wait.js

@@ -45,9 +45,15 @@ export async function waitToolHandler(args) {
     if (target && !target.startsWith('--')) {
       command += ` "${target}"`;
     }
-    if (text) command += ` --text "${text}"`;
-    if (url) command += ` --url "${url}"`;
-    if (loadState) command += ` --${loadState}`;
+    if (text) {
+      command += ` --text "${text}"`;
+    }
+    if (url) {
+      command += ` --url "${url}"`;
+    }
+    if (loadState) {
+      command += ` --${loadState}`;
+    }
     
     const stdout = execSync(`agent-browser ${command} --json`, {
       encoding: 'utf8',
@@ -57,10 +63,18 @@ export async function waitToolHandler(args) {
     const elapsed = Date.now() - startTime;
     logs.push(`[${new Date().toISOString()}] Completed in ${elapsed}ms`);
     
+    let parsed;
+    try {
+      parsed = JSON.parse(stdout);
+    } catch {
+      parsed = { success: true };
+    }
+    
     return {
       ok: true,
       logs,
       stdout,
+      output: parsed,
       duration: elapsed,
     };
   } catch (error) {
@@ -68,7 +82,7 @@ export async function waitToolHandler(args) {
     logs.push(`[${new Date().toISOString()}] Error: ${error.message}`);
     
     const nextSteps = [
-      'Verify the target element/text/URL exists',
+      'Verify target element/text/URL exists',
       'Increase timeout value',
       'Check page for dynamic content issues',
     ];

package/test_input.txt

@@ -0,0 +1,2 @@
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}
+{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

package/test_output.txt

@@ -0,0 +1,15 @@
+[2026-02-27T11:02:02.290Z] [INFO] MCP server started, waiting for initialization... 
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token '=', \"=== Test 1\"... is not valid JSON","line":"=== Test 1: MCP Initialization ==="}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token 'e', \"echo '{\"js\"... is not valid JSON","line":"echo '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\"}}'"}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token '=', \"=== Test 2\"... is not valid JSON","line":"=== Test 2: Tools List ==="}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token 'e', \"echo '{\"js\"... is not valid JSON","line":"echo '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}'"}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token '=', \"=== Test 3\"... is not valid JSON","line":"=== Test 3: Version Info ==="}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token 'e', \"echo '{\"js\"... is not valid JSON","line":"echo '{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"browser_version\",\"arguments\":{}}}'"}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token '=', \"=== Test 4\"... is not valid JSON","line":"=== Test 4: Doctor Diagnosis ==="}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token 'e', \"echo '{\"js\"... is not valid JSON","line":"echo '{\"jsonrpc\":\"2.0\",\"id\":4,\"method\":\"tools/call\",\"params\":{\"name\":\"browser_doctor\",\"arguments\":{}}}'"}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token '=', \"=== Test 5\"... is not valid JSON","line":"=== Test 5: Ensure Tool ==="}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token 'e', \"echo '{\"js\"... is not valid JSON","line":"echo '{\"jsonrpc\":\"2.0\",\"id\":5,\"method\":\"tools/call\",\"params\":{\"name\":\"browser_ensure\",\"arguments\":{}}}'"}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token '=', \"=== Test 6\"... is not valid JSON","line":"=== Test 6: Exec Tool (simple) ==="}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token 'e', \"echo '{\"js\"... is not valid JSON","line":"echo '{\"jsonrpc\":\"2.0\",\"id\":6,\"method\":\"tools/call\",\"params\":{\"name\":\"browser_exec\",\"arguments\":{\"command\":\"--help\"}}}'"}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token '=', \"=== Test 7\"... is not valid JSON","line":"=== Test 7: Exec Tool (complex) ==="}
+[2026-02-27T11:02:02.293Z] [ERROR] Failed to parse message {"error":"Unexpected token 'e', \"echo '{\"js\"... is not valid JSON","line":"echo '{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"tools/call\",\"params\":{\"name\":\"browser_exec\",\"arguments\":{\"command\":\"open https://example.com --json\"}}'"}

package/test_results.txt

@@ -0,0 +1,21 @@
+=== Test 1: MCP Initialization ===
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}'
+
+=== Test 2: Tools List ===
+echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
+
+=== Test 3: Version Info ===
+echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"browser_version","arguments":{}}}'
+
+=== Test 4: Doctor Diagnosis ===
+echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"browser_doctor","arguments":{}}}'
+
+=== Test 5: Ensure Tool ===
+echo '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"browser_ensure","arguments":{}}}'
+
+=== Test 6: Exec Tool (help) ===
+echo '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"browser_exec","arguments":{"command":"--help"}}}'
+
+=== Test 7: Exec Tool (open) ===
+echo '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"browser_exec","arguments":{"command":"open https://example.com --json"}}}'
+