Mcp Design System Extractor

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.

[Demo]

Installation

Using Claude CLI (Recommended)

claude mcp add design-system npx mcp-design-system-extractor@latest \  --env STORYBOOK_URL=http://localhost:6006

With self-signed certificate:

claude mcp add design-system npx mcp-design-system-extractor@latest \  --env STORYBOOK_URL=https://my-storybook.example.com \  --env NODE_TLS_REJECT_UNAUTHORIZED=0

Using npm

npm install -g mcp-design-system-extractor

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

From Source

git clone https://github.com/freema/mcp-design-system-extractor.gitcd mcp-design-system-extractornpm install && npm run buildnpm run setup  # Interactive setup for Claude Desktop

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:

{  "mcpServers": {    "design-system": {      "command": "node",      "args": ["/path/to/dist/index.js"],      "env": {        "STORYBOOK_URL": "https://my-storybook.example.com",        "NODE_TLS_REJECT_UNAUTHORIZED": "0"      }    }  }}

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

// List all components (compact mode recommended)await list_components({ compact: true });
// Search for componentsawait search_components({ query: "button", searchIn: "name" });
// Find components by purposeawait search_components({ purpose: "form inputs" });
// Get variants for a componentawait get_component_html({  componentId: "button",  variantsOnly: true});// Returns: { variants: ["primary", "secondary", "disabled"] }
// Get HTML (async mode - default)await get_component_html({ componentId: "button--primary" });// Returns: { job_id: "job_xxx", status: "queued" }
// Poll for resultawait job_status({ job_id: "job_xxx" });// Returns: { status: "completed", result: { html: "...", classes: [...] } }
// Get HTML (sync mode)await get_component_html({  componentId: "button--primary",  async: false,  timeout: 30000});// Returns: { html: "...", classes: [...] }
// Get HTML with stylesawait get_component_html({  componentId: "button--primary",  async: false,  includeStyles: true});
// Check all running jobsawait job_list({ status: "active" });
// Extract theme infoawait get_theme_info({ includeAll: false });
// Get design tokens from CSSawait get_external_css({  cssUrl: "https://my-storybook.com/assets/main.css"});

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:

[MCP Servers Connected]

Component Discovery:

Show me all available button components in the design system

Building New Features:

I need to create a user profile card. Find relevant componentsfrom the design system and show me their HTML structure.

Design System Analysis:

Extract the color palette and typography tokens from the design system.I want to ensure my new component matches the existing styles.

Component Migration:

Get the HTML and styles for the "alert" component. I need torecreate it in a different framework while keeping the same look.

Multi-Tool Workflow:

First list all form-related components, then get the HTML forthe input and select components. I'm building a registration form.

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 22.12+
• Chrome/Chromium (for Puppeteer)
• Running Storybook instance (see below for supported versions)

Supported Storybook versions

Storybook 7, 8, 9 and 10. The server reads the story index from /index.json, falling back to /stories.json, and renders stories through /iframe.html?id=<storyId> — endpoints that have been stable across all four major versions.

Storybook 6 and earlier are not supported: they predate /index.json and use a different story-id scheme.

Both a dev server (npm run storybook) and a built static Storybook served over HTTP will work.

Development

See DEVELOPMENT.md for detailed development instructions.

Author

Created by Tomáš Grasl

License

MIT