list_blocks_in_category

After the agent has a category (via list_block_categories), this tool hands back every slug inside it. Cheaper than scanning the full 6000-block index and more accurate than matching on title substrings.

When to use

• The agent committed to a category ("let's add a pricing section") and needs to see the candidates.
• Building a "compare blocks in the same category" prompt.
• Before calling get_item or get_install_command — you need an exact slug.

How it works

1. readdirSync('packages/blocks/{category}') — a direct filesystem scan.
2. Filters to *.tsx files.
3. Strips the .tsx extension.
4. Sorts alphabetically.
5. Caches the result in a per-category Map for the life of the Node process.

If the category folder doesn't exist, returns an empty array (not an error).

Source: lib/mcp/content-loader.ts#listBlocksInCategory.

Category folder names must match exactly — list_block_categories returns the canonical forms.

Arguments

Response

{
  "category": "pricing",
  "count": 5,
  "totalInCategory": 40,
  "slugs": [
    "pricing-basic-toggle",
    "pricing-featured-hero-shelves",
    "pricing-grouped-comparison-table",
    "pricing-metric-hero-tiles",
    "pricing-split-highlight"
  ]
}

• count = number of slugs in this response (respects limit).
• totalInCategory = total count in the category, so the agent knows if it truncated.
• Every slug is installable via get_install_command — no further resolution needed.

Example prompts

use shadcnio to list every pricing block

use shadcnio to list five hero blocks and give me the source of the one that sounds most suited to a dev tool landing page

use shadcnio and compare the first 3 cta blocks — summarize their layouts from the source

Manual invocation

curl -s -X POST "https://www.shadcn.io/api/mcp?token=YOUR_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_blocks_in_category",
      "arguments": {
        "category": "pricing",
        "limit": 5
      }
    }
  }' | jq '.result.content[0].text | fromjson | .slugs'

Tips + gotchas

• Exact match on category — hero works, Hero doesn't, heroes doesn't. If the agent got the name from list_block_categories, it'll be right.
• Unknown category → empty list, not error — this is intentional so the agent can probe without triggering failure paths.
• Per-category cache — the first call to a category does disk I/O; subsequent calls are pure memory reads. Adding a new block requires a server restart to show up.
• Slug naming convention — most slugs start with the category prefix (hero-announcement, pricing-split-highlight), but it's a convention, not a rule enforced by the tool.
• Block URLs are flat — the slug alone forms the URL: /blocks/{slug}. Never construct /blocks/{category}/{slug} — that's not a real route.