layout-detector-mcp

🚀 Layout Detector MCP

Layout Detector MCP是一个MCP（模型上下文协议）服务器，它可以分析网页截图，提取布局信息。给定一张截图和图像资源，它能找出每个资源的位置，并计算空间关系，从而让AI助手能够以正确的语义结构重建布局。

🚀 快速开始

从GitHub安装

pip install git+https://github.com/katlis/layout-detector-mcp.git

或者克隆项目并在本地安装

git clone https://github.com/katlis/layout-detector-mcp.git
cd layout-detector-mcp
pip install .

验证安装：

python3 -c "from layout_detector import server; print('OK')"

📦 安装指南

配置

将以下内容添加到你的Claude Code MCP设置中（~/.claude.json 或项目的 .claude/settings.json）：

{
  "mcpServers": {
    "layout-detector": {
      "command": "layout-detector-mcp"
    }
  }
}

添加配置后，重启Claude Code并运行 /mcp 以验证服务器是否已连接。

❓ 问题描述

当AI助手查看截图时，它可以描述看到的内容，但无法提取精确的像素测量值。这使得在没有人工干预或大量反复尝试的情况下，很难准确地重建布局。

💡 解决方案

这个MCP服务器使用计算机视觉（OpenCV模板匹配）来实现以下功能：

1. 查找已知资源 - 在截图中以像素级精度定位图像
2. 分析关系 - 计算角度、距离和相对位置
3. 检测模式 - 识别径向、网格、堆叠、侧边栏或自由形式的布局
4. 支持语义重建 - 为现代CSS实现提供结构化数据

🛠️ 工具介绍

analyze_layout

执行完整的布局分析，包括模式检测。这是你将主要使用的工具。

参数：

• screenshot_path（字符串，必需）：截图图像的绝对路径
• asset_paths（字符串数组，必需）：要查找的资源图像的绝对路径
• threshold（数字，可选）：匹配置信度，范围0-1，默认值为0.8

返回值：

{
  "viewport": { "width": 900, "height": 650 },
  "pattern": {
    "type": "radial",
    "confidence": 0.90
  },
  "radial": {
    "center_x": 450,
    "center_y": 250,
    "center_element": "logo.gif",
    "average_radius": 196
  },
  "elements": [
    {
      "asset_name": "planet1.gif",
      "x": 628,
      "y": 89,
      "width": 62,
      "height": 62,
      "angle_degrees": 45.0,
      "distance_from_center": 240
    }
  ]
}

find_assets_in_screenshot

在截图中定位图像资源，不进行布局分析。

参数：

• screenshot_path（字符串，必需）：截图图像的路径
• asset_paths（字符串数组，必需）：要查找的资源图像的路径
• threshold（数字，可选）：匹配置信度，范围0-1，默认值为0.8

返回值：

{
  "found": 5,
  "total_assets": 6,
  "matches": [
    {
      "asset_path": "/path/to/logo.png",
      "asset_name": "logo.png",
      "x": 350,
      "y": 200,
      "width": 200,
      "height": 100,
      "center_x": 450,
      "center_y": 250,
      "confidence": 0.95
    }
  ]
}

get_screenshot_info

获取截图的基本尺寸信息。

参数：

• screenshot_path（字符串，必需）：截图图像的路径

返回值：

{
  "path": "/path/to/screenshot.png",
  "width": 900,
  "height": 650
}

📋 支持的布局模式

| 模式 | 描述 | 返回的关键数据 | |------|------|----------------| | 径向 | 元素围绕中心点排列 | 中心元素、角度、距离 | | 网格 | 元素按行和列排列 | 行/列位置、间距 | | 堆叠 | 垂直分区（页眉/主体/页脚） | 分区名称、Y位置 | | 侧边栏 | 两列布局，带有狭窄的侧边栏 | 侧边栏位置、宽度 | | 自由形式 | 无明显模式 | 原始X/Y坐标 |

💻 使用示例

配置完成后，Claude Code可以使用这些工具：

用户：使用 /assets 中的图像重建此网页截图

Claude：我将首先使用布局检测器分析布局。

[调用 analyze_layout 工具]

分析结果显示：
- 视口：900x650像素
- 模式：径向（置信度90%）
- 中心元素：logo.gif，位于 (450, 250)
- 8个元素围绕中心排列
- 与中心的平均距离：196像素

我将使用CSS实现此布局，将logo居中，并使用绝对定位放置其他元素...

🖼️ 支持的图像格式

• PNG
• JPEG
• GIF（包括动画 - 使用第一帧）
• WebP
• BMP

🐞 故障排除

"No module named 'cv2'"

未安装OpenCV。运行以下命令进行安装：

pip install opencv-python-headless

MCP服务器未在 /mcp 中显示

1. 检查设置文件路径是否正确
2. 确保命令路径是绝对路径（对于源码安装）
3. 修改设置后重启Claude Code
4. 运行 python3 test_install.py 以验证包是否正常工作

低置信度匹配

尝试降低 threshold 参数（默认值为0.8）。0.6 - 0.7之间的值可能有助于处理压缩或缩放的图像。

🛠️ 开发指南

# 以可编辑模式安装，并包含开发依赖项
pip install -e ".[dev]"

# 运行测试
pytest

# 测试安装
python3 test_install.py

📋 依赖要求

• Python 3.11+
• OpenCV（opencv-python-headless）
• NumPy
• Pillow
• MCP SDK

📄 许可证

本项目采用MIT许可证。