104はじめる
← ブログ

Claude Code と Cursor が本当に使える shadcn/ui レジストリの作り方

2026 年、shadcn レジストリは仕事の半分にすぎません。ネームスペース、.md URL の Markdown ドキュメント、llms.txt、MCP サーバー、プライベートレジストリで、AI エージェントが正しくインストールできるようにします。

Preet Suthar · · 5分で読めます

  • shadcn/ui
  • AI
  • React
  • Developer tools

いまや shadcn/ui コンポーネントの多くは、人がコマンドを打つのではなく、AI コーディングエージェントによってインストールされています。レジストリを公開するなら、エージェントがあなたのユーザーです。エージェントはコンポーネントを見つけ、props を推測せずに読み、正しいインストールコマンドを実行する必要があります。ドキュメントサイトをクリックして回る人間にしか使えないレジストリは、誤用されるレジストリです。

私は shadcn/ui レジストリの HextaUI を運営していて、今年のかなりの時間を Claude Code、Cursor、shadcn の MCP サーバーで動くようにすることに使いました。結果として重要だったことのすべてを、もう一度やるならこの順で、という順番で書きます。

1. バリデーションを通るレジストリを公開する

基本から始めます。各アイテムはレジストリスキーマに従った JSON ファイルで、name、type、files、dependencies、registryDependencies を持ちます。インデックスは安定した URL に、各アイテムは予測できる URL に置きます:

https://your-site.com/r/registry.json
https://your-site.com/r/button.json
https://your-site.com/r/all.json

registry.json のソースから shadcn build で生成し、デプロイ前にバリデーションしてください。CLI には 2026 年 5 月にレジストリの validate ステップが加わりました。バリデーションに通らないレジストリは、エージェントにとっては何も言わずに失敗し、エージェントはコンポーネントを手で書いて間違えます。

大きな差を生む細部が二つあります:

  • registryDependencies には完全な URL を書く。 自分の Dialog が自分の Button に依存するなら、button ではなく https://your-site.com/r/button.json を指定してください。そうしないと CLI は shadcn/ui の Button を取ってきます。
  • すべてに依存する all.json アイテム。「デザインシステムをセットアップして」と頼まれたエージェントはこれに手を伸ばします。

2. ネームスペースを登録する

レジストリのネームスペース機能が入ってからは、ユーザーは components.json にこれを追加します:

{
  "registries": {
    "@hextaui": "https://hextaui.com/r/{name}.json"
  }
}

その後は短い名前でインストールします:

npx shadcn@latest add @hextaui/dialog

このスニペットをインストールページと llms.txt に載せてください。shadcn の MCP サーバーが検索するのはこの短い形式なので、ネームスペースのないレジストリは、ほとんどのエージェントがレジストリを閲覧するのに使うそのツールからは見えません。

レジストリがプライベートなら、オブジェクト形式で環境変数を使ったヘッダーを指定できます。CLI はこれを展開し、ログには残しません:

{
  "registries": {
    "@acme-pro": {
      "url": "https://acme.com/r/pro/{name}.json",
      "headers": {
        "Authorization": "Bearer ${ACME_TOKEN}"
      }
    }
  }
}

3. すべてのドキュメントページに Markdown 版を用意する

エージェントは HTML の取得が苦手で、Markdown の取得は得意です。すべてのドキュメント URL が .md で同じ内容を返すようにしてください。説明、インストールコマンド、完全なソース、使い方、サンプル、キーボード対応、API テーブルです。

https://hextaui.com/docs/button      -> HTML for people
https://hextaui.com/docs/button.md   -> Markdown for agents

Markdown を手書きしないでください。ページと同じソースから生成して、両者がずれないようにします。HextaUI では .md ルートがページの React ツリーをたどってシリアライズするので、ページにサンプルを追加すれば Markdown にも自動で追加されます。

ここで最も重要なのは API リファレンスです。props テーブルを読めるエージェントは、存在しない size="xl" を捏造しません。

4. llms.txt と llms-full.txt を公開する

llms.txt はサイトのルートに置く Markdown のインデックスです。プロジェクトが何か、いつ使うか、いつ使わないか、インストール方法、そしてドキュメントページごとに .md へのリンクを一行ずつ書きます。llms-full.txt は全ドキュメントページを連結したもので、一度にすべて読み込みたいエージェント向けです。

「使うべきでない場面」のセクションは、みんなが飛ばす部分であり、サポートの問い合わせを減らしてくれる部分でもあります。レジストリが React と Tailwind 専用なら、そう書いてください。でないとエージェントは Vue プロジェクトにインストールしようとします。

インストールコマンドは最初の 10 行以内に置いてください。エージェントは先頭を読みます。

5. 読み取り専用・キー不要の MCP サーバーを動かす

shadcn CLI には独自の MCP サーバー(npx shadcn@latest mcp)があり、components.json にあるどのレジストリも検索できます。これでインストールはカバーされます。ドキュメント、キーボード操作の一覧、サンプルはカバーされません。

そこで私は https://hextaui.com/mcp でもう一つ動かしています。Streamable HTTP、読み取り専用、API キー不要で、ツールは search_docs、get_component、get_component_api、get_examples、get_install_command の五つです。Claude Code からは一行でつながります:

claude mcp add --transport http hextaui https://hextaui.com/mcp

Cursor と VS Code も MCP の設定で同じ URL を受け付けます。つながってしまえば、「非同期の結果を持つ HextaUI の combobox を追加して」という依頼が、ドキュメント検索、API の読み取り、正しいインストールコマンドへと変わり、その間に推測は入りません。

見つけやすくもしておきましょう。/.well-known/mcp/server-card.json にサーバーカードを、MCP レジストリ形式の server.json を公開します。エージェントとその周辺ツールは、まずそこを見るようになってきています。

6. HTTP の表面を OpenAPI と実のあるエラーで記述する

上記はすべて素の HTTP でもあり、エージェントは HTTP を直接呼ぶことが増えています。operation id と型付きレスポンスを持つ openapi.json を公開してください。エラーは RFC 9457 の application/problem+json で返し、次に何をすべきかを示す resolution フィールドを付けます:

{
  "type": "https://hextaui.com/docs/api#not-found",
  "title": "Component not found",
  "status": 404,
  "detail": "No component named 'modal'.",
  "resolution": "Try 'dialog' or 'alert-dialog'. The catalog is at /mcp/index.json."
}

ヒント付きの 404 を受け取ったエージェントは立て直せます。HTML のエラーページを受け取ったエージェントは、記憶を頼りにコンポーネントを書きます。

7. スキルファイルを公開する

Claude Code をはじめ、増え続けるエージェントたちは、ツールの使い方を説明する SKILL.md ファイルを読みます。/.well-known/agent-skills/<name>/SKILL.md に一つ置いてください。コンポーネントの探し方、ドキュメントの読み方、インストールの仕方を、正確なコマンド付きで書きます。Markdown 一ページですが、サイトの中で最もレバレッジの効くページです。

8. 自分ではなくエージェントでテストする

MCP サーバーだけをつなぎ、他のコンテキストは何もない状態で、Claude Code でまっさらな Next.js プロジェクトを開きます。「<your registry> から、範囲選択と週末を無効にするルール付きの date picker を追加して」と頼んでください。何をするかを観察します。間違った推測はどれも、.md ドキュメントか llms.txt の穴です。

次に、MCP なしで llms.txt だけを与えて Cursor で同じことをします。その次は URL だけで。レジストリはこの三段階を通して、なだらかに劣化するべきです。

これで得られるもの

MCP サーバーか .md ドキュメントにつながったエージェントは、props テーブルを推測せずに読み、コンポーネントを書き直さずにインストールコマンドを実行し、依存関係を正しい順序でインストールします。HextaUI のレジストリ側は 1 週間ほどの作業でした。エージェント側はもっと長くかかりましたが、いまインストールの大半を担っている相手にとってレジストリを使えるものにしたのはこちらの部分です。

実際に動いているものをすべて見たい場合は、hextaui.com/llms.txt、任意のドキュメントページに .md を付けたもの、MCP のドキュメント、そして OpenAPI 仕様付きの API ドキュメント をどうぞ。

よくある質問

shadcn CLI に MCP サーバーがあるのに、自前の MCP サーバーは必要ですか? shadcn の MCP は components.json に登録されたレジストリ横断の検索とインストールを担います。自前のサーバーはドキュメント、API、サンプルを担います。ほとんどのレジストリは両方あったほうが得をします。

MCP サーバーに API キーを要求すべきですか? 公開ドキュメントには不要です。キーを要求するたびに、諦めるエージェントが一つ増えます。認証はプライベートなアイテムに限り、components.json のヘッダー経由でベアラートークンを使ってください。

内容を重複させずに Markdown ドキュメントを生成するには? ページが使っているのと同じコンポーネントツリーをレンダリングし、Markdown にシリアライズします。ソースは一つ、フォーマットは二つです。

llms.txt には何を書きますか? 説明、使うべき場面と使うべきでない場面、インストールコマンド、ネームスペースのスニペット、そしてドキュメントページごとに .md へのリンクを一行ずつです。

関連記事