npm - @bsbofmusic/agent-browser-mcp-opencode - Versions diffs - 1.0.0 → 1.0.1 - Mend

@bsbofmusic/agent-browser-mcp-opencode 1.0.0 → 1.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.

Files changed (2) hide show

package/README.md +184 -129
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,28 +1,27 @@
 # @bsbofmusic/agent-browser-mcp-opencode
-MCP server for Vercel agent-browser - browser automation CLI for AI agents.
+MCP Server for Vercel agent-browser - browser automation CLI for AI agents.
-## 什么是 MCP Server
+---
-MCP (Model Context Protocol) Server 是一个中间层，允许 AI 助手（如 OpenCode、Claude Code 等）通过标准化接口调用外部工具。
+## What is This?
-## 这是什么
+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.
-本项目是对 [vercel-labs/agent-browser](https://github.com/vercel-labs/agent-browser) 的 MCP 封装（Wrapper），通过 MCP 接口提供浏览器自动化能力。
+### 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
-- **一键部署**: 启用 MCP 后自动安装 agent-browser 和 Chromium
-- **自检自愈**: 内置 `browser_ensure` 和 `browser_doctor` 工具，自动检测和修复问题
-- **自动更新**: 支持 `always-latest` 模式，每次调用前检查更新
-- **结构化工具**: 提供常用动作的封装（open、snapshot、click、fill 等）
-- **通用透传**: 通过 `browser_exec` 执行任意 agent-browser 命令
+---
-## 一键启用
+## One-Click Enable
-### OpenCode 配置
+### OpenCode Configuration
-在 `opencode.json` 中添加:
+Add to your `opencode.json`:
 ```json
 {
@@ -36,50 +35,61 @@ MCP (Model Context Protocol) Server 是一个中间层，允许 AI 助手（如
 }
 ```
-### 直接运行
+### Direct Run
 ```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
-| 工具名 | 描述 |
-|--------|------|
-| `browser_ensure` | 手动触发全量自愈（安装/修复/升级） |
-| `browser_doctor` | 诊断环境问题并输出修复建议 |
-| `browser_help` | 列出所有可用命令 |
-| `browser_version` | 显示版本信息 |
-| `browser_exec` | 执行任意 agent-browser CLI 命令 |
+### Core Tools
-### 结构化动作
+| Tool | Description |
+|------|-------------|
+| `browser_ensure` | Manually trigger full repair (install/upgrade) |
+| `browser_doctor` | Diagnose issues with actionable nextSteps |
+| `browser_help` | List all available commands |
+| `browser_version` | Show version info |
+| `browser_exec` | Execute any agent-browser CLI command |
-| 工具名 | 描述 |
-|--------|------|
-| `browser_open` | 导航到 URL |
-| `browser_snapshot` | 获取页面可访问性树（带 refs） |
-| `browser_click` | 点击元素 |
-| `browser_fill` | 填写表单字段 |
-| `browser_screenshot` | 截图 |
-| `browser_close` | 关闭浏览器 |
-| `browser_get_text` | 获取元素文本 |
-| `browser_find` | 语义定位查找元素 |
-| `browser_wait` | 等待元素/文本/URL/时间 |
-| `browser_tab` | 管理浏览器标签页 |
+### Structured Actions
-## 使用示例
+| Tool | Description |
+|------|-------------|
+| `browser_open` | Navigate to URL |
+| `browser_snapshot` | Get accessibility tree with refs |
+| `browser_click` | Click element (@e1 or CSS selector) |
+| `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 |
-### 基本流程
+---
+## Schema Examples
+### browser_open
+**Input:**
 ```json
 {
   "name": "browser_open",
@@ -87,65 +97,92 @@ agent-browser-mcp-opencode
 }
 ```
+**Output:**
+```json
+{
+  "ok": true,
+  "url": "https://example.com",
+  "duration": 2341
+}
+```
+### browser_snapshot
+**Input:**
 ```json
 {
   "name": "browser_snapshot",
-  "arguments": {"interactive": true}
+  "arguments": {"interactive": true, "compact": true}
 }
 ```
+**Output:**
 ```json
 {
-  "name": "browser_click",
-  "arguments": {"selector": "@e1"}
+  "ok": true,
+  "output": {
+    "success": true,
+    "data": {
+      "snapshot": "- heading \"Example\" [ref=e1]\n  - button \"Submit\" [ref=e2]"
+    }
+  },
+  "duration": 1234
 }
 ```
-### 使用透传
+### browser_exec
+**Input:**
 ```json
 {
   "name": "browser_exec",
   "arguments": {
-    "command": "open example.com && agent-browser find role button click --name Submit"
+    "command": "open example.com && snapshot -i",
+    "timeoutMs": 60000
   }
 }
 ```
-## 自动更新策略
+---
+## Auto-Update Strategy
-### 环境变量
+### Environment Variables
-| 变量 | 默认值 | 描述 |
-|------|--------|------|
-| `ALWAYS_LATEST` | `1` | 每次调用前检查更新 |
-| `UPDATE_STRATEGY` | `simple` | 更新策略: `atomic` 或 `simple` |
-| `LOG_LEVEL` | `info` | 日志级别: `error`, `warn`, `info`, `debug` |
-| `CACHE_DIR` | 系统 temp | 缓存目录 |
-| `RUNTIME_DIR` | `~/.agent-browser` | 运行时目录 |
+| 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` |
-### Atomic 更新策略
+### Strategies
-使用双目录（`runtime_active/` + `runtime_staging/`）实现原子更新:
-1. 在 staging 目录执行更新
-2. 验证成功后切换到新版本
-3. 失败则回滚到原版本
+**Simple (default):**
+- Direct overwrite installation
+- No rollback capability
-### Simple 更新策略
+**Atomic:**
+- Uses `runtime_active/` + `runtime_staging/` directories
+- Validates before switching
+- Rolls back on failure
-直接覆盖安装，不支持回滚。
+---
-## 运行目录
+## Runtime Directories
-- **配置目录**: `~/.agent-browser/`
-- **状态文件**: `~/.agent-browser/sessions/`
-- **加密密钥**: `~/.agent-browser/.encryption-key`
+| Directory | Location | Purpose |
+|-----------|----------|---------|
+| 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.
-## 常见错误与排障
+---
-### 运行 `browser_doctor` 获取诊断信息
+## Troubleshooting
+### Run browser_doctor
 ```json
 {
@@ -153,94 +190,112 @@ agent-browser-mcp-opencode
 }
 ```
-输出包含:
-- 问题分类（网络/权限/依赖/系统库/可执行文件/浏览器）
-- 严重程度（critical/high/medium）
-- 修复建议（nextSteps）
+**Output includes:**
+- Issue categories: network/permissions/dependencies/system_libraries/executable/browser/auth
+- Severity: critical/high/medium
+- nextSteps: actionable fix recommendations
+### Common Issues
-### 常见问题
+1. **agent-browser not installed**
+   - Run: `browser_ensure`
+   - Or: `npx agent-browser install`
-1. **agent-browser 未安装**
-   - 运行: `browser_ensure`
-   - 或: `npx agent-browser install`
+2. **Chromium not installed**
+   - Run: `npx agent-browser install`
-2. **Chromium 未安装**
-   - 运行: `npx agent-browser install`
+3. **Permission errors**
+   - Check npm global directory permissions
+   - Consider using npx instead
-3. **权限错误**
-   - 检查 npm 全局目录权限
-   - 考虑使用 npx 而非全局安装
+4. **Network issues**
+   - Set npm mirror: `npm config set registry https://registry.npmmirror.com`
+   - Check proxy: `npm config get proxy`
-4. **网络问题**
-   - 配置 npm 镜像: `npm config set registry https://registry.npmmirror.com`
-   - 检查代理设置: `npm config get proxy`
+---
-## 验证计划
+## Verification Plan
+### 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.3 稳定健全
-- `browser_doctor` 输出 7 类问题分类
-- `browser_ensure` 幂等可重复执行
-- 失败时返回结构化错误+nextSteps
+### 6.2 Capability Coverage
-### 6.4 自动更新
-- `browser_version` 显示版本信息
-- `ALWAYS_LATEST=1` 时每次调用前检查更新
+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
-### 6.5 部署即用
-- MCP 启动后无需额外配置
-- 重启后自动恢复可用状态
+### 6.3 Stability
-### 6.6 失败场景
-- 断网: 返回网络错误+nextSteps
-- 无权限: 返回权限错误+nextSteps
-- 缺依赖: 返回依赖错误+nextSteps
+- `browser_doctor` outputs 7 issue categories
+- `browser_ensure` is idempotent
+- Errors include logs + nextSteps
-## 合规与封装声明
+### 6.4 Auto-Update
-### 封装声明 / Wrapper Notice
+- `browser_version` shows current/latest
+- `ALWAYS_LATEST=1` checks on each call
-本项目是对上游项目 **agent-browser** 的 MCP 封装（wrapper），用于通过 MCP 接口调用其功能。
+### 6.5 Deployment Ready
-- 上游项目地址: https://github.com/vercel-labs/agent-browser
-- 本项目不是上游项目的官方发布
-- 上游项目的名称、商标与版权归其各自权利人所有
-- 上游项目按其许可证条款授权使用；本项目已在 THIRD_PARTY_NOTICES.md 中包含上游许可证与必要声明
+- No manual config after first enable
+- Survives MCP/Agent restart
-### 上游许可证
+### 6.6 Failure Scenarios
-agent-browser 使用 **Apache-2.0** 许可证。
+| Scenario | Expected Output |
+|----------|-----------------|
+| No network | Network error + nextSteps |
+| No permission | Permission error + nextSteps |
+| Missing deps | Dep error + nextSteps |
-详见 [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)
+---
-## 版本历史
+## Wrapper Declaration
-详见 [CHANGELOG.md](./CHANGELOG.md)
+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
+- Upstream trademarks/copyrights belong to respective owners
-Apache-2.0 License
+See [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md) for license details.
-Copyright (c) 2024-2025 bsbofmusic
+---
+## Upstream License
+agent-browser is licensed under **Apache-2.0**.
+This project includes upstream code per Apache-2.0 requirements.
+---
+## Version History
-This project includes code from the upstream project agent-browser which is licensed under Apache-2.0.
+See [CHANGELOG.md](./CHANGELOG.md)
-## 支持
+---
-如有问题，请提交 Issue:
-- MCP 问题: https://github.com/issues
-- agent-browser 问题: https://github.com/vercel-labs/agent-browser/issues
+## 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

package/package.json CHANGED Viewed

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