关于 playwright-spatial-layout-mcp
playwright-spatial-layout-mcp 是面向 AI Agent 和浏览器测试流程的 MCP 服务，借助 Playwright 测量页面渲染后的几何布局，补充仅查看 DOM 无法获得的信息。
主要功能
- 01读取元素边界、层级和视口可见性
- 02检测目标元素与遮挡层的重叠
- 03验证空间布局规则
- 04比较不同视口下的布局变化
适用场景
- 01检查横幅是否挡住结账按钮
- 02验证导航与内容的位置关系
- 03找出元素在移动端和桌面端间的位移
MCP 相关
它向 MCP 客户端提供基于 Playwright 的布局分析工具，包括提取边界、检测遮挡、验证空间规则和测量视口重排。
配置
本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。
工具
6收录的工具列表 · 更新于 2 周前
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| url | string | 是 | 要分析的页面 URL |
| viewport | object | 否 | 视口大小（默认值：1280×720） |
| viewport.width | integer | 是 | 视口宽度，单位为 px |
| viewport.height | integer | 是 | 视口高度，单位为 px |
| selectors | array | 是 | CSS 选择器或 Playwright 定位器字符串 |
详细介绍
playwright-spatial-layout-mcp 🐸📐
一个借助 Playwright，让 AI Agent 能够感知网页布局几何空间的 MCP 服务。
AI Agent 可以读取 DOM 并知道某个按钮存在，但它们看不到按钮是否被固定页眉遮挡、是否因错误的 CSS 规则被挤出屏幕，或者是否在移动设备上与其他元素重叠。此 MCP 通过公开实时浏览器中的实际边界框数据来解决这个问题。
🤔 问题
当 AI Agent 分析 Playwright 测试失败时，它会读取无障碍树：
“DOM 中存在‘提交’按钮。它的角色是 button。它可见。”
它看不到的是：
- 🙈 按钮位于
y: 1450px— 在移动设备上已经滚动到首屏以下 - 🙈 Cookie 横幅覆盖了按钮的 73%，导致按钮无法点击
- 🙈 在 375px 视口下，导航栏与主视觉区彼此重叠
- 🙈 CSS 重构后，某个元素向右偏移了 200px
playwright-spatial-layout-mcp 为 Agent 提供坐标、交叉比例和布局偏移数据，使其能够分析渲染后的页面，而不仅仅是标记。
🛠️ 工具
extract_bounding_boxes
返回一个或多个元素的位置、尺寸、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"]
}
}
}
💡 Agent 提示词示例
“检查 Cookie 横幅是否在移动设备上遮挡了结账按钮（375px 视口）”
“验证导航栏是否位于主视觉区上方，以及侧边栏是否与主要内容重叠”
“告诉我从桌面尺寸调整到移动设备尺寸时，哪些元素偏移最大”
“在 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
评论
一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。