shadcn-registry-sync-mcp 🚀

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

![TypeScript](https://www.typescriptlang.org/) ![MCP](https://modelcontextprotocol.io/) ![shadcn/ui](https://ui.shadcn.com/) ![Commitizen](http://commitizen.github.io/cz-cli/) ![Code Style](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

yarn install
yarn build

2. Configure Your MCP Client

Add to your MCP configuration (e.g., claude_desktop_config.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

// 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:

// 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:

{
  "$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:

# 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:

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

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

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

Dependency Filters

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.

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

npm run build

Watch Mode

npm run dev

Test Locally

# 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:

{
  "$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

Clone and install:

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

Build the project:

   yarn build

Run linter:

   yarn lint

Format code:

   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:

yarn commit

This will launch an interactive prompt that helps you create commits following the Conventional Commits 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 for details on:

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

---

🤝 Contributing

Contributions are welcome! See our Architecture Guide for understanding the codebase.

Quick Contribution Guide

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

---

📄 License

MIT License — feel free to use in your projects!

---

🙏 Acknowledgments

shadcn/ui — Amazing component library
Model Context Protocol — AI integration standard
Radix UI — Accessible primitives

---

Made with ❤️ for the shadcn/ui community

Report Issue · Request Feature · View Architecture

</div>

shadcn-registry-sync-mcp