MCP Design System Extractor

🚀 MCP Design System Extractor

A Model Context Protocol (MCP) server that extracts component information from Storybook design systems. It connects to Storybook instances (including those from https://storybook.js.org) and extracts HTML, styles, and component metadata.

✨ Features

• 🔍 List Components: Retrieve all available components from your Storybook.
• 📄 Extract HTML: Obtain the rendered HTML of any component variant with dynamic JavaScript support.
• 🔎 Search Components: Locate components by name, title, or category.
• 🎛️ Component Props: Get component props/API documentation, including types and defaults.
• 🔗 Component Dependencies: Analyze which components are used within other components.
• 📐 Layout Components: Retrieve all layout components (Grid, Container, Stack, etc.) with examples.
• 🎨 Theme Information: Extract the design system theme (colors, spacing, typography, breakpoints).
• 🎯 Search by Purpose: Find components by their purpose (form inputs, navigation, feedback).
• 🧩 Composition Examples: Get examples of how components are combined together.
• 📝 External CSS Analysis: Fetch and analyze CSS files to extract design tokens and variables.

📦 Installation

npm install && npm run build
npm run setup  # Interactive setup for Claude Desktop

Or set manually:

export STORYBOOK_URL=http://localhost:6006

🚀 Quick Start

See DEVELOPMENT.md for detailed setup instructions.

💻 Usage Examples

Basic Usage

// List all components (recommended first step)
await listComponents({ category: "all" });

// Search for all components using wildcard
await searchComponents({ query: "*", searchIn: "all" });

// Search for specific components
await searchComponents({ query: "button", searchIn: "name" });

// Get all variants of a specific component
await getComponentVariants({ componentName: "Button" });

// Get HTML for a specific button variant (use exact story ID from above)
await getComponentHTML({ 
  componentId: "button--primary",
  includeStyles: true 
});

// Get component props documentation
await getComponentProps({
  componentId: "button--primary"
});

// Find components by purpose
await getComponentByPurpose({
  purpose: "form inputs"
});

// Get layout components with examples
await getLayoutComponents({
  includeExamples: true
});

// Extract theme information
await getThemeInfo({
  includeAll: false
});

// Analyze component dependencies
await getComponentDependencies({
  componentId: "card--default"
});

// Get composition examples
await getComponentCompositionExamples({
  componentId: "button--primary",
  limit: 3
});

// RECOMMENDED: Extract design tokens only (small response, avoids token limits)
await getExternalCSS({
  cssUrl: "https://my-storybook.com/assets/main.css"
  // extractTokens: true (default), includeFullCSS: false (default)
});

// ONLY when you specifically need CSS content (may hit token limits)
await getExternalCSS({
  cssUrl: "./assets/tokens.css",
  includeFullCSS: true,
  maxContentSize: 10000
});

// Search with pagination
await searchComponents({
  query: "button",
  page: 1,
  pageSize: 10
});

Advanced Usage

When using with Claude or other AI assistants:

1. Start with discovery: Use list_components with category: "all" or search_components with query: "*" to see all available components.
2. Get story IDs: Use get_component_variants to find exact story IDs needed for other tools.
3. Use exact IDs: Story IDs must be in the format "component-name--story-name" (e.g., "button--primary").
4. Explore by purpose: Use get_component_by_purpose to find components by their function.
5. Debug issues: Tools now include debug information when no results are found.

📚 Documentation

Available Tools

Core Tools

1. list_components

   • Lists all available components from the Storybook instance.
   • Returns components with their names, categories, and associated stories.
   • Use category: "all" or omit the category parameter to list all components.
   • Filter by specific category path (e.g., "Components/Buttons", "Layout").
   • Supports pagination with page and pageSize parameters (default: 50 per page).

2. get_component_html

   • Extracts HTML from a specific component story in Storybook.
   • Requires the story ID format: "component-name--story-name" (e.g., "button--primary").
   • Use list_components or get_component_variants first to find valid story IDs.
   • Optional CSS style extraction for understanding component styling.
   • Supports dynamic JavaScript - rendered content.

Component Analysis Tools

3. get_component_props

   • Extracts component props/API documentation from Storybook's argTypes configuration.
   • Includes prop names, types, default values, required status, and control options.
   • Requires the story ID format: "component-name--story-name".

4. get_component_dependencies

   • Analyzes rendered HTML to find which other components a given component internally uses.
   • Detects React components, web components, and CSS class patterns.
   • Helps understand component relationships and composition.
   • Requires the story ID format: "component-name--story-name".

Design System Tools

5. get_layout_components

   • Gets all layout components (Grid, Container, Stack, Box) with usage examples.
   • Optional HTML examples for each layout component.
   • Useful for understanding page structure and composition patterns.

6. get_theme_info

   • Gets design system theme information (colors, spacing, typography, breakpoints).
   • Extracts CSS custom properties/variables from the design system.
   • Categorizes tokens by type for better organization.
   • Optional parameter to include all CSS custom properties found.

Discovery Tools

7. get_component_by_purpose

   • Search for components by their purpose or function.
   • Available purposes: "form inputs" (input fields, selects, checkboxes), "navigation" (menus, breadcrumbs, tabs), "feedback" (alerts, toasts, modals), "data display" (tables, cards, lists), "layout" (grids, containers, dividers), "buttons" (all button types), "progress" (loaders, spinners), "media" (images, videos, carousels).
   • Flexible pattern matching for finding components by use case.
   • Supports pagination with page and pageSize parameters (default: 50 per page).

8. get_component_composition_examples

   • Gets examples of how components are combined together in real - world patterns and layouts.
   • Returns HTML examples showing the component used with other components in forms, cards, layouts, or complex UI patterns.
   • Helps understand how components work together in practice.
   • Optional limit parameter to control the number of examples returned.

9. get_external_css ⚠️ TOKEN - OPTIMIZED

   • DEFAULT: Returns ONLY design tokens + file stats (avoids token limits).
   • Does NOT return CSS content by default (prevents 25K token limit errors).
   • Extracts & categorizes tokens: colors, spacing, typography, shadows, breakpoints.
   • Use includeFullCSS: true only when you specifically need CSS content.
   • Security - protected: only accepts URLs from the same domain as your Storybook.
   • Perfect for design token extraction without hitting response size limits.

🔧 Technical Details

Connects to Storybook via /index.json and /iframe.html endpoints. Uses Puppeteer with headless Chrome for dynamic JavaScript rendering. Extracts component HTML, styles, props, dependencies, and design tokens with smart caching and timeout protection.

📄 License

This project is licensed under the MIT license.

⚠️ Important Note

• Ensure Storybook is running and STORYBOOK_URL is correct.
• Use the exact story ID format: "component-name--story-name".
• Try list_components first to see available components.
• Check the /index.json endpoint directly in the browser.
• See DEVELOPMENT.md for detailed troubleshooting.

💡 Usage Tip

• Prerequisites: Node.js 18+ and Chrome/Chromium (for Puppeteer) are required, along with a running Storybook instance.
• Development: See DEVELOPMENT.md for detailed development instructions.