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

package/README.md

@@ -1,246 +1,219 @@
 # @bsbofmusic/agent-browser-mcp-opencode
 
-MCP server for Vercel agent-browser - browser automation CLI for AI agents.
+<div align="center">
 
-## 什么是 MCP Server
+  **MCP Server for agent-browser**  
+  <sub><sup>Browser automation for• AI agents</sup></sub>
 
-MCP (Model Context Protocol) Server 是一个中间层，允许 AI 助手（如 OpenCode、Claude Code 等）通过标准化接口调用外部工具。
+  [![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)
 
-## 这是什么
+</div>
 
-本项目是对 [vercel-labs/agent-browser](https://github.com/vercel-labs/agent-browser) 的 MCP 封装（Wrapper），通过 MCP 接口提供浏览器自动化能力。
+---
 
-## 功能特性
+<div align="center">
 
-- **一键部署**: 启用 MCP 后自动安装 agent-browser 和 Chromium
-- **自检自愈**: 内置 `browser_ensure` 和 `browser_doctor` 工具，自动检测和修复问题
-- **自动更新**: 支持 `always-latest` 模式，每次调用前检查更新
-- **结构化工具**: 提供常用动作的封装（open、snapshot、click、fill 等）
-- **通用透传**: 通过 `browser_exec` 执行任意 agent-browser 命令
+  **Browser automation for AI agents via Model Context Protocol**
 
-## 一键启用
+</div>
 
-### OpenCode 配置
+---
 
-在 `opencode.json` 中添加:
-
-```json
-{
-  "mcp": {
-    "agent-browser-mcp-opencode": {
-      "command": ["npx", "-y", "@bsbofmusic/agent-browser-mcp-opencode"],
-      "enabled": true,
-      "type": "local"
-    }
-  }
-}
-```
-
-### 直接运行
+## Quick Start
 
 ```bash
 npx @bsbofmusic/agent-browser-mcp-opencode
 ```
 
-### 全局安装
+---
 
-```bash
-npm install -g @bsbofmusic/agent-browser-mcp-opencode
-agent-browser-mcp-opencode
-```
+## Tools
 
-## 工具列表
+### Core Tools
 
-### 核心工具
+| Tool | Description |
+|------|-------------|
+| `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 |
 
-| 工具名 | 描述 |
-|--------|------|
-| `browser_ensure` | 手动触发全量自愈（安装/修复/升级） |
-| `browser_doctor` | 诊断环境问题并输出修复建议 |
-| `browser_help` | 列出所有可用命令 |
-| `browser_version` | 显示版本信息 |
-| `browser_exec` | 执行任意 agent-browser CLI 命令 |
+### Action Tools
 
-### 结构化动作
+| Tool | Description |
+|------|-------------|
+| `browser_open` | Navigate to URL |
+| `browser_snapshot` | Get accessibility tree with refs |
+| `browser_click` | Click element |
+| `browser_fill` | Fill form field |
+| `browser_screenshot` | Take screenshot |
+| `browser_close` | Close browser |
+| `browser_get_text` | Get element text |
+| `browser_find` | Semantic locator (role/text/label) |
+| `browser_wait` | Wait for element/text/URL/time |
+| `browser_tab` | Manage tabs |
 
-| 工具名 | 描述 |
-|--------|------|
-| `browser_open` | 导航到 URL |
-| `browser_snapshot` | 获取页面可访问性树（带 refs） |
-| `browser_click` | 点击元素 |
-| `browser_fill` | 填写表单字段 |
-| `browser_screenshot` | 截图 |
-| `browser_close` | 关闭浏览器 |
-| `browser_get_text` | 获取元素文本 |
-| `browser_find` | 语义定位查找元素 |
-| `browser_wait` | 等待元素/文本/URL/时间 |
-| `browser_tab` | 管理浏览器标签页 |
+---
 
-## 使用示例
+## Usage Examples
 
-### 基本流程
+### Basic Workflow
 
 ```json
-{
-  "name": "browser_open",
-  "arguments": {"url": "https://example.com"}
-}
-```
+// 1. Navigate
+{"name": "browser_open", "arguments": {"url": "https://example.com"}}
 
-```json
-{
-  "name": "browser_snapshot",
-  "arguments": {"interactive": true}
-}
+// 2. Get interactive elements
+{"name": "browser_snapshot", "arguments": {"interactive": true}}
+
+// 3. Click element
+{"name": "browser_click", "arguments": {"selector": "@e1"}}
 ```
 
+### Semantic Locator
+
 ```json
 {
-  "name": "browser_click",
-  "arguments": {"selector": "@e1"}
+  "name": "browser_find",
+  "arguments": {
+    "type": "role",
+    "value": "button",
+    "action": "click",
+    "name": "Submit"
+  }
 }
 ```
 
-### 使用透传
+### Using browser_exec
 
 ```json
 {
   "name": "browser_exec",
   "arguments": {
-    "command": "open example.com && agent-browser find role button click --name Submit"
+    "command": "open example.com && snapshot -i && click #submit"
   }
 }
 ```
 
-## 自动更新策略
-
-### 环境变量
-
-| 变量 | 默认值 | 描述 |
-|------|--------|------|
-| `ALWAYS_LATEST` | `1` | 每次调用前检查更新 |
-| `UPDATE_STRATEGY` | `simple` | 更新策略: `atomic` 或 `simple` |
-| `LOG_LEVEL` | `info` | 日志级别: `error`, `warn`, `info`, `debug` |
-| `CACHE_DIR` | 系统 temp | 缓存目录 |
-| `RUNTIME_DIR` | `~/.agent-browser` | 运行时目录 |
-
-### Atomic 更新策略
+---
 
-使用双目录（`runtime_active/` + `runtime_staging/`）实现原子更新:
-1. 在 staging 目录执行更新
-2. 验证成功后切换到新版本
-3. 失败则回滚到原版本
+## Auto-Update
 
-### Simple 更新策略
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ALWAYS_LATEST` | `1` | Check for updates before each call |
+| `UPDATE_STRATEGY` | `simple` | `atomic` or `simple` |
+| `LOG_LEVEL` | `info` | `error`, `warn`, `info`, `debug` |
 
-直接覆盖安装，不支持回滚。
+---
 
-## 运行目录
+## Runtime Directories
 
-- **配置目录**: `~/.agent-browser/`
-- **状态文件**: `~/.agent-browser/sessions/`
-- **加密密钥**: `~/.agent-browser/.encryption-key`
+| Directory | Location |
+|-----------|----------|---------|
+| Config | `~/.agent-browser/` | User configuration |
+| Sessions | `~/.agent-browser/sessions/` | Saved auth states |
+| Cache | System temp | Temporary files |
 
-这些目录会在首次运行时自动创建。
+---
 
-## 常见错误与排障
+## Troubleshooting
 
-### 运行 `browser_doctor` 获取诊断信息
+### Run Diagnostics
 
 ```json
-{
-  "name": "browser_doctor"
-}
+{"name": "browser_doctor"}
 ```
 
-输出包含:
-- 问题分类（网络/权限/依赖/系统库/可执行文件/浏览器）
-- 严重程度（critical/high/medium）
-- 修复建议（nextSteps）
+**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 未安装**
-   - 运行: `browser_ensure`
-   - 或: `npx agent-browser install`
+---
 
-2. **Chromium 未安装**
-   - 运行: `npx agent-browser install`
+## Platform Compatibility
 
-3. **权限错误**
-   - 检查 npm 全局目录权限
-   - 考虑使用 npx 而非全局安装
+| 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 |
 
-4. **网络问题**
-   - 配置 npm 镜像: `npm config set registry https://registry.npmmirror.com`
-   - 检查代理设置: `npm config get proxy`
+---
 
-## 验证计划
+## Verification
+
+### 6.1 One-Click Deployment
 
-### 6.1 一键部署
 ```bash
 npx @bsbofmusic/agent-browser-mcp-opencode
 ```
-预期: 自动完成依赖安装，无需手动操作
 
-### 6.2 完美复刻
-使用 5+ 核心命令验证:
-- `browser_open` - 导航
-- `browser_snapshot` - 获取树
-- `browser_click` - 点击
-- `browser_fill` - 填写
-- `browser_screenshot` - 截图
-- `browser_exec` - 透传
+**Expected**: Auto-installs dependencies without manual steps.
+
+### 6.2 Capability Coverage
+
+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
+
+- `browser_doctor` outputs 7 issue categories
+- `browser_ensure` is idempotent
+- Errors include logs + nextSteps
 
-### 6.3 稳定健全
-- `browser_doctor` 输出 7 类问题分类
-- `browser_ensure` 幂等可重复执行
-- 失败时返回结构化错误+nextSteps
+### 6.4 Auto-Update
 
-### 6.4 自动更新
-- `browser_version` 显示版本信息
-- `ALWAYS_LATEST=1` 时每次调用前检查更新
+- `browser_version` shows current/latest
+- `ALWAYS_LATEST=1` checks on each call
 
-### 6.5 部署即用
-- MCP 启动后无需额外配置
-- 重启后自动恢复可用状态
+### 6.5 Deployment Ready
 
-### 6.6 失败场景
-- 断网: 返回网络错误+nextSteps
-- 无权限: 返回权限错误+nextSteps
-- 缺依赖: 返回依赖错误+nextSteps
+No manual config after first enable. Survives MCP/Agent restart.
 
-## 合规与封装声明
+### 6.6 Failure Scenarios
 
-### 封装声明 / Wrapper Notice
+| Scenario | Expected Output |
+|----------|-----------------|
+| No network | Network error + nextSteps |
+| No permission | Permission error + nextSteps |
+| Missing deps | Dep error + nextSteps |
 
-本项目是对上游项目 **agent-browser** 的 MCP 封装（wrapper），用于通过 MCP 接口调用其功能。
+---
 
-- 上游项目地址: https://github.com/vercel-labs/agent-browser
-- 本项目不是上游项目的官方发布
-- 上游项目的名称、商标与版权归其各自权利人所有
-- 上游项目按其许可证条款授权使用；本项目已在 THIRD_PARTY_NOTICES.md 中包含上游许可证与必要声明
+## Wrapper Declaration
 
-### 上游许可证
+This project is a **wrapper** for **agent-browser** by Vercel Labs.
 
-agent-browser 使用 **Apache-2.0** 许可证。
+- **Upstream**: https://github.com/vercel-labs/agent-browser
+- **License**: Apache-2.0
+- This is **NOT** an official upstream release
+- Upstream trademarks/copyrights belong to respective owners
 
-详见 [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)
+See [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) for license details.
 
-## 版本历史
+---
 
-详见 [CHANGELOG.md](./CHANGELOG.md)
+## License
 
-## 许可证
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue)](https://img.shields.io/badge/License-Apache%202.0-blue)
 
 Apache-2.0 License
 
 Copyright (c) 2024-2025 bsbofmusic
 
-This project includes code from the upstream project agent-browser which is licensed under Apache-2.0.
+---
 
-## 支持
+## Support
 
-如有问题，请提交 Issue:
-- MCP 问题: https://github.com/issues
-- agent-browser 问题: https://github.com/vercel-labs/agent-browser/issues
+- **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.0",
+  "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"}}}'
+