Semantic index across shadcn-format component registries: find components by what they do.
io.github.francesco0242/matchcn โ Model Context Protocol (MCP) Server
This MCP server provides a semantic index across shadcn-format component registries. Its purpose is to help users find components by what they do, using a description-driven approach rather than only names or paths. The server is identified as io.github.francesco0242/matchcn.
๐ ๏ธ Key Features
Semantic index over shadcn-format component registries
Component discovery based on functionality intent (what they do)
๐ Use Cases
Locate shadcn-format components by their described purpose
Match components to functionality across multiple registries
โก Developer Benefits
Enables intent-based searching for components in shadcn-format registries
Supports workflows where component selection depends on behavior rather than exact identifiers
โ ๏ธ Limitations
Available data does not specify tool count, topics, or implementation details beyond semantic indexing and functionality-based discovery
Claude Code calling matchcn's pick_component tool to find and install a real login form component, live
The problem
npx shadcn add can install a component from any registry that publishes
a registry.json. Hundreds of registries do. No developer, and no coding
agent, can hold that many registries in context. 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. "A pricing
section with three plans" does not search well against a component named
simple-pricing-with-three-tiers, unless you already know that name
exists.
matchcn tags every component it indexes across seven fixed properties
(category, domain, motion, visual density, interaction model, and two
others) using classifier.dev, then matches a
plain-language brief against those tags with deterministic code. Same
brief, same ranking, every time. No forced guesses: when nothing fits
well, matchcn says so instead of returning the closest wrong answer.
Works with Claude Desktop (claude_desktop_config.json), Claude Code
(.mcp.json), Cursor, and any other MCP-compatible client. This exposes
one tool: pick_component(brief, registry?, maxResults?, hints?, resolve?).
More of a copy-paste person? Give your coding agent this prompt and let
it set itself up:
Set up the matchcn MCP server using npx -y matchcn. Configure it for
my coding agent, then use pick_component to find UI components that
match my brief. Show me the match reasons and install command before
adding a component.
Example
code
$ 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
This is real output from a real run. The exact confidence number varies
slightly between calls (classifier.dev does not guarantee identical
answers across calls), but the outcome, the chosen component, and the
install command have been stable across every run tried.
Every response includes a per-dimension reason: which of the seven
tagged properties matched the brief and which did not, both sides' actual
values, never just a pass or fail bit. That is what makes a no_match or
a shortlist result debuggable instead of a dead end.
For AI agents
If you are an LLM reading this to decide whether to use matchcn: this
tool exists specifically for you. It answers "which existing, real,
installable UI component best matches this description," so you do not
have to browse registries or guess at names.
Tool:pick_component
Input:
ts
{
brief: string; // plain-language description, requiredregistry?: string; // restrict to one registry, optionalmaxResults?: 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 parsingcategory?: string; // same labels components are tagged withmotion?: 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"
}
Fastest path (local mode): write the brief in English, pass hints,
and set resolve: "caller". matchcn then makes no model calls at all:
ranking is local and deterministic (about 80 ms warm on the full
catalog), and on a tie you get the ranked shortlist back, each candidate
with a one-line summary of its tagged properties, and pick yourself.
Omit a hint you are unsure about rather than guessing; omitted fields are
simply not ranked on. Without hints and resolve, behavior is unchanged.
json
{"brief":"a login form with email and password fields","hints":{"category":"form-input","interaction_model":"form-input","domain":"auth"},"resolve":"caller"}
Output is always one of three shapes, never a fourth "best guess" shape:
outcome: "confident" โ one chosen component: name, registry,
installCommand (a ready-to-run npx shadcn add <url> command),
sourceUrl, confidence, and reasons (per-dimension match detail).
If the component has language/styling variants, they are listed with
their own install commands.
outcome: "shortlist" โ several candidates that all fit reasonably
well with no clear single winner, ranked, each with the same
per-dimension reasons, plus differentiators: which specific
dimension(s) actually separate them, so you can decide on that axis
instead of picking arbitrarily.
outcome: "no_match" โ nothing in the catalog is a real fit. The
closest candidates are still listed for context but explicitly marked
as rejected, not returned as an answer. Do not install one of these
just because it was the closest; the catalog does not have what was
asked for. With resolve: "caller" this outcome is never returned,
since only the server-side Resolve step reads candidates against the
brief: a tie comes back as a shortlist and judging whether any
candidate genuinely fits is up to you.
Every result also reports briefParsedBy (hints or classifier) and
resolvedBy (server or caller), and every candidate carries a
summary line.
Call this before hand-rolling a component or guessing a registry name.
It is deterministic: the same brief against the same catalog version
always ranks candidates the same way.
How it works
Five stages. Tagging runs ahead of time and is committed as data
(data/tags/); matching at query time is plain deterministic code, not
a model call, so results are reproducible.
Ingest โ fetch each registry's registry.json, normalize into one
shape.
Tag โ one batched call per chunk of components to classifier.dev,
across seven dimensions: category, domain, motion,
visual_density, interaction_model, needs_external_data,
decorative_only. Output is committed JSON, reviewable like code.
Match โ parse the brief into the same seven dimensions with one
classifier.dev call, then rank every tagged component against it in
plain code. Each dimension's contribution to the ranking is weighted
by its own confidence, so a weak tag pulls its weight down instead of
polluting the result.
Resolve โ for close calls, one more call reviews the top
candidates' real descriptions and picks a winner, or says none of them
fit. Skipped when the top match is already clearly ahead, to save a
round trip.
Surface โ the MCP server in this repo. One tool, pick_component.
Registries indexed
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. Every
component you install still comes directly from its own registry via
npx shadcn add <url>.
4,578 components total. The first six are the original motion/marketing
family; the middle three are a product-UI expansion (forms, tables,
dashboards, data display) added after checking each registry's
demo/duplicate conventions individually rather than assuming they match
the original six; cnippet and uiable are a second product-UI expansion,
added the same way; plate and react-aria are a third, added the same
way after each got its own filter fix (dropping plate's documentation
pages, collapsing react-aria's tailwind/css/hooks style-prefix
duplicates down to one canonical component each). shadcn-ui-blocks is a
fourth: its combined free+paid index was excluded outright (82% of it
paywalled, see Limitations below), but the vendor's own maintainer
pointed at a separate, curated free-only index, which a real per-item
check found 100% installable unauthenticated, so only that free-only
index is used here.
aceternity's count already excludes 163 page-template components a real
per-item availability check found paywalled at their actual install URL;
shadcn-dashboard's count already excludes 165 components for the same
reason; shadcnblocks was tagged but is not currently indexed, see
Limitations below. Tagging runs through
classifier.dev, a free, keyless classification
endpoint backed by TypeSafe's Jev decision
model.
matchcn is an independent, unofficial project. It is not affiliated with,
endorsed by, or a partner of shadcn, any of the registries above, or
classifier.dev/TypeSafe.
Limitations
Read this before relying on matchcn for something important.
Some registries are partly or fully excluded for paywalled components,
found by a real per-item availability check (does npx shadcn add
actually work unauthenticated, not just what the index claims):
aceternity (163 of 281 tagged components, mostly page-template demo
pages) and shadcn-dashboard (165 of 508) had the gated share filtered
out before shipping. shadcnblocks was tagged (4,171 components) but is
held back entirely: its own filter check got contaminated by the
vendor's rate limiter, so it ships once a clean check runs rather than
on bad data. shadcnuikit and shadcn-space were evaluated and skipped
outright for the same reason (40% and 33.3% paywalled). shadcn-ui-blocks's
combined registry.json was evaluated the same way and skipped for the
same reason, worse than either: 3,198 of its 3,903 real blocks (82%)
are -pro- named and return 401 unauthenticated on their actual
install URL. Its maintainer later pointed at a separate, curated
free-only index the vendor publishes at a different URL; a fresh
per-item check against that one found 626/626 (100%) installable
unauthenticated, so only that free-only index is indexed here, not the
combined one. cult-ui.com isn't indexed at all: its registry sits
behind a bot challenge.
Tag confidence varies by registry and dimension, and the matcher
already accounts for it.visual_density used to be the clear
weakest dimension (36-37% under 0.6 confidence, both a counting-based
and a named-anchor wording were tried and both plateaued there). It was
reformulated from a 3-way label choice to a continuous probability
(a structural change, not another wording tweak), piloted against a
real sample before any backfill, then backfilled across the full
catalog: full-catalog result is now 21.4% under-threshold, in line
with the rest of the schema (13.5-21.5% across all seven dimensions;
motion is nominally the new low point, by less than a percentage
point). assistant-ui (agent/chat UI content, far from the schema's
motion/marketing anchors) still tags less confidently than the rest of
the catalog. cnippet and uiable were measured at full scale after an
earlier 20-item pre-tagging sample suggested they might be worse
(35% under 0.6): they are not. Across their full 8,388 choice-dimension
answers, 24.4% score under 0.6 confidence, matching the catalog-wide
baseline almost exactly. A confidence-weighted matcher discounts all
of this automatically, so a weak tag pulls its own weight down instead
of producing a wrong confident answer, but a brief that leans heavily
on assistant-ui-style content is the one most likely to get a
shortlist or no-match instead of a clean pick. Separately, uiable's
descriptions are still largely name-echoed templates ("Button
component.") rather than hand-written text โ a real data-quality gap,
it just doesn't show up as measurably lower tag confidence.
Non-English briefs are auto-translated before matching, quality
depends on the source language and phrasing. A free wording-only fix
("judge by meaning, any language") was tried first and reverted for no
measured benefit. What actually closed the gap: local language
detection plus real translation to English before parsing (see
src/runtime/translate.ts). Verified directly on the exact case that
first exposed this: a Polish pricing brief that previously returned
no_match now returns a real shortlist of pricing components once
translated. Detection is local and free; translation calls a free,
keyless third-party API (rate-limited per calling machine, not a
shared pool this project could exhaust for everyone, since matchcn
runs locally per user). Any detection or translation failure falls
back to the original text silently, exactly as if this did not exist,
so this can only help or be a no-op, never break a brief that already
worked. Detection is restricted to the languages this project actually
supports translating (found necessary after real briefs in Polish and
Russian were confidently misdetected as unsupported languages when the
detector was allowed to consider all ~180 it knows, silently skipping
translation); detection on short, ambiguous phrases within the
supported set can still occasionally misfire, and translation quality
for the detected language is out of this project's control.
Ranking blends tagged-dimension distance with a text-relevance signal
over each candidate's name and title (TF-IDF-weighted cosine
similarity against the brief, not the tagged dimensions alone), because
the seven tagged dimensions cannot by themselves distinguish
near-identical variants (a login form, an OTP field, and a generic
form-input block all score as form-input/auth/static). This
closed a real, measured gap: a real-catalog eval found "a login form
with email and password fields" losing to an OTP field by a wide margin
despite eight genuine login-form components being indexed; after the
fix, the real login form is a near-tie for the top rank, which Resolve
then breaks using each candidate's real description. Text relevance can
only be computed from a component's name and title (the full
description used at tagging time is not persisted for match-time use),
so components with a sparse or generic title benefit less from this
signal than ones with a specific, literal name.
14 of 372+ shadcn-format registries are indexed. This is not a
comprehensive index of the ecosystem.
None of the above produces a wrong forced answer: when confidence is
genuinely low, pick_component returns a shortlist or an explicit
no-match, never a single silent guess. That is the actual point of the
tagging and ranking design, not a disclaimer bolted on afterward.
Development
bash
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
The ingest/tag pipeline that produces data/tags/ is also in this repo:
bash
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 spends real classifier.dev decisions (free tier: 20,000/day,
3,000/min per IP, no API key needed). It checkpoints after every chunk, so
an interrupted run resumes without re-tagging anything already done.
Contributing
Issues and PRs are welcome, on a separate branch, never directly to
main. Only @whosfranki merges; opening
a PR does not mean it lands, but every one gets read.
Good first contributions:
Fix a registry's filter.src/pipeline/filter.ts has one function
per registry (see open issues
for known gaps, e.g. a non-component type the current filter doesn't
drop). Run pnpm ingest --registry=<name> against the affected
registry and check the normalized output by hand before proposing a fix.
Add a registry. Add an entry to src/runtime/registries.ts, verify
its filter is correct (no demo/duplicate/non-component pollution, the
same manual check every existing registry got, not an assumption), run
pnpm check-availability before shipping (a registry.json's index gives
no signal about which components are actually paywalled), then pnpm tag.
Do not add a registry and tag it in the same PR as an unrelated change.
Improve a tagging dimension's criteria.src/runtime/dimensions.ts.
Any wording change needs a before/after comparison on a real sample
before it's proposed, not just a plausible-sounding rewrite; a prior
attempt at a "make non-English briefs work" wording fix was tested this
way and reverted for no measured benefit, which is the standard this
project holds fixes to.
Runtime bugs in src/runtime/match.ts, pick.ts, resolve.ts.
What a PR should include: what was measured before the change, what
changed, what was measured after. "This should help" without a before/
after comparison on a real brief or component sample will get sent back
for one.