Playwright Spatial Layout MCP

playwright-spatial-layout-mcp 🐸📐

An MCP server that gives AI agents geometric spatial awareness of web page layouts using Playwright.

AI agents can read the DOM and know a button exists — but they can't see that it's hidden under a sticky header, pushed off-screen by a broken CSS rule, or overlapping another element on mobile. This MCP fixes that by exposing real bounding box mathematics from a live browser.

---

🤔 The Problem

When an AI agent analyzes a Playwright test failure, it reads the accessibility tree:

_"The Submit button exists in the DOM. It has role=button. It is visible."_

What it cannot see:

• 🙈 The button is at y: 1450px — below the fold on mobile
• 🙈 A cookie banner overlaps it by 73%, making it unclickable
• 🙈 On a 375px viewport the nav and hero section overlap each other
• 🙈 An element shifted 200px to the right after a CSS refactor

playwright-spatial-layout-mcp gives the agent coordinates, intersection ratios, and layout shift data so it can reason about the rendered page — not just the markup.

---

🛠️ Tools

extract_bounding_boxes

Returns position, size, z-index, and viewport visibility for one or more elements.

{

"url": "https://your-app.com", "selectors": ["header", ".hero-cta", "footer"], "viewport": { "width": 375, "height": 812 } }

[

{ "selector": ".hero-cta", "box": { "x": 16, "y": 892, "width": 343, "height": 48 }, "z_index": "auto", "is_visible": true, "is_in_viewport": false } ]

---

detect_visual_occlusion

Checks if one element physically overlaps another by computing bounding box intersection.

{

"url": "https://your-app.com", "target_selector": ".checkout-button", "overlay_selector": ".cookie-banner" }

{

"is_occluded": true, "intersection_ratio": 0.61, "occluded_area_px": 4128 }

---

verify_spatial_relationships

Validates a set of layout rules and returns pass/fail with a human-readable reason per rule.

Supported rule types: left_of · right_of · above · below · contains · not_overlapping

{

"url": "https://your-app.com", "rules": [ { "type": "above", "element_a": "nav", "element_b": ".hero" }, { "type": "not_overlapping", "element_a": ".sidebar", "element_b": ".main-content" } ] }

{

"passed": false, "results": [ { "passed": true, "reason": "'nav' bottom (64px) is above '.hero' top (64px)" }, { "passed": false, "reason": "'.sidebar' and '.main-content' overlap by 12%" } ] }

---

compute_viewport_reflow

Measures how element positions and sizes change across multiple viewport sizes.

{

"url": "https://your-app.com", "selectors": ["nav", ".hero", ".cta-button"], "viewports": [ { "width": 375, "height": 812 }, { "width": 768, "height": 1024 }, { "width": 1280, "height": 720 } ] }

[

{ "selector": ".cta-button", "shifted": true, "max_delta_x": 442, "max_delta_y": 318, "max_delta_width": 897, "max_delta_height": 0 } ]

---

🚀 Installation

npx playwright-spatial-layout-mcp

Or install globally:

npm install -g playwright-spatial-layout-mcp

npx playwright install chromium

Claude Desktop config

{

"mcpServers": { "playwright-spatial-layout-mcp": { "command": "npx", "args": ["-y", "playwright-spatial-layout-mcp"] } } }

---

💡 Example Agent Prompts

_"Check if the cookie banner is blocking the checkout button on mobile (375px viewport)"_

_"Verify that the navigation is above the hero section and the sidebar doesn't overlap the main content"_

_"Show me which elements shift the most when resizing from desktop to mobile"_

_"Is the promotional modal covering the primary CTA on iPad viewport?"_

---

🔗 Related Projects

• playwright-trace-decoder-mcp — root-cause analysis of CI failures from Playwright traces
• flakiness-knowledge-graph-mcp — knowledge graph of flaky test patterns
• ast-impact-mapper-mcp — find affected tests from code changes via TypeScript AST
• zod-contract-mock-forge-mcp — deterministic mock generation from Zod schemas

---

📄 License

MIT © vola-trebla