Basecoat UI MCP

Basecoat UI MCP

Basecoat UI 向けのオフライン Model Context Protocol サーバー（React のバンドルや必須化なしで shadcn/ui の外観を実現します）。
Astro、Next.js、HTML、Tailwind CSS 4 向けに厳選されたテンプレート、マクロレイアウト、リズムトークン、静的検証を提供します。

このサーバーは、クライアントがドキュメントをスクレイピングする必要がないよう、AI コーディングエージェント向けに決定的なオフラインレジストリを公開します。ローカルの stdio 経由で動作し、実行時のネットワークリクエストはゼロ、応答は < 2 KB に制限され、字句解析／ヒューリスティックによる静的ソース検証も範囲が制限されています。レンダリング、データアクセス、認証、セッション、認証情報、OAuth、captcha、その他の実行時の動作は、ホストアプリケーションの責任です。

インストール

Node.js 22.14.0 以降が必要です。

クライアント別クイックスタート

Cursor（.cursor/mcp.json）

{
  "mcpServers": {
    "basecoat-ui": {
      "command": "npx",
      "args": ["-y", "@intellmedia/basecoat-ui-mcp", "--project-root", "${workspaceFolder}"]
    }
  }
}

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "basecoat-ui": {
      "command": "npx",
      "args": ["-y", "@intellmedia/basecoat-ui-mcp", "--project-root", "/absolute/path/to/your/application"]
    }
  }
}

Claude Code（CLI）

claude mcp add basecoat-ui -- npx -y @intellmedia/basecoat-ui-mcp --project-root $(pwd)

汎用 npx（インストール不要）

{
  "mcpServers": {
    "basecoat-ui": {
      "command": "npx",
      "args": ["-y", "@intellmedia/basecoat-ui-mcp", "--project-root", "/absolute/path/to/your/application"]
    }
  }
}

npm

npm install --global @intellmedia/basecoat-ui-mcp

サーバーを MCP クライアントに追加します。ホストアプリケーションには絶対パスを指定してください。そうすることで、デザインコンテキストと永続セッションが意図したプロジェクトに紐づきます。

{
  "mcpServers": {
    "basecoat-ui": {
      "command": "basecoat-ui-mcp",
      "args": ["--project-root", "/absolute/path/to/your/application"]
    }
  }
}

コンパイル済みのエントリーポイントを直接実行することもできます。

{
  "mcpServers": {
    "basecoat-ui": {
      "command": "node",
      "args": [
        "/absolute/path/to/node_modules/@intellmedia/basecoat-ui-mcp/dist/server/stdio.js",
        "--project-root",
        "/absolute/path/to/your/application"
      ]
    }
  }
}

公開パッケージには、ビルド済みの dist/ と、変更不可能なセマンティックスナップショットが src/semantics/ に含まれています。サーバーの起動時にはこのスナップショットが読み込まれ、インストール済みパッケージ内への書き込みは行われません。パッケージの契約テストでは、最初にビルドを行い、実際の npm tarball を作成して展開し、展開したパッケージツリーを読み取り専用に設定します。その後、ネットワークトリップワイヤーのもとで dist/server/stdio.js を起動し、MCP の初期化とツール一覧のリクエストを完了してから接続を閉じます。ソースのチェックアウトには dist/ は含まれません。

ソースから

git clone https://github.com/zygiu-zygis/basecoat-ui-mcp.git
cd basecoat-ui-mcp
npm ci
npm run build
npm start -- --project-root /absolute/path/to/your/application

--project-root は BASECOAT_PROJECT_ROOT より優先され、BASECOAT_PROJECT_ROOT は起動ディレクトリより優先されます。選択されるディレクトリはホストプロジェクトであり、MCP のインストールディレクトリではありません。サーバーが公開するのは stdio のみです。

プロジェクトルートの設定

設定されたルートは、次の 2 点を制御します。

• basecoat://project/context は、そのディレクトリから DESIGN.md を読み込みます。
• 永続的なマクロセッションは、<project-root>/.basecoat/designer/ に保存されます。
• .basecoat/rhythm.json は任意の厳格なオーバーライドです。プロジェクトルート内の実在する .basecoat ディレクトリに置き、65,536 UTF-8 バイト以下の通常ファイルで、シンボリックリンクではなく、解決後のパスがそのルート内にある必要があります。ファイルが存在しない場合や拒否された場合、パッケージに含まれるプロファイルは変更されません。一致するマッピング ID は既存の位置で置き換えられ、パッケージ内の順序が維持されます。

使用されるのは、この正確なディレクトリだけです。サーバーが親ディレクトリをたどることはありません。ホストプロジェクト内に .basecoat/ を保持し、デザインセッションがワークフローの一部である場合はバックアップしてください。MCP サーバーがホストアプリケーションのソースファイルに書き込むことはありません。

Basecoat MCP ツール

このサーバーは、プロジェクトのセットアップと設定、意図駆動型レイアウトのオーケストレーション、テーマ対応チャート、コンポーネントの取得、マクロデザイングラフ、セマンティック状態コントラクトという6つのアーキテクチャレイヤーに分類された、22個のオフライン MCP ツールを公開します。各ツールの結果は、最大 1,999 UTF-8 バイトの上限付き MCP パケットです。大きな結果セットではカーソルを使用し、レスポンスが JSON の途中で分割されることはありません。

MCP ツール一覧

ツール名	レイヤー	説明	モード
basecoat_setup_config	セットアップと設定	フレームワークのボイラープレート、Tailwind CSS 4 のインポート、OKLCH 変数、フラッシュのないダークモードスクリプトを生成します	読み取り専用
basecoat_page_architect	意図ファストパス	コンテナーグリッドのコントラクトと明示的なスロット構成を備えた、完全なレイアウトの骨組みを計画します	読み取り専用
basecoat_compose_stack	意図ファストパス	スロットのハイドレーションを用いて、合成可能なコンポーネントスタックを標準シェル（sidebar-01..16、topbar、inset、split）に組み立てます	読み取り専用
basecoat_rules_enforcer	意図ファストパス	Tailwind v4、FSM 状態コントラクト、セマンティックトークン、ダッシュボードルールにわたる技術的制約を適用します	読み取り専用
basecoat_creative_director	意図ファストパス	Kanso のミニマリズム、4px/8px の視覚的リズム、密度プロファイル、タイポグラフィの段階、コントラストの組み合わせを提示します	読み取り専用
basecoat_component_syntax	意図ファストパス	FSM の状態バリアントとインライン SVG アイコンを事前設定した、コピーして貼り付け可能な HTML/Astro コンポーネントマークアップを提供します	読み取り専用
basecoat_list_charts	チャートとデータビジュアライゼーション	7つのカテゴリにわたる、テーマ対応のチャートブループリント56個をキーワード検索で一覧表示および絞り込みます	読み取り専用
basecoat_get_chart_blueprint	チャートとデータビジュアライゼーション	セマンティック CSS トークン（--chart-1..5）と5つのフレームワーク向けマウントスクリプトを使用したチャート HTML を取得します	読み取り専用
basecoat_quality_inspector	品質と監査	HTML/Astro マークアップを監査し、スコア（0-100）、レターグレード、構文違反、a11y の欠落、自動修正の提案を返します	読み取り専用
search_components	コンポーネント	意図やクエリを使って、厳選された62個のコンポーネントから最大8件の簡潔なコンポーネント概要を検索します	読み取り専用
get_component_details	コンポーネント	Astro または HTML 用の最小限のコンポーネントテンプレート、依存関係、構成ガイダンスを取得します	読み取り専用
get_component_html	コンポーネント	厳選された任意のコンポーネントの HTML マークアップテンプレートと依存関係を取得します	読み取り専用
validate_composition	静的解析	最大256 KiBのマークアップを対象に、移行エラー、リズム、FSM バインディング、アクセシビリティを静的にチェックします	読み取り専用
validate_markup	静的解析	HTML/Astro マークアップの構文、構造、ランドマークの順序、セマンティック制約を検証します	読み取り専用
search_macro_blocks	マクログラフ	84個のブロックとエイリアスから、クエリ、役割、ファミリー、タグを使って承認済みのマクロレイアウトブロックを検索します	読み取り専用
get_macro_block	マクログラフ	コンパイル済みマクロブロックブループリントのセクション（マニフェスト、構造、スロット、ポート、ルールなど）を取得します	読み取り専用
begin_design	マクログラフ	プロファイルとレジストリのリビジョンを固定する、ハッシュ検証済みの永続的なデザインセッションを .basecoat/designer/ に作成します	変更（冪等）
get_design_context	マクログラフ	デザインセッションの絞り込まれたビュー（sessions、overview、decisions、graph、rules、focus、next）を読み取ります	読み取り専用
apply_design_patch	マクログラフ	expectedRevision と冪等な operationId を使用して、グラフへのアトミックな変更を適用します	変更（冪等）
validate_design	マクログラフ	ドラフトまたは完成したデザイングラフを検証し、診断の合計数とページ分割された問題一覧を返します	読み取り専用
get_rhythm_rules	セマンティクスとトークン	プロジェクトローカルのオーバーライドに対応し、適用されるセマンティックリズムプロファイルとファミリーごとに承認されたユーティリティを読み取ります	読み取り専用
get_fsm_recipe	セマンティクスと状態	有限状態マシンのインタラクション状態、イベント、遷移、ガード、アクションを読み取ります	読み取り専用

Intent-Driven Design Layer (Fast Path)

1. basecoat_setup_config - フレームワークとスタイルの設定ジェネレーターです。6 つのターゲット（astro、vanilla、nextjs、sveltekit、vite、htmx）、8 種類の美的スタイルパック（vega、nova、maia、lyra、mira、luma、sera、rhea）に対応するすぐに使えるボイラープレート、完全な OKLCH @theme inline ブロック、同期型の <head> インラインダークモードスクリプトを出力します。
2. basecoat_page_architect - intent、recipe、block によって、レシピ（src/macros/authoring/recipes/*.json）とマクロブロック（src/macros/authoring/blocks/*.json）を検索します。明示的な data-slot マーカー、セマンティック HTML スケルトン、グリッド構造、レスポンシブコンテナーを備えた、完全なレイアウトの骨組みを提供します。5 種類のダッシュボードページのアーキタイプをすべて網羅しています。
   • エグゼクティブダッシュボード（workspace-dashboard、executive-dashboard）- KPI 統計カード、収益チャート、最近のアクティビティ。
   • E コマース概要（ecommerce-overview）- 販売指標、収益分析、売れ筋商品カード、注文概要。
   • 分析ワークスペース（analytics-workspace）- フィルターツールバー、時系列インタラクティブチャート、コホート分析の内訳。
   • データテーブル詳細（workspace-detail、data-table-detail）- 検索／フィルター機能付きのページネーション対応データテーブルと、スライドオーバー式の詳細確認ドロワー。
   • 設定画面の分割レイアウト（workspace-settings、settings-split-screen）- 縦型セクションナビゲーションとフォームコントロールを備えた、2 列のレスポンシブレイアウト。 密度設定にも対応しています（高密度のエンタープライズツール向けの compact、標準的なインターフェース向けの comfortable）。
3. basecoat_compose_stack - 7 カテゴリー（shell-stacks、header-stacks、kpi-stacks、chart-stacks、table-stacks、overlay-stacks、form-stacks）にわたる、事前構築済みコンポーネントスタック 45 種類を、正規シェル（sidebar-01..sidebar-16、topbar-shell、inset-shell、split-shell）に動的に組み合わせ、自動スロット補完を行います。
4. basecoat_rules_enforcer - tailwind-v4、fsm-contracts、tokens、semantic-html、dashboard-patterns にわたる厳格な技術的制約を適用します。
   • MET-01：KPI の数値には text-2xl／text-3xl と tabular-nums、およびセマンティックなトレンド指標が必要です。
   • TBL-01：データテーブルには <div class="overflow-x-auto"> ラッパー、固定表示でぼかし効果のある <thead class="sticky top-0 bg-background/90 backdrop-blur">、右揃えの数値セルが必要です。
   • FRM-01：入力コントロールには、関連付けられた <label class="label" for="id"> を含む <div class="field"> ラッパーが必要です。
   • NAV-01：ヘッダーにはコンパクトな h-12 または h-14 を使用する必要があります（大きすぎる h-16 は禁止）。
   • TW4-01：非推奨の Tailwind v3 ユーティリティ（bg-opacity-*、flex-shrink-*、@tailwind ディレクティブ）を拒否します。
   • TOK-01：任意の角括弧付き寸法（w-[327px]）と、ハードコードされた 16 進カラー（#ff0000、bg-[#123456]）を拒否します。
   • FSM-01：インタラクティブなプリミティブ（dialog、dropdown-menu、accordion、tabs）に有限状態マシンの契約を適用します。
5. basecoat_creative_director - Kanso のミニマリズムと Basecoat のデザイン知見を提示します。
   • 密度プロファイル：compact（p-4 gap-4、ヘッダー h-12、テーブル py-2）、standard（p-6 gap-4/gap-6、ヘッダー h-14、テーブル py-3）、comfortable（p-6 md:p-8、ヘッダー h-14）。
   • 数学的な 4px／8px の視覚的リズムグリッドとタイポグラフィの階層（すべての指標と数値テーブルセルに tabular-nums を適用）。
   • border ユーティリティと競合しない、控えめな 1px のカードリングによる浮き上がり表現。
   • WCAG 2.1 AA（コントラスト >= 4.5:1）および APCA（$L_c \ge 60$）に準拠したトークンの組み合わせ。
6. basecoat_component_syntax - src/registry/components.json からコピーして使える HTML または Astro コンポーネントのマークアップを提供します。事前設定された FSM 状態バリアント（default、active、loading、disabled、open、closed、open/closed）、検証済みのインライン SVG アクションアイコン（plus、edit、trash、search、chevron-down、check、external-link）、複合コンポーネントのパターンも含まれます。
   • metric-card（metrics-summary、kpi-card）- tabular-nums の数値とトレンドバッジを備えた統計カード。
   • data-table（datatable）- overflow-x-auto でラップされた固定ヘッダー付きテーブル。数値セルは右揃えです。
   • sidebar-shell（sidebar-dashboard-shell）- デスクトップでは固定表示のナビゲーション、md 未満ではレスポンシブなフライアウト。
7. basecoat_quality_inspector - ダッシュボード監査ルールに照らして HTML／Astro の構成を監査します。対象ルールは table-overflow-wrapper、kpi-metric-tabular-nums、table-numeric-alignment、a11y-focus-ring（フォーカス時に見えるリングがない outline-none を検出）、任意カラー／寸法の違反、WCAG／APCA のコントラストの組み合わせです。score（0-100）、文字による grade（A-F）、構造化された問題、および実行可能な autoFixSuggestions を返します。

テーマに対応したチャートとデータの視覚化

8. basecoat_list_charts - 7 つのカテゴリ（area、bar、line、pie、radar、radial、tooltip）にわたる、テーマに対応した 56 個のチャートブループリントを検索し、キーワード search / query、レイアウト占有領域（layoutFootprint）、requiredTokens、バリアントの概要で絞り込みます。
9. basecoat_get_chart_blueprint - チャートコンテナーの HTML（chart-container、role="img"、アクセシブルなフォールバックとしての <table class="sr-only">、および bg-background/95 backdrop-blur-sm を使用したグラスモーフィズムのツールチップマークアップ）、CSS トークン（var(--chart-1) から var(--chart-5)、var(--color-border)、var(--color-muted-foreground)）、クライアントの options、layoutFootprint、5 つのフレームワーク（vanilla、astro、react、vue、svelte）向けのフレームワークマウントコードを取得します。オプションで themeTokens を上書きできます。chartId またはエイリアス id を指定できます（デフォルトは area-default）。dashboard-01 と svg-area-chart（data-chart-id="area-interactive"）に直接統合されています。node scripts/ingest-shadcn-charts.mjs によって決定論的に生成されます。

コンポーネントツール

• search_components は、厳選された 62 個のコンポーネントから最大 8 件の簡潔な {id, name, intent} 概要を返し、マークアップは返しません。intent と query は任意です。空の検索では空のリストが返されます。
• get_component_details は、依存関係と構成のガイダンスを含む Astro または HTML のテンプレートを 1 つ返します。サイズが大きすぎる項目は、安全のため処理を中止します。theme-toggle は theme-switcher に解決されます。
• get_component_html は、厳選された任意のコンポーネントの HTML マークアップテンプレートと依存関係を返します（environment のデフォルトは html です）。
• validate_composition は、最大 256 KiB（262,144 UTF-8 バイト）の HTML または Astro ソースを静的に検査し、最大 24 件の問題を返します（WCAG 2.1 / APCA トークンのコントラスト、任意の寸法、ダイアログのフォーカストラップ、aria-controls のバインディングなど）。code または html と、任意で semanticProfile または densityProfile（comfortable|compact）を渡します。レンダリングや実行、アプリケーションモジュールの解決は行わず、実行時のブラウザーアクセシビリティを保証するものでもありません。
• validate_markup は、Basecoat のガイドラインに照らして HTML/Astro ソースの構文、コンテナーのタグ、ランドマークの順序、セマンティック制約を静的に検証します。

マクロツール

マクロレイヤーは、シェル、認証フロー、データワークスペース、スロット、ポート、ルール、レシピを組み合わせる、このプロジェクト用にキュレーションされたプロジェクト固有のシステムです。固定されたレジストリスナップショットにコンパイルされます。これらのレイアウト契約は、shadcn や MCP によって自動的に提供されるものではありません。

1. search_macro_blocks - クエリ、ロール、ファミリー、タグを使って、84 個のブロックとエイリアスから互換性のあるブループリントブロックを検索します。
2. get_macro_block - manifest、structure、slots、ports、rules、dependencies、provenance などのブロックセクションを読み取ります。
3. begin_design - 永続的なデザインセッションを作成し、そのプロファイルとレジストリリビジョンを固定します。固定されたレジストリは読み込み時にハッシュ検証されます。
4. get_design_context - セッション一覧や、overview、graph、rules、focus、next などの絞り込んだビューを読み取ります。
5. apply_design_patch - expectedRevision と冪等性を持つ operationId を使って、アトミックなグラフ変更を適用します。確定した変更は必ず成功確認を返します。サイズの大きい任意のペイロードは truncated: true として省略される場合があります。
6. validate_design - ドラフトまたは完全なデザイングラフを検証し、診断結果をページごとに取得します。

デザインセッションは <project-root>/.basecoat/designer/ に保存されます。レジストリリビジョンはコンテンツアドレス方式で管理されます。パッケージのスナップショットが変更された後も、セッションは固定されたリビジョンを使用し続けます。デザインスナップショットの形式は d:<designId>@<revision> です。

キュレーション済みブロックブループリント（翻訳済みの shadcn/ui v4 ブロックを含む、84 個のブロックとエイリアス）：

• 標準シェルとサイドバー：sidebar-01 から sidebar-16、sidebar-dashboard-shell、sidebar-inset-shell、sidebar-collapsible-icon、sidebar-mobile-flyout、sidebar-nav、topbar-shell、topbar-nav、app-shell、page-header。
• ダッシュボードとワークスペース：dashboard-01 から dashboard-07、dashboard-workspace、dashboard-main、dashboard-activity、analytics、analytics-workspace、ecommerce-overview、tasks、tasks-table-workspace、mail、mail-workspace。
• 指標とデータテーブル：metrics-summary、data-table-rich、data-table、data-table-detail-layout、data-workspace、data-bulk-actions、data-filters、data-pager、products、billing、settings。
• フォームと認証：login-01 から login-05、signup-01 から signup-05、otp-01 から otp-05、form-field-group、forms、form-section、authentication、auth-sign-in、auth-sign-up、auth-split-screen、auth-recovery、auth-reset。
• チャートとフィードバック：svg-area-chart、empty-state、error-boundary、newsletter-waitlist、pricing-tiers、segmented-toggle、detail-drawer-panel、product-detail-layout、settings-workspace。

複数ブロックのレシピ（11 個のページレシピ）：

• workspace-dashboard - 完全な分析ダッシュボード（KPI カード、アクティビティチャート、レコードテーブル）。
• ecommerce-overview - 注文指標と商品ハイライトを備えた、E コマース運用ダッシュボード。
• analytics-workspace - 時系列チャートとコホートビューを備えた分析ダッシュボード。
• workspace-settings - ナビゲーション、ヘッダー、設定ワークスペースのタブを備えたアプリケーションシェル。
• workspace-detail / tasks-table-workspace - スライドオーバー式の詳細確認ドロワーを備えたデータテーブルワークスペース。
• mail-workspace - 受信トレイ一覧と詳細ビューを備えた複数ペインのメールクライアントレイアウト。
• auth-flow - サインインカードとサインアップカード間の双方向認証フロー。
• auth-split-flow - ヒーローメディアを使い、サインインとサインアップを組み合わせた分割画面の認証フレーム。
• data-records - フィルター、テーブル、ページャーを備えたレコードページ。
• marketing-pricing - 3 段階の価格表とニュースレター／ウェイトリストのバナーを組み合わせたもの。

セマンティックツール

セマンティックレイヤーでは、コンパイル済みのリズムプロファイルと有限状態機械のレシピを提供します。

1. get_rhythm_rules - プロファイルとファミリーのフィルターを指定して、承認済みの間隔、タイポグラフィ、サーフェス、境界線、レイアウトパターンにアクセスします。
2. get_fsm_recipe - dialog、navigation（collapsible-navigation）、auth-flow、tabs のインタラクション状態、イベント、遷移、ガード、アクションを読み取ります。

セマンティックツールでは、マクロツールと同じ上限付きページネーションを使用します。各リズムレコードでは、セマンティックトークン ID と承認済みの Tailwind ユーティリティを別々に保持します。ユーティリティは class に指定し、セマンティック ID はデザインメタデータとエージェントの推論で使用してください。<project-root>/.basecoat/rhythm.json のプロジェクトオーバーライドは、有効なコンテンツ参照とリビジョンに反映されます。FSM レシピは構造メタデータであり、ランタイム実装ではありません。

エンドツーエンドの例

ダッシュボードページでは、次の手順に従います。

get_design_context(view="sessions")
begin_design(designId="admin", profile="app-default", operationId="begin-admin")
get_rhythm_rules(profile="default", family="density")
search_macro_blocks(q="shell", limit=8)
apply_design_patch(
  designId="admin",
  expectedRevision=0,
  operationId="add-dashboard",
  operations=[{ op: "instantiate_recipe",
               recipe: "workspace-dashboard",
               pagePrefix: "admin" }]
)
get_design_context(view="overview", designId="admin")
get_macro_block(idOrRef="app-shell", section="structure", designId="admin")
get_fsm_recipe(recipe="dialog", section="transitions")

選択したコンポーネントリーフをホストプロジェクトに実装し、apply_design_patch(record_written) で完了した領域を記録します。生成した Astro または HTML ソースに対して validate_design(mode="complete") と validate_composition を実行して完了します。競合または再起動の後は、セッションを再読み込みし、返されたリビジョンとカーソルを使用してください。

エージェント向けガイダンスとして、templates/cursor/basecoat-designer.mdc をホストプロジェクトの .cursor/rules にコピーします。MCP サーバーは、利用側アプリケーションのソースファイルを書き込みません。

既存の UI の監査またはスタイル変更

デザインセッションは必要ありません。basecoat://design/theming と basecoat://design/rhythm を読み込み、変更する各コントロールについて get_component_details を呼び出してから、<head> のスクリプトと <style> を含むレンダリング済みレイアウトソースに対して validate_composition を実行します。テーマのルールは次のとおりです。

• theme-strategy-mixed - @media (prefers-color-scheme: dark) と .dark クラスの戦略を組み合わせると、ダークトークンがライトモードに漏れます。
• theme-storage-key - テーマスクリプトが Basecoat の themeMode 以外のキーにテーマを保存すると、window.basecoat.theme と異なる第 2 のリゾルバーが作成されます。

デプロイ前に、OS のダーク設定を有効にし、空の localStorage を使用してライトモードとダークモードのスクリーンショットを確認してください。

ソースの適応とオフラインインポート

マクロインポーターは、ローカル優先となるよう意図的に設計されています。チェックアウト済み、またはその他の方法でローカルに保存した shadcn スタイルの registry-item.json、レビュー済みのマッピング、ローカルの依存関係ロックを受け付けます。

npm run import:blocks -- \
  --item=/path/to/registry-item.json \
  --mapping=/path/to/mapping.json \
  --lock=/path/to/dependency-lock.json \
  --dry-run

このコマンドは、shadcn のレジストリアイテムをオンラインから取得したり、パッケージをインストールしたり、アップストリームコードを実行したり、ランタイムのネットワークリクエストを行ったりしません。不明、ロックされていない、または明示的にサポート対象外の依存関係については、推測ではなく診断情報を出力します。省略された OAuth、captcha、セッション、認証情報、その他のアプリケーション機能は、対応が必要な項目として報告されます。インポーターが出力するのは、キュレーションされた構造ブロックのみです。ランタイムの動作はホストアプリケーションで実装する必要があります。

マッピングとそこから得られる来歴情報により、境界が明確になります。shadcn スタイルのソースは入力リファレンスであり、レイアウトコントラクト、スロット、ポート、ルール、レシピは、このプロジェクトのマクロレイヤーが所有するキュレーション済みの適応物です。これらは shadcn または MCP が提供する機能ではありません。アップストリームの更新は、メンテナーによる別個の作成作業であり、MCP サーバーから実行されることはありません。

Basecoat MCP リソース

サーバーは、3 本柱の Skill Vault、コアデザインシステムのコントラクト、複数フレームワーク向けの統合ガイド、ライブのホストプロジェクトコンテキストを網羅する8 つの権威ある MCP リソースを公開します。

MCP リソース一覧

リソース URI	カテゴリ	説明	MIME タイプ
basecoat://skills/core	スキル保管庫	Basecoat UI の中核となるデザイン哲学、Kanso のミニマリズム、基礎的なコンポーネントの使い方	text/markdown
basecoat://skills/dashboard	スキル保管庫	ダッシュボードの包括的なアーキテクチャ、レイアウトパターン、ページの種類、サイドバーの設定、監査チェックリスト	text/markdown
basecoat://skills/charts	スキル保管庫	テーマ対応のチャート設計図、CSS トークンのマッピング（--chart-1..5）、ApexCharts の設定、複数フレームワークとの統合	text/markdown
basecoat://skills/files/*	スキル保管庫	96 ファイルからなるスキル保管庫全体の個別のドキュメントやリファレンス Markdown ファイルを読み込む動的ファイルアクセスリソース	text/markdown
basecoat://design/rhythm	デザインシステム	コンテンツ階層、4px/8px の視覚的なスペーシングリズム、タイポグラフィの段階、密度プロファイル、構造的な構成ルール	text/markdown
basecoat://design/theming	テーマ設定とダークモード	Basecoat の OKLCH トークン仕様、8 種類の公式スタイルパック（Vega..Rhea）、クラスベースのダークモード（themeMode リゾルバー）、フラッシュ防止の初期化処理	text/markdown
basecoat://integration/frameworks	統合ガイド	Astro、Next.js、Express、Vite、Tailwind CSS 4 の設定、およびフレームワークに依存しない HTML を網羅した本番環境向け統合ガイド	text/markdown
basecoat://project/context	プロジェクトのコンテキスト	ホストプロジェクトの DESIGN.md をオンデマンドで読み込みます（上限は 6,000 UTF-8 バイト）	application/json

• basecoat://skills/core は、デザイン哲学、アトミックなスタイリングの原則、コンポーネントの構築など、Basecoat CSS を使用してクリーンでミニマルなインターフェースを構築するための基礎的なガイドラインを提供します。
• basecoat://skills/dashboard は、エンタープライズ向けダッシュボードのアーキテクチャ、ナビゲーションパターン、データ表示の規則、フォームのレイアウト、アクセシビリティのチェックリストを提供します。
• basecoat://skills/charts は、5 種類のフレームワークにわたる、純粋な Basecoat CSS カラートークン（var(--chart-1) から var(--chart-5)）を使用した、テーマ対応の ApexCharts と SVG データビジュアライゼーションに関する包括的なガイダンスを提供します。
• basecoat://skills/files/* を使うと、96 ファイルからなるスキル保管庫（skills/basecoat、skills/basecoat-dashboard、skills/basecoat-charts）内の任意の Markdown ファイルを動的に検索して取得できます。
• basecoat://design/rhythm は、コンテンツ階層、スペーシング、タイポグラフィ、コンポーネントファミリー、構造的な構成に関するルールを提供します。
• basecoat://design/theming は、Basecoat のトークン仕様、8 種類すべての公式スタイルパック（Vega、Nova、Maia、Lyra、Mira、Luma、Sera、Rhea）、window.basecoat.theme（themeMode キー）によるクラスベースのダークモード、フラッシュ防止の初期化処理、フォームコントロールとオートフィルに関する注意点を提供します。既存の UI のスタイルを変更または監査する前にお読みください。
• basecoat://integration/frameworks は、Astro、Next.js、Express、Vite、Tailwind CSS 4（@import "basecoat-css/vega"; のようなスタイルパックのインポートを含む）、Basecoat の JavaScript の選択的な読み込み、ネイティブダイアログの設定に関する情報を提供します。
• basecoat://project/context は、設定されたホストプロジェクトの DESIGN.md をオンデマンドで読み込みます。出力は 6,000 UTF-8 バイト が上限で、可能な場合は改行または文の区切りで切り詰められます。シンボリックリンクと通常ファイル以外は拒否されます。

推奨フロー：

1. リズムとプロジェクトコンテキストのリソースを読み込みます。
2. コンテンツ階層とレイアウトを決定します。
3. 概要を検索し、選択したコンポーネントの詳細のみをリクエストします。
4. 本番環境のアセットを接続する際は、統合リソースを読み込みます。
5. 最終的なソースを検証します。

最小限の HTML の例

ホストアプリケーションから、コンパイル済みの Tailwind と Basecoat のスタイルシートが提供されます。

<link rel="stylesheet" href="/assets/basecoat.css">
<button type="button" class="btn" data-variant="default">Save changes</button>

ヘッダーコントロールのグループ（スタイルプリセットのセレクター + テーマ切り替え）

<div class="flex items-center gap-2">
  <select id="style-variant-select" class="select h-8 w-28 text-sm leading-none" aria-label="Style pack">
    <option value="vega">Vega</option>
    <option value="nova">Nova</option>
    <option value="maia">Maia</option>
    <option value="lyra">Lyra</option>
    <option value="mira">Mira</option>
    <option value="luma">Luma</option>
    <option value="sera">Sera</option>
    <option value="rhea">Rhea</option>
  </select>
  <button type="button" aria-label="Toggle dark mode" data-tooltip="Toggle dark mode" data-side="bottom" onclick="window.basecoat.theme.toggle()" class="btn size-8" data-variant="outline" data-size="icon">
    <span class="hidden dark:block" aria-hidden="true"><svg class="lucide lucide-sun size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="4"/><path d="M12 2v2m0 16v2m-7.07-2.93 1.41-1.41m11.32-11.32 1.41-1.41M2 12h2m16 0h2m-2.93 7.07-1.41-1.41M6.34 6.34 4.93 4.93"/></svg></span>
    <span class="block dark:hidden" aria-hidden="true"><svg class="lucide lucide-moon size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20.985 12.486a9 9 0 1 1-9.473-9.472c.405-.022.617.46.402.803a6 6 0 0 0 8.268 8.268c.344-.215.825-.004.803.401"/></svg></span>
  </button>
</div>

Basecoat 1.x では、btn と data-variant、data-size を使用します。インタラクティブなコンポーネントには、ホスト側で読み込む必要がある細分化された JavaScript モジュールが一覧表示されます。

マクロ駆動のダッシュボード生成

MCP サーバーは、接続された LLM が複雑なレイアウト（Shadcn ダッシュボードなど）をすぐに、予測可能な方法で組み立てられるようにする、堅牢なマクロレイアウト一式（search_macro_blocks）を提供します。

• レイアウトの柔軟性：サイドバー（sidebar-dashboard-shell、sidebar-inset-shell）とトップバーアーキテクチャ（topbar-shell、topbar-nav）の両方をサポートします。
• 厳格な検証：validate_composition ツールにより、生成されたレイアウトが Basecoat CSS のテーマ設定コントラクト、厳格な間隔リズムのスケール（0、2、4、6、8、12）、および適切なランドマークアクセシビリティに準拠していることを確認します。
• エージェントへのガイダンス：LLM は search_macro_blocks を使用して shell（レイアウトラッパー）を見つけ、dashboard-main または dashboard-workspace で main コンテナーを埋めることが推奨されています。これにより、React のランタイム成果物を含まない、決定論的でピクセル単位まで忠実な Shadcn/ui のパロディが実現します。

レジストリと除外項目

チェックイン済みのレジストリには、厳選された62 個のコンポーネントが含まれています。React を使用せず、純粋な Basecoat CSS 向けに適合させた shadcn/ui New York v4 のプリミティブ全 57 個に、明示的な FSM 状態コントラクトを備えた Basecoat 拡張機能（theme-switcher、segmented-toggle、svg-area-chart、native-select）を加えたものです。

accordion、alert、alert-dialog、aspect-ratio、avatar、badge、breadcrumb、button、button-group、calendar、card、carousel、chart、checkbox、collapsible、combobox、command、context-menu、data-table、date-picker、dialog、drawer、dropdown-menu、empty、field、form、hover-card、input、input-group、input-otp、item、kbd、label、menubar、native-select、navigation-menu、pagination、popover、progress、radio-group、resizable、scroll-area、segmented-toggle、select、separator、sheet、sidebar、skeleton、slider、sonner、spinner、svg-area-chart、switch、table、tabs、textarea、theme-switcher、toast、toggle、toggle-group、tooltip

カタログの総数

• 厳選コンポーネント 62 個：shadcn/ui の new-york-v4 プリミティブ 57 個すべてに加え、検証済みの HTML/Astro マークアップテンプレート、React のバンドル要件なし、有限状態マシン（FSM）コントラクトを備えた Basecoat 拡張機能です。
• マクロブロックとエイリアス 84 個：sidebar-01..16、dashboard-01..07、login-01..05、signup-01..05、otp-01..05、mail、tasks、forms、products、analytics、billing、settings を網羅したレイアウトの設計図です。
• ページレシピ 11 個：複数ページにまたがるエンドツーエンドのレイアウトグラフ（workspace-dashboard、ecommerce-overview、analytics-workspace、workspace-settings、workspace-detail、tasks-table-workspace、mail-workspace、auth-flow、auth-split-flow、data-records、marketing-pricing）です。
• 合成可能なコンポーネントスタック 45 個：7 カテゴリ（shell-stacks、header-stacks、kpi-stacks、chart-stacks、table-stacks、overlay-stacks、form-stacks）にわたる合成可能なスタックで、正規シェルへのスロットハイドレーションに対応しています。
• テーマ対応のチャート設計図 56 個：7 カテゴリ（area、bar、line、pie、radar、radial、tooltip）にわたるビジュアライゼーションで、CSS トークン（var(--chart-1) から var(--chart-5)）にマッピングされ、5 つのフレームワーク（vanilla、astro、react、vue、svelte）向けのマウントに対応しています。
• 3 本柱のスキルボルトに含まれる Markdown ファイル 96 個：skills/basecoat（コアの基礎知識と 57 個のコンポーネントガイド）、skills/basecoat-dashboard（ダッシュボードのアーキテクチャ、ブロックパターン、監査チェックリスト）、skills/basecoat-charts（ApexCharts の設計図とトークンマッピング）に分散しています。

メンテナンススナップショットには、上流で検出されたコンポーネント 41 個が記録されています。現在、shadcn/ui のプリミティブ 57 個すべてにテンプレート、依存関係、状態コントラクトを付けて厳選しています。Slider は slider モジュールではなく、basecoat-css/range を使用します。

ランタイムには、ネットワーククライアント、リモートドキュメントへの依存関係、フロントエンドフレームワークのランタイム、リモートメディア分析、バンドル済みホストアセットはありません。生成されるテンプレートでは basecoat-css/all を使用できません。各コントローラーは明示的にインポートします。検索結果にマークアップは含まれず、新たに検出されたコンポーネントが自動的に昇格されることはありません。また、JSON や HTML をレスポンスの予算に合わせて切り詰めることもありません。

Astro と静的 HTML のユースケース

Astro では、Vite、Tailwind CSS 4、CSS の順序、コントローラーの選択的インポート、ネイティブな <dialog> の接続、ClientRouter フックに対応する integration リソースを使用します。静的 HTML では、一覧に記載されたビルド済みコントローラーファイルを basecoat-css からホストアプリケーションのアセットディレクトリにコピーし、依存関係の順序を維持してください。チャートテンプレートには、ホストから提供される Chart.js が必要です。

メンテナーが固定された Basecoat スナップショットを更新できるのは、明示的な不変のコミットソースを指定する場合に限られます。 例：npm run sync -- --ref <40-character-commit-sha> これは HTTPS を使用する唯一のコマンドです。このコマンドはレジストリを変更する前に、スキーマ、エクスポート、通知、レスポンスの予算、バージョンの方向性、アトミックな置き換えを検証します。 shadcn のマッピングやマクロブロックは更新しません。

開発と検証

npm ci で依存関係をインストールし、対象を絞ったチェックを実行します。

npm run check
npm pack --dry-run
npm audit --omit=dev

npm run check は型チェック、コンパイル済みの両方のスナップショットの検証、ビルドと Node テストスイートの実行、ブランチ差分の空白エラーのチェックを行います。テストスイートでは、パッケージ化された読み取り専用 MCP bin もオフラインでテストします。npm pack --dry-run は、tarball を残さずにパッケージのファイル許可リストを確認します。 npm audit --omit=dev は、npm アドバイザリデータベースを使って本番依存関係をチェックするため、ネットワークアクセスが必要です。メンテナーは、次のコマンドで固定された Basecoat ソースを検証できます。

リリース時の整合性を示す証拠を得るため、承認済みの公開の前後にローカルのみで実行されるルーチンを実行してください。

npm run release:check -- --phase=pre-release --write=tmp/release-pre.json
npm run release:check -- --phase=post-release --write=tmp/release-post.json

このルーチンは、現在のリポジトリメタデータから対象範囲を検出し、ローカルの権威ある値を比較して、current、expected、correction、status、verification を記録します。パッケージの識別情報、サーバーマニフェストの整合性、stdio トランスポート、公開する機能、インストールメタデータ、節度ある見つけやすさのための文言を確認します。ネットワークリクエストや外部への書き込みは一切行いません。GitHub、npm、MCP Registry、およびディレクトリやカタログの修正は、明示的に承認された手動の作業として扱われます。バッジ、ダウンロード数、上流への参照、検索結果のスニペットを、リリースの根拠として扱わないでください。

npm run sync -- --ref <40-character-commit-sha> --check

同期コマンドだけがネットワーク境界です。マクロ作成に関する変更には npm run compile:blocks が必要です。生成された src/macros/registry.snapshot.json を確認してから、npm run compile:blocks:check を実行してください。

貢献

1. デフォルトブランチから、対象を絞ったブランチを作成します。
2. コンポーネントのテンプレート、マクロの契約、ドキュメントを、チェックイン済みのソースと整合させます。
3. npm run typecheck、npm run compile:semantics:check、npm run compile:blocks:check、npm run test を実行します。
4. パッケージの内容またはメタデータを変更する場合は、npm pack --dry-run を実行します。
5. プルリクエストには、動作の変更、出力上限への影響、ホストアプリケーション側で必要な作業を記載します。

GitHub Actions ワークフローを追加しないでください。上流レジストリの更新やマクロの作成はメンテナーによるレビュー対象であり、サーバーの起動時に行う作業ではありません。

トラブルシューティング

• サーバーは起動するが、間違ったプロジェクトを読み込む： 絶対パスの --project-root または BASECOAT_PROJECT_ROOT を設定してください。設定がない場合は、プロセスの起動ディレクトリが使われます。
• DESIGN.md を利用できない： 設定したルートに通常のファイルを配置してください。親ディレクトリやシンボリックリンクはたどりません。
• ソースのチェックアウトから起動できない： npm start の前に npm run build を実行してください。
• マクロの結果にカーソルが含まれる： そのカーソルを使って次のページをリクエストしてください。部分的な JSON を連結したり、解析したりしないでください。レジストリ、デザイン、または有効なリズムのリビジョンが変更されると、以前のカーソルは無効になります。
• 適用の確認応答に truncated: true が含まれる： 変更はコミット済みです。省略された詳細については、コンテキストまたは検証ツールを再度読み込んでください。
• インポーターの診断に OAuth、captcha、または未対応の依存関係が記載されている： ホストアプリケーションまたはレビュー済みのマッピングで実装するか、解決してください。インポーターは実行時の動作を推測しません。
• デザインのパッチが競合する： get_design_context を再読み込みして現在のリビジョンを使い、新しい一意の operationId を送信してください。

実行時の境界、永続化、パケット制限、同期ポリシーについては、ARCHITECTURE.md を参照してください。再現可能な不具合は課題トラッカーで報告してください。

作成者、ライセンス、上流への帰属表示

MIT License の下、Žygimantas Jasiulionis / Intellmedia が作成・保守しています。

Basecoat UI は、Ronan Berder による独立した MIT ライセンスのプロジェクトです。改変したテンプレートとメタデータには、THIRD_PARTY_NOTICES.md に記載されている Basecoat の完全な通知が残されています。Basecoat は shadcn/ui のデザインパターンを取り入れており、通知にはその帰属表示も含まれています。Basecoat の CSS や shadcn のソースは、ここに同梱されていません。