io.github.vola-trebla/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