MCP Web Snapshot

MCP Web Snapshot

一个模型上下文协议（MCP）服务，使用 Playwright 提供全面的网站快照功能。此服务可通过结构化的无障碍快照、网络监控和控制台消息收集，让大模型捕获并分析网页。

主要功能

• 🚀 快速轻量：使用 Playwright 的无障碍树，高效生成快照
• 🎯 针对大模型优化：结构化数据输出，专为 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 Agent 使用 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
}

自定义选项

• 视口大小：调整浏览器窗口尺寸
• 用户代理：自定义浏览器标识
• 超时：控制页面操作的最长等待时间
• 内容筛选：修改响应正文大小限制和内容类型筛选条件

使用场景

大模型引导的测试

捕获全面的页面状态，用于自动生成测试：

"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. Fork 此仓库
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. 提交 pull request

请确保所有测试均通过，并保持或提高当前的测试覆盖率。

许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。

致谢

• 灵感来自文章 MCP Server Website Snapshot
• 基于 Microsoft's Playwright MCP 构建
• 使用 Playwright 实现可靠的浏览器自动化
• 使用 Model Context Protocol 集成大模型

相关项目

• Playwright MCP - 交互式浏览器自动化 MCP 服务
• MCP Python SDK - MCP 服务 Python 框架