playwright-spatial-layout-mcp

Geometric vision for AI agents: bounding boxes, occlusion, viewport reflow

An MCP server that gives AI agentsgeometric spatial awarenessof 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.

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."

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

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 } ]

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

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

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%" } ] }

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 } ]

npm install -g playwright-spatial-layout-mcp npx playwright install chromium

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

"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?"

- 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

Create and manage end-to-end tests using the Octomind platform.