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 許可證。