iflow-mcp_gustavo-meilus-mcp-web-snapshot 0.1.0__py3-none-any.whl

iflow_mcp_gustavo_meilus_mcp_web_snapshot/registry.py

@@ -0,0 +1,14 @@
+from mcp.server.fastmcp import FastMCP
+from iflow_mcp_gustavo_meilus_mcp_web_snapshot.tools.snapshot_url import website_snapshot
+
+
+def register_all_tools(mcp_server: FastMCP) -> None:
+    """
+    Register all tools with the MCP server.
+
+    Args:
+        mcp_server: The FastMCP server instance to register tools with
+    """
+
+    # Add more tools here as you create them
+    mcp_server.tool()(website_snapshot)

iflow_mcp_gustavo_meilus_mcp_web_snapshot/server.py

@@ -0,0 +1,15 @@
+from mcp.server.fastmcp import FastMCP
+from iflow_mcp_gustavo_meilus_mcp_web_snapshot.registry import register_all_tools
+
+# Create an MCP server
+mcp = FastMCP("Website Snapshot")
+
+# Register all tools
+register_all_tools(mcp)
+
+if __name__ == "__main__":
+    mcp.run()
+
+def main():
+    """Entry point for the MCP server"""
+    mcp.run()

iflow_mcp_gustavo_meilus_mcp_web_snapshot/tools/__init__.py

@@ -0,0 +1 @@
+

iflow_mcp_gustavo_meilus_mcp_web_snapshot/tools/snapshot_url.py

@@ -0,0 +1,228 @@
+from typing import Optional, List, Dict, Any
+from dataclasses import dataclass
+
+from mcp.types import TextContent
+from playwright.async_api import async_playwright, Response, Request
+from pydantic import BaseModel, Field
+from urllib.parse import urlparse
+
+
+class AuthenticatedSnapshotArgs(BaseModel):
+    url: str = Field(
+        description="Path to navigate to after authentication (e.g., /leads)"
+    )
+    include_network: bool = Field(
+        default=True, description="Include network monitoring"
+    )
+    include_console: bool = Field(default=True, description="Include console messages")
+
+
+@dataclass
+class NetworkRequest:
+    request: Optional[Request] = None
+    response: Optional[Response] = None
+    request_body: Optional[str] = None
+    response_body: Optional[str] = None
+
+
+CONFIG = {
+    "viewport": {"width": 1920, "height": 1080},
+    "user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36",
+    "timeout": 15000,
+}
+
+
+def should_show_content(content_type: str, content_length: int) -> bool:
+    return content_length <= 50000 and any(
+        content_type.startswith(t)
+        for t in ["application/json", "text/", "application/xml"]
+    )
+
+
+def format_requests(requests: List[NetworkRequest]) -> str:
+    if not requests:
+        return "No requests captured"
+
+    formatted = []
+    for req in requests:
+        if req.request:
+            formatted.append(f"🌐 {req.request.method} {req.request.url}")
+            formatted.append(
+                f"   Status: {req.response.status if req.response else 'Pending'}"
+            )
+            if req.response_body:
+                formatted.append(f"   Response: {req.response_body[:200]}...")
+    return "\n".join(formatted)
+
+
+def format_console(messages: List[Any]) -> str:
+    if not messages:
+        return "No console messages"
+    return "\n".join(
+        [
+            f"🖥️ [{getattr(msg, 'type', 'log').upper()}] {getattr(msg, 'text', str(msg))}"
+            for msg in messages
+        ]
+    )
+
+
+def add_element_refs(snapshot: str) -> str:
+    lines = snapshot.split("\n")
+    ref_counter = 1
+
+    for i, line in enumerate(lines):
+        if any(
+            keyword in line.lower()
+            for keyword in ["button", "link", "input", "textbox"]
+        ):
+            lines[i] = f"{line} [ref={ref_counter}]"
+            ref_counter += 1
+
+    return "\n".join(lines)
+
+
+def parse_refs(snapshot: str) -> List[Dict[str, str]]:
+    refs = []
+    for line in snapshot.split("\n"):
+        if "[ref=" in line:
+            ref_start = line.find("[ref=") + 5
+            ref_end = line.find("]", ref_start)
+            if ref_end > ref_start:
+                refs.append(
+                    {
+                        "ref": line[ref_start:ref_end],
+                        "element": line[: line.find("[ref=")].strip(),
+                    }
+                )
+    return refs
+
+
+def is_valid_url(url: str) -> bool:
+    parsed = urlparse(url)
+    return all([parsed.scheme, parsed.netloc])
+
+
+async def website_snapshot(target_url: str) -> List[TextContent]:
+    """
+    Take authenticated page snapshots with monitoring
+    Example: https://example.com
+    """
+
+    if not is_valid_url(target_url):
+        return [
+            TextContent(
+                type="text", text="Url must be valid, example: https://example.com"
+            )
+        ]
+
+    async with async_playwright() as p:
+        browser = await p.chromium.launch(headless=True)
+
+        try:
+            context = await browser.new_context(
+                viewport=CONFIG["viewport"], user_agent=CONFIG["user_agent"]
+            )
+
+            page = await context.new_page()
+            page.set_default_timeout(CONFIG["timeout"])
+
+            network_requests: List[NetworkRequest] = []
+            console_messages: List[Any] = []
+
+            # Setup monitoring
+            page.on("console", lambda msg: console_messages.append(msg))
+
+            async def handle_request(request: Request):
+                request_body = None
+                if request.method.upper() in ["POST", "PUT", "PATCH"]:
+                    try:
+                        request_body = await request.post_data()
+                    except Exception:
+                        pass
+                network_requests.append(
+                    NetworkRequest(request=request, request_body=request_body)
+                )
+
+            async def handle_response(response: Response):
+                for entry in network_requests:
+                    if entry.request == response.request and not entry.response:
+                        entry.response = response
+                        try:
+                            content_type = response.headers.get("content-type", "")
+                            content_length = int(
+                                response.headers.get("content-length", "0")
+                            )
+
+                            if should_show_content(content_type, content_length):
+                                entry.response_body = await response.text()
+                            else:
+                                entry.response_body = (
+                                    f"[{content_type} - {content_length} bytes]"
+                                )
+                        except Exception:
+                            entry.response_body = "[Error reading response]"
+                        break
+
+            page.on("request", handle_request)
+            page.on("response", handle_response)
+
+            # Navigate to target and capture snapshot
+            await page.goto(target_url, wait_until="domcontentloaded")
+            await page.wait_for_load_state("load", timeout=CONFIG["timeout"])
+
+            try:
+                await page.wait_for_selector(
+                    "[data-testid], button, .MuiButton-root", timeout=10000
+                )
+            except Exception:
+                await page.wait_for_timeout(3000)
+
+            # Capture snapshot
+            aria_snapshot = await page.locator("body").aria_snapshot()
+            snapshot_with_refs = add_element_refs(aria_snapshot)
+            element_refs = parse_refs(snapshot_with_refs)
+
+            # Format output
+            output_parts = [
+                f"🔍 {await page.title()}",
+                f"📍 {page.url}",
+                "",
+                "🎭 Accessibility Snapshot:",
+                snapshot_with_refs,
+            ]
+
+            output_parts.extend(
+                ["", "🌐 Network Requests:", format_requests(network_requests)]
+            )
+
+            output_parts.extend(["", "🖥️ Console:", format_console(console_messages)])
+
+            summary_parts = [f"{len(element_refs)} elements"]
+
+            summary_parts.append(
+                f"{len([r for r in network_requests if r.request])} requests"
+            )
+
+            summary_parts.append(f"{len(console_messages)} console messages")
+
+            await context.close()
+
+            return [
+                TextContent(
+                    type="text",
+                    text=f"✅ Captured snapshot with {', '.join(summary_parts)}",
+                ),
+                TextContent(type="text", text="\n".join(output_parts)),
+                TextContent(
+                    type="text",
+                    text="🎯 Element References:\n"
+                    + "\n".join(
+                        [f"[ref={r['ref']}]: {r['element']}" for r in element_refs]
+                    ),
+                ),
+            ]
+
+        except Exception as error:
+            return [TextContent(type="text", text=f"❌ Failed: {str(error)}")]
+        finally:
+            await browser.close()

iflow_mcp_gustavo_meilus_mcp_web_snapshot-0.1.0.dist-info/METADATA

@@ -0,0 +1,306 @@
+Metadata-Version: 2.4
+Name: iflow-mcp_gustavo-meilus-mcp-web-snapshot
+Version: 0.1.0
+Summary: A Model Context Protocol (MCP) server that provides comprehensive website snapshot capabilities using Playwright for LLM integration
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: mcp[cli]>=1.9.2
+Requires-Dist: playwright>=1.52.0
+Description-Content-Type: text/markdown
+
+# MCP Web Snapshot
+
+A Model Context Protocol (MCP) server that provides comprehensive website snapshot capabilities using [Playwright](https://playwright.dev). 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:
+
+```json
+{
+  "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:
+
+```bash
+# 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"]`.
+
+```json
+{
+  "mcpServers": {
+    "mcp-web-snapshot": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/path/to/mcp-web-snapshot",
+        "run",
+        "python",
+        "src/server.py"
+      ]
+    }
+  }
+}
+```
+
+## Development Setup
+
+### Local Installation
+
+1. Clone this repository:
+
+```bash
+git clone https://github.com/your-username/mcp-web-snapshot.git
+cd mcp-web-snapshot
+```
+
+2. Install dependencies using uv:
+
+```bash
+uv sync
+```
+
+3. Install Playwright browsers:
+
+```bash
+uv run playwright install
+```
+
+4. Run the server:
+
+```bash
+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:
+
+```bash
+# 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**:
+
+```python
+# 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`:
+
+```python
+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
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature-name`
+3. Make your changes and add tests
+4. Run tests: `uv run pytest`
+5. Check test coverage: `PYTHONPATH=. uv run pytest --cov=src.tools.snapshot_url --cov-report=term-missing`
+6. Ensure code style compliance: `uv run ruff check`
+7. 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](LICENSE) file for details.
+
+## Acknowledgments
+
+- Inspired by [MCP Server Website Snapshot](https://www.linkedin.com/pulse/mcp-server-website-snapshot-gustavo-meilus-oiigf/) article
+- Built on the foundation of [Microsoft's Playwright MCP](https://github.com/microsoft/playwright-mcp)
+- Powered by [Playwright](https://playwright.dev) for reliable browser automation
+- Uses [Model Context Protocol](https://modelcontextprotocol.io) for LLM integration
+
+## Related Projects
+
+- [Playwright MCP](https://github.com/microsoft/playwright-mcp) - Interactive browser automation MCP server
+- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk/) - MCP server python framework

iflow_mcp_gustavo_meilus_mcp_web_snapshot-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+iflow_mcp_gustavo_meilus_mcp_web_snapshot/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+iflow_mcp_gustavo_meilus_mcp_web_snapshot/registry.py,sha256=3Vg-276l8f1SKfqRinxAPRLNQYQBXiGjZxxLh-zVF1c,411
+iflow_mcp_gustavo_meilus_mcp_web_snapshot/server.py,sha256=9Pw4ZGSnl33nkTpvsYFRwfPb5iaBDZxaCWTcebdoSvA,334
+iflow_mcp_gustavo_meilus_mcp_web_snapshot/tools/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+iflow_mcp_gustavo_meilus_mcp_web_snapshot/tools/snapshot_url.py,sha256=PbkfZV7OJawQK79VM5WZUvsd28htDyKAJW1FsrJxx1o,7651
+iflow_mcp_gustavo_meilus_mcp_web_snapshot-0.1.0.dist-info/METADATA,sha256=wZuDOreRp34FPWdRc-BFt7c4x8nM_ZyQkEEhkYsFNu8,8975
+iflow_mcp_gustavo_meilus_mcp_web_snapshot-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+iflow_mcp_gustavo_meilus_mcp_web_snapshot-0.1.0.dist-info/entry_points.txt,sha256=cNWUokXsdOIu2LXgjQatwmmJAmhttrEwe4zWWHjIpY4,91
+iflow_mcp_gustavo_meilus_mcp_web_snapshot-0.1.0.dist-info/licenses/LICENSE,sha256=VUnkswHYoOJ_Yu1pMITTAU49A7dRnew17IBrr0qOqIg,1071
+iflow_mcp_gustavo_meilus_mcp_web_snapshot-0.1.0.dist-info/RECORD,,

iflow_mcp_gustavo_meilus_mcp_web_snapshot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

iflow_mcp_gustavo_meilus_mcp_web_snapshot-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-web-snapshot = iflow_mcp_gustavo_meilus_mcp_web_snapshot.server:main

iflow_mcp_gustavo_meilus_mcp_web_snapshot-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Gustavo Meilus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.