mcp-web-snapshot
MCP Web Snapshot is an MCP server that offers comprehensive website snapshot capabilities using Playwright. It is designed for AI to efficiently capture and analyze web pages, providing structured data through network monitoring and console message collection.
GitHub Stars
1
User Rating
Not Rated
Forks
0
Issues
0
Views
1
Favorites
0
MCP Web Snapshot
A Model Context Protocol (MCP) server that provides comprehensive website snapshot capabilities using Playwright. This server enables LLMs to capture and analyze web pages through structured accessibility snapshots, network monitoring, and console message collection.
Key Features
- ๐ Fast and lightweight: Uses Playwright's accessibility tree for efficient snapshots
- ๐ฏ LLM-optimized: Structured data output designed specifically for AI consumption
- ๐ Comprehensive monitoring: Captures network requests, responses, and console messages
- ๐ Element references: Adds unique identifiers to interactive elements for precise targeting
- ๐ก๏ธ Production-ready: Built-in error handling, resource limits, and timeout management
- โ Well-tested: Comprehensive test suite with code coverage
Requirements
- Python 3.11 or newer
- VS Code, Cursor, Windsurf, Claude Desktop or any other MCP client
Getting Started
First, install the MCP Web Snapshot server with your client. A typical configuration looks like this:
{
"mcpServers": {
"mcp-web-snapshot": {
"command": "uv",
"args": [
"--directory",
"/path/to/mcp-web-snapshot",
"run",
"python",
"src/server.py"
]
}
}
}
Install in VS Code
You can install the MCP Web Snapshot server using the VS Code CLI:
# For VS Code
code --add-mcp '{"name":"mcp-web-snapshot","command":"uv","args":["--directory","/path/to/mcp-web-snapshot","run","python","src/server.py"]}'
After installation, the MCP Web Snapshot server will be available for use with your GitHub Copilot agent in VS Code.
Install in Cursor
Go to Cursor Settings
โ MCP
โ Add new MCP Server
. Name to your liking, use command
type with the command uv
and args ["--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"
]
}
}
}
Development Setup
Local Installation
- Clone this repository:
git clone https://github.com/your-username/mcp-web-snapshot.git
cd mcp-web-snapshot
- Install dependencies using uv:
uv sync
- Install Playwright browsers:
uv run playwright install
- Run the server:
uv run python src/server.py
Project Structure
โโโ 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
Testing
The project includes a comprehensive test suite using 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
Test coverage currently stands at 92%, covering:
- Successful snapshot capture and formatting
- Network request and console message monitoring
- URL validation
- Error handling and recovery
Available Tools
Website Snapshot
Tool: website_snapshot
Description: Take comprehensive snapshots of web pages with monitoring capabilities
Parameters:
target_url
(string): The URL to capture (must be a valid URL with protocol)
Features:
- ๐ญ Accessibility Snapshot: Captures the complete accessibility tree structure
- ๐ Network Monitoring: Records all network requests and responses during page load
- ๐ฅ๏ธ Console Messages: Captures client-side console output (logs, warnings, errors)
- ๐ฏ Element References: Adds unique reference IDs to interactive elements
- ๐ Performance Metrics: Provides summary of captured elements and network activity
Example Usage:
# Through MCP client
result = await website_snapshot("https://example.com")
Output Structure:
โ
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"
Configuration
The server can be configured through the CONFIG
dictionary in src/tools/snapshot_url.py
:
CONFIG = {
"viewport": {"width": 1920, "height": 1080},
"user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36",
"timeout": 15000, # 15 seconds
}
Customization Options
- Viewport Size: Adjust browser window dimensions
- User Agent: Customize browser identification
- Timeout: Control maximum wait time for page operations
- Content Filtering: Modify response body size limits and content type filters
Use Cases
LLM-Guided Testing
Capture comprehensive page state for automated test generation:
"Please take a snapshot of https://myapp.com/login and help me create Page Object Model classes based on the discovered elements and structure."
Web Content Analysis
Extract structured data for content analysis and monitoring:
"Take a snapshot of https://competitor.com/pricing and analyze any pricing changes or new features compared to what we discussed last week."
Accessibility Auditing
Leverage accessibility tree data for compliance checking:
"Please capture a snapshot of https://myapp.com and identify any accessibility issues or areas for improvement based on WCAG guidelines."
API Integration Analysis
Monitor network activity to understand application behavior:
"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."
Cross-Browser Testing Setup
Generate test scenarios based on captured interactions:
"Snapshot https://myapp.com/checkout and help me create comprehensive test cases that cover all the interactive elements and user workflows."
Error Handling
The server includes comprehensive error handling:
- Invalid URLs: Returns helpful error messages for malformed URLs
- Network Timeouts: Configurable timeout limits with graceful fallbacks
- Browser Crashes: Automatic cleanup and resource management
- Content Limits: Smart filtering of large response bodies to prevent memory issues
Contributing
- Fork the repository
- Create a feature branch:
git checkout -b feature-name
- Make your changes and add tests
- Run tests:
uv run pytest
- Check test coverage:
PYTHONPATH=. uv run pytest --cov=src.tools.snapshot_url --cov-report=term-missing
- Ensure code style compliance:
uv run ruff check
- Submit a pull request
Please ensure all tests pass and maintain or improve the current test coverage.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
- Inspired by MCP Server Website Snapshot article
- Built on the foundation of Microsoft's Playwright MCP
- Powered by Playwright for reliable browser automation
- Uses Model Context Protocol for LLM integration
Related Projects
- Playwright MCP - Interactive browser automation MCP server
- MCP Python SDK - MCP server python framework
0
Followers
10
Repositories
0
Gists
4
Total Contributions