This server provides a tool that renders HTML and numerically detects layout defects by measuring DOM coordinates and text rectangles, without requiring baseline images.
Key detectable issues:
Text overlaps (unreadable intersecting text)
Element overflow (viewport, container, horizontal scroll)
Content clipping (via overflow: hidden)
Unfilled placeholders (undefined, NaN, {{name}})
Draft/placeholder text (Lorem ipsum, TODO)
Broken references (missing images, CSS, scripts)
Duplicate IDs
Invisible text (matching colors or zero font-size)
Element collisions (optional)
Input: Accepts HTML as a file path, raw string, or localhost URL (blocks remote networks by default), with a required viewport size. Outputs a summary and array of findings in text or JSON format. It is read-only, deterministic, and waits for fonts/animations to settle. Best suited for single-page layout checks; not for visual regression, responsive multi-width testing, or accessibility evaluation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@layout-doctor-mcp check /path/to/report.html for layout issues at 1280x720"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
HTMLを実際にレンダリングして、レイアウトの破綻を数値で検出するMCPサーバー。
比較用のベースライン画像は要りません。いま生成したその1枚だけで判定します。
これは検査専用のツールです。 ファイルの書き換えや自動修正は一切行いません。読み取りのみで動作します。
[エラー] text-overlap-001
テキスト「料金プラン」と「人気No.1」が 59×17px(面積 1003px²)重なっており、文字が読めなくなります。
→ div.hero > h1 (24, 48) 163×36px
→ span.badge (128, 55) 66×17px
対処: どちらかの位置・余白を調整するか、重ねる意図がある場合は背景を不透明にしてください。AIにHTMLやスライドを作らせると、コードは正しいのに表示が壊れていることがあります。文字が重なる、枠からはみ出す、undefined がそのまま出る。しかし生成した本人はレンダリング結果を見ていないので気づけません。
既存のビジュアルテストツールは、ほぼすべてが**「前回の画像と比べて変わったか」**を見る回帰テストです。いま作ったばかりの1枚には、比べる相手がいません。
スクリーンショットを撮って画像認識に判断させる方法もありますが、視覚モデルは「この要素があの要素より37px右にはみ出している」といった空間的な把握を苦手としています。
このツールは画像を見ません。DOMの座標と、文字が実際に描画された矩形を実測します。 だから「なんとなく崩れている」ではなく「どの要素が何ピクセルはみ出しているか」が返ります。
Related MCP server: websight
npmへの公開は準備中です。現在は clone してビルドします。
git clone https://github.com/h-kazuki-pixel/layout-doctor-mcp.git
cd layout-doctor-mcp
npm install && npm run build
npx playwright install chromium⚠️ **npx playwright install chromium は必ずこのディレクトリの中で、npm install のあとに実行してください。**別の場所で実行すると、依存とは異なるバージョンの Playwright 用に Chromium が入り、起動時に Executable doesn't exist at ... エラーになります。
Linux では共有ライブラリが不足していることがあります。その場合は次を使ってください(管理者権限が必要です)。
npx playwright install --with-deps chromium設定ファイル claude_desktop_config.json の場所:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
次を追記します。/absolute/path/to は clone した場所に置き換えてください。
{
"mcpServers": {
"layout-doctor": {
"command": "node",
"args": ["/absolute/path/to/layout-doctor-mcp/dist/src/index.js"]
}
}
}macOS の Claude Desktop は起動時にシェルのPATHを継承しないため、npx ではなく node と絶対パスで指定するのが確実です。
Chromiumを新たに入れたくない場合、既にあるChromeを使えます。
{
"mcpServers": {
"layout-doctor": {
"command": "node",
"args": ["/absolute/path/to/layout-doctor-mcp/dist/src/index.js"],
"env": {
"LAYOUT_DOCTOR_CHROMIUM": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
}
}
}
}Windows / Linux では、パスを次のように置き換えてください。JSONの中では \ を \\ と2つ重ねて書きます。
Windows: C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe
Linux: /usr/bin/google-chrome(または /usr/bin/chromium)
設定ファイルの手編集につまずいたら、Claude Desktop に以下をそのまま貼り付けてください。
layout-doctor-mcp をセットアップしてください。
https://github.com/h-kazuki-pixel/layout-doctor-mcp の README を読む
clone とビルドのコマンドを1つずつ提示する
私の claude_desktop_config.json に必要な設定を追記する(node と絶対パスを使う)
設定後、動作確認として layout_check を1回実行して結果を見せる
私は非エンジニアです。実行するコマンドは1つずつ提示してください。
MCPサーバーを立てなくても、動作を確認できます。
git clone https://github.com/h-kazuki-pixel/layout-doctor-mcp.git
cd layout-doctor-mcp
npm install && npm run build
npx playwright install chromium
cat > /tmp/broken.html <<'EOF'
<!DOCTYPE html><html><head><meta charset="utf-8"><style>
body{margin:0;font-family:sans-serif}
.badge{position:absolute;left:120px;top:52px;background:#e74c3c;color:#fff;padding:2px 8px}
</style></head><body>
<div style="padding:24px"><h1>料金プラン</h1><p>月額 undefined 円</p></div>
<span class="badge">人気No.1</span>
</body></html>
EOF
node --input-type=module -e "
import { inspect, formatReport } from './dist/src/inspect.js';
const r = await inspect({ source: { kind: 'path', value: '/tmp/broken.html' },
viewport: { width: 800, height: 600 } });
console.log(formatReport(r));
"次のように出力されます。
検査完了: エラー 2 件 / 警告 0 件 / 情報 0 件
ビューポート 800×600 / 所要 434ms
[エラー] placeholder-left-001
本文に undefined が残っています。該当箇所: 「…料金プラン 月額 undefined 円 人気No.1…」
→ html
対処: 変数の埋め込みが失敗しています。値が未定義でないか、テンプレートエンジンが適用されているかを確認してください。
[エラー] text-overlap-001
テキスト「料金プラン」と「人気No.1」が 59×17px(面積 1003px²)重なっており、文字が読めなくなります。
→ div > h1 (24, 48) 163×36px
→ span.badge (128, 55) 66×17px
対処: どちらかの位置・余白を調整するか、重ねる意図がある場合は背景を不透明にしてください。
補足:
- 計測: 要素 6 個 / テキスト矩形 3 個 (抽出 7ms・判定 1ms)所要時間はブラウザの起動を含むため環境によって大きく変わります。座標もフォントによって数ピクセル前後します。
ツールは layout_check の1つだけです。
{
"path": "/Users/you/work/report.html",
"viewport": { "width": 1280, "height": 720 }
}path(ファイルの絶対パス)・html(文字列)・url(既定では localhost のみ)のいずれか1つと、viewport を渡します。
viewport に既定値はありません。 画面幅によって結果が変わるため、必ず明示してもらう設計にしています。スライドなら 1280×720、一般的なWebページなら 1280×800 が目安です。
引数 | 既定 | 説明 |
| element-collision 以外すべて | 実行する検査を絞り込む |
| 3 / 24 | この大きさ未満の重なり・はみ出しを無視する |
|
| 外部への通信を許可する |
|
|
|
|
| 遅れて描画される要素がある場合の追加待機 |
| — | 使用するChromiumのパス |
検査 | 深刻度 | 内容 |
| error |
|
| warning | Lorem ipsum / TODO などの仮テキストの残留 |
| error | 画像・CSS・スクリプトの参照先が存在しない |
| warning |
|
| error | 要素が画面外へはみ出している |
| error | 文書幅が画面を超え、横スクロールが発生する |
| warning | 子要素が親コンテナからはみ出している |
| error |
|
| error | 文字同士が重なって読めない |
| warning | 文字色と背景色が同一、または |
| warning | 要素同士の重なり(既定では無効) |
text-overlap についてこのツールの中心となる検査です。要素の枠(ボックス)同士の重なりは、バッジやオーバーレイなど意図的なデザインであることが多く、そのまま報告すると誤検出だらけになります。
そこで、要素ではなく文字が実際に描画された矩形同士の交差だけを見ます。文字と文字が重なっているなら、それはほぼ確実に不具合だからです。
さらに、同じ行に並ぶ単語同士(隣り合う <span> など)は同じブロック内として除外し、overflow:hidden で切り取られて画面に出ていない文字も判定から外しています。
element-collision が既定で無効な理由要素同士の重なりは、意図的な重ね置きと本当の不具合を機械的に区別できません。誤検出でツール全体の信頼を落とすより、必要な人だけが有効にする形を選びました。checks に明示的に含めると実行されます。
静的なHTMLしか検査しないなら — 文字列検査だけで足りる用途(プレースホルダの残留チェックのみ等)であれば、grep や既存のHTMLリンターの方が速く、ブラウザも要りません
前回との差分を見たいなら — このツールは1枚を単体で判定します。「変更前と変わったか」を見たい場合は Applitools や Playwright の視覚回帰の方が適しています
複数の画面幅をまとめて調べたいなら — 指定された1つの幅しか見ません。レスポンシブ対応の網羅検査は対象外です
アクセシビリティを総合的に見たいなら — コントラスト比・ARIA・キーボード操作は扱いません。axe-core 系のツールを使ってください
デザインの善し悪しを評価したいなら — 幾何的に破綻しているかだけを見ます。配色やバランスの判断はしません
このツールは、作者の他のMCPサーバー(jp-dates など)が守っている「完全オフライン・依存ゼロ」の方針から意図的に外れています。
レイアウトの破綻は、実際にレンダリングしなければ分かりません。Playwright と Chromium への依存はその代償です。導入がやや重くなる代わりに、推測ではなく実測を返します。
代わりに次を守っています。
通信は既定で遮断 — allowNetwork: true を指定しない限り、localhost 以外へ通信しません。検査対象のHTMLが外部へリクエストを飛ばすこともありません
読み取り専用 — ファイルの作成・変更・削除を一切行いません
ツールは1つだけ — 説明文が長いツールを多数並べると、利用者の毎ターンのコンテキストとコストを圧迫します。layout_check の1本に絞り、詳細はこのREADMEに置いています
各所見には verdict が付きます。
static — レンダリング結果を見るまでもなく確定している問題(プレースホルダの残留など)
candidate — 座標上は検出したが、人間の目に見えるかは未判定
candidate には、透明な要素同士の重なりのように「座標は重なっているが実際には見えない」ものが混ざりえます。この切り分け(レンダリング結果を用いた可視性の確認)は v0.5 で追加予定です。
デザインの良し悪し、コントラスト比などのアクセシビリティ全般、前回との差分(ビジュアル回帰)、複数幅にわたるレスポンシブ検査は対象外です。詳しくは「使わない方がいい場合」を参照してください。
同じ入力なら常に同じ結果を返すため、測定前に次を行っています。
CSSアニメーションとトランジションを停止(止めないと測るたびに結果が変わります)
Webフォントの読み込み完了を待機(フォントが差し替わると文字幅が変わり、座標がすべてずれます)
デバイスピクセル比を 1 に固定、ロケールとタイムゾーンを固定
外部への通信を既定で遮断(allowNetwork: true で解除)
Node.js 18 以上
Chromium(Playwright経由、または既存のChrome)
Linux では Chromium が要求する共有ライブラリが必要です(npx playwright install --with-deps chromium で導入されます)
LAYOUT_DOCTOR_CHROMIUM には Chromium のほか、製品版の Google Chrome や Microsoft Edge も指定できます(いずれも Chromium 系のため、Playwright の CDP で制御できます)。ただし動作確認は Playwright 同梱の Chromium で行っています。
検査項目の分類と、DOM座標だけでは人間に見えない問題まで拾ってしまうという知見は、以下の研究に基づいています。論文の記述を参照した独自実装であり、これらのツールのコードは使用していません。
Walsh, Snyder, Kapfhammer, McMinn: Automated Layout Failure Detection for Responsive Web Pages — レイアウト破綻の5分類
Althomali, Kapfhammer, McMinn: Automated visual classification of DOM-based presentation failure reports for responsive web pages (STVR 2021) — DOM検出の偽陽性と、不透明度操作による可視性判定
npm testテスト50件が通ります(geometry.test.ts 28件 / static.test.ts 22件)。検査項目ごとに「破綻を検出できること」と「意図的なデザインを誤検出しないこと」を対にして確認しています。
重なったテキストを検出する / 隙間なく並んだ2列は重なりとみなさない
スクリーンリーダー専用テキストを誤検出しない
overflow: hidden で隠れたテキストは重なりとみなさない
同じ入力を2回検査すると同じ結果になる(決定論性)
外部リソースは既定で読み込まれない
MIT
HTMLをレンダリングしてレイアウトの破綻を検出する。検査専用でファイルは変更しない。
比較用のベースライン画像は不要。DOMの座標と文字の描画矩形を実測するため、 「どの要素が何ピクセルはみ出しているか」が数値で返る。
検出: 文字の重なり / 画面外や親からのはみ出し / overflow:hidden による切り捨て / 横スクロールの発生 / undefined・{{name}} 等の未展開 / 参照切れ / id重複 / 不可視テキスト
引数:
html | path | url のいずれか1つ(必須)
viewport (必須): { width, height }。幅で結果が変わるため既定値なし
checks (任意): 検査の絞り込み。既定は element-collision 以外すべて
format (任意): "text"(既定)または "json" その他: minOverlapPx, minOverlapArea, allowNetwork, executablePath, settleMs
戻り値: summary(pass, errors, warnings, infos)と findings の配列。 各所見は check / severity / verdict / elements(selector, text, rect)/ evidence / suggest を持つ。 verdict は "static"(確定)か "candidate"(座標上は検出、可視性は未判定)。
対象外: デザインの評価、コントラスト比などのアクセシビリティ検査、前回との差分比較。
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | 検査するページのURL(既定では localhost のみ) | |
| html | No | 検査するHTML文字列 | |
| path | No | 検査するHTMLファイルの絶対パス | |
| checks | No | 実行する検査。省略時は element-collision 以外 | |
| format | No | 出力形式(既定text) | |
| settleMs | No | 描画後の追加待機ms | |
| viewport | Yes | ビューポート(CSSピクセル)。スライドは1280x720、Webは1280x800が目安 | |
| allowNetwork | No | 外部通信を許可する(既定false) | |
| minOverlapPx | No | 重なりの最小幅(既定3) | |
| executablePath | No | 使用するChromiumのパス | |
| minOverlapArea | No | 重なりの最小面積px2(既定24) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true; the description reinforces and extends this by stating no baseline image is needed, that measurement is done via DOM coordinates and text drawing rectangles, and that verdicts are classified as 'static' or 'candidate' to indicate certainty. This adds meaningful behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for purpose, detections, arguments, return value, and exclusions. It is information-dense but not bloated; however, it does partially restate parameter details already present in the schema, which keeps it from a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter tool with no output schema, the description thoroughly covers the return shape (summary plus findings with check/severity/verdict/elements/evidence/suggest) and explains the static/candidate verdict nuance. It also documents exclusions, defaults, and required inputs, making it nearly self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the one-of constraint for html/path/url, the reason viewport has no default, and the default values for checks and format. It does not explain every parameter in detail, but it meaningfully supplements the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool renders HTML to detect layout breakage and provides a concrete list of detectable issues (text overlap, overflow, horizontal scroll, unexpanded placeholders, broken references, duplicate IDs, invisible text). It also explicitly notes it is inspection-only and does not modify files, distinguishing its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use it (detect layout breakage) and when not to use it (excludes design evaluation, accessibility contrast checks, and before/after diff comparison). It also clarifies key constraints such as providing exactly one of html/path/url and the viewport being mandatory because width affects results.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0layout_checkScored across 1 tool
Only one tool exists, so there is no possibility of confusion or incorrect selection. The tool uniquely targets layout checking with a clear and comprehensive role. Disambiguation is trivially perfect.
The single tool name 'layout_check' follows a clear verb-noun pattern (check the layout) and accurately describes its function. Since there is no other tool to compare patterns, the consistency is essentially unqualified, but a perfect 5 would require a larger set. A 4 reflects the lack of pattern evidence rather than any inconsistency.
The server has only one tool, which per the rubric is considered too few for a typical tool server. While the tool itself is comprehensive and covers many layout-checks, the extreme minimalism limits workflow flexibility and integration. This falls into the 'too few' category rather than the borderline 1-2 range.
The tool covers a wide range of layout-detection features (overlap, overflow, truncation, horizontal scroll, unresolved references, id duplication, invisible text), and explicitly excludes unrelated areas like accessibility and design evaluation. For its stated purpose of layout diagnostics, the surface is remarkably complete. However, the lack of any companion tools (e.g., to fix issues or compare against a baseline) creates a minor gap in a full workflow, so it doesn't earn a perfect 5.
Capture screenshots, detect visual regressions between page versions, and analyze with AI.
Render-and-verify API: HTML/CSS to image or PDF, screenshot any URL, confirm the text rendered.
Validate HTML/CSS, audit SEO and JSON-LD, check links, and capture responsive screenshots.
Browser-based QA for AI-built software. Test pages with real browsers via agents.
