# MCP Server Starter Template
A comprehensive starter template for building **Model Context Protocol (MCP) servers**, specifically designed for UI libraries and component registries. This template provides a robust foundation for creating MCP servers that can fetch, categorize, and provide component information to AI assistants like Claude.
## 🌎 Real world example?
Check out the [stackzero-labs/mcp](https://github.com/stackzero-labs/mcp) which uses this template to expose its UI components and blocks to AI models. You can also checkout the UI referenced project [stackzero/ui](https://github.com/stackzero-labs/ui)
## 🚀 Features
- **Ready-to-use MCP server** with TypeScript support
- **Component registry integration** for UI libraries
- **Categorized component organization** with flexible category system
- **Zod schema validation** for type safety
- **Development tools** including hot reload and inspector
- **Example implementation** using a real project URL for demonstration
- **Extensible architecture** for custom component types and categories
## 📋 Prerequisites
- Node.js 18 or higher
- pnpm (recommended) or npm
- Basic understanding of TypeScript and MCP
## 🤝 Intended Use Cases
This template is specifically designed for libraries following the `registry` format (like `shadcn/ui`), making it ideal for:
- UI component libraries
- Design systems
- Component registries that need to be accessible via AI assistants
- Tools, utilities, and frameworks that require a structured way to expose UI components to AI models
> Read more about components registries like shadcn/ui here [Component Registries](https://ui.shadcn.com/docs/registry).
With some customizations however, it can be adapted for other types of MCP servers as well.
## 🛠️ Installation
1. Clone or download this template:
```bash
git clone https://github.com/mnove/mcp-starter.git
cd mcp-starter
```
2. Install dependencies:
```bash
pnpm install
```
3. Build the project:
```bash
pnpm run build
```
## ⚙️ Configuration
### 1. Update Project Configuration
Edit `src/lib/config.ts` to point to your own component registry:
```typescript
export const mcpConfig = {
projectName: "your-project-name",
// Replace with your actual project URL
baseUrl: "https://your-ui-library.com",
registryUrl: "https://your-ui-library.com/r",
registryFileUrl: "https://your-ui-library.com/registry.json",
};
```
**Note**: This template currently uses `https://ui.stackzero.co` as a demonstration URL. You **must** replace this with your actual project URL for production use.
### 2. Define Component Categories
Customize `src/lib/categories.ts` to match your component structure:
```typescript
export const componentCategories = {
Buttons: ["button-primary", "button-secondary", "button-ghost"],
Forms: ["input-text", "input-email", "textarea"],
// Add your categories here
};
```
### 3. Update Server Metadata
Modify `src/server.ts` to customize your server information:
```typescript
const server = new McpServer({
name: "your-mcp-server-name",
version: "1.0.0",
});
```
## 🏃♂️ Development
### Start Development Server
```bash
pnpm run dev
```
### Build for Production
```bash
pnpm run build
```
### Inspect MCP Server
```bash
pnpm run inspect
```
This opens the MCP Inspector to test your server tools interactively.
## 📚 Available Tools
The MCP server provides the following tools:
### `getUIComponents`
Returns a comprehensive list of all UI components from your registry.
### Category-specific Tools
Dynamic tools are created for each category defined in `componentCategories`:
- `getButtons` - Get all button components
- `getForms` - Get all form components
- etc.
Each category tool provides:
- Component implementation details
- Usage examples
- Installation instructions
- Related components
## 🏗️ Project Structure
```
mcp-starter/
├── src/
│ ├── server.ts # Main MCP server implementation
│ ├── lib/
│ │ ├── config.ts # Configuration settings
│ │ └── categories.ts # Component categories
│ └── utils/
│ ├── api.ts # API fetching utilities
│ ├── formatters.ts # Data formatting helpers
│ ├── schemas.ts # Zod validation schemas
│ └── index.ts # Utility exports
├── dist/ # Built files
├── package.json
└── README.md
```
## 🔧 Customization
### Adding New Component Types
1. **Update schemas** in `src/utils/schemas.ts`:
```typescript
export const CustomComponentSchema = z.object({
name: z.string(),
category: z.string(),
// Add your fields
});
```
2. **Add API functions** in `src/utils/api.ts`:
```typescript
export async function fetchCustomComponents() {
// Your implementation
}
```
3. **Register new tools** in `src/server.ts`:
```typescript
server.tool("getCustomComponents" /*...*/);
```
### Extending Categories
Simply add new categories to `src/lib/categories.ts`:
```typescript
export const componentCategories = {
// Existing categories...
Navigation: ["navbar", "sidebar", "breadcrumbs"],
DataDisplay: ["table", "card", "badge"],
};
```
The server will automatically create tools for new categories.
### Why categories?
Categories help organize components logically, making it easier for AI assistants to find and suggest relevant components based.
Also, some models and IDE have a limit on the number of tools they can handle, so categorizing helps to keep the number of tools manageable.
## 📖 Registry Format
Your component registry should follow this structure:
### Registry File (`registry.json`)
```json
{
"registry": [
{
"name": "button-primary",
"type": "registry:component",
"description": "Primary button component"
}
]
}
```
### Component Details (`/r/{component-name}.json`)
```json
{
"name": "button-primary",
"type": "registry:component",
"files": [
{
"content": "// Component implementation"
}
]
}
```
## 🚀 Deployment
### As a Local MCP Server
1. Build the project:
```bash
pnpm run build
```
2. Configure in your MCP client (e.g., Claude Desktop):
```json
{
"mcpServers": {
"your-mcp-server": {
"command": "node",
"args": ["/path/to/mcp-starter/dist/server.js"]
}
}
}
```
### As an NPM Package
You can also publish this template as an NPM package for easy installation in other projects.
1. Update `package.json` with your details
2. Build and publish:
```bash
pnpm run build
npm publish
```
## 🤝 Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to this project.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🤝 Contact
Marcello - [@mnove](https://github.com/mnove)
## 🙏 Acknowledgments
- Built with [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)
- Inspired by the need for better AI-component integration
- Thanks to the MCP community for their contributions
---
**⚠️ Important**: Remember to replace `https://ui.stackzero.co` with your actual project URL before using this template in production!
