io.github.vola-trebla/playwright-spatial-layout-mcp
MCP server that gives AI agents geometric spatial awareness of web page layouts using Playwright
Open source Open in the app JSON README (API)
About
MCP server that gives AI agents geometric spatial awareness of web page layouts using Playwright
Details
- Kind
- MCP servers
- Topic
- Web search, scraping & browser
- Publisher
- vola-trebla
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.0
- Last push
- 2026-05-19T02:00:24Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:39
- Updated
- 2026-08-29 04:01:39
- Origin id
io.github.vola-trebla/playwright-spatial-layout-mcp
README
# playwright-spatial-layout-mcp 🐸📐
[](https://www.npmjs.com/package/playwright-spatial-layout-mcp)
[](https://www.npmjs.com/package/playwright-spatial-layout-mcp)
[](https://github.com/vola-trebla/playwright-spatial-layout-mcp/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
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.
```json
{
"url": "https://your-app.com",
"selectors": ["header", ".hero-cta", "footer"],
"viewport": { "width": 375, "height": 812 }
}
```
```json
[
{
"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.
```json
{
"url": "https://your-app.com",
"target_selector": ".checkout-button",
"overlay_selector": ".cookie-banner"
}
```
```json
{
"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`
```json
{
"url": "https://your-app.com",
"rules": [
{ "type": "above", "element_a": "nav", "element_b": ".hero" },
{ "type": "not_overlapping", "element_a": ".sidebar", "element_b": ".main-content" }
]
}
```
```json
{
"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.
```json
{
"url": "https://your-app.com",
"selectors": ["nav", ".hero", ".cta-button"],
"viewports": [
{ "width": 375, "height": 812 },
{ "width": 768, "height": 1024 },
{ "width": 1280, "height": 720 }
]
}
```
```json
[
{
"selector": ".cta-button",
"shifted": true,
"max_delta_x": 442,
"max_delta_y": 318,
"max_delta_width": 897,
"max_delta_height": 0
}
]
```
---
## 🚀 Installation
```bash
npx playwright-spatial-layout-mcp
```
Or install globally:
```bash
npm install -g playwright-spatial-layout-mcp
npx playwright install chromium
```
### Claude Desktop config
```json
{
"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](https://github.com/vola-trebla/playwright-trace-decoder-mcp) — root-cause analysis of CI failures from Playwright traces
- [flakiness-knowledge-graph-mcp](https://github.com/vola-trebla/flakiness-knowledge-graph-mcp) — knowledge graph of flaky test patterns
- [ast-impact-mapper-mcp](https://github.com/vola-trebla/ast-impact-mapper-mcp) — find affected tests from code changes via TypeScript AST
- [zod-contract-mock-forge-mcp](https://github.com/vola-trebla/zod-contract-mock-forge-mcp) — deterministic mock generation from Zod schemas
---
## 📄 License
MIT © [vola-trebla](https://github.com/vola-trebla)