# shadcn.io MCP

You are working in a project with the shadcn.io MCP server connected (its name is `shadcnio`). It serves copy-paste components for React, Vue, Svelte and Solid, page blocks, icons from hundreds of libraries, brands' design systems as DESIGN.md files and starter templates, with install commands for the project's own stack. Look things up there before you write UI by hand, and install what it returns instead of retyping it.

## Before you call anything

- Pick the target from `package.json`, once, and pass it on every call:
  - `framework`: `react`, `vue`, `svelte` or `solid`.
  - `base`, for React only, the primitives the components are built on: `base` (Base UI, `@base-ui/react`, the default), `radix` (`radix-ui` or `@radix-ui/*`), `aria` (`react-aria-components`) or `ark` (`@ark-ui/react`). Use the one the project already has; Base UI when it has none. Never install a second primitive library into a project that has one.
  - Vue, Svelte and Solid components are built on Ark UI: pass only the framework.
- Read `components.json` for the aliases (`aliases.ui`, `aliases.utils`) and list the ui folder: pass what is there as `have`, so installs leave the project's own files alone.
- Read the lockfile for the package manager and pass it as `packageManager`.
- No `components.json` yet: call `get_project_setup` once (for React pass `stack`: `next`, `vite`, `tanstack-start`…, and `existing: true` for an app that already exists), run what it returns, then add components. Never run init again in a configured project.

## Find before you write

- A component: `search_components` with what it does ("date range", "modal", "toast"); shadcn/ui's names and other spellings find ours. `list_components` is the catalog by category.
- A pattern inside components ("controlled dialog", "combobox with groups", "form in a sheet"): `search_demos`, across every demo.
- A section or a screen (a pricing table, a settings page, a kanban board): `search_blocks` by what it does, or `list_blocks` by category. A whole page: `plan_page` with a one-line `brief` (and `kind`: `marketing` or `app`), then `get_block` with the picks' `names`.
- A brand's look ("like Linear", "a dark fintech"): `search_designs`, then `get_design`. Save its Markdown as `DESIGN.md` at the project's root and set the theme's tokens from it.
- A new app: `search_templates` may already have most of it.
- Icons: use the set the project has (`lucide-react`, `@tabler/icons-react`…). `search_icons` with `library` and several `queries` in one call, then `get_icon` with `names`: a set with a package returns the import, nothing to install.
- Ask for exactly what you need: one search with a good query beats three vague ones. Use `limit`.

## Install, don't paste

- `get_component` with `include: ["install", "usage"]` gives the command and a usage snippet in one call. Add `"demo"` or `"api"` only when you need them. Several components for one feature: pass `names` and get one install for all of them.
- Run the install command exactly as returned: React and Solid use the shadcn CLI, Vue `shadcn-vue`, Svelte `shadcn-svelte`. The URL carries the user's registry token: never print it in full, write it into source files, logs or commits, or strip it.
- No shell, or the user wants to review first: `get_install_plan` (with `have` and `packageManager`) returns every file, package and CSS change. Write the files at the project's aliases; a long plan names the rest in `pending`: request those as `files`.
- Blocks are part of Pro: `get_block` with `include: ["install"]`, `names` for a whole page in one command. If the server says an item needs Pro, tell the user; do not rebuild the block from memory and present it as the real one.
- After an install, import from the project's ui alias (`@/components/ui/dialog`), and check `usageNeeds`: a component the usage snippet imports that the install did not bring.

## Use components as their docs say

- Props and parts come from the server, not from memory: `get_component_api` for an outline (`part` or `prop` for one in full), `get_component_docs` with `sections` for the prose you need, `get_demo` for another demo (pass `uiAlias` from `components.json`, so its imports point at the project's folder).
- Follow the base's composition model and never mix them: Base UI merges onto a host with `render`, Radix and Ark UI with `asChild`, React Aria with render props and its own event names (`onPress`, `isDisabled`).
- Ark UI's Select, Combobox and Listbox take a `collection` built with its helpers, not a loose `items` array; follow the demo.
- Forms, theming, colors and RTL: `get_guide`. Each form field type has a demo per form library: `get_demo` with `name` `react-hook-form`, `tanstack-form` or `formisch`.
- Keep what the installed files give you: `data-slot` attributes, labels, focus handling and keyboard behavior. Extend a component with a prop or a wrapper; edit its file only for a change the whole project should get.

## Style it with the project's theme

- Use the theme's tokens (`bg-background`, `text-muted-foreground`, `border-input`, `bg-primary`), never palette classes (`gray-500`) or hex values. Dark mode follows from the tokens.
- Respect the project's radius, fonts and spacing; when a `DESIGN.md` exists, follow it.
- Layout with flex or grid and `gap-*`; logical properties (`ms-*`, `pe-*`, `start-*`) so RTL works.
- Icons: decorative ones get `aria-hidden="true"` and a `size-*` class, not a numeric `size` prop.

## Calls and limits

- Prefer one call with `include` or `names` to several round trips; the answers stay small unless you ask for source.
- When several MCP servers are connected, the user names this one ("use shadcnio to…"); for UI work, prefer it to guessing.
- `whoami` shows who is connected and the rate limit. If a call is rate limited or unauthorized, say so and stop; do not fall back to scraping the site.

## Do not

- Do not hand-write a component, block or icon the server has, or copy one from another registry from memory.
- Do not install for the wrong target: a Radix component into a Base UI project, a React file into a Svelte one.
- Do not invent registry URLs or item names: use the names and commands the tools return.
- Do not install the whole catalog "to be safe": add what the task needs.
- Do not overwrite files the user changed: pass `have`, and read a diff before accepting an overwrite prompt.

## Before you finish

- Run the project's type check and linter, and open the page you changed.
- List what you installed (components, blocks, icons), the commands you ran, and anything that needed Pro or a setup step the user still has to do.