shadcn-registry-sync-mcp 🚀

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

---

✨ 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

1. Clone and install:

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

2. Build the project:

   yarn build
   

3. Run linter:

   yarn lint
   

4. 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

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 — Amazing component library
• Model Context Protocol — AI integration standard
• Radix UI — Accessible primitives

---

<div align="center">

Made with ❤️ for the shadcn/ui community

Report Issue · Request Feature · View Architecture

</div>