plugins/browser/README.md

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。快速概览：

• 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

# 探测二进制
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。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 失效等