ui-indexador

Your AI builds UI from memory. Give it the whole shadcn ecosystem.

ui-indexador indexes every component and block of the shadcn registry ecosystem (about 105,000 items from 320+ registries), ranks the registries by proof of use, and lets an AI agent find the right piece by meaning through an MCP server or a plain HTTP API. Every result carries its licence and the npx shadcn@latest add @registry/item command that installs it. It stores no component code: the shadcn CLI fetches it from the original registry.

Its own landing page (site/) was built with it: every section was searched for through its MCP server, and the page shows the queries, the candidates and what was chosen.

Quick start

git clone https://github.com/eddremonts86/ui-indexador && cd ui-indexador
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt   # mcp (1.x or 2.x) + numpy
ollama pull nomic-embed-text      # optional: semantic search (keyword search works without it)
bash refresh.sh                   # build the index: rank registries (needs `gh auth login`), crawl, embed (~15 min)
.venv/bin/python server.py        # http://127.0.0.1:3040  (API + landing page once site/ is built)
.venv/bin/python test_server.py   # smoke test: every endpoint + the MCP tool list

Add it to your agent (stdio; the client starts it):

claude mcp add ui-indexador -- "$PWD/.venv/bin/python" "$PWD/mcp_server.py"     # Claude Code

Codex (~/.codex/config.toml):

[mcp_servers.ui-indexador]
command = "/path/to/ui-indexador/.venv/bin/python"
args = ["/path/to/ui-indexador/mcp_server.py"]

Or over HTTP: .venv/bin/python mcp_server.py --http serves MCP on http://127.0.0.1:3041/mcp.

Environment: UI_INDEXER_PORT / UI_INDEXER_HOST (3040 / 127.0.0.1), UI_INDEXER_MCP_PORT (3041), UI_INDEXER_OLLAMA (http://localhost:11434), UI_INDEXER_EMBED_MODEL (nomic-embed-text).

Related MCP server: ui-registry-mcp

What it answers

The landing page (site/)

Vite + React 19 + Tailwind 4 + shadcn (Radix), built from registry components found with this app through its MCP server: site/build-log.json records every query, candidate and choice and the page renders it ("Built with itself"); site/THIRD_PARTY.md lists the installed items and licences; site/DOGFOOD.md what building it taught about the indexer.

cd site && pnpm install && pnpm build    # site/dist (not committed); server.py then serves it at /
pnpm dev                                 # 127.0.0.1:3042, API paths proxied to :3040

server.py serves site/dist at / (gzip, immutable cache for hashed /assets/), and the health JSON at / when the site is not built. The page reads live numbers from /health and /facets and searches /items.

Which registries are indexed, and adding more

• GET /registries (MCP list_registries) lists every indexed registry with homepage, stars, licence, score and source (directory = the official shadcn directory, manual = added by hand). /registries.md groups them. /items?registry=@name lists one registry's items; /facets counts everything.

• Add one the directory does not list (yours, a small one, or the official @shadcn set, already added):

  python3 scripts/add-registry.py @name "https://site.com/r/{name}.json" [--homepage URL] [--description TEXT]
  python3 scripts/add-registry.py --list
  python3 scripts/add-registry.py --remove @name

  The URL is the item template from the registry's components.json entry. It is checked (the index must answer with items) and saved in data/extra-registries.json (committed); it joins the index on the next refresh.

Refresh

bash refresh.sh ranks the registries (directory + extras; needs gh logged in for stars, otherwise keeps the current ranking), crawls every item with layout tags, and embeds only what changed (skipped if Ollama is down). --quick skips the layout crawl. The servers see the new files on the next request.

The crawl refuses to shrink the catalog by more than 20% in one run, so a network blip keeps yesterday's index.

Run it as a service (macOS)

bash schedule/install.sh installs three per-user launchd agents: ui-indexador.api (server.py on :3040, kept alive), ui-indexador.mcp (MCP over HTTP on :3041/mcp, kept alive) and ui-indexador.refresh (refresh.sh daily at 11:30, a notification on failure, logs in logs/ for 14 days). --run-now also starts a refresh, --status, --uninstall. On Linux, run the same three commands under systemd or cron.

How the index is made

1. scripts/rank-registries.py --out data: the shadcn directory (ui.shadcn.com/r/registries.json) plus extra-registries.json, ranked by GitHub stars, size and endpoint health → registries.json / .md (generated, needs gh).

2. scripts/survey-registries.py catalog --out data: every item of every ranked registry from its registry.json (name, type, categories, dependencies), tagged with a kind by its name and description. --deep also fetches each block's source and tags its layout and visual features. Generated, not committed.

3. scripts/fetch-themes.py: tweakcn presets (Apache-2.0) plus vibes/keywords from shadcn-ui-mcp-server (MIT).

4. Hand work: scripts/capture.py screenshots (kept local, not in git: they are captures of other people's sites), the survey CSVs and INDEX.md.

Kinds and layouts are heuristics from names and code: use them to narrow, then look before choosing.

Search

• Semantic (default when available): q is embedded with the local Ollama (nomic-embed-text, first 256 Matryoshka dimensions) and compared with every item's name, title, description, kind and categories, so "buy flight tickets" finds booking, checkout and boarding-pass pieces that never say "flight". The 300 nearest items join the literal keyword hits; a keyword hit and a strong registry break near-ties. English queries work best. Needs data/embeddings.npy, numpy and Ollama with nomic-embed-text pulled (UI_INDEXER_OLLAMA, default http://localhost:11434).

• Keyword (mode=keyword, or the fallback when semantic is unavailable; the response says why in note): every word of q must start a word in the item's text.

• Icons/logos (~43k) and examples are hidden unless kind=icon/logo, type=example or include_hidden=1.

• framework=react by default (from each item's dependencies, else its registry's description); vue, svelte, solid, react-native, … or any.

• osi_only=1 keeps items whose registry has an OSI licence. Licences are per registry.

• Mirrors: @registrydirectory republishes other registries' items. A copy of an item indexed under its own registry is not served; the rest carry mirror_of and no licence or stars (those would be the mirror's).

Bound to 127.0.0.1 by default (--host / UI_INDEXER_HOST to change it). There is no auth: do not expose it as is. Not yet: a hosted instance, per-item licences, detection of Next.js-only items (see site/DOGFOOD.md).

Licence

MIT (see LICENSE); bundled third-party data and components are listed in NOTICE and site/THIRD_PARTY.md. Indexed items belong to their authors under their own licences.