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

1. Clone the repository

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

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

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

Component Development Workflow

1. Develop component in frontend/src/components/
2. Create interactive stories for documentation
3. Test component in Storybook
4. MCP server automatically discovers new components
5. 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

1. Fork the repository
2. Create a feature branch
3. Add your component with proper stories
4. Test in Storybook
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details

🔗 Links

• Model Context Protocol Documentation
• Storybook Documentation
• Tailwind CSS Documentation
• React Documentation

---

Built with ❤️ for modern design systems and AI integration