encode-ui

encode-ui

Component lookup over the encode-ui registry — 352 shadcncomponents, served to AI coding agents over MCP. Your agent searches the catalog, reads anycomponent's source, and hands back the exact npx shadcn@latest add command.

Read-only by design. This server tells an agent what to install; installing stays on yourown shadcn path, and nothing here touches your project.

Install

One stdio command. npx fetches it on first run — nothing to install or keep current:

npx -y encode-ui

Zero flags gives you the zero-setup web engine: it fetches the catalog from the deployedregistry at startup, caches it, and falls back to a bundled copy, so startup never failsoffline. Only three runtime dependencies are required — the native stack behind the semanticengine is optional, so a machine that can't build it still installs and still runs.

Claude Code

The -- is required; without it claude reads the server's flags as its own.

claude mcp add encode-ui -- npx -y encode-ui

Verify with claude mcp list (→ ✔ Connected) or /mcp in a session.

Claude Desktop, Gemini CLI, and other hosts

The same JSON block works anywhere that speaks stdio MCP — Claude Desktop'sSettings → Developer → Edit Config, or ~/.gemini/settings.json:

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

Prefer this form when passing flags: they arrive as discrete args that no wrapper canreinterpret. Restart the host completely after editing. If the server never appears in aGUI-launched app, it likely didn't inherit your shell's PATH — use an absolute npx path.

ChatGPT is not supported: its connectors accept only remote HTTPS MCP servers, and this oneis stdio.

Gated components

A few items need an account. Sign in at encode-ui.com, copy thetoken from any gated item's Install tab, and put it in the registration's env block —not on the command line, where ps can read it:

{ "env": { "ENCODE_UI_TOKEN": "eyJ…" } }

Everything else works without it.

Tools

Every search and list hit carries pure: true when the item's whole install tree adds nonpm packages beyond the shadcn substrate you already have. search_components andlist_components take a dependencyFree filter.

Two behaviours worth knowing. Search is not an oracle of absence — for "does the registryhave X?" or "list everything in Y", enumerate with list_groups then list_components andjudge the descriptions. And a misspelt name is an error, not an empty result: it comesback carrying the closest matches, so the agent self-corrects in one turn.

Prompts

Two slash commands carry the long-form guidance, at zero token cost until invoked:

use-registry is the recurring workflow (discover → assess → install → customize);setup-project is the one-time consumer init — the components.json namespace, the OKLCHtoken contract, tw-animate-css, and a smoke test.

Engines

--registry-engine <web|catalog|db> picks how search works. The default is fine for mostpeople; the other two trade setup for better ranking.

• web (default) — no model, no index. Fetches the catalog from the registry, and sourcebodies per call. Its search is a plain filter over names, aliases and keywords, sobehaviour-style discovery works best by reading the encode-ui://catalog resource onceand letting the model judge the descriptions.
• catalog — offline lexical ranking over the bundled index. Ranking never touches thenetwork; source bodies still come from the origin (or a registry checkout, if onesurrounds the package).
• db — hybrid semantic + lexical retrieval over each component's description, fullsource, and demo. The strongest for vague, behaviour-style queries. Served from theindex.db shipped in the package; the first query downloads ~1.2 GB of ONNX weights onceper machine (--lexical-only skips the model entirely).

Configuration

Every install-time property is a flag; --help prints this to stderr. The onlyconfiguration environment variable is ENCODE_UI_TOKEN.

A flag the selected engine would ignore is a usage error (exit 2), same as a malformedvalue — the server never warn-and-ignores something you typed deliberately. Path flagsexpand ~ and resolve relative values against the server's cwd.

Gotchas

• Rebuilding the index means restarting every running server. The build replacesindex.db with a new file, while the server opens it once and holds the handle — so along-lived server keeps serving the deleted snapshot, silently. After a rebuild, reconnectand check that the startup banner's item count matches.
• Icons are data, not components. The registry ships no icon components; find_iconsanswers from vendored lucide metadata at the exact tag the registry pins forlucide-react. Ask it rather than guessing an import.

License

MIT — see LICENSE. This package ships a prebuilt index carrying component source,some of it adapted from other MIT-licensed projects; their notices travel with it inNOTICE.md. The bundled agent-index.json is generated from the registry, soregenerating it is a maintainer task rather than something a clone can reproduce.