金大哥 - pagelens-mcp MCP 详情

article

README

🚀 PageLens

PageLens 是一个 MCP 服务器，它能为 AI 编码代理提供前端应用的视觉反馈。只需一条命令，无需配置，你的 AI 代理就能查看你的应用、点击按钮、读取控制台错误并对比视觉变化。

🚀 快速开始

1. 启动开发服务器

npm run dev
# 应用运行于 http://localhost:5173

2. 将 PageLens 添加到 MCP 配置中

⚠️ 重要提示

PageLens 尚未发布到 npm。请参考开发部分从源代码安装，然后使用以下配置并指定本地路径。

Claude Code（项目根目录下的 .mcp.json）：

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

Cursor（.cursor/mcp.json）：

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

3. 启动你的代理

就这么简单。代理现在可以使用所有 PageLens 工具了。你可以让它“截取我的应用截图”或“检查控制台错误”，它会立即执行。

✨ 主要特性

为 AI 编码代理提供前端应用的视觉反馈，消除手动循环。
无需配置，一条命令即可启动。
被动收集控制台日志和网络错误。
每次交互后自动返回截图。
内置视觉差异对比和视觉质量审查工具。
支持实时调试和多路由截图。

📦 安装指南

从源代码安装

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

💻 使用示例

基础用法

npx pagelens http://localhost:3000

📚 详细文档

问题描述

在使用 AI 编码代理（如 Claude Code、Cursor、Windsurf）进行前端开发时，代理无法看到应用的外观。这会导致一个痛苦的手动循环：

代理进行代码更改。
你查看浏览器。
你用文字描述视觉问题，或者截图并拖入聊天框。
你手动复制控制台错误。
每次会话重复数十次。

PageLens 完全消除了这个循环。

工作原理

你的应用 (localhost:3000)
        |
无头 Chrome (Puppeteer)
        |
PageLens MCP 服务器
        |
Claude Code / Cursor / Windsurf

PageLens 启动一个指向你开发服务器的无头浏览器，被动收集控制台日志和网络错误，并提供任何与 MCP 兼容的 AI 代理都可以调用的工具 —— 截图、点击、输入、DOM 检查、视觉差异对比 —— 无需你手动操作。

为何选择 PageLens 而非 Playwright MCP / Browser 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 编码代理能够看到你的前端应用 —— 并消除该循环中的每一个手动步骤。

工具介绍

观察工具

| 工具 | 描述 | | ---- | ---- | | 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 768x1024、desktop 1280x720）或自定义 width/height。返回截图。 | | dom_inspect | 获取元素的计算样式、类、子元素和边界框。 | | get_page_info | 返回当前 URL、页面标题、视口大小、滚动位置和文档尺寸。 |

差异对比工具

| 工具 | 描述 | | ---- | ---- | | visual_diff | 将当前页面与存储的基线进行比较。首次调用捕获基线，后续调用返回带有突出显示的更改像素的差异图像和百分比摘要。 | | multi_route_screenshot | 一次调用即可对多个路由进行截图。返回每个路由的带标签图像。 |

调试工具

| 工具 | 描述 | | ---- | ---- | | toggle_headless | 在无头和可见浏览器之间切换。当可见时，会弹出一个 Chrome 窗口，你可以实时查看代理与你的应用的交互。 |

CLI 选项

pagelens <url> [options]

选项:
  --no-headless        显示浏览器窗口
  --viewport <preset>  初始视口: mobile | tablet | desktop (默认: desktop)
  -h, --help           显示帮助信息

架构

src/
├── index.ts              # CLI 入口点，参数解析
├── server.ts             # MCP 服务器，工具注册
├── browser.ts            # Puppeteer 生命周期，被动日志/错误收集
├── tools/
│   ├── screenshot.ts     # 截图、元素截图、多路由截图
│   ├── console.ts        # 控制台日志、网络错误
│   ├── interact.ts       # 点击、输入、导航、设置视口
│   ├── inspect.ts        # DOM 检查
│   └── diff.ts           # 视觉差异对比
└── utils/
    └── viewport-presets.ts

关键设计决策：

延迟连接 —— MCP 服务器立即启动。在首次调用工具时才导航到你的应用，因此如果你的开发服务器尚未运行，PageLens 不会崩溃。
被动收集 —— 从浏览器启动的那一刻起，控制台日志和网络错误就会被捕获到环形缓冲区中。代理可以在需要时检查，而不是在事件发生时检查。
每次交互后截图 —— click、type、navigate 和 set_viewport 操作都会返回截图，以便代理始终能看到其操作的结果。
基线存储 —— 视觉差异对比的基线按路由存储在内存中，无需进行文件系统设置。

🔧 技术细节

技术栈

TypeScript —— 类型安全的工具处理程序和 MCP 集成
Puppeteer —— 无头 Chrome 自动化（捆绑 Chromium）
@modelcontextprotocol/sdk —— 官方 MCP 服务器 SDK
pixelmatch + pngjs —— 用于视觉差异对比的像素级图像比较

📄 许可证

本项目采用 MIT 许可证。

pagelens-mcp