mcp-server-storybook-design-system by caroolt - MCP Server

System Design MCP

A comprehensive design system with Model Context Protocol (MCP) integration, featuring a React frontend with Storybook documentation and a Node.js backend that provides AI-powered component discovery and code generation capabilities.

🏗️ Project Architecture

This is a monorepo containing:

Frontend: React-based design system with Storybook documentation
Backend: MCP server for AI integration with component discovery and code generation
Integration: Seamless connection between design system and AI tools

🚀 Features

Frontend (Design System)

Modern React Components: Button, Card, Input, and more
Storybook Documentation: Interactive component playground
Tailwind CSS: Utility-first styling
TypeScript: Full type safety
Hot Module Replacement: Fast development experience

Backend (MCP Server)

Component Discovery: AI-powered component search and listing
Code Generation: Automatic JSX code generation with props
Storybook Integration: Real-time scraping of component documentation
Caching: Performance optimization with intelligent caching
Multiple Tools: Comprehensive API for component interaction

🛠️ Tech Stack

Frontend

React 18 - UI library
Vite - Build tool and dev server
Storybook 7 - Component documentation
Tailwind CSS 4 - Styling framework
TypeScript - Type safety

Backend

Node.js - Runtime environment
Model Context Protocol (MCP) - AI integration protocol
Express - Web framework (if needed)
Cheerio - HTML parsing for Storybook scraping
Node Cache - Performance caching
Zod - Schema validation

📦 Available Components

Button

Versatile button component with multiple variants:

Variants: primary, secondary, outline, ghost
Sizes: sm, md, lg
States: normal, disabled

Card

Flexible container component:

Variants: default, elevated, outlined
Padding: sm, md, lg
Features: optional title and subtitle

Input

Form input component with validation:

Types: text, email, password, number, tel, url
Sizes: sm, md, lg
States: normal, error, disabled, required
Features: label, help text, error message

🚀 Quick Start

Prerequisites

Node.js 18+
pnpm (recommended) or npm

Installation

Clone the repository

git clone <repository-url>
cd system-design-mcp

Install dependencies

# Install all dependencies (root + frontend + backend)
pnpm install:all

# Or install individually
pnpm install
pnpm --filter frontend install
pnpm --filter backend install

Development

Start Everything (Recommended)

# Start both frontend and backend concurrently
pnpm dev

Start Individual Services

# Frontend only (Vite dev server)
pnpm dev:frontend

# Backend only (MCP server)
pnpm dev:backend

# Storybook only
pnpm dev:storybook

Access Points

Frontend Application: http://localhost:5173
Storybook Documentation: http://localhost:6006
MCP Server: Runs via stdio (for AI integration)

🔧 MCP Server Tools

The backend provides several AI-powered tools for component interaction:

1. `list-components`

Lists all available components in the design system.

2. `get-component-info`

Retrieves detailed information about a specific component including:

Props and their types
Default values
Descriptions
Available examples

3. `generate-component-code`

Generates JSX code for a component with specific properties.

4. `search-components`

Searches components by functionality or keywords.

5. `get-component-examples`

Retrieves usage examples for a specific component.

6. `check-storybook-status`

Verifies Storybook accessibility and status.

📁 Project Structure

system-design-mcp/
├── frontend/                 # React design system
│   ├── src/
│   │   ├── components/       # Reusable components
│   │   │   ├── Button.tsx
│   │   │   ├── Button.stories.tsx
│   │   │   ├── Card.tsx
│   │   │   ├── Card.stories.tsx
│   │   │   ├── Input.tsx
│   │   │   ├── Input.stories.tsx
│   │   │   └── index.ts
│   │   ├── App.tsx
│   │   ├── main.tsx
│   │   └── index.css
│   ├── .storybook/          # Storybook configuration
│   ├── package.json
│   └── vite.config.ts
├── backend/                 # MCP server
│   ├── src/
│   │   └── mcp-server.ts    # Main MCP server implementation
│   ├── package.json
│   └── tsconfig.json
├── package.json             # Root package.json
├── pnpm-workspace.yaml      # Monorepo configuration
└── README.md

🎨 Design System Usage

Adding New Components

Create the component in frontend/src/components/
Create the story in frontend/src/components/[Component].stories.tsx
Export the component in frontend/src/components/index.ts
View in Storybook: pnpm dev:storybook
View in app: pnpm dev:frontend

Component Development Workflow

Develop component in frontend/src/components/
Create interactive stories for documentation
Test component in Storybook
MCP server automatically discovers new components
AI tools can immediately access component information

🔌 AI Integration

The MCP server enables AI tools to:

Discover Components: Automatically find all available components
Understand Props: Get detailed prop information and types
Generate Code: Create JSX code with proper props
Search Components: Find components by functionality
Access Examples: Get real usage examples from Storybook

Example AI Usage

// AI can ask: "Show me all button components"
// MCP responds with: Button component details, props, examples

// AI can ask: "Generate a primary button with 'Click me' text"
// MCP responds with: <Button variant="primary">Click me</Button>

🚀 Production Deployment

Build All

pnpm build

Build Individual Services

pnpm build:frontend
pnpm build:backend

Start Production Server

pnpm start

🧪 Testing

# Run backend tests
pnpm test

📝 Environment Variables

Create a .env file in the backend directory:

STORYBOOK_URL=http://localhost:6006
STORYBOOK_API_URL=http://localhost:6006
CACHE_TIMEOUT=300

🤝 Contributing

Fork the repository
Create a feature branch
Add your component with proper stories
Test in Storybook
Submit a pull request

📄 License

MIT License - see LICENSE file for details

🔗 Links

Built with ❤️ for modern design systems and AI integration