# shadcnspace-mcp

Official Model Context Protocol (MCP) server for [Shadcn Space](https://shadcnspace.com).

This MCP server allows AI-powered IDEs and coding agents (Cursor, Windsurf, Claude Desktop, Cline, Antigravity, etc.) to discover, search, install, and architect **Shadcn Space** UI blocks, landing pages, and components directly inside your project — with zero copy-pasting.

## Quick Installation

### Using the CLI

```bash
npx shadcnspace-cli install <client>
```

### Supported Clients

- [x] cursor
- [x] windsurf
- [x] claude
- [x] cline
- [x] antigravity

## Manual Installation

Add to your IDE or client's MCP configuration (`mcpServers`):

```json
{
  "mcpServers": {
    "shadcnspace-mcp": {
      "command": "npx",
      "args": ["-y", "shadcnspace-mcp@latest"]
    }
  }
}
```

For more details, visit our documentation: [**How to use MCP Server**](https://shadcnspace.com/docs/getting-started/mcp-server-docs)

---

## Available Tools

The server provides **14 specialized tools** callable via MCP:

| Tool Name                  | Description                                                                                                                                                                                                                   |
| :------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `listCategories`           | Returns all 14 block categories (`hero`, `features`, `pricing`, `testimonials`, `faq`, `cta`, `header`, `footer`, `stats`, `forms`, `content`, `ecommerce`, `ai`, `widgets`) with live counts of total, free, and PRO blocks. |
| `listBlocks`               | Lists blocks with license info (`isPro`). Supports filtering by `category` and license type (`all`, `free`, `pro`).                                                                                                           |
| `listFreeBlocks`           | Lists only 100% free Shadcn Space blocks that do not require any license. Supports optional category and keyword filters.                                                                                                     |
| `listComponents`           | Lists base components with search query and license filter (`all`, `free`, `pro`).                                                                                                                                            |
| `getBlockInstall`          | Returns official installation command, component export name, import path, JSX example, style options (base/radix), and license requirements for a specific block.                                                            |
| `searchBlocks`             | Search blocks by keyword, category, and optional `freeOnly` filter.                                                                                                                                                           |
| `listInstalledBlocks`      | Lists blocks currently installed in the user's project and gets their files.                                                                                                                                                  |
| `listPages`                | Lists all Shadcn Space full pages.                                                                                                                                                                                            |
| `getPageInstall`           | Returns official installation command, export name, import path, usage example, and style options for a specific full page.                                                                                                   |
| `searchPages`              | Search full pages using keywords or tags.                                                                                                                                                                                     |
| `listInstalledPages`       | Lists pages currently installed in the project.                                                                                                                                                                               |
| `getLandingPageGuidelines` | Comprehensive UI/UX landing page architecture: section sequence (Hero -> Logos -> Features -> Testimonials -> Pricing -> FAQ -> CTA -> Footer), container standards, and vertical spacing cadence.                            |
| `handleError`              | Self-healing diagnostic tool for resolving license errors, missing `components.json`, component not found, and CLI installation failures.                                                                                     |
| `get_audit_checklist`      | Mandatory workflow rules for AI agents: style check (base/radix), package manager detection, license handling, and navbar deduplication.                                                                                      |

> **Note on Licensing:** All pages and PRO blocks require a valid license key and email configured under registries in `components.json`. Free blocks can be installed directly without any license.

---

## Available Prompts

The server provides **7 rich prompts** to accelerate UI architecture:

| Prompt / Command           | Description                                                                                               |
| :------------------------- | :-------------------------------------------------------------------------------------------------------- |
| `build-landing-page`       | Step-by-step guidance for an AI agent to architect and assemble a complete, high-converting landing page. |
| `add-hero-section`         | Find, install, and integrate a high-impact hero block into an existing page.                              |
| `add-pricing-section`      | Add a multi-tier pricing table with monthly/annual billing toggles.                                       |
| `add-feature-grid`         | Add a modern feature showcase or bento grid section.                                                      |
| `create-ui`                | General prompt to architect a full UI page using Shadcn Space blocks.                                     |
| `search`                   | Find specific UI blocks by topic or keyword.                                                              |
| `customization-guidelines` | Strict guidelines defining which parts of installed blocks can be safely customized (text only).          |

---

## Testing & Debugging with MCP Inspector

You can interactively inspect, test, and debug all tools and prompts in your browser using the official MCP Inspector:

```bash
npm run inspector
```

---

## Example Agent Usage

Once configured in your AI IDE, you can ask prompts like:

> _"Show me all free hero blocks available in Shadcn Space."_

> _"Build a complete SaaS landing page for an AI productivity app using hero, bento features, testimonials, pricing, and FAQ."_

> _"Give me the install command and import statement for `pricing-01` in base style."_

> _"What categories of blocks are available in Shadcn Space?"_

---

## Agent Instructions (Claude / Cursor / Windsurf)

To ensure your AI assistant follows official Shadcn Space best practices (checking Base vs Radix, package managers, and avoiding duplicate navbars), copy the system prompt in [claude-instructions.md](claude-instructions.md) into your `.cursorrules`, `.windsurfrules`, or Claude Project Instructions.

---

## License & Credits

Created by [Shadcn Space](https://shadcnspace.com).

[MIT](LICENSE.md)