Pagelens MCP

🚀 PageLens

AIコーディングエージェントにフロントエンドアプリの視覚的なフィードバックを提供するMCPサーバーです。1つのコマンドで、設定不要です。AIエージェントがアプリを見たり、ボタンをクリックしたり、コンソールエラーを読んだり、視覚的な変更を比較したりすることができるようになります。

npx pagelens http://localhost:3000

🚀 クイックスタート

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ツールにアクセスできるようになります。「アプリのスクリーンショットを撮って」や「コンソールエラーをチェックして」と要求すると、そのまま動作します。

✨ 主な機能

PageLensは、AIコーディングエージェントにフロントエンドアプリの視覚的なフィードバックを提供することで、開発プロセスを大幅に改善します。具体的には、以下のような機能を提供します。

問題解決

フロントエンド開発でAIコーディングエージェント（Claude Code、Cursor、Windsurfなど）を使用する際、エージェントはアプリの外観を見ることができません。これにより、手動でのループが発生しますが、PageLensはこのループを完全に排除します。

動作原理

あなたのアプリ (localhost:3000)
        |
ヘッドレスChrome (Puppeteer)
        |
PageLens MCPサーバー
        |
Claude Code / Cursor / Windsurf

PageLensは、開発サーバーを指すヘッドレスブラウザを起動し、コンソールログとネットワークエラーを受動的に収集します。また、MCP互換のAIエージェントが呼び出せるツール（スクリーンショット、クリック、入力、DOM検査、視覚的な差分比較など）を提供します。

他のツールとの比較

一般的なブラウザ自動化MCPは低レベルのプリミティブを公開しますが、PageLensはAIフロントエンド開発ループに特化して設計されています。以下は、PageLensと一般的なブラウザMCPの比較です。

💻 使用例

基本的な使用法

npx pagelens http://localhost:3000

高度な使用法

# ブラウザウィンドウを表示する
pagelens http://localhost:3000 --no-headless

# 初期ビューポートを設定する
pagelens http://localhost:3000 --viewport mobile

📚 詳細ドキュメント

ツール

観測

インタラクション

差分比較

デバッグ

CLIオプション

pagelens <url> [options]

Options:
  --no-headless        ブラウザウィンドウを表示する
  --viewport <preset>  初期ビューポート: mobile | tablet | desktop (default: desktop)
  -h, --help           ヘルプを表示する

🔧 技術詳細

アーキテクチャ

src/
├── index.ts              # CLIエントリポイント、引数解析
├── server.ts             # MCPサーバー、ツール登録
├── browser.ts            # Puppeteerのライフサイクル、受動的なログ/エラー収集
├── 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統合
• Puppeteer — ヘッドレスChrome自動化（Chromiumをバンドル）
• @modelcontextprotocol/sdk — 公式MCPサーバーSDK
• pixelmatch + pngjs — 視覚的な差分比較のためのピクセルレベルの画像比較

📄 ライセンス

MIT