MCP Design System Extractor

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

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 from https://storybook.js.org

Features

• 🔍 List Components: Get all available components from your Storybook
• 📄 Extract HTML: Get the rendered HTML of any component variant with dynamic JavaScript support
• 🔎 Search Components: Find 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: Get all layout components (Grid, Container, Stack, etc.) with examples
• 🎨 Theme Information: Extract 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

Quick Start

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

Or set manually:

export STORYBOOK_URL=http://localhost:6006

Usage

See DEVELOPMENT.md for detailed setup instructions.

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

3. get_component_variants

   • Gets all story variants/states for a specific component
   • Returns all stories (variants) for a component with their IDs, names, and parameters
   • Component name must match exactly as shown in list_components (case-sensitive)

4. search_components

   • Search components by name, title, or category using case-insensitive partial matching
   • Name is component name only (e.g., "Button")
   • Title is full story path (e.g., "Components/Forms/Button")
   • Category is the grouping (e.g., "Components/Forms")
   • Use query: "*" to list all components
   • Search in specific fields: "name", "title", "category", or "all" (default)
   • Supports pagination with page and pageSize parameters (default: 50 per page)

Component Analysis Tools

5. 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 story ID format: "component-name--story-name"

6. 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 story ID format: "component-name--story-name"

Design System Tools

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

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

9. 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)

10. 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 number of examples returned

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

Example 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
});

AI Assistant Usage Tips

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

How It Works

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.

Troubleshooting

• Ensure Storybook is running and STORYBOOK_URL is correct
• Use exact story ID format: "component-name--story-name"
• Try list_components first to see available components
• Check /index.json endpoint directly in browser
• 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.

License

MIT