Pagelens MCP

🚀 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）进行前端开发时，代理无法看到应用的外观。这会导致一个痛苦的手动循环：

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

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 并不试图成为一个通用的浏览器自动化框架。它只做一件事 —— 让你的 AI 编码代理能够看到你的前端应用 —— 并消除该循环中的每一个手动步骤。

工具介绍

观察工具

交互工具

差异对比工具

调试工具

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 许可证。