| # browser |
|
|
| 浏览器 MCP 插件（v3.0）：**纯 Lightpanda 单后端透传**，提供 28 个通用浏览器 MCP 工具， |
| 为各环境 agent 暴露与 Lightpanda 上游一致的浏览器能力。 |
|
|
| ## 设计理念 |
|
|
| Lightpanda 的 `lightpanda mcp` 子命令本身就是一个标准 stdio MCP server，自带 28 个工具（27 browser tool + save） |
| （含 JSON Schema 与标准化错误码）。本插件**不重新发明浏览器语义**，只做四件事： |
|
|
| 1. **子进程生命周期**：单例长驻 `lightpanda mcp` 子进程，复用会话，支持链式操作 |
| （`goto` → `click` → `extract`）。 |
| 2. **JSON-RPC 透传**：行分隔协议，`initialize` 握手 + `tools/call` 透传。 |
| 3. **run_log 埋点**：每次调用创建 run，记录 init/call/complete/error 事件。 |
| 4. **错误码归一**：上游错误归一为 `BrowserError`，前端可据 code 给修复指引。 |
| |
| 工具名、参数、返回结构、错误码全部由 Lightpanda 上游决定——平台层零手写 schema、零漂移。 |
| |
| ## 为什么纯 Lightpanda |
| |
| 云端服务器资源不足以运行 Chrome。Lightpanda 是轻量无头浏览器，无需 Chrome/Chromium， |
| 适合资源受限环境。Playwright 兜底依赖 Chrome，在本场景下失效，已移除。 |
| |
| ## 28 个工具 |
| |
| | 类别 | 工具 | |
| |---|---| |
| | 导航 | `browser-goto` `browser-search` `browser-getUrl` | |
| | 读取 | `browser-markdown` `browser-html` `browser-links` `browser-evaluate` `browser-extract` `browser-tree` `browser-nodeDetails` `browser-interactiveElements` `browser-structuredData` `browser-detectForms` `browser-findElement` `browser-consoleLogs` `browser-getCookies` `browser-getEnv` | |
| | 交互 | `browser-click` `browser-fill` `browser-scroll` `browser-hover` `browser-press` `browser-selectOption` `browser-setChecked` | |
| | 等待 | `browser-waitForSelector` `browser-waitForScript` `browser-waitForState` | |
| | 录制 | `browser-save`（把会话存为可复用 agent 脚本，写磁盘） | |
| |
| 工具名格式为 `browser-{上游名}`（保留 camelCase）；入参统一 `params: dict` 透传给上游，校验由 Lightpanda 负责。 |
| 完整参数说明见 `/api/tools` 端点或各工具 description。 |
| |
| ## 架构 |
| |
| ``` |
| agent ──FastMCP──▶ mcp.py（28 个 @mcp_tool 薄壳） |
| │ |
| ▼ |
| LightpandaClient（单例长驻） |
| ├─ initialize 握手（一次性） |
| ├─ tools/list 缓存（一次性，漂移校验） |
| └─ tools/call 透传（每次调用） |
| ▼ |
| ProcessSupervisor（stderr→日志文件） |
| ▼ |
| lightpanda mcp 子进程（stdio JSON-RPC） |
| ``` |
| |
| ``` |
| plugins/browser/ |
| ├── plugin.json 元数据 + binary_dependencies |
| ├── main.py Plugin 类（on_enable/on_disable/check_readiness/get_status） |
| ├── api.py FastAPI 路由 |
| ├── mcp.py 28 个 @mcp_tool（工厂从 tools_meta 生成） |
| ├── frontend/index.html 静态 UI |
| └── browser/ |
| ├── binary_locator.py 探测 lightpanda 二进制（env/PATH/常见路径/WSL） |
| ├── process_supervisor.py 子进程监管（stderr→文件） |
| ├── mcp_client.py 行分隔 JSON-RPC 客户端 |
| ├── client.py LightpandaClient 单例 |
| ├── tools_meta.py 28 工具元数据（27 browser tool + save） |
| └── errors.py BrowserError + 错误码（对齐上游） |
| ``` |
| |
| ## 配置 |
| |
| ### 环境变量 |
| |
| | 变量 | 默认 | 说明 | |
| |---|---|---| |
| | `LIGHTPANDA_BINARY` | 自动探测 | Lightpanda 可执行文件绝对路径 | |
| |
| ### 子进程 |
| |
| - **懒启动**：插件 enable 时不预启动；首次工具调用时拉起子进程并握手。 |
| - **长驻**：子进程持续运行，复用会话；`on_disable` 或 `/process/stop` 时关闭。 |
| - **日志**：stderr 重定向到 `data/lightpanda/mcp.log`（stdio 协议强约束：stderr 不能走 PIPE）。 |
| |
| ## 安装 |
| |
| 详见 [INSTALL.md](./INSTALL.md)。快速概览： |
| |
| - **Linux / macOS**：下载 nightly release 二进制 |
| - **Windows**：Lightpanda 无原生二进制，需 WSL2 或 Docker |
| - **HuggingFace Spaces**：Dockerfile 内置 nightly release |
| |
| ## 使用 |
| |
| ### 通过 MCP 客户端（Claude Desktop 等） |
| |
| 插件通过平台 FastMCP 暴露 28 个工具，agent 直接调用 `browser-goto` / `browser-markdown` 等。 |
| |
| ### 通过平台 UI |
| |
| 1. 访问 `/tool/browser` |
| 2. 顶部"Lightpanda 二进制"卡片显示状态；未找到时按 OS 显示安装命令 |
| 3. "工具调用"面板选工具 + 填参数，点"执行" |
| 4. "运行日志"与"结果"区展示调用过程与返回 |
| 5. "健康检查"显示二进制/子进程/工具缓存状态及漂移校验 |
| |
| ### 通过 HTTP API |
| |
| ```bash |
| # 探测二进制 |
| curl http://localhost:7860/plugins/browser/api/binary-check |
| |
| # 列出工具 |
| curl http://localhost:7860/plugins/browser/api/tools |
| |
| # 健康检查 |
| curl http://localhost:7860/plugins/browser/api/health |
| |
| # 调用 goto |
| curl -X POST http://localhost:7860/plugins/browser/api/mcp/browser-goto \ |
| -H "Content-Type: application/json" \ |
| -d '{"url": "https://example.com"}' |
| |
| # 查看子进程日志 |
| curl http://localhost:7860/plugins/browser/api/process/logs?tail=50 |
| ``` |
| |
| ## 限制 |
| |
| - **Lightpanda 是 Beta**：参考 https://lightpanda.io/#status，部分网站可能不兼容 |
| - **WSL2 局限**：Windows 上 WSL 与主进程通信经 stdin/stdout 转发，可能比 Linux 直接调用慢 |
| - **工具集漂移**：`tools_meta.py` 是静态锚点；上游新增工具时需同步。`/health` 端点提供漂移校验预警 |
| |
| ## 故障排查 |
| |
| | 现象 | 原因 | 解决 | |
| |---|---|---| |
| | `BINARY_NOT_FOUND` | PATH 中无 lightpanda | 按顶部卡片安装命令安装；或设 `LIGHTPANDA_BINARY` | |
| | `PROCESS_NOT_READY` | 子进程启动/握手失败 | 查看 `/process/logs`；可能二进制损坏或版本不兼容 | |
| | `PROTOCOL_TIMEOUT` | 子进程未及时响应 | 增大 timeout；查 `/process/logs` 找根因 | |
| | `NODE_NOT_FOUND` | selector 未命中元素 | 先用 `browser-tree`/`browser-findElement` 定位元素 | |
| | `FRAME_NOT_LOADED` | 未先 goto 导航 | 先调 `browser-goto` 加载页面 | |
| |
| ## 变更记录 |
| |
| 见 [CHANGELOG](#v30)。v3.0 相对 v2.0：废弃多 driver 抽象与 Playwright/CDP，改为纯 Lightpanda 透传； |
| 工具数 12 → 28（与上游对齐）；修复 v2 多个必现 bug。 |
| |
| ### v3.0 |
| |
| - 纯 Lightpanda 单后端，删除 Playwright/CDP/lightpanda_driver/registry/driver 抽象 |
| - 28 个工具从上游 `tools.zig` 静态提取，工厂生成，零手写 schema |
| - 单例长驻子进程，复用会话 |
| - 修复 v2 的 `mcp_markdown` params.timeout 崩溃、`/binary-check` import 错、registry key 失效等 |
| |
