chasesaurabh/mcp-page-capture

mcp-page-capture is a Model Context Protocol (MCP) server that orchestrates headless Chromium via Puppeteer to capture pixel-perfect screenshots of arbitrary URLs. It is optimized for Copilot/MCP-enabled environments and can be embedded into automated workflows or run as a standalone developer tool.
Features
- 📸 High-fidelity screenshots powered by Puppeteer and headless Chromium
- ⚙️ **LLM-optimized schema** with minimal parameters exposed and sensible defaults
- 🔍 Structured DOM extraction with optional CSS selectors for AI-friendly consumption
- 📱 Device presets for mobile emulation (iPhone, iPad, Android, desktop)
- 🎯 **6 simplified steps** for LLM friendliness: viewport, wait, fill, click, scroll, screenshot
- 🤖 **Smart defaults** - screenshot auto-captured, field types auto-detected
- 🆕 **Consistent parameters** - target for elements, for for waiting, to for scrolling, device for viewport
- 🔄 Automatic retry with exponential backoff for transient failures
- 📊 Telemetry hooks for centralized observability and monitoring
- 💾 Pluggable storage backends (local filesystem, S3, memory)
- 🛡️ Structured logging plus defensive error handling for operational visibility
- 🔌 Launch via npm start, npm run dev, or as a long-lived MCP sidecar
- 🐳 Docker image with multi-platform support (amd64, arm64)
How It Works
1. The MCP transport boots a Node.js server and registers the captureScreenshot and extractDom tools.
2. Incoming tool invocations are validated against the relevant type definitions.
3. Puppeteer starts (or reuses) a Chromium instance, navigates to the requested URL, and either captures a screenshot or serializes the DOM according to the tool parameters.
4. The server returns structured content (images, text, DOM trees, metadata) to the caller or downstream workflow.
Requirements
- Node.js ≥ 18.x
- npm ≥ 9.x
- Chromium package download permissions (first run)
- Network access to the target URLs
🌟 LLM-Friendly Features
Simplified Schema (5-Star LLM Rating)
- ✅ Only 4 top-level parameters: url, steps, headers, validate
- ✅ Exactly 6 step types (no more, no less)
- ✅ Consistent parameter naming across all steps
- ✅ Automatic screenshot if omitted
- ✅ Smart field type detection
- ✅ Actionable error messages with recovery suggestions
- ✅ Single source of truth for all schemas
- ✅ Deprecation warnings for legacy parameters
- ✅ **NEW**: Validate mode for pre-flight step checking
- ✅ **NEW**: Step order enforcement with auto-correction
- ✅ **NEW**: Embedded LLM reference in MCP server instructions
Quick Start for LLMs
See **LLM Quick Reference** for the 6 primary step types and common patterns.
For advanced features, see **Advanced Steps**.
The 6 Step Types (Exactly 6, No More)
| Step | Purpose | Key Parameters | Example |
|------|---------|----------------|--------|
| viewport | Set device | device, width, height | { "type": "viewport", "device": "mobile" } |
| wait | Wait for element/time | for OR duration, timeout | { "type": "wait", "for": ".loaded" } |
| fill | Fill form field | target, value, submit | { "type": "fill", "target": "#email", "value": "a@b.com" } |
| click | Click element | target, waitFor | { "type": "click", "target": "button", "waitFor": ".result" } |
| scroll | Scroll page | to, y | { "type": "scroll", "to": "#footer" } |
| screenshot | Capture (auto-added) | fullPage, element | { "type": "screenshot", "fullPage": true } |
**Step Order**: Auto-fixed! viewport auto-moves to first, screenshot auto-added at end.
Composite Patterns (NEW)
High-level patterns that auto-expand to multiple steps:
Installation
From source (recommended during development)
From npm
Running the server
For hot reload while iterating locally, run npm run dev.
Why Docker?
- Guarantees a consistent Puppeteer + Chromium environment with all system libraries when teammates or CI run the server. No more "it works on my machine" mismatches.
- Provides a ready-to-deploy container image for hosting mcp-page-capture as a sidecar/service on Kubernetes, ECS, Fly.io, etc.