playwright-spatial-layout-mcp

playwright-spatial-layout-mcp 🐸📐

Playwright を使用して、AI エージェントにウェブページのレイアウトに関する幾何学的な空間認識を提供する MCP サーバーです。

AI エージェントは DOM を読み取ってボタンの存在を把握できますが、そのボタンが固定ヘッダーの下に隠れていることや、壊れた CSS ルールによって画面外に押し出されていること、モバイル画面で別の要素と重なっていることは確認できません。この MCP は、実際に動作しているブラウザーからバウンディングボックスの数学的な情報を提供することで、この問題を解決します。

---

🤔 問題点

AI エージェントが Playwright のテスト失敗を分析するとき、アクセシビリティツリーを読み取ります。

「Submit ボタンは DOM に存在します。role=button です。表示されています。」

しかし、確認できないことは次のとおりです。

• 🙈 ボタンが y: 1450px にあり、モバイル画面ではスクロールしないと見えません
• 🙈 Cookie バナーがボタンに 73% 重なり、クリックできません
• 🙈 ビューポートの幅が 375px のとき、ナビゲーションとヒーローセクションが互いに重なります
• 🙈 CSS のリファクタリング後、要素が右に 200px 移動しました

playwright-spatial-layout-mcp は、エージェントに座標、交差率、レイアウトシフトのデータを提供するため、マークアップだけでなく、レンダリングされたページについて推論できます。

---

🛠️ ツール

extract_bounding_boxes

1 つ以上の要素について、位置、サイズ、z-index、ビューポート内で表示されているかどうかを返します。

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

バウンディングボックスの交差を計算し、ある要素が別の要素と物理的に重なっているかどうかを確認します。

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

一連のレイアウトルールを検証し、ルールごとに人が読める理由と合否を返します。

対応するルールタイプ：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

複数のビューポートサイズにわたって、要素の位置とサイズがどのように変化するかを測定します。

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

---

🚀 インストール

npx playwright-spatial-layout-mcp

または、グローバルにインストールします。

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

Claude Desktop の設定

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

---

💡 エージェントへのプロンプト例

「モバイル（ビューポート幅 375px）で Cookie バナーがチェックアウトボタンを遮っているか確認してください」

「ナビゲーションがヒーローセクションより上にあることと、サイドバーがメインコンテンツと重なっていないことを確認してください」

「デスクトップからモバイルにサイズを変更したとき、最も大きく移動する要素を教えてください」

「iPad のビューポートでプロモーションモーダルが主要な CTA を覆っていますか？」

---

🔗 関連プロジェクト

• playwright-trace-decoder-mcp — Playwright のトレースから CI の失敗原因を分析します
• flakiness-knowledge-graph-mcp — 不安定なテストパターンのナレッジグラフです
• ast-impact-mapper-mcp — TypeScript AST を使い、コード変更の影響を受けるテストを特定します
• zod-contract-mock-forge-mcp — Zod スキーマから決定論的なモックを生成します

---

📄 ライセンス

MIT © vola-trebla