h-kazuki-pixel/layout-doctor-mcp

**HTMLを実際にレンダリングして、レイアウトの破綻を数値で検出するMCPサーバー。**
比較用のベースライン画像は要りません。いま生成したその1枚だけで判定します。
> **これは検査専用のツールです。** ファイルの書き換えや自動修正は一切行いません。読み取りのみで動作します。
なぜ作ったか
AIにHTMLやスライドを作らせると、コードは正しいのに**表示が壊れている**ことがあります。文字が重なる、枠からはみ出す、undefined がそのまま出る。しかし生成した本人はレンダリング結果を見ていないので気づけません。
既存のビジュアルテストツールは、ほぼすべてが**「前回の画像と比べて変わったか」**を見る回帰テストです。いま作ったばかりの1枚には、比べる相手がいません。
スクリーンショットを撮って画像認識に判断させる方法もありますが、視覚モデルは「この要素があの要素より37px右にはみ出している」といった空間的な把握を苦手としています。
このツールは画像を見ません。**DOMの座標と、文字が実際に描画された矩形を実測します。** だから「なんとなく崩れている」ではなく「どの要素が何ピクセルはみ出しているか」が返ります。
インストール
npmへの公開は準備中です。現在は clone してビルドします。
⚠️ **npx playwright install chromium は必ずこのディレクトリの中で、npm install のあとに実行してください。**別の場所で実行すると、依存とは異なるバージョンの Playwright 用に Chromium が入り、起動時に Executable doesn't exist at ... エラーになります。
Linux では共有ライブラリが不足していることがあります。その場合は次を使ってください(管理者権限が必要です)。
Claude Desktop の設定
設定ファイル claude_desktop_config.json の場所:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
次を追記します。/absolute/path/to は clone した場所に置き換えてください。
macOS の Claude Desktop は起動時にシェルのPATHを継承しないため、npx ではなく **node と絶対パスで指定するのが確実**です。
**Chromiumを新たに入れたくない場合**、既にあるChromeを使えます。
Windows / Linux では、パスを次のように置き換えてください。JSONの中では \ を \\ と2つ重ねて書きます。
- Windows: C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe
- Linux: /usr/bin/google-chrome(または /usr/bin/chromium)
セットアップをAIに任せる
設定ファイルの手編集につまずいたら、Claude Desktop に以下をそのまま貼り付けてください。
---
layout-doctor-mcp をセットアップしてください。
1. https://github.com/h-kazuki-pixel/layout-doctor-mcp の README を読む
2. clone とビルドのコマンドを1つずつ提示する
3. 私の claude_desktop_config.json に必要な設定を追記する(node と絶対パスを使う)
4. 設定後、動作確認として layout_check を1回実行して結果を見せる
私は非エンジニアです。実行するコマンドは1つずつ提示してください。
---
1分お試し
MCPサーバーを立てなくても、動作を確認できます。
次のように出力されます。
所要時間はブラウザの起動を含むため環境によって大きく変わります。座標もフォントによって数ピクセル前後します。
使い方
ツールは layout_check の1つだけです。
path(ファイルの**絶対パス**)・html(文字列)・url(既定では localhost のみ)のいずれか1つと、viewport を渡します。
**viewport に既定値はありません。** 画面幅によって結果が変わるため、必ず明示してもらう設計にしています。スライドなら 1280×720、一般的なWebページなら 1280×800 が目安です。
主な引数
| 引数 | 既定 | 説明 |
|---|---|---|
| checks | element-collision 以外すべて | 実行する検査を絞り込む |
| minOverlapPx / minOverlapArea | 3 / 24 | この大きさ未満の重なり・はみ出しを無視する |
| allowNetwork | false | 外部への通信を許可する |
| format | "text" | "json" にすると機械処理向けの出力になる |
| settleMs | 0 | 遅れて描画される要素がある場合の追加待機 |
| executablePath | — | 使用するChromiumのパス |
検出できる問題
| 検査 | 深刻度 | 内容 |
|---|---|---|
| placeholder-left | error | undefined / NaN / {{name}} など、値が埋まらなかった箇所 |
| draft-text-left | warning | Lorem ipsum / TODO などの仮テキストの残留 |
| broken-reference | error | 画像・CSS・スクリプトの参照先が存在しない |
| duplicate-id | warning | id の重複 |
| viewport-overflow | error | 要素が画面外へはみ出している |
| horizontal-scroll | error | 文書幅が画面を超え、横スクロールが発生する |
| container-overflow | warning | 子要素が親コンテナからはみ出している |
| content-clipped | error | overflow:hidden で内容が切り取られ、読めなくなっている |
| text-overlap | error | 文字同士が重なって読めない |
| invisible-text | warning | 文字色と背景色が同一、または font-size がゼロ |
| element-collision | warning | 要素同士の重なり(**既定では無効**) |
text-overlap について
このツールの中心となる検査です。要素の枠(ボックス)同士の重なりは、バッジやオーバーレイなど**意図的なデザインであることが多く**、そのまま報告すると誤検出だらけになります。
そこで、要素ではなく**文字が実際に描画された矩形**同士の交差だけを見ます。文字と文字が重なっているなら、それはほぼ確実に不具合だからです。
さらに、同じ行に並ぶ単語同士(隣り合う など)は同じブロック内として除外し、overflow:hidden で切り取られて画面に出ていない文字も判定から外しています。