MCP网页快照服务器
项目介绍
MCP Web快照
一个使用Playwright提供全面网站快照能力的模型上下文协议（MCP）服务器。该服务器使LLMs能够通过结构化的可访问性快照、网络监控和控制台消息收集来捕获和分析网页。
主要特性
- 🚀 快速且轻量级：使用Playwright的可访问性树进行高效的快照
- 🎯 优化用于LLM：专门设计用于AI消费的结构化数据输出
- 📊 全面监控：捕捉网络请求、响应和控制台消息
- 🔍 元素引用：为交互元素添加唯一标识符以实现精确定位
- 🛡️ 生产就绪：内置错误处理、资源限制和超时管理
- ✅ 经过充分测试：具有代码覆盖率的全面测试套件
要求
- Python 3.11或更新版本
- VS Code, Cursor, Windsurf, Claude Desktop 或其他任何MCP客户端
开始使用
首先，使用您的客户端安装MCP Web快照服务器。典型的配置如下所示：
{
"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快照服务器：
# 对于VS Code
code --add-mcp '{"name":"mcp-web-snapshot","command":"uv","args":["--directory","/path/to/mcp-web-snapshot","run","python","src/server.py"]}'
安装后，MCP Web快照服务器将在VS Code中与GitHub Copilot代理一起可用。
在Cursor中安装
前往Cursor设置 → MCP → 添加新MCP服务器。按喜好命名，使用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"
]
}
}
}
开发环境设置
本地安装
- 克隆此仓库：
git clone https://github.com/your-username/mcp-web-snapshot.git
cd mcp-web-snapshot
- 使用uv安装依赖项：
uv sync
- 安装Playwright浏览器：
uv run playwright install
- 运行服务器：
uv run python src/server.py
项目结构
├── src/
│ ├── server.py # 主MCP服务器入口点
│ ├── registry.py # 工具注册逻辑
│ └── tools/
│ ├── __init__.py
│ └── snapshot_url.py # 网站快照实现
├── tests/ # 测试套件
│ ├── __init__.py
│ ├── test_snapshot_url.py # 网站快照单元测试
│ └── README.md # 测试文档
├── pyproject.toml # 项目配置
├── pytest.ini # Pytest配置
├── uv.lock # 依赖项锁文件
└── README.md # 此文件
测试
该项目包括使用pytest的全面测试套件：
# 运行所有测试
uv run pytest
# 带有详细输出运行
uv run pytest -v
# 带有覆盖率报告运行
PYTHONPATH=. uv run pytest --cov=src.tools.snapshot_url --cov-report=term-missing
当前测试覆盖率为92%，涵盖：
- 成功捕获并格式化快照
- 网络请求和控制台消息监控
- URL验证
- 错误处理和恢复
可用工具
网页快照
工具：website_snapshot
描述：带有监控功能的网页综合快照
参数：
target_url(字符串)：要捕获的URL（必须是带协议的有效URL）
特性：
- 🎭 可访问性快照：捕获完整的可访问性树结构
- 🌐 网络监控：记录页面加载期间的所有网络请求和响应
- 🖥️ 控制台消息：捕获客户端控制台输出（日志、警告、错误）
- 🎯 元素引用：为交互元素添加唯一参考ID
- 📊 性能指标：提供捕获元素和网络活动的总结
示例用法：
# 通过MCP客户端
result = await website_snapshot("https://example.com")
输出结构：
✅ 捕获了包含25个元素、12个请求、0个控制台消息的快照
🔍 示例网站 - 首页
📍 https://example.com
🎭 可访问性快照：
- 导航 "主要":
- 链接 "首页": [ref=1]
- 链接 "关于我们": [ref=2]
- 按钮 "联系我们" [ref=3]
- 主:
- 标题 "欢迎来到示例"
- 链接 "开始": [ref=4]
🌐 网络请求：
🌐 GET https://example.com
状态码: 200
响应: <!DOCTYPE html><html>...
🖥️ 控制台：
无控制台消息
🎯 元素引用：
[ref=1]: 链接 "首页"
[ref=2]: 链接 "关于我们"
[ref=3]: 按钮 "联系我们"
[ref=4]: 链接 "开始"
配置
服务器可以通过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秒
}
自定义选项
- 视口大小：调整浏览器窗口尺寸
- 用户代理：自定义浏览器识别
- 超时：控制页面操作的最大等待时间
- 内容过滤：修改响应体大小限制和内容类型过滤器
使用场景
LLM引导测试
捕获全面的页面状态以生成自动化测试：
"请对https://myapp.com/login进行快照，并基于发现的元素和结构帮助我创建Page Object Model类。"
网页内容分析
提取结构化数据进行内容分析和监控：
"对https://competitor.com/pricing进行快照，并分析与上周讨论相比的任何定价变化或新功能。"
可访问性审计
利用可访问性树数据进行合规检查：
"请对https://myapp.com进行快照，并根据WCAG指南识别任何可访问性问题或改进领域。"
API集成分析
监控网络活动以了解应用程序行为：
"在登录后对https://dashboard.example.com进行快照，并展示正在执行的API调用，以便我可以理解数据流。"
跨浏览器测试设置
基于捕获的交互生成测试场景：
"对https://myapp.com/checkout进行快照，并帮助我创建涵盖所有交互元素和用户工作流程的全面测试案例。"
错误处理
服务器包括全面的错误处理：
- 无效URL：对于格式错误的URL返回有用的错误信息
- 网络超时：具有优雅回退的可配置超时限制
- 浏览器崩溃：自动清理和资源管理
- 内容限制：智能过滤大型响应体以防止内存问题
贡献
- 分叉仓库
- 创建功能分支：
git checkout -b feature-name - 修改代码并添加测试
- 运行测试：
uv run pytest - 检查测试覆盖率：
PYTHONPATH=. uv run pytest --cov=src.tools.snapshot_url --cov-report=term-missing - 确保代码风格符合规范：
uv run ruff check - 提交拉取请求
请确保所有测试通过，并保持或提高当前的测试覆盖率。
许可证
本项目采用MIT许可证 - 查看LICENSE文件获取详情。
致谢
- 受到MCP服务器网站快照文章的启发
- 基于微软的Playwright MCP的基础构建
- 由Playwright提供可靠浏览器自动化
- 使用模型上下文协议进行LLM集成
相关项目
- Playwright MCP - 交互式浏览器自动化MCP服务器
- MCP Python SDK - MCP服务器Python框架