轻熊猫无头浏览器 kuanbandu/dsh-lightpanda-mcp

dsh-lightpanda-mcp

一个「只改配置」的 DSH 插件包，把 Lightpanda 作为 MCP 工具服务器挂进来，提供无头浏览器能力（读取页面、点击填表、截图、提取结构化数据等）。

包名：@kuanbandu/dsh-lightpanda-mcp（MIT，见 LICENSE）。

快速开始

1. 确认 lightpanda 在 PATH 上：lightpanda version；不在就软链到 PATH 里的目录。
ln -sfn ~/.local/bin/lightpanda ~/.npm-global/bin/lightpanda
lightpanda version

2. git clone https://github.com/kuanbandu/dsh-lightpanda-mcp.git
3. 在 DSH 里执行 plugin_manager install_bundle，target 填克隆目录的绝对路径。
4. 新开一个会话，工具会以 mcp__lightpanda__ 出现。

要求

| 项目 | 说明 |
| DeepSeek Harness | @deepseek-ai/dsh-mcp-client 随 dsh 自带，无需额外安装 |
| Lightpanda 二进制 | lightpanda 必须在 PATH 上 —— 用 lightpanda version 确认 |
| 平台 | Linux x86_64（其他目标自行构建） |
| Node.js | 本包不需要 |

验证

重启后工具以 mcp__lightpanda__<tool> 出现。快速冒烟测试：

1. mcp__lightpanda__goto，url: https://example.com
2. mcp__lightpanda__markdown — 应返回页面文本
3. mcp__lightpanda__tree — 带 backendNodeId 的语义树

如果什么都没出现，手工运行 lightpanda mcp（使用 Harness 相同的 PATH），看 stderr。
failOnStartupError 故意设为 false，二进制异常时降级为「工具缺失」而非阻塞启动。

工具

| 分组 | 工具 |
| 读取页面 | tree, markdown, html, extract, structuredData, links, consoleLogs, nodeDetails |
| 导航/等待 | goto, getUrl, waitForSelector, waitForScript, waitForState, scroll |
| 交互 | click, hover, fill, selectOption, setChecked, press, findElement, interactiveElements, detectForms |
| 检查/捕获 | screenshot, download, getCookies |
| 逃生舱 | evaluate（页面 JS）、save（录制可复用的 agent 脚本） |
| 会话/杂项 | session_list, session_new, session_close, getEnv, search |

经验法则：陌生页面先 tree；用 selector 缩小读取范围；数据任务最后用 extract；把页面文本当不可信数据。

配置

全部在 cordis.patch.yml：

| 键 | 值 | 用途 |
| serverName | lightpanda | 工具前缀 mcp__lightpanda__ |
| transport | stdio | 本地子进程，无端口/鉴权 |
| command / args | lightpanda / [mcp] | 不在 PATH 时也可填绝对路径 |
| env | 关闭遥测与 core dump | 保持安静、避免崩溃转储 |
| toolCallTimeoutMs | 120000 | 长时间爬取与 waitForState: networkidle 需要余量 |
| maxInstructionBytes | 16384 | 页面指令载荷上限 |
| failOnStartupError | false | 二进制缺失不阻塞启动 |
| reconnect | 开启，500 ms → 30 s，10 次 | 浏览器进程崩溃后自动恢复 |

限制

- 截图是 Lightpanda 计算出的文本布局，非像素级渲染。
- 无持久化已登录 profile —— 已登录流程请用 DSH 浏览器桥。
- Lightpanda 是快速迭代的 nightly 软件；请固定你测试过的二进制版本。

许可证

MIT（见 LICENSE）。