MCP Design System Extractor

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.

Installation

Using Claude CLI (Recommended)

With self-signed certificate:

Using npm

Then configure in your MCP client (see Environment Variables).

From Source

Related MCP server: Unity MCP Integration

Key Dependencies

• Puppeteer: Uses headless Chrome for dynamic JavaScript component rendering

• Chrome/Chromium: Required for Puppeteer (automatically handled in Docker)

• Works with built Storybook distributions

Features

• List Components: Get all available components from your Storybook with compact mode

• Extract HTML: Get the rendered HTML of any component (async or sync mode)

• Search Components: Find components by name, title, category, or purpose

• Component Dependencies: Analyze which components are used within other components

• Theme Information: Extract design system theme (colors, spacing, typography)

• External CSS Analysis: Fetch and analyze CSS files to extract design tokens

• Async Job Queue: Long-running operations run in background with job tracking

Environment Variables

Example with self-signed certificate:

Usage

See DEVELOPMENT.md for detailed setup instructions.

Available Tools (9 total)

Core Tools

1. list_components

   • Lists all available components from the Storybook instance

   • Use compact: true for minimal output (reduces response size)

   • Filter by category parameter

   • Supports pagination with page and pageSize (default: 20)

2. get_component_html

   • Extracts HTML from a specific component story

   • Async by default: Returns job_id, use job_status to poll for results

   • Set async: false for synchronous mode (uses timeout parameter)

   • Use variantsOnly: true to get list of available variants (sync, fast)

   • Optional includeStyles: true for CSS extraction (Storybook CSS filtered out)

   • Story ID format: "component-name--story-name" or just "component-name" (auto-resolves to default variant)

3. search_components

   • Search components by name, title, category, or purpose

   • query: Search term (use "*" for all)

   • purpose: Find by function ("form inputs", "navigation", "feedback", "buttons", etc.)

   • searchIn: "name", "title", "category", or "all" (default)

   • Supports pagination with page and pageSize

Component Analysis Tools

4. get_component_dependencies

   • Analyzes rendered HTML to find which other components are used internally

   • Detects React components, web components, and CSS class patterns

   • Requires story ID format: "component-name--story-name"

Design System Tools

5. get_theme_info

   • Extracts design system theme (colors, spacing, typography, breakpoints)

   • Gets CSS custom properties/variables

   • Use includeAll: true for all CSS variables

6. get_external_css

   • DEFAULT: Returns only design tokens + file stats (avoids token limits)

   • Extracts & categorizes tokens: colors, spacing, typography, shadows

   • Use includeFullCSS: true only when you need full CSS content

   • Security-protected: only accepts URLs from same domain as Storybook

Job Management Tools

7. job_status

   • Check status of an async job

   • Returns: status, result (when completed), error (when failed)

   • Poll this after calling get_component_html in async mode

8. job_cancel

   • Cancel a queued or running job

   • Returns whether cancellation was successful

9. job_list

   • List all jobs with their status

   • Filter by status: "all" (default), "active" (queued/running), "completed"

   • Returns job list + queue statistics

Example Usage

AI Assistant Usage Tips

1. Start with discovery: Use list_components with compact: true

2. Get variants first: Use get_component_html with variantsOnly: true

3. Use async for HTML: Default async mode prevents timeouts on large components

4. Poll job_status: Check job completion before reading results

5. Search by purpose: Use search_components with purpose parameter

Example Prompts

Once connected, you can use natural language prompts with Claude:

Component Discovery:

Building New Features:

Design System Analysis:

Component Migration:

Multi-Tool Workflow:

How It Works

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

Troubleshooting

• Ensure Storybook is running and STORYBOOK_URL is correct

• Use list_components first to see available components

• For large components, use async mode (default) and poll job_status

• Check /index.json endpoint directly in browser

• SSL certificate errors: Set NODE_TLS_REJECT_UNAUTHORIZED=0 for self-signed certificates

• See DEVELOPMENT.md for detailed troubleshooting

Requirements

• Node.js 18+

• Chrome/Chromium (for Puppeteer)

• Running Storybook instance

Development

See DEVELOPMENT.md for detailed development instructions.

Author

Created by Tomáš Grasl

License

MIT