awwwards-doctor

Awwwards MCP Doctor

awwwards-mcp のツールチェーンを修復する場合、または作業中に回避策を講じる場合に使用します。 診断 → 機械的な修復 → パーサーの修復（ずれがある場合）→ ユーザーのタスクの再開の順に進めてください。ユーザーデータは削除しないでください。唯一の破壊的な手順（キャッシュ DB を別の場所に移動）では、古いファイルを保持します。--fix の場合は OS の一時ディレクトリに、手動でリセットする場合は完全バックアップ後にキャッシュと同じ場所に保持します。

プロファイルに関する注意： このスキルのツールは search_sites、get_site_details、 capture_live_site、analyze_page_structure、capture_component、 export_design_tokens、analyze_images です。以下の例では 1.x の名前（デフォルトの full プロファイル）を使用しています。AWWWARDS_MCP_PROFILE=v2 の場合は、代わりに search_references {request:{kind:"sites", ...}}、 get_reference {request:{kind:"site_details", slug}}、 capture_page {request:{kind:"screenshot", url}}、 inspect_page {request:{kind:"structure", url}}、 capture_page {request:{kind:"component", url}}、 inspect_page {request:{kind:"tokens", url}}、audit_page {request:{kind:"images", url}} を使用してください。完全な対応表： v2-routing.md。

1. doctor を実行する（awwwards-mcp のソースチェックアウト）

これらは awwwards-mcp のソースチェックアウトのルートから実行してください （github.com/INSANE0777/Awwwards-mcp）。ここでいうリポジトリとは、package.json が awwwards-mcp であるものです。awwwards-skills のチェックアウトから実行しないでください。npm パッケージにはこれらのスクリプトは含まれていません。サーバーをインストール済みの場合は、代わりにセクション 3 を使用してください。

npm run doctor             # diagnose only
npm run doctor -- --fix    # diagnose AND apply available fixes
npm run doctor -- --json   # machine-readable report

doctor は 5 項目をチェックし、機械的に修復できるものを修復します。

チェック項目	失敗の意味	--fix の動作
network	awwwards.com がリクエストをブロックまたはチャレンジした	ローカルで修復できることはありません。待ってから後で再試行してください。ループで再試行しないでください
parser-drift	パーサーが想定する awwwards.com のマークアップが変更された	修正用のフィクスチャとして、ライブページの生データを docs/drift-<timestamp>/（gitignore 対象）に保存します
playwright-chromium / ffmpeg-static	オプションのキャプチャ依存関係が見つからないか、壊れている	インストールします（開発依存関係 + npx playwright install chromium）
cache	SQLite DB が破損またはロックされている、あるいはインデックスが 30 日以上古い	読み取れない DB を別の場所（temp 内に保持）へ移動し、npm run index で再構築します
boot	dist/cli.js が起動しない	npm run build

修復後に doctor を再実行してください。MCP が修復されたと判断するには、判定結果が HEALTHY である必要があります。

2. 実際に発生したパーサーのずれを修正する（唯一のコードレベルの失敗）

doctor が parser-drift を報告した場合、アンカープローブで問題が発生したパーサーを特定できます。 修復手順 — 機械的に進め、各手順で確認してください。

1. 証拠を保存する：docs/drift-*/ の --fix スナップショットが新しい正解です。（日次の GitHub Action でも、ずれが発生したアンカー名を記載した parser-drift の追跡用 issue が作成または更新されます。）
2. 新しいアンカーを特定する：保存した HTML を開き、古いアンカーに置き換わったマークアップを探します（古いアンカーの 目的 を検索します。例：カードの JSON ブロブ、Elements セクションの見出し、og:image メタデータ）。
3. src/parsers.ts のパーサーのアンカーを付け直す — 必要最小限の変更（split/indexOf/正規表現リテラルを 1 つ）にとどめ、周辺のロジックは変更しないでください。
4. プローブリストを更新する：scripts/parser-drift-probe.mjs（同じ awwwards-mcp チェックアウト内の PROBE_GROUPS）を更新し、次回同じ失敗を検出できるようにします。
5. フィクスチャを更新する：クライアントと同じ UA でライブページをダウンロードし、test/fixtures/listing.html（または詳細ページのフィクスチャ）を置き換えます。オフラインテストではフィクスチャのみを使用します。フィクスチャを更新することで、実際のページに対してアンカーを付け直したことを確認できます。
6. npm run typecheck && npm test — すべてのテストに合格する必要があります。
7. fix: re-anchor <parser> after awwwards.com markup change としてコミットし、追跡用 issue を参照します。

注：年間アワードのツール（get_annual_*）はパーサーではなく、公式 JSON API（src/annual.ts）から取得します。また、アワード別の拡張リスト（sites_of_the_month/year、nominees、winner_category_*）には、test/fixtures/awards/ 内に専用の縮小フィクスチャがあります。これらのアンカーにずれが発生した場合は、日次リストのフィクスチャと併せて更新してください。

3. エンドユーザー（リポジトリをチェックアウトせず npm 経由でインストール）

doctor スクリプトはリポジトリ内にあるため、npm でインストールしたサーバーでは次の手順に従ってください。

1. バージョン通知を確認します。起動時に、より新しい awwwards-mcp が存在する場合は stderr に表示されます。npm install -g awwwards-mcp@latest を実行して更新し（または npx キャッシュをクリアして）、エージェントを再起動します。「壊れている」という報告の意外に多くは、新しいリリースで修正済みの古いパーサーが原因です。 MCP サーバーの環境変数に AWWWARDS_AUTO_UPDATE=1 を設定すると、起動時のバックグラウンドでの自動更新が有効になります。

2. バックアップを取ってから、データベースのみをリセットします。 DB の書き込み中でないことを確認するため、先にエージェント／MCP サーバーを停止してください。CACHE="${AWWWARDS_CACHE_DIR:-$HOME/.awwwards-mcp}" でキャッシュのルートを解決します（サーバーも同じ変数を読み取ります）。まずコピーを別の場所に保存し、その後 SQLite ファイルのみを移動します。次回のインデックス作成／実行時に再構築されます。

   CACHE="${AWWWARDS_CACHE_DIR:-$HOME/.awwwards-mcp}"
   STAMP="$(date +%Y%m%d-%H%M%S)"
   cp -R "$CACHE" "$CACHE.backup-$STAMP"
   mkdir -p "$CACHE.moved-$STAMP"
   for f in "$CACHE"/cache.db*; do [ -e "$f" ] && mv "$f" "$CACHE.moved-$STAMP/"; done
   

   キャッシュルートを一括削除すると、preferences.json（セットアップ時の選択内容）、skill-memory/findings.jsonl（学習済みの調査結果）、受賞者のウォッチ（cache.db 内の行）、images/ と scene-captures/ 内のキャプチャも削除されます。対象を絞ったリセットで失われるのは検索インデックスとウォッチの行のみです。インデックスは再構築されますが、ウォッチは再登録が必要です。設定、学習済みの調査結果、キャプチャは保持されます。キャッシュルートに対して rm -rf を実行しないでください。

3. それでも失敗する場合は、上流の問題（ブロックまたはずれ）です。失敗した URL の生 HTML を添付して、awwwards-mcp リポジトリで issue を作成してください。

4. 実行中のタスクを復旧する（問題に気づいた理由）

ユーザーのビルドや調査は、修復が終わるのを待ちません。適切に縮退して対応します。

• 古いキャッシュは味方です：ライブ取得に失敗した場合、search_sites／get_site_details はキャッシュデータを返します。返信では「7日前のキャッシュデータ」のように、その旨を伝えます。
• BlockedError が出たら、再試行せずに停止します：クライアントはブロックを回避して再試行しません。ユーザーに伝え、キャッシュや代替データを使って続行します。
• キャプチャツールが停止している場合（playwright が見つからない場合）：npm run doctor -- --fix で chromium が復旧するまでは、ブラウザー不要で CDN から配信される get_site_details のスクリーンショットに切り替えます。
• トークン／画像ツールが停止している場合：export_design_tokens は capture_component パックを再利用します（同じ playwright／chromium の要件があります）。analyze_images にも同じブラウザーが必要です。playwright がない場合、どちらも親切なインストール案内ではなく、生のブラウザー／モジュールエラー（例：Cannot find package 'playwright'）を返します。案内を返すツールは capture_live_site／analyze_page_structure です。キャッシュ済みの get_site_details スクリーンショットが代替手段になります。analyze_images はアセットをダウンロードしません。画像がゼロの場合、ページに <img> 要素がない（canvas／CSS 背景コンテンツ）か、スキャンで画像が見つからなかったという意味であり、監査の不具合ではありません。
• 単一の帯状画像、プリローダー、または mode:"anchors" が返る場合：1.14 では内側のスクロールルート（scrollRoot）を検出し、全画面ローダーが消えるまで待機します。1.15 では内側スクロールのあるページに対して mode:"anchors" を返します。これは、スクローラー上の6枚のビューポート画像を、インライン画像なしの JSON パス（anchors[].scrollTop／file）として返します。これは正しい成功ペイロードであり、キャプチャの不具合ではありません。ビューポート画像を1枚だけ明示的に取得するには、scrollCapture:"viewport" を使います。scrollRoot の再クエリーでエラーが発生した場合（一致件数が0件または2件以上）、スキャン後から撮影までの間に DOM が変化しています。再実行するか、ラベルと一致件数を報告します。ページが引き続き単一の帯状画像を返す場合、コンテンツがシャドウ DOM または canvas 内にある可能性があります。全体の帯状マップとして扱わず、制約を調査して報告します。
• タスクの途中でパーサーの挙動が変わった場合：結果が部分的に空になることがあります（例：パレットなしで詳細情報だけが返る）。欠けている部分を明示し、劣化したデータを完全なものとして黙って提示しないでください。
• MCP が再び正常になったら、失敗した呼び出しを再実行し、代替手段で得た結果と照合します。

改善サイクルを締めくくる

修復から得られる教訓は最も価値が高く、習得にも多くの労力がかかっています。awwwards-skills リポジトリをチェックアウトし（インストール済みのスキルコピーにはこの開発スクリプトは含まれていません）、診断と修正が成功した後に、次を実行します。 node scripts/skill-memory.mjs record --skill awwwards-doctor --phase repair --symptom "..." --rule "..." [--evidence <report path>]。Distill は繰り返し発生する失敗の兆候をこのインストール済みコピーに統合するため、次の修復ではその知見を活用できます。ルールの有効性が確認できたら、promote --skill awwwards-doctor を実行します。出力からマシン固有の証拠パスが取り除かれ、配布用コピーの PR に使える状態になります。

アンチパターン

• ブロックされたリクエストをループで再試行すること。礼儀を守るためのルールとブロック検出は、まさに awwwards.com への過剰なリクエストを防ぐためにあります。
• 生の HTML を差分比較して挙動の変化を検出すること。ページの見た目だけの変更で毎日のように誤検知が起きます。重要なのはパーサーのアンカーの検査だけです。
• 結果を黙って空にするようパーサーを緩めて「修正」すること。アンカーを見つけられないパース処理では、明確なエラーを返す必要があります（それが挙動変化の兆候です）。
• 「リセット」のためにキャッシュのルートディレクトリを一括削除すること。設定、学習済みの調査結果、注目対象の監視情報、キャプチャが失われます。まずバックアップし、cache.db* だけを移動します。
• 1つのチェックに合格したからといって、doctor の UNHEALTHY 判定を解決済みとして扱うこと。