AI导哈

前端开发视觉反馈工具

PageLens 是一个为 AI 编程代理提供前端应用视觉反馈的 MCP 服务器，通过无头浏览器自动捕获屏幕截图、控制台错误和网络错误，简化前端开发流程。

  • by amoghmanral
  • TypeScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 amoghmanral/pagelens-mcp

使用说明

PageLens

MCP服务器，为AI编码代理提供前端应用程序的视觉反馈。一个命令，无需配置——你的AI代理现在可以看到你的应用程序、点击按钮、读取控制台错误和差异视觉变化。

npx pagelens http://localhost:3000

问题

当使用AI编码代理（Claude Code、Cursor、Windsurf）进行前端开发时，代理是盲目的。它可以编辑代码，但看不到应用程序的样子。这会产生一个痛苦的手动循环：

  1. 代理进行代码更改
  2. 你看浏览器
  3. 您可以用文字描述视觉问题，或截图并拖动到聊天中
  4. 您手动复制控制台错误
  5. 每次会话重复数十次

PageLens完全消除了这种循环。

运作原理

Your app (localhost:3000)
        |
Headless Chrome (Puppeteer)
        |
PageLens MCP Server
        |
Claude Code / Cursor / Windsurf

PageLens启动一个指向您的开发服务器的无头浏览器，被动收集控制台日志和网络错误，并公开任何兼容MCP的AI代理都可以调用的工具——屏幕截图、点击、打字、DOM检查、视觉差异——而无需您手动执行任何操作。

为什么PageLens胜过剧作家MCP/浏览器MCP？

通用浏览器自动化MCP公开了低级原语——你会得到 evaluate JavaScript, take screenshot, click element 作为单独的、断开连接的动作。PageLens是专门为AI前端开发循环构建的，它以重要的方式改变了设计：

PageLens 通用浏览器MCP
设置 npx pagelens <url> --零配置 需要浏览器启动管理、连接处理
控制台/网络错误 在后台被动收集。代理人随时都会检查。 代理必须主动轮询或设置侦听器。工具调用之间的错误丢失。
互动反馈 每一个 click, type, navigate 自动返回屏幕截图 代理必须记住在每次操作后进行屏幕截图
视觉回归 内置 visual_diff --基线捕获、像素比较、差异图像、变化百分比 不可用。代理需要手动截图、存储、比较。
视觉质量审查 visual_audit 返回一个结构化的检查表，提示代理批判性地评估布局、对比度、内容准确性 没有等效项。代理人往往在没有指导的情况下，表面上确认“看起来不错”。
现场调试 toggle_headless 打开Chrome浏览器并实时查看代理程序的工作情况 通常仅支持无头模式或需要重新启动
多路径审计 multi_route_screenshot 在一次通话中捕获多个页面 客服必须单独导航和截图每条路线

PageLens并不试图成为一个通用的浏览器自动化框架。它只做一件事——让你的AI编码代理关注你的前端——并从循环中删除每一个手动步骤。

快速开始

1.启动您的开发服务器

npm run dev
# App running at http://localhost:5173

2.将PageLens添加到MCP配置中

注： PageLens还没有在npm上。看 发展 部分从源代码安装，然后使用下面的配置和本地路径。

克劳德代码 (.mcp.json 在项目根目录中）：

{
  "mcpServers": {
    "pagelens": {
      "command": "node",
      "args": ["/path/to/PageLens/dist/index.js", "http://localhost:5173"]
    }
  }
}

光标 (.cursor/mcp.json):

{
  "mcpServers": {
    "pagelens": {
      "command": "node",
      "args": ["/path/to/PageLens/dist/index.js", "http://localhost:5173"]
    }
  }
}

3.启动您的代理

就是这样。代理现在可以访问所有PageLens工具。让它“截取我的应用程序的屏幕截图”或“检查控制台错误”，它就可以正常工作了。

工具

观察

工具 说明
screenshot 将当前页面捕获为PNG格式。可选的 route 为了首先导航， fullPage 对于整个可滚动页面。
screenshot_element 通过CSS选择器对特定DOM元素进行截图。
console_logs 返回自上次调用以来的所有控制台输出（日志、警告、错误）。返回后清除缓冲区。
network_errors 返回自上次调用以来所有失败的网络请求。返回后清除缓冲区。
visual_audit 带有指导性检查表的屏幕截图促使代理批判性地评估内容的准确性、布局、对比度和抛光度，而不仅仅是确认呈现的内容。

交互

工具 说明
click 按选择器单击元素。点击后返回屏幕截图。
type 在输入框中键入文本。可选的 clear 以替换现有内容。返回屏幕截图。
scroll 按给定的像素数向上/向下滚动页面或特定元素。返回屏幕截图。
hover 通过选择器将鼠标悬停在元素上，以触发工具提示、下拉菜单或悬停样式。返回屏幕截图。
select 从以下选项中选择一个 <select> 按值下拉。返回屏幕截图。
navigate 转到URL或路径。返回新页面的屏幕截图。
set_viewport 调整到预设大小(mobile 375x812， tablet 768×1024， desktop 1280x720）或定制 width/height。返回屏幕截图。
dom_inspect 获取元素的计算样式、类、子元素和边界框。
get_page_info 返回当前URL、页面标题、视口大小、滚动位置和文档尺寸。

困难

工具 说明
visual_diff 将当前页面与存储的基线进行比较。第一次调用捕获基线，后续调用返回一个差异图像，突出显示更改的像素和百分比摘要。
multi_route_screenshot 一次通话中多条路线的截图。返回每条路线的标记图像。

调试

工具 说明
toggle_headless 在无头浏览器和可见浏览器之间切换。当可见时，会出现一个Chrome窗口，以便您可以实时观看代理与您的应用程序的交互。

CLI选项

pagelens <url> [options]

Options:
  --no-headless        Show the browser window
  --viewport <preset>  Initial viewport: mobile | tablet | desktop (default: desktop)
  -h, --help           Show help

建筑

src/
├── index.ts              # CLI entry point, arg parsing
├── server.ts             # MCP server, tool registration
├── browser.ts            # Puppeteer lifecycle, passive log/error collection
├── tools/
│   ├── screenshot.ts     # screenshot, screenshot_element, multi_route_screenshot
│   ├── console.ts        # console_logs, network_errors
│   ├── interact.ts       # click, type, navigate, set_viewport
│   ├── inspect.ts        # dom_inspect
│   └── diff.ts           # visual_diff
└── utils/
    └── viewport-presets.ts

关键设计决策：

  • 延迟连接 --MCP服务器立即启动。导航到您的应用程序发生在第一次工具调用时，因此如果您的开发服务器尚未运行，PageLens永远不会崩溃。
  • 被动收集 --从浏览器启动的那一刻起，控制台日志和网络错误就被捕获在环形缓冲区中。代理会在它想要的时候进行检查，而不是在事件发生的时候。
  • 每次互动后的截图 — click, type, navigate，以及 set_viewport 所有这些都会返回一个屏幕截图，这样代理就可以始终看到它所做操作的结果。
  • 基线存储 --视觉差异基线按路线存储在内存中。不需要文件系统设置。

发展

git clone https://github.com/amoghmanral/pagelens.git
cd pagelens
npm install
npm run build

使用Claude Code进行本地测试：

claude mcp add pagelens -- node /path/to/PageLens/dist/index.js http://localhost:3000

技术栈

  • TypeScript --类型安全工具处理程序和MCP集成
  • 操纵者 --无头Chrome自动化（捆绑Chromium）
  • @模型上下文协议/sdk --官方MCP服务器SDK
  • 像素匹配 + pngjs --用于视觉差异的像素级图像比较

许可证

麻省理工学院

相关 MCP