# shadcn-registry-sync-mcp 🚀

> **Automate your shadcn/ui registry maintenance with AI-powered precision**

[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue.svg)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-Server-green.svg)](https://modelcontextprotocol.io/)
[![shadcn/ui](https://img.shields.io/badge/shadcn-ui-black.svg)](https://ui.shadcn.com/)
[![Commitizen](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
[![Code Style](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://prettier.io/)

---

## ✨ Why This Tool?

Tired of manually updating `registry.json` every time you create a new component?

**shadcn-registry-sync-mcp** is an intelligent MCP server that automatically scans your project, detects components, analyzes dependencies, and generates a production-ready `registry.json` — all with a single command to your AI assistant.

### 🎯 What You Get

| Before                     | After                     |
| -------------------------- | ------------------------- |
| ❌ Manual registry updates | ✅ **One-command sync**   |
| ❌ Missing dependencies    | ✅ **Auto-detected deps** |
| ❌ Inconsistent metadata   | ✅ **Smart descriptions** |
| ❌ Error-prone copy-paste  | ✅ **100% automated**     |

---

## 🚀 Quick Start

### 1. Install & Build

```bash
yarn install
yarn build
```

### 2. Configure Your MCP Client

Add to your MCP configuration (e.g., `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "shadcn-registry-sync": {
      "command": "node",
      "args": ["/path/to/shadcn-registry-sync-mcp/dist/index.js"],
      "cwd": "/path/to/shadcn-registry-sync-mcp"
    }
  }
}
```

### 3. Use with Your AI Assistant

Simply tell your AI:

> **"Sync my shadcn registry"**

Or:

> **"Update registry.json for my project at /path/to/project"**

That's it! ✨

---

## 🎁 Features

### 🔍 Intelligent Scanning

Automatically discovers components in:

- `src/components/*` — UI components
- `src/features/*` — Feature modules (layouts, components, models)
- `src/hooks/*` — Custom React hooks
- `src/lib/*` — Utility libraries
- `src/types/*` — TypeScript definitions

### 🧠 Smart Dependency Analysis

```typescript
// Your component
import { Button } from '@/components/button';
import { Slot } from '@radix-ui/react-slot';

// Auto-detected:
// - registryDependencies: ["@shadcn-ui/button"]
// - dependencies: ["@radix-ui/react-slot"]
```

### 📝 Auto-Generated Descriptions

The tool analyzes your source code to generate meaningful descriptions:

```typescript
// DialogDeleteUser.tsx
/**
 * Confirmation dialog for deleting users
 */
export function DialogDeleteUser() { ... }

// → description: "Confirmation dialog for deleting users"
```

**Pattern Recognition:**

- `dialog-delete-*` → "Confirmation dialog for deleting \*"
- `drawer-configure-*` → "Configuration drawer for \*"
- `chart-trend-*` → "Trend line chart visualization"
- `*-models` → "Data models, types, and API service functions"

### 🎯 shadcn/ui Compatible

Output follows the official shadcn/ui registry schema:

```json
{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "shadcn-ui",
  "homepage": "https://ui.shadcn.com",
  "items": [
    {
      "name": "button",
      "type": "registry:component",
      "title": "Button",
      "description": "A reusable button component",
      "files": [...],
      "dependencies": ["@radix-ui/react-slot"],
      "registryDependencies": ["@shadcn-ui/icon"]
    }
  ]
}
```

---

## 💡 Use Cases

### For Component Library Maintainers

Keep your registry in sync with zero effort:

```
Developer: "I just added 5 new components to src/components"
AI: "I'll sync the registry for you."
→ registry.json updated automatically
```

### For Large Projects

Handle complex feature-based architectures:

```
src/features/
├── auth/
│   ├── components/
│   │   ├── dialog-login/
│   │   └── dialog-otp/
│   ├── layouts/
│   │   └── login-page-layout/
│   └── models/
└── report/
    └── components/
        └── chart-trend-double-line/

→ All detected and categorized correctly
```

### For Teams

Ensure consistent registry structure across the team:

```
No more:
- "Who forgot to update the registry?"
- "Why are dependencies missing?"
- "Why does this component break when installed?"
```

---

## 🛠️ Manual Usage

Run standalone without MCP:

```bash
# Set project root
export PROJECT_ROOT=/path/to/your/project

# Run sync
node run-local.js
```

Output:

```
[run-local] Project root: /path/to/your/project
[run-local] Scanning...
[run-local] Found 42 items
[run-local] Building registry...
[run-local] Written to /path/to/your/project/registry.json
```

---

## 📊 What Gets Synced?

| Type           | Directory          | Registry Type        | Example                        |
| -------------- | ------------------ | -------------------- | ------------------------------ |
| **Components** | `src/components/*` | `registry:component` | button, card, dialog           |
| **Blocks**     | `src/features/*`   | `registry:block`     | layouts, multi-file components |
| **Hooks**      | `src/hooks/*`      | `registry:hook`      | use-mobile, use-debounce       |
| **Libraries**  | `src/lib/*`        | `registry:lib`       | utils, axios, storage          |
| **Types**      | `src/types/*.d.ts` | `registry:file`      | tanstack-table, zod-schema     |

---

## 🔧 Configuration

### Customize Scan Directories

Edit `src/constants.ts`:

```typescript
export const COMPONENT_DIRS = ['src/components', 'src/ui', 'src/shared'];
export const FEATURE_DIR = 'src/features';
export const HOOKS_DIR = 'src/hooks';
export const LIB_DIR = 'src/lib';
export const TYPES_DIR = 'src/types';
```

### Skip Patterns

```typescript
export const SKIP_FILE_PATTERNS = [
  /\.stories\.tsx?$/, // Storybook
  /\.test\.tsx?$/, // Tests
  /\.spec\.tsx?$/, // Specs
];

export const LIB_SKIP_DIRS = ['storybook', 'docs'];
```

### Dependency Filters

```typescript
export const FRAMEWORK_DEPS = new Set([
  'react',
  'react-dom',
  'react-router',
  // These won't be tracked as dependencies
]);
```

---

## 🏗️ Architecture

For detailed architecture documentation, see [ARCHITECTURE.md](./ARCHITECTURE.md).

**Key Modules:**

- **scanner.ts** — Discovers components in your project
- **parser.ts** — Analyzes imports and classifies dependencies
- **builder.ts** — Constructs shadcn-compatible registry
- **describer.ts** — Generates smart descriptions from source code

---

## 🧪 Development

### Build

```bash
npm run build
```

### Watch Mode

```bash
npm run dev
```

### Test Locally

```bash
# Point to your project
export PROJECT_ROOT=/path/to/test/project
node run-local.js

# Verify output
cat registry.json | jq '.items | length'
```

---

## 📝 Example Output

After running sync, your `registry.json` will look like:

```json
{
  "$schema": "https://ui.shadcn.com/schema/registry.json",
  "name": "shadcn-ui",
  "homepage": "https://ui.shadcn.com",
  "items": [
    {
      "name": "utils",
      "type": "registry:lib",
      "title": "Utils",
      "description": "General utility functions including className merging (cn) and common helper methods",
      "files": [
        {
          "type": "registry:lib",
          "path": "src/lib/utils.ts"
        }
      ]
    },
    {
      "name": "use-mobile",
      "type": "registry:hook",
      "title": "useMobile",
      "description": "React hook for detecting mobile viewport. Returns a boolean indicating whether the current screen width is below the mobile breakpoint",
      "files": [
        {
          "type": "registry:hook",
          "path": "src/hooks/use-mobile.ts"
        }
      ],
      "dependencies": ["react"]
    },
    {
      "name": "button",
      "type": "registry:component",
      "title": "Button",
      "description": "A reusable button component built on Radix UI Slot",
      "files": [
        {
          "type": "registry:component",
          "path": "src/components/button/index.tsx"
        }
      ],
      "dependencies": ["@radix-ui/react-slot", "class-variance-authority"],
      "registryDependencies": ["@shadcn-ui/icon"]
    }
  ]
}
```

---

## 🛠️ Development

### Setup Development Environment

1. **Clone and install**:

   ```bash
   git clone https://github.com/your-org/shadcn-registry-sync-mcp.git
   cd shadcn-registry-sync-mcp
   yarn install
   ```

2. **Build the project**:

   ```bash
   yarn build
   ```

3. **Run linter**:

   ```bash
   yarn lint
   ```

4. **Format code**:
   ```bash
   yarn format
   ```

### Available Scripts

| Command             | Description                        |
| ------------------- | ---------------------------------- |
| `yarn build`        | Compile TypeScript to JavaScript   |
| `yarn dev`          | Watch mode for development         |
| `yarn lint`         | Run ESLint                         |
| `yarn lint:fix`     | Auto-fix ESLint errors             |
| `yarn format`       | Format code with Prettier          |
| `yarn format:check` | Check code formatting              |
| `yarn check`        | Run both lint and format check     |
| `yarn commit`       | Interactive commit with Commitizen |

### Commit Guidelines

This project uses **Commitizen** for standardized commit messages:

```bash
yarn commit
```

This will launch an interactive prompt that helps you create commits following the [Conventional Commits](https://www.conventionalcommits.org/) specification.

**Commit types:**

- `feat`: New features
- `fix`: Bug fixes
- `docs`: Documentation changes
- `style`: Code style changes (formatting, etc.)
- `refactor`: Code refactoring
- `perf`: Performance improvements
- `test`: Adding tests
- `build`: Build system changes
- `ci`: CI/CD changes
- `chore`: Maintenance tasks
- `revert`: Reverting changes

**Pre-commit hooks** automatically run linting and formatting on staged files using Husky and lint-staged.

---

## 📝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:

- Development setup
- Code standards
- Commit message format
- Pull request process
- Testing guidelines

---

## 🤝 Contributing

Contributions are welcome! See our [Architecture Guide](./ARCHITECTURE.md) for understanding the codebase.

### Quick Contribution Guide

1. **Fork** the repository
2. **Create** a feature branch: `git checkout -b feature/amazing-feature`
3. **Make** your changes
4. **Build** and **test**: `yarn build && node run-local.js`
5. **Commit** and **push**
6. **Open** a Pull Request

---

## 📄 License

MIT License — feel free to use in your projects!

---

## 🙏 Acknowledgments

- [shadcn/ui](https://ui.shadcn.com/) — Amazing component library
- [Model Context Protocol](https://modelcontextprotocol.io/) — AI integration standard
- [Radix UI](https://www.radix-ui.com/) — Accessible primitives

---

<div align="center">

**Made with ❤️ for the shadcn/ui community**

[Report Issue](https://github.com/dianramdhani/shadcn-registry-sync-mcp/issues) · [Request Feature](https://github.com/dianramdhani/shadcn-registry-sync-mcp/issues) · [View Architecture](./ARCHITECTURE.md)

</div>