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