preline-mcp

Preline MCP

意図

Preline MCP サーバーを介して、Preline UI のコンポーネントとブロックを HTML ファイルに統合する場合に、このスキルを使用します。サーバーは、統合にすぐ使える HTML、CSS、JS を返す 6 つのツールを公開しています。

次の場合に有効化します：

• ユーザーが「preline」、「add preline」、「/preline」、「use preline」と言った場合
• ユーザーが Preline ライブラリの Tailwind CSS コンポーネントを求めた場合
• ユーザーがブロック（すぐに使えるページセクション）またはスターターページを求めた場合

デフォルト

• スラッグを推測しないでください。 すべてのセクション、コンポーネント、カテゴリの識別子は、正確なケバブケース文字列です。必ず最初に components_list または blocks_categories で確認してください。
• 一度に 1 つずつ。 コンポーネントまたはブロックを 1 つ取得し、完全に統合してから次に進みます。
• 何かを挿入する前に、必ず対象ファイルを読み取ってください。
• コンポーネントの種類がわかっている場合は、components_list({ section: "<inferred-slug>" }) を呼び出してください。これにより応答が小さくなります。セクションを省略するのは、不明な場合に限ります。

選択：コンポーネントかブロックか

ユーザーの発言	使用するもの
「component」／「components」	コンポーネントのワークフロー
「block」／「blocks」（または「example」／「examples」）	ブロックのワークフロー
曖昧な場合	状況に応じて判断します。ブロックのほうが、より完成度の高い結果を得られます

曖昧なリクエストの明確化

次のいずれかに当てはまる場合は、推測せずにユーザーに選んでもらいます。

• 抽象的なリクエスト。 1 つのカテゴリ／セクション、ましてや 1 つのブロック／コンポーネントに確信を持って絞り込むには抽象的すぎる場合です。たとえば、「料金ページ用の何かがほしい」「素敵なフォームが必要」「ダッシュボードの例を見せて」などです。以下のステップ 1 から始めます。
• 候補が同等。 リクエストから 1 つのカテゴリ／セクションまでは絞り込めるものの、blocks_in_category／components_list({ section }) を見ても、タイトルと説明がリクエストで示されたすべての条件をほぼ同じ程度に満たす候補が 2 つ以上残り、レイアウト／機能／スタイルの種類も同じで、候補を絞り込める情報がリクエストにない場合です。この場合は、以下のステップ 3 に進み、該当する候補のみを提示します。

リクエストで示されたすべての条件に一致する候補が 1 つだけの場合（「基本的なアコーディオン」「タブ付きの SaaS ヒーロー」など）は、通常のワークフローに進みます。すでに判断できることをユーザーに問いただしたり、最適な選択肢が明らかなのに念のため質問したりしないでください。

確認の質問や候補リストは、デフォルトではすべて 英語 で提示します。ユーザーがその言語で話しかけてきた場合に限り、ユーザーの言語に切り替えます。

ブロック：

1. 該当するカテゴリを尋ねます。 blocks_categories() を呼び出し、関連する mainSection / subSection / category のパスと、それぞれのタイトルおよび説明を提示します。カタログには各カテゴリの説明が 1 行ずつ記載されているため、独自に要約せず、そのまま提示します。
2. 一度のやり取りで解決できるか試します。 ユーザーの返信でカテゴリが示され、さらに項目を特定できるほど特徴が具体的に説明されている場合（特定のレイアウト、機能、スタイルなど）は、blocks_in_category を呼び出して正確な ID を確認し、そのまま single_block に進みます。ステップ 3 は完全に省略します。
3. それ以外の場合は、最適なブロックを尋ねます。 blocks_in_category({ mainSection, subSection, category }) を呼び出して、ブロックのタイトルと説明を列挙します。前述の候補が同等の場合は、その候補のみを列挙し、ユーザーのニーズに最も近いものを選んでもらいます。
4. 選ばれたブロックを取得して組み込みます。 single_block を使用します。

コンポーネント ― カテゴリではなくセクションを使う同じ流れ：

1. どの セクション が適切か尋ねます（全リストには components_list()、セクションを推測できる場合は components_list({ section }) を使います）。
2. 返信でセクションが示され、さらにコンポーネントを特定できるほど特徴が具体的に説明されている場合は、single_component で直接解決します（適切なデフォルト／バリアントを選ぶには、「スマートなコンポーネント選択」を参照し、relative メタデータを活用します）。
3. それ以外の場合は、そのセクションのコンポーネント（タイトルと説明、および該当する場合は relative.category のグループ分け）を列挙します。前述の候補が同等の場合は、その候補のみを列挙し、最適なものを選んでもらいます。
4. single_component でコンポーネントを取得して組み込みます。

各やり取りでは、焦点を絞った質問を 1 つだけ、短く見やすいリストとともに提示します。自由回答の「何がほしいですか？」と尋ねたり、質問を避けるためだけにスラッグを推測したりするよりも効果的です。

複合リクエストとレイアウトリクエスト

1つのコンポーネントを超える内容（複数の要素、領域、ページ全体、アプリのシェルなど）をリクエストされた場合、その場しのぎで取得しないでください。まず全体の完成形を計画し、その後、ノードを1つずつ取得して統合します。同じ手順は、ダッシュボード、設定ページ、製品ページ、複数ステップのフォーム、「X、Y、Zを含むカード／セクション／レイアウト」など、あらゆる形状に適用できます。

1. まず、全体に関わる制約を確定します。 全体に適用される要素（クラスシステム（テーマトークンとユーティリティのどちらを使うか → isUtilityBased / theme）、共通のサーフェス／色、間隔／密度、繰り返し要素の状態など）は、最初に一度決めます。その後のすべての取得と編集で同じ設定を保ちます。
2. ツリーに分解します： コンテナー → 領域 → リーフコンポーネント。内容を書き出し、各リーフを1回の取得単位にします。
3. すべてのノードを探し、確認します。 references/catalog-map.md を使って適切な場所を確認します。抽象的な意図（ページ全体／領域／シェル）→ 適切な blocks_categories ブランチ（適合する既製のブロックがあれば、それを骨組みとして再利用します）。名前が指定された各要素 → 適切な components_list({ section })。マップが示すのは「どこを探すか」だけです。挿入する前に、ツールの出力で正確なスラッグを必ず確認してください。
4. 最も外側から、一度に1つずつ組み立てます。 骨組み／外側のコンテナーで共通のサーフェスとスクリプト／初期化アンカーを設定し、その後、領域ごとに内側を埋めていきます。次に進む前に、各領域を完全に統合してください（統合ルール）。返されたクラスは維持し、変更するのはテキストのみです。ただし、ユーザーが変更を求めた特定のサーフェス／色／状態は例外です。構造上の適応はすべて、マークアップを書く前に適用してください（統合ルールの Adapt before you write を参照）。
5. 完成した結果を、要素ごとにリクエストと照合して確認します。

詳しい手順と実例については、references/composite-layouts.md を参照してください。

ワークフロー：コンポーネント

1. components_list({ section: "<slug>" })   → get valid component IDs
2. single_component({ section, component }) → get HTML/CSS/JS
3. Read target file
4. Integrate HTML, CSS, scripts, init (see Integration Rules)
5. Repeat from step 1 only after integration is complete

ワークフロー：ブロック

1. blocks_categories()                                    → get hierarchy
2. blocks_in_category({ mainSection, subSection, category }) → get block IDs
3. single_block({ mainSection, subSection, category, block }) → get HTML/CSS/JS
4. Read target file
5. Integrate HTML, CSS, scripts, init (see Integration Rules)
6. Repeat from step 1 only after integration is complete

統合ルール

HTML - ユーザーが必要とする場所に挿入します。

CSS（`` セクション）：

• 必ず <head> 内の </head> の直前に配置します
• <body> 内や </body> の近くには絶対に配置しないでください

外部スクリプト（`` セクション）：

• `` ラベルは応答内のセクションマーカーであり、対象ファイル内の配置場所ではありません
• 配置アルゴリズム：対象ファイルを開き、</body> から上方向に走査します。空行、コメント、構造タグではないタグ（</script>、</style> など）は飛ばします
• 最初に到達した構造タグの終了タグ（</main>、</section>、</div>、</footer>、</article>）を基準位置にします
• <script src> タグをその基準位置の後に挿入し、既存の Preline コアスクリプトの前後に適切な順序で配置します。Preline コアスクリプトとは、src に preline を含む読み込み済みの <script src> のことです（例：…/preline/dist/index.js。正確なパスはインストール方法によって異なります）。
  • src に preline を含まないスクリプト（lodash、apexcharts などのサードパーティーライブラリ）→ Preline コアスクリプトの前
  • src に preline を含むスクリプト（hs-*-helpers.js などの Preline ヘルパー）→ Preline コアスクリプトの後
  • Preline コアスクリプトがまだない場合は、preline を含まないスクリプト、次に preline を含むスクリプトの順にします
  • インラインの初期化 <script> は必ず最後にし、</body> の直前に配置します

初期化（`` セクション）：

• </body> の直前に配置します
• ブロックに <script> タグがすでに含まれていない場合は、window.addEventListener('load', () => { ... }) で囲みます

大きな応答（アーティファクト）： 応答を一時作業ファイルに書き込んだ場合は、Read ツールで一度読み込み（大きなファイルでは offset/limit を使用）、必要なブロックを対象にコピーしてから、一時ファイルを削除します。配置に必要な部分だけでよい場合は、アーティファクト全体をコンテキストに読み込まないでください。

書き込む前に調整します。 依頼内容が取得したマークアップと異なる場合（ユーザーが依頼していない領域（パンくずリスト、デモメニュー、プレースホルダーのロゴなど）、異なるブロックやラベルなど）は、最終的なマークアップをメモリ上で先に作成してから、各領域を一度の編集で対象に書き込みます。取得したマークアップをそのまま挿入してから、編集を何度も続けてはいけません。そのような編集は大きなマークアップを再転送することになり、コンテキストを浪費し、ファイルの状態との不整合を招きます。

同じトークンは同じ色です。 テーマトークン（bg-navbar、bg-sidebar、bg-layer など）は、テーマ内で一貫しています。2つの面を同じ色にするには、同じトークンクラスを指定してください。プロジェクトの CSS を読んで、トークンを実際の色に置き換えてはいけません。

返されたマークアップを信頼し、再検証しないでください。 MCP が返すクラス、構造、data-hs-* 属性は、Preline によって有効性が保証されています。これは避けるべき最大の時間の浪費です。次のことはしないでください。

• クラスの存在を「確認」したり、デザインのトークンがどの色になるかを調べたりするために、ユーザーのコンパイル済み CSS（例：main.css）を grep、解析、走査しないでください。Preline クラスは利用側のビルド時に解決されるため、特定のスタイルシートに存在しなくても何も意味しません。
• HTML/DOM/AST バリデーター（Python の HTMLParser、タグの対応チェックなど）を書かないでください。SVG や void 要素によって単純なパーサーは誤動作し、誤ったエラーが発生します。
• 生成されたコードを「再確認」するためだけに、配置済みのアーティファクトを再読したり、編集済みファイルを開き直したりしないでください。

マークアップを配置し、テキストだけを変更して、次に進みます。生成コードやプロジェクトの CSS を監査するのではなく、依頼内容に照らして確認してください（ユーザーが指定したすべての要素が含まれているか）。

スマートなコンポーネント選択

components_list は、コンポーネントごとに relative オブジェクトを返す場合があります。

• isSectionDefault: true - そのセクションに推奨されるデフォルトです。依頼が曖昧な場合は、こちらを優先してください
  • 例外：説明に「複数のバリアント」とあり、ユーザーがそのうち1つを求めている場合は、単一バリアントのコンポーネントを選んでください
• category - 論理的なグループです（例："color-variants"、"states"）
• isCategoryDefault: true - そのカテゴリに推奨されるデフォルトです。依頼がスタイルグループを示している場合は、こちらを優先してください

利用可能なテーマ

default（青）・harvest（琥珀色）・retro（フューシャ）・moon（グレースケール）・ocean（シアン）・bubblegum（ピンク）・cashmere（モーブ）・autumn（オレンジ）・olive（緑）

single_component または single_block で、isUtilityBased: true, theme: "<name>" として渡します。

主要なリファレンス

• references/catalog-map.md - ルーティングマップ：ブロックの意図オントロジー（ページ全体／シェル）と、目的別にグループ化されたすべてのコンポーネントセクション（JS プラグインのマーク付き）が記載されています。検出を行う前に、適切な section／blocks ブランチを選ぶために参照してください。
• references/composite-layouts.md - 複数コンポーネント／ページ／シェルのリクエスト向けの完全な手順と、具体的な例
• references/mcp-tools-reference.md - 全 6 ツールの完全なパラメーター仕様、配置アルゴリズムの詳細