get_registry_stats

get_registry_stats is the "what's on shadcn.io?" bird's-eye view. It lets an agent answer that question in one call instead of enumerating surface by surface.

When to use

• Answering onboarding / marketing questions ("what can I build with shadcn.io?").
• Giving the user a coverage sense before a plan ("we have 56 block categories — here are the ones most relevant to your SaaS").
• Dashboards and internal tooling.

How it works

First call does real work; subsequent calls within 10 minutes are pure memory reads.

On cache miss:

1. For each surface, run a lightweight readdirSync (directory metadata only — no file contents read). For block categories and components, walks the per-category subdirectories recursively. For flat surfaces (ai, charts, etc.), counts .tsx files directly.
2. loadBlockCategories() reads content/blocks/meta.json (already cached from the other tools).
3. Two aggregate queries against the icons DB: library.count() and library.aggregate({ _sum: { iconCount } }).
4. Sum the surface totals and return.

On cache hit: in-memory object read. Zero I/O.

Concurrent callers share one in-flight promise — no stampede: if 50 requests arrive simultaneously, exactly one does the scan.

Source: lib/mcp/stats.ts#getRegistryStats.

Arguments

None.

Response

{
  "totalItems": 6524,
  "surfaces": {
    "blocks":     { "total": 6120, "categories": 56 },
    "ai":         { "total": 48 },
    "components": { "total": 82 },
    "examples":   { "total": 164 },
    "hooks":      { "total": 27 },
    "charts":     { "total": 18 },
    "button":     { "total": 12 },
    "background": { "total": 14 },
    "shaders":    { "total": 9 },
    "text":       { "total": 16 },
    "themes":     { "total": 14 }
  },
  "icons": {
    "libraries": 222,
    "total": 285043
  },
  "computedAt": "2026-04-16T14:32:18.412Z",
  "cacheTtlSeconds": 600
}

• computedAt tells the agent how stale the snapshot is.
• cacheTtlSeconds declares the cache window — a well-behaved agent can choose to trust the numbers for that window without re-asking.

Example prompts

use shadcnio to give me a summary of everything available

use shadcnio get_registry_stats and tell me how many pricing-category blocks I can pick from

use shadcnio — how many icons total do I have access to?

Manual invocation

curl -s -X POST "https://www.shadcn.io/api/mcp?token=YOUR_TOKEN" \
  -H "content-type: application/json" -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_registry_stats","arguments":{}}}' \
  | sed -n 's/^data: //p' | jq '.result.content[0].text | fromjson'

Tips + gotchas

• Counts, not premium/free split. This tool intentionally skips scanning file contents for @premium tags — that would require reading every file on cache miss, which we avoid. If you need the split, ask for list_items and filter client-side, or wait for a dedicated tool.
• blocks.categories counts folder names from content/blocks/meta.json, not the sum of blocks across categories (that's blocks.total).
• total for components is recursive because packages/components/ is organized into subcategories. For ai, hooks, etc. it's a flat count.
• Cache respects mtime indirectly. The 10-minute TTL catches any registry additions within that window. If you're in dev and just added a file, wait up to 10 minutes or restart the server.