mcp-playwright-screenshot

# mcp-playwright-screenshot MCP server that captures webpage screenshots using Playwright and returns the PNG image as base64 via MCP "image" content. Includes domain safety guards and size limits. - Tech: TypeScript, Playwright, MCP SDK, stdio transport - Tool name: screenshot - Output: image/png (base64) ## Features - Playwright chromium, headless - Full-page or viewport screenshots - Viewport and deviceScaleFactor control - Navigation waitUntil: load | domcontentloaded | networkidle (default) - Security: - Only http/https - Blocks government domains (*.gov, *.gov.TLD) - Blocks localhost and private IP ranges (127/8, 10/8, 172.16–31/12, 192.168/16, ::1, fc00::/7, fe80::/10) - Limits: - Max viewport width: 12000 - Max viewport and full-page height: 100000 ## Project structure - src/server.ts: MCP server (stdio), tool wiring, Zod input schema - src/screenshot.ts: Playwright logic, validation, PNG base64 result - src/types.ts: Types, ErrorCodes, CodedError - src/security/domainGuard.ts: URL normalization and domain/IP guard - src/security/sizeGuard.ts: Viewport/full-page size guards - src/utils/file.ts: File utilities (not used by tool output; kept for potential file saving) ## Requirements - Node.js 18+ (ESM, NodeNext) - npm - Playwright browsers: install with npx playwright install ## Install ```bash npm install npx playwright install ``` ## Scripts ```bash # Dev (TypeScript via ts-node/esm) npm run dev # Build to dist/ npm run build # Start built server npm start ``` Server runs as an MCP stdio server (reads/writes JSON-RPC over stdio). ## MCP tool - Name: screenshot - Description: Capture a URL as PNG; returns base64 image content; includes domain/size guards. Input schema (Zod, defaults shown): - url: string (required, http/https only) - fullPage: boolean = true - viewport: { width: number; height: number } (default 1280x800) - deviceScaleFactor: number = 1 (> 0) - waitUntil: "load" | "domcontentloaded" | "networkidle" = "networkidle" - timeoutMs: number = 30000 (positive integer) - darkMode: boolean = false Output: - content: [{ type: "image", data: <base64>, mimeType: "image/png" }] ## Example (JSON-RPC over stdio) List tools: ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } ``` Call screenshot: ```json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "screenshot", "arguments": { "url": "https://example.com", "fullPage": true, "viewport": { "width": 1280, "height": 800 }, "deviceScaleFactor": 1, "waitUntil": "networkidle", "timeoutMs": 30000, "darkMode": false } } } ``` Successful result (truncated): ```json { "jsonrpc": "2.0", "id": 2, "result": { "content": [ { "type": "image", "data": "iVBORw0KGgoAAA... (base64) ...", "mimeType": "image/png" } ] } } ``` ## Error handling All errors return `isError: true` with a text message. Error codes: - E_INVALID_URL: URL invalid or not http/https - E_BLOCKED_DOMAIN: Government domain or localhost/private IP is blocked - E_SIZE_EXCEEDED: Viewport or page size out of bounds; invalid numeric params - E_NAVIGATION_TIMEOUT: Page navigation timed out - E_SCREENSHOT_FAILED: Navigation or screenshot failure - E_IO_ERROR: Generic I/O error Example error response: ```json { "jsonrpc": "2.0", "id": 2, "result": { "isError": true, "content": [ { "type": "text", "text": "E_BLOCKED_DOMAIN: 禁止访问政府类站点: example.gov" } ] } } ``` ## Security notes - Hostname normalized (lowercase, Punycode) before checks - Blocks: *.gov and *.gov.TLD; localhost; private IP literals (IPv4, IPv6) - No DNS resolution is performed for security checks ## Behavior notes - Headless chromium - PNG only - darkMode switches `colorScheme` to "dark" - Full page height is validated before screenshot ## Development - ESM + TypeScript (NodeNext) - Zod for request validation - Stdio transport via @modelcontextprotocol/sdk ## License MIT (add a LICENSE file if required).