MCP Web Snapshot

MCP Web Snapshot

Playwright を使用して包括的なウェブサイトのスナップショット機能を提供する、Model Context Protocol（MCP）サーバーです。このサーバーでは、構造化されたアクセシビリティスナップショット、ネットワークの監視、コンソールメッセージの収集を通じて、LLM がウェブページをキャプチャして分析できます。

主な機能

• 🚀 高速で軽量：Playwright のアクセシビリティツリーを使用し、効率的にスナップショットを取得します
• 🎯 LLM に最適化：AI が利用しやすいように設計された構造化データを出力します
• 📊 包括的な監視：ネットワークリクエスト、レスポンス、コンソールメッセージをキャプチャします
• 🔍 要素参照：インタラクティブな要素に一意の識別子を追加し、正確に指定できるようにします
• 🛡️ 本番環境に対応：エラー処理、リソース制限、タイムアウト管理を内蔵しています
• ✅ 十分なテスト：コードカバレッジを含む包括的なテストスイートを備えています

要件

• Python 3.11 以降
• VS Code、Cursor、Windsurf、Claude Desktop、またはその他の MCP クライアント

はじめに

まず、クライアントを使って MCP Web Snapshot サーバーをインストールします。一般的な設定は次のとおりです。

{
  "mcpServers": {
    "mcp-web-snapshot": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-web-snapshot",
        "run",
        "python",
        "src/server.py"
      ]
    }
  }
}

VS Code へのインストール

VS Code CLI を使用して MCP Web Snapshot サーバーをインストールできます。

# For VS Code
code --add-mcp '{"name":"mcp-web-snapshot","command":"uv","args":["--directory","/path/to/mcp-web-snapshot","run","python","src/server.py"]}'

インストール後、VS Code の GitHub Copilot エージェントで MCP Web Snapshot サーバーを利用できるようになります。

Cursor へのインストール

Cursor Settings → MCP → Add new MCP Server に移動します。任意の名前を付け、タイプに command を選択し、コマンドに uv、引数に ["--directory", "/path/to/mcp-web-snapshot", "run", "python", "src/server.py"] を指定します。

{
  "mcpServers": {
    "mcp-web-snapshot": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-web-snapshot",
        "run",
        "python",
        "src/server.py"
      ]
    }
  }
}

開発環境のセットアップ

ローカルインストール

1. このリポジトリをクローンします。

git clone https://github.com/your-username/mcp-web-snapshot.git
cd mcp-web-snapshot

2. uv を使用して依存関係をインストールします。

uv sync

3. Playwright ブラウザーをインストールします。

uv run playwright install

4. サーバーを実行します。

uv run python src/server.py

プロジェクト構成

├── src/
│   ├── server.py               # Main MCP server entry point
│   ├── registry.py             # Tool registration logic
│   └── tools/
│       ├── __init__.py
│       └── snapshot_url.py     # Web snapshot implementation
├── tests/                      # Test suite
│   ├── __init__.py
│   ├── test_snapshot_url.py    # Unit tests for website_snapshot
│   └── README.md               # Test documentation
├── pyproject.toml              # Project configuration
├── pytest.ini                  # Pytest configuration
├── uv.lock                     # Lock file for dependencies
└── README.md                   # This file

テスト

このプロジェクトには、pytest を使用した包括的なテストスイートが含まれています。

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run with coverage report
PYTHONPATH=. uv run pytest --cov=src.tools.snapshot_url --cov-report=term-missing

現在のテストカバレッジは 92% で、次の項目を対象としています。

• スナップショットの取得とフォーマットの成功
• ネットワークリクエストとコンソールメッセージの監視
• URL の検証
• エラー処理と復旧

利用可能なツール

ウェブサイトのスナップショット

ツール：website_snapshot

説明：監視機能を使ってウェブページの包括的なスナップショットを取得します

パラメーター：

• target_url（string）：キャプチャする URL（プロトコルを含む有効な URL である必要があります）

機能：

• 🎭 アクセシビリティスナップショット：アクセシビリティツリーの構造全体をキャプチャします
• 🌐 ネットワーク監視：ページ読み込み中のすべてのネットワークリクエストとレスポンスを記録します
• 🖥️ コンソールメッセージ：クライアント側のコンソール出力（ログ、警告、エラー）をキャプチャします
• 🎯 要素参照：インタラクティブな要素に一意の参照 ID を追加します
• 📊 パフォーマンス指標：キャプチャした要素とネットワークアクティビティの概要を提供します

使用例：

# Through MCP client
result = await website_snapshot("https://example.com")

出力構造：

✅ Captured snapshot with 25 elements, 12 requests, 0 console messages
🔍 Example Website - Home Page
📍 https://example.com

🎭 Accessibility Snapshot:
- navigation "Main":
  - link "Home": [ref=1]
  - link "About": [ref=2]
  - button "Contact" [ref=3]
- main:
  - heading "Welcome to Example"
  - link "Get Started": [ref=4]

🌐 Network Requests:
🌐 GET https://example.com
   Status: 200
   Response: <!DOCTYPE html><html>...

🖥️ Console:
No console messages

🎯 Element References:
[ref=1]: link "Home"
[ref=2]: link "About"
[ref=3]: button "Contact"
[ref=4]: link "Get Started"

設定

サーバーは src/tools/snapshot_url.py の CONFIG ディクショナリで設定できます。

CONFIG = {
    "viewport": {"width": 1920, "height": 1080},
    "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36",
    "timeout": 15000,  # 15 seconds
}

カスタマイズ項目

• ビューポートサイズ：ブラウザーウィンドウのサイズを調整します
• ユーザーエージェント：ブラウザーの識別情報をカスタマイズします
• タイムアウト：ページ操作の最大待機時間を設定します
• コンテンツフィルタリング：レスポンス本文のサイズ制限とコンテンツタイプのフィルターを変更します

ユースケース

LLM によるテスト支援

包括的なページ状態をキャプチャし、テストを自動生成します。

"Please take a snapshot of https://myapp.com/login and help me create Page Object Model classes based on the discovered elements and structure."

ウェブコンテンツ分析

コンテンツの分析と監視に使用する構造化データを抽出します。

"Take a snapshot of https://competitor.com/pricing and analyze any pricing changes or new features compared to what we discussed last week."

アクセシビリティ監査

アクセシビリティツリーのデータを活用して、準拠状況を確認します。

"Please capture a snapshot of https://myapp.com and identify any accessibility issues or areas for improvement based on WCAG guidelines."

API 統合の分析

ネットワークアクティビティを監視し、アプリケーションの動作を把握します。

"Take a snapshot of https://dashboard.example.com after I log in and show me what API calls are being made so I can understand the data flow."

クロスブラウザーテストのセットアップ

キャプチャしたインタラクションに基づいて、テストシナリオを生成します。

"Snapshot https://myapp.com/checkout and help me create comprehensive test cases that cover all the interactive elements and user workflows."

エラー処理

このサーバーには、包括的なエラー処理が組み込まれています。

• 無効な URL：形式が正しくない URL に対して、わかりやすいエラーメッセージを返します
• ネットワークタイムアウト：設定可能なタイムアウト制限と、適切なフォールバック機能を備えています
• ブラウザーのクラッシュ：自動的にクリーンアップし、リソースを管理します
• コンテンツの制限：メモリの問題を防ぐため、大きなレスポンス本文をスマートにフィルタリングします

貢献

1. リポジトリをフォークします
2. フィーチャーブランチを作成します：git checkout -b feature-name
3. 変更を加え、テストを追加します
4. テストを実行します：uv run pytest
5. テストカバレッジを確認します：PYTHONPATH=. uv run pytest --cov=src.tools.snapshot_url --cov-report=term-missing
6. コードスタイルに準拠していることを確認します：uv run ruff check
7. プルリクエストを送信します

すべてのテストに合格することを確認し、現在のテストカバレッジを維持または向上させてください。

ライセンス

このプロジェクトは MIT ライセンスの下で公開されています。詳しくはLICENSEファイルをご覧ください。

謝辞

• MCP Server Website Snapshotの記事に着想を得ています
• Microsoft's Playwright MCPを基盤として構築されています
• 信頼性の高いブラウザー自動化を実現するため、Playwrightを使用しています
• LLM との統合にModel Context Protocolを使用しています

関連プロジェクト

• Playwright MCP - インタラクティブなブラウザー自動化を行う MCP サーバー
• MCP Python SDK - MCP サーバー向け Python フレームワーク