playwright-spatial-layout-mcp

Visão geométrica para agentes de IA: caixas delimitadoras, oclusão, refluxo de viewport

GitHubExperimente este MCPPatrocinado

Documentação

playwright-spatial-layout-mcp 🐸📐

npm version npm downloads CI License: MIT

Um servidor MCP que dá aos agentes de IA consciência espacial geométrica dos layouts de páginas web usando Playwright.

Agentes de IA podem ler o DOM e saber que um botão existe — mas não conseguem ver que ele está escondido sob um cabeçalho fixo, empurrado para fora da tela por uma regra CSS quebrada ou sobreposto a outro elemento no mobile. Este MCP resolve isso expondo a matemática real de bounding boxes de um navegador ao vivo.

🤔 O Problema

Quando um agente de IA analisa uma falha de teste do Playwright, ele lê a árvore de acessibilidade:

"O botão Submit existe no DOM. Ele tem role=button. Ele é visível."

O que ele não consegue ver:

  • 🙈 O botão está em y: 1450px — abaixo da dobra no mobile
  • 🙈 Um banner de cookies o sobrepõe em 73%, tornando-o inutilizável
  • 🙈 Em um viewport de 375px, a navegação e a seção hero se sobrepõem
  • 🙈 Um elemento deslocado 200px para a direita após um refactor de CSS

playwright-spatial-layout-mcp dá ao agente coordenadas, taxas de interseção e dados de deslocamento de layout para que ele possa raciocinar sobre a página renderizada — não apenas o markup.

🛠️ Ferramentas

extract_bounding_boxes

Retorna posição, tamanho, z-index e visibilidade no viewport para um ou mais 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

Verifica se um elemento se sobrepõe fisicamente a outro calculando a interseção dos bounding boxes.

{
  "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 um conjunto de regras de layout e retorna aprovado/reprovado com uma razão legível para cada regra.

Tipos de regra suportados: 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

Mede como as posições e tamanhos dos elementos mudam em vários tamanhos 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
  }
]

🚀 Instalação

npx playwright-spatial-layout-mcp

Ou instale globalmente:

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

Configuração do Claude Desktop

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

💡 Exemplos de Prompts para Agentes

"Verifique se o banner de cookies está bloqueando o botão de checkout no mobile (viewport de 375px)"

"Verifique se a navegação está acima da seção hero e se a barra lateral não se sobrepõe ao conteúdo principal"

"Mostre quais elementos se deslocam mais ao redimensionar do desktop para o mobile"

"O modal promocional está cobrindo o CTA principal no viewport do iPad?"

🔗 Projetos Relacionados

📄 Licença

MIT © vola-trebla