awwwards-setup

Awwwards MCP のセットアップ

awwwards MCP サーバーを初めて利用する際のオンボーディングです。最初に本格的な検索を行う前に、ユーザーがどのような形式で結果を受け取りたいかを把握し、使用する場合に限ってオプションの大容量依存関係をインストールします。選択内容はすべて保存され、同じ選択を再度尋ねることはありません。

プロファイルに関する注意： このスキルのツールは、search_sites、list_categories、get_annual_categories（および get_annual_nominees / get_annual_nominee）、new_winners、watch_site、capture_live_site、analyze_page_structure、record_site_motion、export_design_tokens、analyze_images、analyze_bundle です。以下の例では 1.x の名前（デフォルトは full）を使用しています。AWWWARDS_MCP_PROFILE=v2 の場合は、次を使用します。 search_references {request:{kind:"sites", ...}}、 browse_awards {request:{kind:"filters"}}、 browse_awards {request:{kind:"annual_categories"}}（同様に kind:"annual_nominees" および kind:"annual_nominee"）、 monitor_awards {request:{action:"poll_winners"}}、 monitor_awards {request:{action:"add_watch", kind, pattern}}、 monitor_awards {request:{action:"list_watches"}}、 monitor_awards {request:{action:"remove_watch", kind, pattern}}、 capture_page {request:{kind:"screenshot", url}}、 inspect_page {request:{kind:"structure", url}}、 capture_page {request:{kind:"recording", url}}、 inspect_page {request:{kind:"tokens", url}}、 audit_page {request:{kind:"images", url}}、および audit_page {request:{kind:"bundle", url}}。 AWWWARDS_MCP_ATLAS=1 の場合、full プロファイルには search_atlas、get_atlas、capture_atlas、export_evidence_pack が追加され、v2 には export_evidence_pack と Atlas の各分岐が追加されます。awwwards-atlas スキルを参照してください。 完全な対応表： v2-routing.md。

0. 既存の設定を確認する

~/.awwwards-mcp/preferences.json を読み込みます（キャッシュディレクトリは AWWWARDS_CACHE_DIR によって別の場所に設定されている場合があります。設定されている場合は、その値に従ってください）。ファイルが存在し、以下のフィールドが指定されている場合は、その内容をユーザーに知らせずに適用して終了します。オンボーディングを再度行わないでください。フィールドが不足している場合は、そのフィールドについてのみ尋ねます。ファイルが存在しない場合は、そのまま続行してください。

0b. MCP が接続されていませんか？まず接続してください

プロファイルに依存しない検出方法です。サーバーが未登録なのは、利用可能な Awwwards ツールが一つもない場合に限られます。接続済みの v2 セッションには意図的に search_sites や list_categories がありません。search_references や get_index があるかどうかで判別してください。接続済みの core セッションには 13 個のツールが登録され、list_categories は含まれません。そのため、これを必須にしないでください。Awwwards ツールが一つでも応答したら、ステップ 1 に進んでください。

何も利用できない場合、エージェントにサーバーがまだ登録されていません。ほかのことを始める前に設定してください。エージェントを検出し、追加コマンドを使用します（任意の依存関係はステップ 1 で後から一度だけインストールします。API キーやアカウントは不要で、Node ≥ 22.13 が必要です）。

エージェント	コマンド
Claude Code	claude mcp add awwwards -- npx -y awwwards-mcp
Codex CLI	codex mcp add awwwards -- npx -y awwwards-mcp
OpenCode (opencode.json)	"mcp": { "awwwards": { "type": "local", "command": ["npx", "-y", "awwwards-mcp"] } }
mcpServers 標準のクライアント（Claude Desktop、Cursor、Windsurf、Gemini CLI、Cline、Continue）	"mcpServers": { "awwwards": { "command": "npx", "args": ["-y", "awwwards-mcp"] } }

pi の場合（設計上 MCP はありません）：このスキルをエージェントのスキルディレクトリにインストールしてください。pi ではワークフローを利用できますが、ライブデータを使うには別のエージェントまたは MCP 対応の拡張機能が必要です。登録後、ツールが表示されるにはエージェントの再起動が必要です。そのことを伝えて、そこでいったん停止してください。設定（ステップ 1）は今のうちに収集して保存しておけば、再起動後のセッションですぐに実行できます。 任意の環境変数の追加：AWWWARDS_CACHE_DIR（キャッシュの保存先をカスタマイズ）、 AWWWARDS_AUTO_UPDATE=1（新しいリリースのバックグラウンド自動更新）、 AWWWARDS_MCP_PROFILE=core|full|v2（core は get_annual_categories を含むビルドループ用の 13 個のツールのみを登録します。full は 41 個すべてを公開します（AWWWARDS_MCP_ATLAS=1 の場合は 45 個）。v2 は統合された 10 個のツールと、既存の名前およびフラットな入力を維持した 5 個のツール（create_design_brief、build_project、verify_build、verify_flow、analyze_network_capture）を登録します。Atlas を有効にすると 16 個です。置き換えられる 1.x の 34 個の名前のみが使えなくなります。デフォルトは full です。変更するにはサーバーの再起動が必要です）。AWWWARDS_MCP_ATLAS=1 は実験的な Atlas ツールと CLI 用の独立したオプトインフラグです。core は変更されません。awwwards-atlas スキルを参照してください。v2 の旧名から新名への対応表は v2-routing.md にあります。v2 セッションで 1.x の名前を混在させないでください。 AWWWARDS_MCP_MAX_RESPONSE_BYTES（デフォルトは 32 MB。上限を超えた結果は切り詰めを示す JSON になります）、 AWWWARDS_MCP_DEBUG_MEMORY=1（ツール呼び出しごとに stderr にメトリクスを 1 行出力）、 AWWWARDS_MCP_ATTACH=1（ログイン済みページへの読み取り専用 CDP 接続を許可）。 1 リリース前の旧式表記である AWARDS_MCP_* も使用できます。正式な表記は AWWWARDS_MCP_* です。

1. ユーザーに確認する（一括ですべて）

短い質問票としてまとめて提示します。ユーザーには一度だけ回答してもらい、 4 回も追加で質問しないようにします。それぞれに妥当なデフォルトを提示し、 「デフォルトをそのまま使う」だけで回答できるようにしてください。

1. 結果の密度 — search_sites を使うとき、結果をどのように表示しますか？

   • Full（デフォルト）：すべての結果にスクリーンショットをインライン表示します。デザインをひと目で判断するのに適していますが、コンテキストを多く消費します。
   • Compact：簡潔なテキストカードを表示し、インラインプレビューはリクエストされたページの上位 2 件の結果だけに表示します。幅広い調査や、長時間稼働するエージェントに適しています。 これは responseMode パラメーターに対応します。選択されたデフォルトは、リクエストに別の指定がない限り、すべての検索で使用されます（画面を評価するタスクでは、引き続き full を使用してください）。"responseMode": "full" | "compact" として保存します。

2. デフォルトのビューポート：ライブキャプチャ、構造分析、モーション記録で使用します。"desktop"（1440×900、デフォルト）、"mobile"（390×844）、またはモバイルが重要だとユーザーが伝えているデザイン作業では "both" を選択できます。"defaultViewport": "desktop" | "mobile" | "both" として保存します。

3. ライブキャプチャ — 最新のスクリーンショット／構造バンドマップ／モーション記録／デザイントークンのエクスポート／画像監査（capture_live_site、analyze_page_structure、record_site_motion、export_design_tokens、analyze_images）を使いますか？これらには、オプションの playwright と chromium のインストール（約 120 MB）が必要です。 npm install -g awwwards-mcp playwright ffmpeg-static && npm exec --global -- playwright install chromium 次に、同じスコープでこのエージェントの awwwards 登録を npx -y awwwards-mcp からインストール済みのコマンド（awwwards-mcp）に切り替え、サーバーと Playwright が同じグローバルインストールから解決されるようにして、再起動します。はいの場合は、今すぐインストールを実行します（初回のみ必要で、安全に再実行できます）。いいえの場合は、インストールされるまでキャプチャツールでエラーが発生することを伝えます。"capturesEnabled": true | false として保存します。 バンドルのフォレンジック調査向けの追加オプション：npm install -g webcrack を実行すると、analyze_bundle の難読化解除／展開モードが有効になります。これがなくても、ツールは生のチャンクを取得、保存し、キーワード検索できます。

4. ローカルインデックス — search_sites はすぐに使えますが、丁寧なライブスクレイピング（ページごとに約 31 サイト）によって深度を高めます。ローカルインデックス（約 4 分で完了し、中断後の再開が可能。その後はバックグラウンドで自動更新されます）を作成すると、何千ものサイトを対象にした検索を即座に実行できます。 npx -y -p awwwards-mcp awwwards-index（または awwwards-mcp のチェックアウトで npm run index）。実行するかをユーザーに確認してください。承諾された場合はバックグラウンドで実行し、オンボーディングを続けてください。完了を待つ必要はありません。"autoIndex": true | false として保存します。

5. 受賞者のウォッチ — セッションをまたいでスタジオ、タグ、特定のサイトを追跡しますか？ユーザーが名前を挙げた場合は、それぞれを登録します（watch_site、action: "add"、kind: studio|tag|url。エントリーごとに 1 件、award と note は任意）。最初の watch_site list はベースラインを登録するだけだと伝え、ここには何も保存しません（ウォッチはサーバー独自のキャッシュに保存されます）。

6. 最新情報を保つ（任意、保存なし。動作に関する案内のみ）：ユーザーがトレンド調査を行う場合は、セッション開始時に new_winners を実行すると受賞者のベースラインを最新に保ち、ウォッチにも反映されることを伝えます。

オンボーディング中に、年間アワードに関する質問には 3 つの get_annual_* ツールを使用すること、また search_sites のアワードフィルターは日次の受賞者だけでなく、sotm／soty／nominees と受賞カテゴリー別の絞り込み（ecommerce、portfolio、product、typography、businessServices、noCode）にも対応することを伝えてください。

回答は 1 つの JSON オブジェクトとして設定ファイルに保存します。必要に応じて ~/.awwwards-mcp/ を作成してください。

{
  "responseMode": "full",
  "defaultViewport": "desktop",
  "capturesEnabled": true,
  "autoIndex": true,
  "onboardedAt": "2026-09-28T00:00:00.000Z"
}

2. ツールチェーンを確認する（質問なし）

設定の希望を確認したら、次の項目を一度にチェックして、セットアップに問題がないか確認します。

• バージョンのずれ：サーバーの起動時にアップデート通知が（stderr に）表示されていた場合は、新しいバージョンと、そのバージョンを適用する方法（npx -y awwwards-mcp@latest を使うか、サーバーの env に AWWWARDS_AUTO_UPDATE=1 を設定）をユーザーに伝えます。
• capturesEnabled の場合：playwright の解決を確認したことを1行で伝えます。失敗した場合は、npm exec --global -- playwright install chromium が成功するまでキャプチャツールは無効であると伝えます。繰り返し再試行してはいけません。
• キャッシュディレクトリに問題があるように見える場合（SQLite またはロックに関するツールエラー）：awwwards-doctor スキルに案内します。何も削除してはいけません。
• AWWWARDS_MCP_PROFILE=v2 の場合：get_index {request:{kind:"status"}}（ネットワークアクセスなし）を実行するか、ローカルインデックスにデータがある場合は search_references {request:{kind:"sites", query:"portfolio"}} を1回実行して、統合されたインターフェースを確認します。v2 セッションで1.xのツール名を使った場合は、インストールの問題ではなくルーティングエラーです。v2-routing.md を確認し、プロファイルを変更した後に再起動してください。

3. 報告して引き継ぐ

最後に2～3行で、保存した設定、バックグラウンドでインストールまたは起動したもの、ワークフローを開始する次のコマンドを1つにまとめます（通常は、保存した responseMode を使う search_sites です）。簡潔にまとめてください。このスキルの目的はセットアップであり、チュートリアルではありません。実際の使い方は、awwwards-inspiration（調査ループ、受賞サイトのフィード、インデックス操作）、awwwards-motion-study（動画リファレンスの調査）、awwwards-doctor（修復）に記載されています。

後から設定を変更する

ユーザーがこれらの設定の変更（「コンパクトにして」「モバイルでキャプチャして」など）を求めた場合は、設定ファイルを更新し、1行で確認を伝えます。既存の設定がある状態でこのスキルを再実行する場合は、未設定の項目のみを質問します。