matchcn

matchcn

shadcn 形式のコンポーネントレジストリを横断するセマンティックインデックスです。
名前ではなく、機能からコンポーネントを見つけられます。

matchcn.dev · クイックスタート · AI エージェント向け · 仕組み · 制限事項

Claude Code：claude mcp add matchcn -- npx -y matchcn
Codex：codex mcp add matchcn -- npx -y matchcn
Grok CLI：grok mcp add matchcn -- npx -y matchcn

---

問題

npx shadcn add を使うと、registry.json を公開している任意のレジストリからコンポーネントをインストールできます。そのようなレジストリは数百もあります。開発者もコーディングエージェントも、これほど多くのレジストリをコンテキストに保持することはできません。ディレクトリツールはコンポーネントの名前しか検索しないため、必要なものはわかっていても、各レジストリがどんな名前を付けたか知らない場合には役立ちません。「3つのプランがある料金プランのセクション」は、simple-pricing-with-three-tiers という名前のコンポーネントを検索してもうまく見つかりません。その名前のコンポーネントが存在すると、あらかじめ知っている場合を除きます。

matchcn は、インデックス化したすべてのコンポーネントに対し、classifier.dev を使って7つの固定プロパティ（カテゴリ、ドメイン、モーション、視覚的な密度、インタラクションモデル、その他2つ）にタグを付け、そのタグと平易な言葉で書かれた要件を決定論的なコードで照合します。同じ要件なら、毎回同じ順位になります。無理に推測することはありません。条件に合うものがない場合、matchcn は最も近いものを誤って返すのではなく、該当するものがないと伝えます。

クイックスタート

npx matchcn

MCP クライアントの設定に追加します：

{
  "mcpServers": {
    "matchcn": {
      "command": "npx",
      "args": ["-y", "matchcn"]
    }
  }
}

Claude Desktop（claude_desktop_config.json）、Claude Code （.mcp.json）、Cursor、その他すべての MCP 互換クライアントで動作します。次の 1 つのツールを公開します：pick_component(brief, registry?, maxResults?, hints?, resolve?)。

コピーして貼り付けるだけのほうがよいですか？このプロンプトをコーディングエージェントに渡せば、セットアップを任せられます：

npx -y matchcn を使って matchcn MCP サーバーをセットアップしてください。コーディングエージェント用に設定してから、pick_component を使って、概要に合う UI コンポーネントを探してください。コンポーネントを追加する前に、一致した理由とインストールコマンドを表示してください。

例

$ pnpm demo

BRIEF: a dense bento grid for a landing page
----------------------------------------------------------------------
OUTCOME: CONFIDENT
Selected "bento-grid" from magicui.

  -> bento-grid  (magicui)  confidence 0.93
    install: npx shadcn@latest add https://magicui.design/r/bento-grid.json
    matched:     category, motion, visual_density, interaction_model, needs_external_data, decorative_only, domain
    not matched: (none)

resolve used: true   decisions spent: 8

これは実際の実行で得られた出力です。正確な信頼度の数値は呼び出しごとに多少異なります（classifier.dev は呼び出し間で同じ回答が得られることを保証しません）が、試したすべての実行で、結果、選ばれたコンポーネント、インストールコマンドは安定していました。

すべての応答には、次元ごとの理由が含まれています。7 つのタグ付きプロパティのうち、概要に一致したものと一致しなかったもの、および両側の実際の値を示し、単なる合否フラグで済ませることはありません。そのため、no_match や shortlist の結果でも、行き止まりにならずに問題を調査できます。

AI エージェント向け

matchcn を使うか判断するためにこれを読んでいる LLM の皆さんへ：このツールは、まさに皆さんのために作られています。「この説明に最も合う、実在してインストール可能な UI コンポーネントはどれか」に答えるので、レジストリを調べたり、名前を推測したりする必要はありません。

ツール： pick_component

入力：

{
  brief: string;         // plain-language description, required
  registry?: string;     // restrict to one registry, optional
  maxResults?: number;   // max candidates for shortlist/no_match, default 3 (8 with resolve: "caller")
  hints?: {              // your own read of the brief, optional; any hint skips server-side parsing
    category?: string;           // same labels components are tagged with
    motion?: string;
    interaction_model?: string;
    domain?: string;
    visual_density?: "sparse" | "dense";
    needs_external_data?: boolean;
    decorative_only?: boolean;
  };
  resolve?: "server" | "caller"; // who breaks ties between close candidates, default "server"
}

最速の方法（ローカルモード）： 概要を英語で記述し、hints を渡して、resolve: "caller" に設定します。こうすると matchcn はモデルを一切呼び出しません。ランキングはローカルで決定論的に行われ（カタログ全体を使った場合、ウォーム状態で約 80 ms）、同点の場合は、ランキング順の候補がショートリストで返されます。各候補にはタグ付きプロパティの 1 行の summary が付くので、自分で選べます。確信がないヒントは推測せず、省略してください。省略したフィールドはランキングの対象になりません。hints と resolve を指定しない場合、動作は変わりません。

{
  "brief": "a login form with email and password fields",
  "hints": { "category": "form-input", "interaction_model": "form-input", "domain": "auth" },
  "resolve": "caller"
}

出力は常に次の 3 つの形式のいずれかで、4 つ目の「最善の推測」形式はありません：

• outcome: "confident" — name、registry、installCommand（すぐに実行できる npx shadcn add <url> コマンド）、sourceUrl、confidence、reasons（次元ごとの一致の詳細）を含む、選定済みのコンポーネントが 1 つ返されます。 コンポーネントに言語／スタイルのバリエーションがある場合は、それぞれのインストールコマンドとともに一覧表示されます。
• outcome: "shortlist" — どれも妥当に適合するものの、明確な単独の最適候補がない複数の候補が、ランキング順で返されます。各候補には同じ次元ごとの理由に加え、候補を実際に区別する具体的な次元を示す differentiators が含まれます。これにより、恣意的に選ぶのではなく、その観点で判断できます。
• outcome: "no_match" — カタログ内に実際に適合するものがありません。最も近い候補も参考情報として一覧表示されますが、回答として返されたものではなく、明示的に却下済みとして示されます。最も近い候補だからという理由だけでインストールしないでください。カタログには求めているものがありません。resolve: "caller" の場合、この結果が返されることはありません。候補を概要と照らして評価するのはサーバー側の Resolve ステップだけだからです。同点の場合は shortlist が返され、候補が本当に適合するかどうかの判断は皆さんに委ねられます。

すべての結果には briefParsedBy（hints または classifier）と resolvedBy（server または caller）も含まれ、すべての候補に summary の行が付いています。

コンポーネントを手作業で作ったり、レジストリ名を推測したりする前に、これを呼び出してください。同じカタログバージョンに対して同じ概要を使えば、候補は常に同じ順にランキングされます。

仕組み

5 つの段階があります。タグ付けは事前に実行され、データとしてコミットされます （data/tags/）。クエリ時のマッチングはモデルを呼び出さず、決定論的なコードで行うため、 結果は再現可能です。

1. 取り込み — 各レジストリの registry.json を取得し、1 つの形式に正規化します。
2. タグ付け — コンポーネントの各チャンクに対して、7 つの次元（category、domain、motion、 visual_density、interaction_model、needs_external_data、 decorative_only）を対象に、classifier.dev を 1 回呼び出して一括分類します。出力は JSON としてコミットされ、コードと同様にレビューできます。
3. マッチング — classifier.dev を 1 回呼び出して、ブリーフを同じ 7 つの次元に解析し、その後、タグ付けされたすべてのコンポーネントを決定論的なコードでランク付けします。各次元がランキングに与える影響は、その次元自体の信頼度に応じて重み付けされるため、信頼度の低いタグによって結果が損なわれることはありません。
4. 選定 — 判定が難しい場合は、さらに 1 回呼び出して、上位候補の実際の説明を確認し、最適なものを選ぶか、どれも適合しないと判断します。最上位の候補がすでに明らかに優れている場合は、往復を省くためにスキップします。
5. 提示 — このリポジトリの MCP サーバーです。ツールは 1 つ、pick_component です。

インデックス化されているレジストリ

matchcn は、派生タグ（カテゴリ、モーション、密度など）と、各レジストリ独自のインストールコマンドへのリンクのみを保存します。レジストリのコンポーネントソースをコピー、保存、再配布することはありません。インストールするコンポーネントはすべて、引き続き各レジストリから直接 npx shadcn add <url> で取得します。

レジストリ	ホームページ	インデックス化されたコンポーネント
react-bits	reactbits.dev	204
magicui	magicui.design	79
aceternity	ui.aceternity.com	118
kokonutui	kokonutui.com	51
animate-ui	animate-ui.com	420
motion-primitives	motion-primitives.com	33
shadcn-dashboard	shadcndashboard.dev	343
assistant-ui	assistant-ui.com	154
bundui	bundui.io	217
cnippet	ui.cnippet.dev	1128
uiable	uiable.com	969
plate	platejs.org	174
react-aria	react-aria.adobe.com	62
shadcn-ui-blocks	shadcn-ui-blocks.com	626

合計4,578個のコンポーネントです。最初の6つは、モーション／マーケティング系の元となるグループです。次の3つは、各レジストリのデモや重複に関するルールが元の6つと同じだと決めつけず、それぞれ個別に確認したうえで追加した、プロダクトUIの拡張（フォーム、テーブル、ダッシュボード、データ表示）です。cnippet と uiable は、同じ方法で追加した2つ目のプロダクトUI拡張です。plate と react-aria は、各レジストリに固有のフィルター修正を行ったうえで、同じ方法で追加した3つ目の拡張です（plate のドキュメントページを除外し、react-aria の Tailwind／CSS／hooks のスタイルプレフィックスによる重複を、それぞれの正式なコンポーネント1つに集約しました）。shadcn-ui-blocks は4つ目です。無料版と有料版を合わせたインデックスは、その82％が有料のため、最初から対象外としました（詳しくは下記の「制限事項」を参照）。ただし、ベンダーのメンテナー自身が、厳選された無料版のみの別インデックスを案内してくれました。各項目を実際に確認したところ、すべて認証なしでインストール可能だったため、ここでは無料版のみのインデックスを使用しています。 aceternity の件数は、実際に各項目の提供状況を確認し、実際のインストールURLで有料であることが判明したページテンプレートのコンポーネント163個を、すでに除外した数です。shadcn-dashboard の件数も、同じ理由でコンポーネント165個を除外した数です。shadcnblocks はタグ付けされていますが、現在はインデックス化されていません。詳しくは下記の「制限事項」を参照してください。タグ付けには、TypeSafe の Jev 判定モデルを基盤とする、無料でAPIキー不要の分類エンドポイント classifier.dev を使用しています。

matchcn は独立した非公式プロジェクトです。shadcn、上記の各レジストリ、classifier.dev／TypeSafe との提携関係はなく、それらからの承認も受けていません。

制限事項

matchcn を重要な用途に使う前に、こちらをお読みください。

• 一部のレジストリは、有料コンポーネントを含むため、その一部または全体を除外しています。実際の項目ごとの利用可否チェックに基づいています（インデックスの記載内容だけでなく、未認証で実際に npx shadcn add が動作するかを確認しています）。 aceternity（281 個のタグ付きコンポーネントのうち 163 個。大半はページテンプレートのデモページです）と shadcn-dashboard（508 個のうち 165 個）は、有料のものを除外してから公開しました。shadcnblocks はタグ付け済み（4,171 個のコンポーネント）ですが、全体を保留しています。独自のフィルターチェックがベンダーのレート制限の影響を受けたため、不正確なデータで公開するのではなく、正確なチェックを実行してから公開します。shadcnuikit と shadcn-space も同じ理由で評価のうえ除外しました（有料の割合はそれぞれ 40% と 33.3%）。shadcn-ui-blocks の統合 registry.json も同じ方法で評価し、同じ理由で除外しましたが、その割合はどちらよりも高くなっています。実際に存在する 3,903 個のブロックのうち 3,198 個（82%）は名前に -pro- が含まれ、実際のインストール URL で未認証の場合に 401 を返します。その後、メンテナーからベンダーが別の URL で公開している、個別に選定された無料コンポーネント専用のインデックスが案内されました。そちらを新たに項目ごとにチェックしたところ、626 個すべて（100%）が未認証でインストール可能だったため、ここでは統合インデックスではなく、その無料コンポーネント専用インデックスのみを登録しています。cult-ui.com はインデックスに含まれていません。レジストリがボット検証の背後にあるためです。
• タグの信頼度はレジストリや次元によって異なり、マッチャーはすでにその差を考慮しています。 以前は visual_density が明らかに最も弱い次元でした（信頼度 0.6 未満が 36〜37%。カウントに基づく方法と名前付きアンカーを使った表現の両方を試しましたが、いずれもそこで頭打ちになりました）。3 択のラベルから連続確率に再定式化しました（単なる表現の調整ではなく、構造的な変更です）。全件に適用する前に実際のサンプルで試験し、その後、カタログ全体に適用しました。カタログ全体で基準値未満となる割合は現在 21.4% で、スキーマの他の次元と同程度です（7 次元全体で 13.5〜21.5%。名目上の新たな最低値は motion ですが、1 パーセントポイント未満の差です）。assistant-ui（エージェント／チャット UI のコンテンツ。スキーマのモーション／マーケティングのアンカーとは大きく異なります）は、今もカタログの他の部分より低い信頼度でタグ付けされます。cnippet と uiable は、以前の 20 件の事前タグ付けサンプルで信頼度 0.6 未満が 35% と、さらに低い可能性が示唆されていましたが、全件を対象に測定した結果、その懸念は当たりませんでした。選択肢と次元の組み合わせ 8,388 件全体では、信頼度 0.6 未満は 24.4% で、カタログ全体の基準値とほぼ完全に一致します。信頼度加重マッチャーはこれらすべてを自動的に割り引くため、弱いタグは誤った確信度の高い回答を生むのではなく、自身の重みを下げます。ただし、assistant-ui のようなコンテンツに大きく依存する要件は、適切な候補が見つかるよりも、候補リストまたは一致なしになる可能性が最も高くなります。これとは別に、uiable の説明文は今も大部分が名前を繰り返すテンプレート（「Button component.」など）であり、手書きの文章ではありません。これは実際のデータ品質上の問題ですが、タグの信頼度が測定可能なほど低いという形では表れていません。
• 英語以外の要件はマッチング前に自動翻訳されます。品質は原文の言語と表現に左右されます。 まず、無料でできる表現のみの修正（「言語を問わず、意味に基づいて判断する」）を試しましたが、測定可能な改善がなかったため元に戻しました。実際に差を解消したのは、ローカルでの言語検出と、解析前に英語へ実際に翻訳する処理です（src/runtime/translate.ts を参照）。これが最初に問題を明らかにしたケースそのもので直接検証しました。以前は no_match を返していたポーランド語の価格設定要件が、翻訳後は価格設定コンポーネントの候補リストを返すようになりました。検出はローカルで実行され、無料です。翻訳には、キー不要の無料のサードパーティ API を呼び出します（プロジェクト全体で共有する使い切り可能な枠ではなく、呼び出し元のマシンごとのレート制限です。matchcn は各ユーザーの環境でローカルに動作するためです）。検出または翻訳に失敗した場合は、何もなかったかのように元のテキストをそのまま使用します。そのため、この機能によって改善することはあっても、何もしない場合と同じになるだけで、すでに正常に動作している要件が壊れることはありません。検出対象は、このプロジェクトが実際に翻訳をサポートする言語に限定しています。これは、検出器に既知の約 180 言語すべてを対象とさせた結果、ポーランド語やロシア語の実際の要件が、サポート対象外の言語だと誤って高い確信度で判定され、翻訳が黙ってスキップされることが実際にあったため、必要になった制限です。サポート対象の言語間であっても、短く曖昧な表現では検出を誤る場合があり、検出された言語の翻訳品質はこのプロジェクトの管理外です。
• ランキングでは、タグ付けされた次元間の距離と、各候補の名前およびタイトルに基づくテキスト関連度のシグナルを組み合わせます（タグ付けされた次元だけでなく、要件との TF-IDF 加重コサイン類似度を使います）。タグ付けされた 7 次元だけでは、よく似た候補（ログインフォーム、OTP 入力欄、汎用フォーム入力ブロックは、いずれも form-input／auth／static と評価されます）を区別できないためです。これにより、実測された実際の差が解消されました。実際のカタログを使った評価では、「メールアドレスとパスワード欄のあるログインフォーム」が、インデックスに本物のログインフォームコンポーネントが 8 個あるにもかかわらず、OTP 入力欄に大差で負けていました。修正後は、本物のログインフォームが 1 位とほぼ同点になり、その後 Resolve が各候補の実際の説明文を使って順位を決めます。テキスト関連度の計算に使えるのはコンポーネントの name と title のみです（タグ付け時に使った完全な説明文は、マッチング時に使用できる形では保存されていません）。そのため、タイトルが簡素または汎用的なコンポーネントは、具体的で文字どおりの名前を持つものほど、このシグナルの恩恵を受けません。
• 372 件以上ある shadcn 形式のレジストリのうち、インデックスに登録されているのは 14 件です。 これはエコシステムを網羅したインデックスではありません。 上記はいずれも、誤った回答を無理に選ばせることはありません。確信度が本当に低い場合、pick_component は候補を絞り込んだリストか、明示的な該当なしを返し、何も言わずに単一の候補を推測することはありません。これこそがタグ付けとランキングの設計の本来の目的であり、後付けの免責事項ではありません。

開発

pnpm install
pnpm mcp                # run the MCP server directly, for local testing
pnpm demo               # run 3 briefs end to end with clean terminal output
pnpm typecheck

data/tags/ を生成する取り込み／タグ付けパイプラインも、このリポジトリにあります。

pnpm ingest                          # fetch and normalize every registry.json in REGISTRIES
pnpm ingest --registry=magicui       # just one registry
pnpm tag                             # tag normalized components via classifier.dev, chunked and resumable
pnpm check-availability --registry=some-registry   # real per-item install-URL check, no classifier.dev cost

pnpm tag は classifier.dev の判定を実際に消費します（無料枠：1 日あたり 20,000 件、IP あたり 1 分間に 3,000 件、API キー不要）。各チャンクの処理後にチェックポイントを保存するため、処理が中断されても、すでに完了した項目にタグを付け直すことなく再開できます。

コントリビューション

Issue と PR を歓迎します。別のブランチで作業し、main に直接変更を加えないでください。マージするのは @whosfranki だけです。PR を出しても必ず取り込まれるわけではありませんが、すべて確認します。

初めてのコントリビューションにおすすめの作業：

• レジストリのフィルターを修正する。 src/pipeline/filter.ts には、レジストリごとに関数があります（既知の問題については未解決の Issueを参照してください。たとえば、現在のフィルターでは除外されない、コンポーネントではない type など）。修正を提案する前に、対象のレジストリに対して pnpm ingest --registry=<name> を実行し、正規化された出力を手作業で確認してください。
• レジストリを追加する。 src/runtime/registries.ts にエントリーを追加し、フィルターが正しいことを確認してください（デモ、重複、コンポーネントではない項目が混入していないこと。既存の各レジストリで行っているのと同じ手作業での確認を行い、思い込みで済ませないこと）。リリース前に pnpm check-availability を実行してください（registry.json のインデックスからは、どのコンポーネントが実際に有料でしか利用できないのかは分かりません）。その後、pnpm tag を実行してください。無関係な変更と同じ PR でレジストリの追加とタグ付けを行わないでください。
• タグ付けの基準を改善する。 src/runtime/dimensions.ts が対象です。文言を変更する場合は、もっともらしい書き換えを提案するだけでなく、実際のサンプルで変更前と変更後を比較する必要があります。以前、「英語以外のブリーフにも対応する」ための文言修正を試した際も、この方法で検証した結果、測定可能な効果がなかったため差し戻されました。このプロジェクトでは、修正をこの基準で評価しています。
• src/runtime/match.ts、pick.ts、resolve.ts のランタイムバグ。

PR には、変更前に測定した内容、変更内容、変更後に測定した内容を含めてください。実際のブリーフやコンポーネントのサンプルで変更前後を比較せず、「改善するはずです」とだけ述べた場合は、差し戻されます。

ライセンス

MIT。詳しくは LICENSE を参照してください。