A Model Context Protocol (MCP) server that extracts component information from Storybook design systems. Connects to Storybook instances and extracts HTML, styles, and component metadata. With self-signed certificate: Then configure in your MCP client (see Environment Variables). - Puppeteer: Uses headless Chrome for dynamic JavaScript component rendering - Chrome/Chromium: Required for Puppeteer
Add this skill
npx mdskills install freema/mcp-design-system-extractorWell-documented Storybook extractor with 9 useful tools, async job handling, and clear examples
1# MCP Design System Extractor23A Model Context Protocol (MCP) server that extracts component information from Storybook design systems. Connects to Storybook instances and extracts HTML, styles, and component metadata.4567## Installation89### Using Claude CLI (Recommended)1011```bash12claude mcp add design-system npx mcp-design-system-extractor@latest \13 --env STORYBOOK_URL=http://localhost:600614```1516With self-signed certificate:17```bash18claude mcp add design-system npx mcp-design-system-extractor@latest \19 --env STORYBOOK_URL=https://my-storybook.example.com \20 --env NODE_TLS_REJECT_UNAUTHORIZED=021```2223### Using npm2425```bash26npm install -g mcp-design-system-extractor27```2829Then configure in your MCP client (see [Environment Variables](#environment-variables)).3031### From Source3233```bash34git clone https://github.com/freema/mcp-design-system-extractor.git35cd mcp-design-system-extractor36npm install && npm run build37npm run setup # Interactive setup for Claude Desktop38```3940## Key Dependencies4142- **Puppeteer**: Uses headless Chrome for dynamic JavaScript component rendering43- **Chrome/Chromium**: Required for Puppeteer (automatically handled in Docker)44- Works with built Storybook distributions4546<a href="https://glama.ai/mcp/servers/@freema/mcp-design-system-extractor">47 <img width="380" height="200" src="https://glama.ai/mcp/servers/@freema/mcp-design-system-extractor/badge" alt="Design System Extractor MCP server" />48</a>4950## Features5152- **List Components**: Get all available components from your Storybook with compact mode53- **Extract HTML**: Get the rendered HTML of any component (async or sync mode)54- **Search Components**: Find components by name, title, category, or purpose55- **Component Dependencies**: Analyze which components are used within other components56- **Theme Information**: Extract design system theme (colors, spacing, typography)57- **External CSS Analysis**: Fetch and analyze CSS files to extract design tokens58- **Async Job Queue**: Long-running operations run in background with job tracking5960## Environment Variables6162| Variable | Description | Default |63|----------|-------------|---------|64| `STORYBOOK_URL` | URL of your Storybook instance | `http://localhost:6006` |65| `NODE_TLS_REJECT_UNAUTHORIZED` | Set to `0` to skip SSL certificate verification (for self-signed certs) | `1` |6667**Example with self-signed certificate:**68```json69{70 "mcpServers": {71 "design-system": {72 "command": "node",73 "args": ["/path/to/dist/index.js"],74 "env": {75 "STORYBOOK_URL": "https://my-storybook.example.com",76 "NODE_TLS_REJECT_UNAUTHORIZED": "0"77 }78 }79 }80}81```8283## Usage8485See [DEVELOPMENT.md](./DEVELOPMENT.md) for detailed setup instructions.8687## Available Tools (9 total)8889### Core Tools90911. **list_components**92 - Lists all available components from the Storybook instance93 - Use `compact: true` for minimal output (reduces response size)94 - Filter by `category` parameter95 - Supports pagination with `page` and `pageSize` (default: 20)96972. **get_component_html**98 - Extracts HTML from a specific component story99 - **Async by default**: Returns `job_id`, use `job_status` to poll for results100 - Set `async: false` for synchronous mode (uses `timeout` parameter)101 - Use `variantsOnly: true` to get list of available variants (sync, fast)102 - Optional `includeStyles: true` for CSS extraction (Storybook CSS filtered out)103 - Story ID format: `"component-name--story-name"` or just `"component-name"` (auto-resolves to default variant)1041053. **search_components**106 - Search components by name, title, category, or purpose107 - `query`: Search term (use `"*"` for all)108 - `purpose`: Find by function ("form inputs", "navigation", "feedback", "buttons", etc.)109 - `searchIn`: "name", "title", "category", or "all" (default)110 - Supports pagination with `page` and `pageSize`111112### Component Analysis Tools1131144. **get_component_dependencies**115 - Analyzes rendered HTML to find which other components are used internally116 - Detects React components, web components, and CSS class patterns117 - Requires story ID format: `"component-name--story-name"`118119### Design System Tools1201215. **get_theme_info**122 - Extracts design system theme (colors, spacing, typography, breakpoints)123 - Gets CSS custom properties/variables124 - Use `includeAll: true` for all CSS variables1251266. **get_external_css**127 - **DEFAULT**: Returns only design tokens + file stats (avoids token limits)128 - Extracts & categorizes tokens: colors, spacing, typography, shadows129 - Use `includeFullCSS: true` only when you need full CSS content130 - Security-protected: only accepts URLs from same domain as Storybook131132### Job Management Tools1331347. **job_status**135 - Check status of an async job136 - Returns: `status`, `result` (when completed), `error` (when failed)137 - Poll this after calling `get_component_html` in async mode1381398. **job_cancel**140 - Cancel a queued or running job141 - Returns whether cancellation was successful1421439. **job_list**144 - List all jobs with their status145 - Filter by `status`: "all" (default), "active" (queued/running), "completed"146 - Returns job list + queue statistics147148## Example Usage149150```typescript151// List all components (compact mode recommended)152await list_components({ compact: true });153154// Search for components155await search_components({ query: "button", searchIn: "name" });156157// Find components by purpose158await search_components({ purpose: "form inputs" });159160// Get variants for a component161await get_component_html({162 componentId: "button",163 variantsOnly: true164});165// Returns: { variants: ["primary", "secondary", "disabled"] }166167// Get HTML (async mode - default)168await get_component_html({ componentId: "button--primary" });169// Returns: { job_id: "job_xxx", status: "queued" }170171// Poll for result172await job_status({ job_id: "job_xxx" });173// Returns: { status: "completed", result: { html: "...", classes: [...] } }174175// Get HTML (sync mode)176await get_component_html({177 componentId: "button--primary",178 async: false,179 timeout: 30000180});181// Returns: { html: "...", classes: [...] }182183// Get HTML with styles184await get_component_html({185 componentId: "button--primary",186 async: false,187 includeStyles: true188});189190// Check all running jobs191await job_list({ status: "active" });192193// Extract theme info194await get_theme_info({ includeAll: false });195196// Get design tokens from CSS197await get_external_css({198 cssUrl: "https://my-storybook.com/assets/main.css"199});200```201202### AI Assistant Usage Tips2032041. **Start with discovery**: Use `list_components` with `compact: true`2052. **Get variants first**: Use `get_component_html` with `variantsOnly: true`2063. **Use async for HTML**: Default async mode prevents timeouts on large components2074. **Poll job_status**: Check job completion before reading results2085. **Search by purpose**: Use `search_components` with `purpose` parameter209210## Example Prompts211212Once connected, you can use natural language prompts with Claude:213214215216**Component Discovery:**217```218Show me all available button components in the design system219```220221**Building New Features:**222```223I need to create a user profile card. Find relevant components224from the design system and show me their HTML structure.225```226227**Design System Analysis:**228```229Extract the color palette and typography tokens from the design system.230I want to ensure my new component matches the existing styles.231```232233**Component Migration:**234```235Get the HTML and styles for the "alert" component. I need to236recreate it in a different framework while keeping the same look.237```238239**Multi-Tool Workflow:**240```241First list all form-related components, then get the HTML for242the input and select components. I'm building a registration form.243```244245## How It Works246247Connects to Storybook via `/index.json` and `/iframe.html` endpoints. Uses Puppeteer with headless Chrome for dynamic JavaScript rendering. Long-running operations use an in-memory job queue with max 2 concurrent jobs and 1-hour TTL for completed jobs.248249## Troubleshooting250251- Ensure Storybook is running and `STORYBOOK_URL` is correct252- Use `list_components` first to see available components253- For large components, use async mode (default) and poll `job_status`254- Check `/index.json` endpoint directly in browser255- **SSL certificate errors**: Set `NODE_TLS_REJECT_UNAUTHORIZED=0` for self-signed certificates256- See [DEVELOPMENT.md](./DEVELOPMENT.md) for detailed troubleshooting257258## Requirements259260- Node.js 18+261- Chrome/Chromium (for Puppeteer)262- Running Storybook instance263264## Development265266See [DEVELOPMENT.md](./DEVELOPMENT.md) for detailed development instructions.267268## Author269270Created by [Tomáš Grasl](https://www.tomasgrasl.cz/)271272## License273274MIT275
Full transparency — inspect the skill content before installing.