Layout Detector MCP

🚀 Layout Detector MCP

このMCP（Model Context Protocol）サーバーは、ウェブページのスクリーンショットを分析してレイアウト情報を抽出します。スクリーンショットと画像アセットを与えると、各アセットが表示される場所を特定し、空間的な関係を計算します。これにより、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ツールを呼び出す]

分析結果は以下の通りです:
- ビューポート: 900x650px
- パターン: 放射状（信頼度90%）
- 中心要素: (450, 250)にあるlogo.gif
- 中心の周りに配置された8つの要素
- 中心からの平均距離: 196px

私はこれをCSSを使用して、ロゴを中央に配置し、他の要素を絶対配置を使用して位置決めして実装します...

🖼️ サポートされる画像形式

• PNG
• JPEG
• GIF（アニメーション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 を実行してパッケージが正常に動作することを確認してください。

低い信頼度の一致

閾値パラメータ（デフォルトは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