matchcn is an independent, unofficial project. It is not affiliated with, endorsed by, or a partner of shadcn, any of the registries it indexes, or classifier.dev/TypeSafe.

What it is

Hundreds of registries now publish components in the shadcn registry.json format, and npx shadcn add can install from any of them. No developer or coding agent can hold that many registries in context, and existing directory tools only search component names, which does not help when you know what you need but not what any given registry decided to call it. matchcn tags every component across a fixed set of properties (category, motion, visual density, interaction model, and two others) using classifier.dev, then matches a plain-language brief against those tags with deterministic code, so the same brief always ranks the same way.

Status: early, read this before using it

This is a 2-3 day MVP covering 6 of the 372+ registries shadcn's own public list currently has. It is not a comprehensive index. Specific, known weak points, in order of how much they matter:

visual_density is the weakest tagged dimension. 36% of pilot answers on this dimension score under 0.6 confidence, the worst of the six tagged dimensions, even after a rewrite. A confidence-weighted matcher discounts weak tags automatically, but a visual_density-heavy brief is still the most likely to disappoint. Full numbers: docs/PILOT_REPORT.md, docs/DIMENSIONS.md.
Non-English briefs are known to be weaker, confirmed on 3 Polish test briefs, not fixed. A Polish pricing brief and its English equivalent were compared directly: English found a real, well-tagged pricing component at 0.98 confidence, Polish returned no match at all. A zero-cost fix was tried (an explicit "interpret by meaning, any language" line added to the tagging/matching criteria) and tested properly with a before/after comparison on 3 Polish briefs: it did not help the pricing brief, made a cursor brief measurably worse (a confident shortlist of 3 real candidates became no match), and left a bento grid brief unchanged. It was reverted rather than kept for no measured benefit. Non-English input should not be assumed to work. Details: docs/DECISIONS.md #17.
aceternity's 170 registry:block demo pages are tagged from short index descriptions only, not enriched from source. Their per-item source endpoint returns HTTP 401 for anonymous requests; aceternity's 112 registry:ui primitives do not have this problem and are enriched from real source. Details: docs/DECISIONS.md #12.
cult-ui.com is not indexed at all. Its registry.json sits behind a Vercel bot challenge that a plain HTTP request cannot pass. Details: docs/DECISIONS.md #6.

None of these cause a wrong forced answer: when confidence is genuinely low, pick_component returns a shortlist or an explicit no-match, never a single silent guess. See docs/DEMO_REPORT.md for real examples of all three outcomes, including two briefs designed to fail.

Install

npx matchcn

MCP setup

Add to your MCP client's config (for example Claude Desktop's claude_desktop_config.json, or Claude Code's .mcp.json):

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

This exposes one tool, pick_component(brief, registry?, maxResults?).

Worked example

$ pnpm demo

Brief: a dense bento grid for a landing page. This is real output from a real run. classifier.dev does not guarantee identical answers across calls, so the exact confidence number will vary between runs (0.79 to 0.98 observed across repeated runs during development); the outcome, the chosen component, and the install command have been stable across every run tried.

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

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

resolve used: true   decisions spent: 7

Every response includes a per-dimension reason (which of the six tagged dimensions matched the brief and which did not), never just a name. Full JSON shape and more examples, including a shortlist and two deliberate no-match cases: docs/DEMO_REPORT.md.

How it works

Five stages: Ingest, Tag, Match, Resolve, Surface. Tagging runs ahead of time and is committed as reviewable JSON (data/tags/); matching at query time is deterministic code, not a model call, so the same brief always ranks the same way. Full architecture, every design decision and its rejected alternatives, and the exact tagging criteria used:

docs/WHY.md: the problem, who this is for, what it explicitly is not
docs/ARCHITECTURE.md: the five stages and the data flow
docs/DIMENSIONS.md: the tag schema, every dimension's exact criteria
docs/DECISIONS.md: numbered decision records, alternatives rejected and why
docs/ROADMAP.md: what is shipped, what is deferred, what is parked
docs/PILOT_REPORT.md, docs/FULL_RUN_REPORT.md, docs/DEMO_REPORT.md: real numbers from real runs
RECON.md, docs/FILTER_REPORT.md: what was fetched and what was filtered out, with evidence

Registries indexed, and attribution

matchcn stores only derived tags (category, motion, density, and so on) and a link back to each registry's own install command. It never copies, stores, or redistributes any registry's component source code. Every component you install still comes directly from its own registry via npx shadcn add <url>.

registry	homepage	components indexed
react-bits	reactbits.dev	204
magicui	magicui.design	79
aceternity	ui.aceternity.com	282
kokonutui	kokonutui.com	51
animate-ui	animate-ui.com	420
motion-primitives	motion-primitives.com	33

1,069 components total, drawn from the six registries above. Tagging runs through classifier.dev, a free, keyless classification endpoint backed by TypeSafe's Jev decision model.

Development

pnpm install
pnpm ingest      # fetch and normalize all registries
pnpm tag         # tag all components via classifier.dev
pnpm demo        # run 3 briefs end to end
pnpm test        # determinism tests for the matcher
pnpm typecheck