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