面向开发人员的DevTool Broswer
](https://www.npmjs.com/package/@4bd4ll4h/mcp-devtools-browser)  
一个强大的模型上下文协议（MCP）服务器，使用Puppeteer为LLM提供浏览器自动化功能。
🚀 快速开始
npm install -g @4bd4ll4h/mcp-devtools-browser添加到MCP客户端配置中：
{
"mcpServers": {
"devtools-browser": {
"command": "npx",
"args": ["@4bd4ll4h/mcp-devtools-browser"]
}
}
}✨ 特性
- 浏览器自动化：打开、导航和控制浏览器页面
- DOM检查：以可访问性为重点提取结构化DOM数据
- 网络监控：捕获和分析网络请求
- 事件日志记录：全面的会话跟踪和调试
- 用户交互：单击、键入、滚动、悬停等
- 视觉捕捉：屏幕截图和视觉分析
- 资源管理：自动清理和内存管理
📖 文档
🤝 贡献
______________________________________________________________________
项目规范
项目概述
该项目旨在建立一个 模型上下文协议（MCP） 协助LLM生成 高质量、可靠的网络抓取脚本 使用 TypeScript+Puppeter.
MCP将充当以下之间的受管网关：
- 真实的浏览器环境（Puppeteer）
- 页面生命周期事件（请求、响应、选择器、DOM状态）
- LLM的任务是理解页面并生成抓取操作
目标：
允许LLM自主探索页面、检查网络流量、提取DOM节点路径/选择器，并根据需要生成健壮的抓取脚本。
______________________________________________________________________
核心用例
- 从任何网站提取数据
- 提供、产品、表格、PDF、元数据、图像
- 网络智能
- 检测后端API调用 - 推断JSON数据结构 - 将结构化数据优先于渲染的HTML
- 动态DOM检查
- 选择稳定的选择器 - 滚动并缓慢加载内容 - 处理影子DOM、iframe、modals
______________________________________________________________________
为什么选择MCP？
MCP提供：
- 结构化双向工作流
- 使用模式对操作进行建模
- 更好的编排
- 可重复性
它能够构建 LLM驱动的刮擦剂.
______________________________________________________________________
主要技术挑战
该系统必须解决：
✅ 向LLM展示类似DevTools的见解
- 网络请求/响应
- 标题、正文、错误代码
✅ DOM可见性大
- 没有过载令牌限制
✅ 强大的有状态浏览
- 标签页
- 导航历史记录
- 并行提取
______________________________________________________________________
高级体系结构
LLM MCP Server Puppeteer Controller
|
├── Browser Pool (multi-page sessions)
├── Network Listener
└── DOM Snapshot Manager______________________________________________________________________
关键组件
1. 浏览器管理器
责任：
- 启动/停止浏览器实例
- 创建新选项卡
- 关闭选项卡
- 报告会话信息
建议：
- 维护一个以以下方式键入的内部注册表
sessionId - 每个LLM对话一个会话
2. 选项卡/页面管理器
对于每一页：
- 导航
- 单击、键入、滚动、等待选择器
- 保存屏幕截图
- 保持页面状态
推荐：
- 限制最大打开标签
- 自动清理资源
3. 网络拦截器
目标：
- 捕获所有XHR/接听电话
- 检查响应
- 确定API终点
- 检测潜在的结构化数据源
MCP工具操作：
getNetworkRequests()filterRequestsBy(url|type|status)fetchResponseBody(requestId)
4. DOM检查器
挑战： 页面可能很大；LLM令牌限制适用。
方法：
A.DOM分块
将DOM拆分为切片：
- 按深度
- 按视觉视口
- 按选择器路径
B.选择器聚光灯
LLM请求：
- 突出显示悬停元素或查询的可能选择器
C.CSS路径生成
自动计算：
- CSS选择器
- 路径表达式
- 强大的启发式选择器
______________________________________________________________________
建议LLM面对MCP行动
导航
navigate(url)goBack()goForward()
DOM查询
querySelector(selector)querySelectorAll(selector, limit)extractAttributes(selector, attrs[])getBoundingClientRect(selector)scroll(amount)scrollToBottom()
网络
listNetworkRequests(type?)getRequestDetails(requestId)getResponseBody(requestId)
截图
captureScreenshot(mode=viewport|full)
调试
printConsoleLogs()printNetworkErrors()
效用
generateSelectorsAtPoint(x,y)
______________________________________________________________________
浏览器/选项卡生命周期策略
会话规则
- 每个MCP会话都会创建 一个浏览器实例
- 标签被注册和跟踪
- 硬限制（例如5）以避免内存崩溃
垃圾回收
- 空闲选项卡>N分钟→ 自动关闭
- 关闭会话结束时的所有选项卡
选项卡标识
返回结构化选项卡状态：
{
"tabId": "abc123",
"url": "...",
"title": "...",
"loading": false
}______________________________________________________________________
展示类DevTools功能
方法A——Chrome DevTools协议事件
用途：
page.on('request')page.on('response')page.on('console')
赞成的意见：
- 实时
- 低开销
方法B——拦截和存储网络历史
店铺：
- 方法
- 统一资源定位符
- 状态
- 请求体
- 响应大小/正文提示
稍后让LLM过滤。
方法C——按类型过滤
- XMLHttpRequest
- 获取
- 媒体
- 样式表
- 脚本
可用于目标发现。
推荐：全部三个。
______________________________________________________________________
使大型DOM LLM友好
方法A——语境分块
按以下方式拆分DOM：
- 可见部分
- 语义区域(`
, `)
方法B——仅限选择者摘要
与其转储HTML，不如提供：
selector -> value summary例子：
.OfferTitle -> "Summer Sale"
.OfferPrice -> "$19.99"方法C——按需快照
LLM问：
“给我‘products’容器的DOM”
您仅使用本地化的HTML进行响应。
推荐
A+C组合。
______________________________________________________________________
您建议的方式（评估）
优势
✔ 监控请求捕获隐藏的API ✔ DOM提取支持视觉抓取 ✔ 拦截生命周期提供完整性
弱点/风险
⚠ 转储完整DOM=令牌爆炸 ⚠ JSON响应可能很大 ⚠ 网络日志太多→ noise ⚠ LLM的重复结构混乱
潜在的质量问题
- 选择器不稳定性（动态类）
- 无限的滚动复杂性
- 事件时间问题
- CSP屏蔽截图
我们将使用启发式和检测规则来缓解这些问题。
______________________________________________________________________
推荐的选择器稳定性启发式方法
- 首选：
data-*属性- 语义HTML
- 母链
- 避免：
- 混淆的类名
- 自动生成的ID
- 验证：
- 该选择器在滚动事件中匹配一致的计数
______________________________________________________________________
脚本生成哲学
水平回退顺序：
- 结构化API JSON（最佳）
- 语义HTML
- 计算DOM文本
- 视觉刮擦（最严重）
LLM应使用此层次结构进行操作。
______________________________________________________________________
MCP工具模式示例
示例操作：列出网络请求
{
"name": "listNetworkRequests",
"arguments": {
"type": "xhr",
"status": 200,
"contains": "offers"
}
}示例操作：查询DOM
{
"name": "querySelectorAll",
"arguments": {
"selector": ".offer-card",
"limit": 20,
"attributes": ["href", "innerText"]
}
}______________________________________________________________________
LLM工作流示例
- 导航到目标URL
- 监控JSON端点的网络
- 请求目标区域的DOM快照
- 选择稳定的选择器
- 在TS中生成可重用的抓取脚本
- 在多个页面上测试选择器（如果分页）
- 输出结构化结果
______________________________________________________________________
错误处理策略
- 暴露结构化错误
- 包括堆栈痕迹
- 通知LLM瞬态故障
例子：
{
"error": "SelectorNotFound",
"selector": ".price",
"attempts": 3
}______________________________________________________________________
将来的扩展
- PDF下载
- 文件元数据提取
- 可访问性树刮擦
- 快照差异检测
- 会话重放
______________________________________________________________________
安全考虑
- 不允许导航
localhost端口 - 默认情况下禁用下载
- 清理文件输出路径
- 删除敏感请求标头
______________________________________________________________________
技术栈
语言：TypeScript 浏览器自动化：木偶 协议：MCP 状态存储：内存映射 解析器工具:
- DOM遍历工具
- CSS/XPath生成器库
______________________________________________________________________
文件夹结构（建议）
/src
/mcp
actions/
schemas/
router.ts
/browser
BrowserManager.ts
PageManager.ts
NetworkTracker.ts
DomInspector.ts
utils/
index.ts
types.ts______________________________________________________________________
成功标准
✅ LLM可以：
- 检查网络通话
- 安全地读取DOM结构
- 导航选项卡
- 识别稳定的选择器
- 生成健壮的脚本
✅ 代理人：
- 避免完整的DOM转储
- 尽可能使用API端点
- 可靠地提取结构化结果
______________________________________________________________________
最终目标
一个完全自主的抓取助手，可以：
- 发现数据源
- 生成弹性提取逻辑
- 生成Types/Node脚本
- 处理动态web应用程序
______________________________________________________________________
准备建造
现在Cursor AI有：
- 全局上下文
- 建筑
- 最佳实践启发式
- 风险
- 工作流
- 预期API
此文件应支持智能上下文感知编码辅助。
让我知道你什么时候准备好了：
- 规范脚手架
- MCP动作定义
- Puppeter包装器实现
- 选择器启发式
- JSON模式合约