mcpsystem.design MCP Server

# mcpsystem.design MCP Server A production-ready MCP (Model Context Protocol) server that exposes design system components and style guides for AI assistants. Deployed on Vercel with SSE transport for remote access. **Live Server:** https://www.mcpsystem.design/ ## Features - **Component Specifications**: Access detailed props, types, and descriptions for UI components - **Code Examples**: Get ready-to-use Tailwind CSS code snippets for each component - **Style Guide**: Retrieve colors, typography, spacing scales, and breakpoints - **Search**: Find components by name, description, or category - **SSE Transport**: Remote access via Server-Sent Events for web deployment - **Security Hardened**: Input validation, rate limiting, and structured logging ## Quick Start ### 1. Install Dependencies ```bash npm install ``` ### 2. Local Development Run the Next.js development server: ```bash npm run dev ``` The MCP SSE endpoint will be available at `http://localhost:3000/api/sse` ### 3. Deploy to Vercel ```bash # Install Vercel CLI if not already installed npm i -g vercel # Deploy vercel ``` ## Project Structure ``` ├── app/ # Next.js App Router │ ├── api/ │ │ └── sse/ │ │ └── route.ts # MCP SSE transport endpoint │ ├── patterns/ # Pattern documentation pages │ ├── docs/ # Documentation pages │ └── page.tsx # Landing page ├── lib/ │ ├── design-system/ # Design system data │ │ ├── index.ts # Main exports and helpers │ │ ├── components.ts # Component definitions │ │ ├── style-guide.ts # Colors, typography, spacing │ │ └── types.ts # TypeScript types │ ├── mcp/ # MCP protocol utilities │ │ ├── schemas.ts # Zod validation schemas │ │ ├── errors.ts # JSON-RPC error codes │ │ ├── logger.ts # Structured logging │ │ └── types.ts # TypeScript types │ └── security/ # Security utilities │ ├── host-validator.ts # Host header validation │ └── rate-limiter.ts # Rate limiting ├── components/ # React components for the website ├── packages/ # Publishable packages │ └── ui/ # @mcpsystem/ui Web Components ├── scripts/ # Build and validation scripts │ ├── validate-css-tokens.ts # CSS token validation │ └── validate-component-colors.ts # Component color validation ├── package.json ├── tsconfig.json ├── vercel.json └── README.md ``` ## API Endpoints | Endpoint | Method | Description | |----------|--------|-------------| | `/sse` or `/api/sse` | GET | Establish SSE connection | | `/sse` or `/api/sse` | POST | Send MCP JSON-RPC messages | | `/` | GET | Landing page | ## Available MCP Tools ### Pattern Tools (Tailwind CSS) Tailwind patterns are copy-paste HTML with class variations for variants, sizes, and states. | Tool | Description | |------|-------------| | `list_patterns` | List all Tailwind patterns with categories | | `get_pattern` | Get pattern with class variations | | `search_patterns` | Search patterns by name/description/category | | `get_pattern_examples` | Get code examples for a pattern | ### Style Guide Tools | Tool | Description | |------|-------------| | `get_style_guide` | Get entire style guide or specific section | | `get_colors` | Get color tokens (optionally by category) | | `get_typography` | Get typography styles | | `get_spacing` | Get spacing scale tokens | | `get_breakpoints` | Get responsive breakpoint definitions | | `get_design_system_info` | Get design system overview and stats | ### Component Tools (@mcpsystem/ui) @mcpsystem/ui components are Lit-based Web Components you import and use. | Tool | Description | |------|-------------| | `list_components` | List all @mcpsystem/ui components | | `get_component` | Get component docs with props, events, CSS parts | | `search_components` | Search components by name or description | ## Connecting to AI Assistants ### Cursor 1. Open Cursor Settings (`Cmd+,` on macOS or `Ctrl+,` on Windows/Linux) 2. Search for "MCP" or navigate to **Features → MCP Servers** 3. Click **"Add new MCP server"** 4. Configure with: - **Name:** `mcpdesignsystem` - **Type:** `sse` - **URL:** `https://www.mcpsystem.design/sse` Alternatively, add to your `.cursor/mcp.json` file: ```json { "mcpServers": { "mcpdesignsystem": { "url": "https://www.mcpsystem.design/sse" } } } ``` ### Claude Desktop Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS): ```json { "mcpServers": { "mcpdesignsystem": { "url": "https://www.mcpsystem.design/sse" } } } ``` ### Claude Code CLI Add to your `.claude/settings.json`: ```json { "mcpServers": { "mcpdesignsystem": { "url": "https://www.mcpsystem.design/sse" } } } ``` ## Customizing the Design System ### Modifying Components Edit `lib/design-system/components.ts` to add or modify components. Each component follows this structure: ```typescript { name: "ComponentName", slug: "component-name", description: "Component description", category: "Category", usageNote: "<!-- Tailwind CSS pattern - copy the HTML/classes below -->", tailwind: true, specs: { // Class variations - which Tailwind classes to swap variants: [ { name: "Primary", classes: "bg-primary text-primary-foreground" }, { name: "Secondary", classes: "bg-surface-hover text-default" } ], sizes: [ { name: "Small", classes: "h-8 px-3 text-xs" }, { name: "Medium", classes: "h-10 px-4 text-sm" } ], states: [ { name: "Disabled", classes: "opacity-70 cursor-not-allowed" } ] }, examples: [ { title: "Example Title", code: `<div className="...">Example</div>`, preview: "preview-id" } ], relatedComponents: ["OtherComponent"] } ``` ### Modifying Style Guide Update `lib/design-system/style-guide.ts`: - **Colors**: Organized by category (Semantic tokens, Gray Scale, Accent) - **Typography**: Font family, size, weight, line-height for each style - **Spacing**: Token name, CSS value, and pixel equivalent - **Breakpoints**: Responsive breakpoint values and descriptions ### Color Token Rules Component examples must use **semantic color tokens** instead of raw Tailwind colors: | Instead of | Use | |------------|-----| | `bg-gray-50`, `bg-gray-100` | `bg-surface`, `bg-surface-raised`, `bg-surface-sunken` | | `text-gray-600`, `text-gray-400` | `text-default`, `text-muted`, `text-subtle` | | `border-gray-200` | `border-default`, `border-muted`, `border-emphasis` | | `bg-red-500`, `text-red-600` | `bg-error-emphasis`, `text-error-foreground` | | `bg-green-500`, `text-emerald-600` | `bg-success-emphasis`, `text-success-foreground` | | `bg-amber-500` | `bg-warning-emphasis`, `text-warning-foreground` | | `bg-blue-500` | `bg-info-emphasis`, `text-info-foreground` | ## Validation The project includes two validation scripts that run automatically on build: ### CSS Token Validation Ensures CSS variables in `globals.css` match the design tokens in `style-guide.ts`: ```bash npm run validate:tokens ``` ### Component Color Validation Ensures component examples use semantic color tokens instead of raw Tailwind colors: ```bash npm run validate:component-colors ``` ### Run All Validations ```bash npm run validate ``` **Always run `npm run validate` before committing changes to ensure design system consistency.** ## Development ### Type Checking ```bash npm run typecheck ``` ### Validation ```bash npm run validate # Run all validations (recommended before commits) npm run validate:tokens # CSS token validation only npm run validate:component-colors # Component color validation only ``` ### Building ```bash npm run build # Runs validation + production build ``` ## Security The SSE endpoint includes several security hardening measures: ### Input Validation - All JSON-RPC requests are validated using Zod schemas - Tool arguments are type-checked before execution - Batch requests limited to 100 items maximum ### Rate Limiting - 100 requests per minute per IP address - Returns HTTP 429 with `Retry-After` header when exceeded - In-memory rate limiting (resets on cold starts) ### Host Header Validation - Whitelist-based validation prevents host header injection - Allowed hosts: `www.mcpsystem.design`, `mcpsystem.design`, `localhost` - Invalid hosts default to `www.mcpsystem.design` ### Structured Logging - All requests include unique request IDs (`X-Request-Id` header) - JSON-formatted logs for Vercel log aggregation - Request tracing for debugging and auditing ## Troubleshooting ### SSE Connection Issues - Ensure your client supports SSE transport for MCP - Check that CORS headers are properly configured for your client origin - Vercel has a 60-second timeout for serverless functions; long-running connections may be terminated ### Connection Drops The SSE endpoint sends periodic ping messages to keep the connection alive. If your client disconnects frequently, check your network configuration or proxy settings. ### Rate Limit Errors (HTTP 429) If you receive a 429 status code, you've exceeded the rate limit (100 requests/minute). Wait for the duration specified in the `Retry-After` header before retrying. ## License MIT