playwright-spatial-layout-mcp

Visión geométrica para agentes de IA: cuadros delimitadores, oclusión, reflujo de viewport

Documentación

playwright-spatial-layout-mcp 🐸📐

Un servidor MCP que brinda a los agentes de IA conciencia espacial geométrica de los diseños de páginas web mediante Playwright.

Los agentes de IA pueden leer el DOM y saber que un botón existe, pero no pueden ver que está oculto bajo un encabezado fijo, empujado fuera de la pantalla por una regla CSS rota, o superpuesto a otro elemento en móvil. Este MCP lo soluciona exponiendo las matemáticas reales de los cuadros delimitadores desde un navegador en vivo.

🤔 El Problema

Cuando un agente de IA analiza un fallo de prueba de Playwright, lee el árbol de accesibilidad:

"El botón Submit existe en el DOM. Tiene role=button. Es visible."

Lo que no puede ver:

🙈 El botón está en y: 1450px — debajo del pliegue en móvil
🙈 Un banner de cookies lo superpone en un 73%, haciéndolo no clicable
🙈 En un viewport de 375px, la navegación y la sección hero se superponen entre sí
🙈 Un elemento se desplazó 200px a la derecha después de un refactor de CSS

playwright-spatial-layout-mcp le da al agente coordenadas, ratios de intersección y datos de desplazamiento de diseño para que pueda razonar sobre la página renderizada — no solo sobre el marcado.

🛠️ Herramientas

`extract_bounding_boxes`

Devuelve posición, tamaño, z-index y visibilidad en el viewport para uno o más elementos.

{
  "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`

Comprueba si un elemento se superpone físicamente a otro calculando la intersección de los cuadros delimitadores.

{
  "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`

Valida un conjunto de reglas de diseño y devuelve aprobado/fallido con una razón legible por humanos para cada regla.

Tipos de reglas admitidos: 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`

Mide cómo cambian las posiciones y tamaños de los elementos en múltiples tamaños de viewport.

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

🚀 Instalación

npx playwright-spatial-layout-mcp

O instalar globalmente:

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

Configuración de Claude Desktop

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

💡 Ejemplos de indicaciones para agentes

"Comprueba si el banner de cookies está bloqueando el botón de pago en móvil (viewport de 375px)"

"Verifica que la navegación esté por encima de la sección hero y que la barra lateral no se superponga al contenido principal"

"Muéstrame qué elementos se desplazan más al cambiar de escritorio a móvil"

"¿Está el modal promocional cubriendo el CTA principal en el viewport de iPad?"

🔗 Proyectos relacionados

playwright-trace-decoder-mcp — análisis de causa raíz de fallos de CI a partir de trazas de Playwright
flakiness-knowledge-graph-mcp — grafo de conocimiento de patrones de pruebas inestables
ast-impact-mapper-mcp — encuentra pruebas afectadas por cambios de código mediante el AST de TypeScript
zod-contract-mock-forge-mcp — generación determinista de mocks a partir de esquemas Zod

playwright-spatial-layout-mcp

Documentación