free-design-registry

A standalone, fully-local MCP design registry of 21st-style shadcn components. It scrapes the public 21st.dev registry into a local SQLite database (FTS5 full-text search) and serves the components over MCP on stdio — no third-party MCP paywall, no API keys, no rate limits.

What it does

• Crawler (src/crawler.ts) discovers public component URLs from 21st.dev's sitemap, hydrates each via https://21st.dev/r/{author}/{slug}, and stores the payload in SQLite. Idempotent (INSERT OR REPLACE by id) — re-running refreshes existing rows.

• Database (src/db.ts, src/schema.sql) — a components table plus an FTS5 non-external virtual table kept in sync by plain-SQL triggers, with a final rebuild after each crawl.

• MCP server (src/server.ts) exposes five tools over stdio:

  • search_designs(query, limit?) — full-text search ranked by relevance.

  • inspect_component(id) — full record for one author/slug component.

  • get_build_prompt(id | query) — a detailed, reusable build-prompt scaffold for a component.

  • install_component(id) — the component's file list + install steps.

  • get_theme(identifier, mode?) — design tokens (CSS variables and/or Tailwind config) for an aesthetic keyword ("neon", "minimal", "sunset") or a component id. Curated/inferred: the registry stores metadata only, not raw theme tokens, so output is clearly labeled.

Component ids are "author/slug".

Related MCP server: shadcn MCP Server

Requirements

• Node.js >= 20 (tested on 22). npm.

• No API keys. The crawler talks to the public 21st.dev endpoints directly.

Setup

npm install        # installs better-sqlite3 (prebuilt binary) + deps
npm run build      # esbuild CJS bundle -> dist/server/index.cjs, dist/crawler/index.cjs
                   # (+ copies schema.sql and the base catalog assets/registry.db -> dist/data/)

That's it — the base catalog (7,126 components) ships in the repo as assets/registry.db, so a fresh clone is ready to serve with no crawl. Run npm run crawl only if you want to refresh the data (~15 min; idempotent). Flags below.

Crawl flags

--limit <n> (default: all), --concurrency <n> (default 5), --delay <ms> (default 50, jittered), --dry-run. Useful smoke test: npm run crawl -- --limit 25.

Note on the catalog: 21st.dev's detail endpoint is 403-gated for anonymous hydration, so records are partial (name / author / description; no raw CSS tokens or file contents). That's by design — the value is the searchable metadata + build prompts + curated theme scaffolds, not the source files. get_theme output is therefore clearly labeled as curated/inferred.

Run the MCP server

node dist/server/index.cjs     # or: npm start  /  npm run mcp
npm run dev                    # dev mode (runs src/server.ts directly, no build needed)

The server speaks MCP over stdio; it logs to stderr, stdout is reserved for the protocol.

MCP client config

Point any MCP client (Claude Code, Cursor, Windsurf, OpenCode, etc.) at it:

{
  "mcpServers": {
    "free-designs": {
      "command": "node",
      "args": ["<ABS_PATH_TO_THIS_DIR>/dist/server/index.cjs"]
    }
  }
}

Verify

# row count (expect ~7,000)
node -e "const db=require('better-sqlite3')('dist/data/registry.db');console.log(db.prepare('SELECT COUNT(*) c FROM components').get().c)"
# FTS search
node -e "const db=require('better-sqlite3')('dist/data/registry.db',{readonly:true});console.log(db.prepare(\"SELECT id,name FROM components_fts WHERE components_fts MATCH 'bento' LIMIT 5\").all())"

The database lives at dist/data/registry.db (WAL mode). The base catalog ships in the repo as assets/registry.db and the build copies it into dist/data/; dist/data/ itself is git-ignored. Run npm run crawl to refresh the data.

Agent workflow skills

.cursorrules contains the agent-facing workflow skills (discovery → build prompt → theme → audit). Drop it into any agent's project rules to teach registry usage.

Project layout

free-design-registry/
├── package.json
├── tsconfig.json
├── .gitignore
├── README.md
├── .cursorrules          # agent workflow skills
├── assets/registry.db    # base catalog (7,126 components) — committed; copied to dist/data/ on build
├── test-mcp.mjs          # MCP stdio integration test (all tools)
├── test-theme.mjs        # get_theme integration test
└── src/
    ├── schema.sql        # components table + FTS5 virtual table + triggers
    ├── db.ts             # SQLite access layer (better-sqlite3) + theme engine
    ├── crawler.ts        # discovery + hydration
    ├── server.ts         # MCP stdio server (5 tools)
    └── build.ts          # esbuild CJS bundler

Publishing / rebuilding elsewhere

This is a self-contained repo. To reproduce on any machine or agent:

1. git clone <this-repo>

2. npm install && npm run build

3. Add the MCP client config above.

No secrets, no external services. The base catalog ships in the repo as assets/registry.db (~10 MB), so a fresh clone serves immediately with no crawl. The only network dependency is the public 21st.dev endpoints, and only if you run npm run crawl to refresh the data.