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
}

📋 支持的佈局模式

💻 使用示例

配置完成後，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許可證。