{"id":29449004,"url":"https://github.com/freema/mcp-design-system-extractor","last_synced_at":"2025-08-29T20:04:07.586Z","repository":{"id":300576594,"uuid":"995858452","full_name":"freema/mcp-design-system-extractor","owner":"freema","description":"MCP (Model Context Protocol) server that enables AI assistants to interact with Storybook design systems. Extract component HTML, analyze styles, and help with design system adoption and refactoring.","archived":false,"fork":false,"pushed_at":"2025-08-28T12:49:14.000Z","size":140,"stargazers_count":19,"open_issues_count":0,"forks_count":5,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-28T18:46:26.027Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/freema.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-04T05:41:20.000Z","updated_at":"2025-08-28T12:48:57.000Z","dependencies_parsed_at":"2025-06-22T14:34:33.466Z","dependency_job_id":"25ab75be-01db-4f0d-b8f7-42160c55edf8","html_url":"https://github.com/freema/mcp-design-system-extractor","commit_stats":null,"previous_names":["freema/mcp-design-system-extractor"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/freema/mcp-design-system-extractor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freema%2Fmcp-design-system-extractor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freema%2Fmcp-design-system-extractor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freema%2Fmcp-design-system-extractor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freema%2Fmcp-design-system-extractor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/freema","download_url":"https://codeload.github.com/freema/mcp-design-system-extractor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freema%2Fmcp-design-system-extractor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272756322,"owners_count":24987834,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-29T02:00:10.610Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-13T19:02:28.159Z","updated_at":"2025-08-29T20:04:07.580Z","avatar_url":"https://github.com/freema.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Developer Tools","📚 Projects (1974 total)","サーバー実装","カテゴリ","🌐 Web Development","Server Implementations"],"sub_categories":["Design \u0026 UI","MCP Servers","🛠️ \u003ca name=\"developer-tools\"\u003e\u003c/a\u003e開発者ツール","🛠️ \u003ca name=\"developer-tools\"\u003e\u003c/a\u003e開発ツール","💻 \u003ca name=\"developer-tools\"\u003e\u003c/a\u003eDeveloper Tools"],"readme":"# MCP Design System Extractor\n\nA 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.\n\n## Key Dependencies\n\n- **Puppeteer**: Uses headless Chrome for dynamic JavaScript component rendering\n- **Chrome/Chromium**: Required for Puppeteer (automatically handled in Docker)\n- Works with built Storybook distributions from https://storybook.js.org\n\n\u003ca href=\"https://glama.ai/mcp/servers/@freema/mcp-design-system-extractor\"\u003e\n  \u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@freema/mcp-design-system-extractor/badge\" alt=\"Design System Extractor MCP server\" /\u003e\n\u003c/a\u003e\n\n## Features\n\n- 🔍 **List Components**: Get all available components from your Storybook\n- 📄 **Extract HTML**: Get the rendered HTML of any component variant with dynamic JavaScript support\n- 🔎 **Search Components**: Find components by name, title, or category\n- 🎛️ **Component Props**: Get component props/API documentation including types and defaults\n- 🔗 **Component Dependencies**: Analyze which components are used within other components\n- 📐 **Layout Components**: Get all layout components (Grid, Container, Stack, etc.) with examples\n- 🎨 **Theme Information**: Extract design system theme (colors, spacing, typography, breakpoints)\n- 🎯 **Search by Purpose**: Find components by their purpose (form inputs, navigation, feedback)\n- 🧩 **Composition Examples**: Get examples of how components are combined together\n- 📝 **External CSS Analysis**: Fetch and analyze CSS files to extract design tokens and variables\n\n## Quick Start\n\n```bash\nnpm install \u0026\u0026 npm run build\nnpm run setup  # Interactive setup for Claude Desktop\n```\n\nOr set manually:\n```bash\nexport STORYBOOK_URL=http://localhost:6006\n```\n\n## Usage\n\nSee [DEVELOPMENT.md](./DEVELOPMENT.md) for detailed setup instructions.\n\n## Available Tools\n\n### Core Tools\n\n1. **list_components**\n   - Lists all available components from the Storybook instance\n   - Returns components with their names, categories, and associated stories\n   - Use `category: \"all\"` or omit category parameter to list all components\n   - Filter by specific category path (e.g., \"Components/Buttons\", \"Layout\")\n   - Supports pagination with `page` and `pageSize` parameters (default: 50 per page)\n\n2. **get_component_html**\n   - Extracts HTML from a specific component story in Storybook\n   - Requires story ID format: \"component-name--story-name\" (e.g., \"button--primary\")\n   - Use list_components or get_component_variants first to find valid story IDs\n   - Optional CSS style extraction for understanding component styling\n   - Supports dynamic JavaScript-rendered content\n\n3. **get_component_variants**\n   - Gets all story variants/states for a specific component\n   - Returns all stories (variants) for a component with their IDs, names, and parameters\n   - Component name must match exactly as shown in list_components (case-sensitive)\n\n4. **search_components**\n   - Search components by name, title, or category using case-insensitive partial matching\n   - Name is component name only (e.g., \"Button\")\n   - Title is full story path (e.g., \"Components/Forms/Button\")  \n   - Category is the grouping (e.g., \"Components/Forms\")\n   - Use `query: \"*\"` to list all components\n   - Search in specific fields: \"name\", \"title\", \"category\", or \"all\" (default)\n   - Supports pagination with `page` and `pageSize` parameters (default: 50 per page)\n\n### Component Analysis Tools\n\n5. **get_component_props**\n   - Extracts component props/API documentation from Storybook's argTypes configuration\n   - Includes prop names, types, default values, required status, and control options\n   - Requires story ID format: \"component-name--story-name\"\n\n6. **get_component_dependencies**\n   - Analyzes rendered HTML to find which other components a given component internally uses\n   - Detects React components, web components, and CSS class patterns\n   - Helps understand component relationships and composition\n   - Requires story ID format: \"component-name--story-name\"\n\n### Design System Tools\n\n7. **get_layout_components**\n   - Gets all layout components (Grid, Container, Stack, Box) with usage examples\n   - Optional HTML examples for each layout component\n   - Useful for understanding page structure and composition patterns\n\n8. **get_theme_info**\n   - Gets design system theme information (colors, spacing, typography, breakpoints)\n   - Extracts CSS custom properties/variables from the design system\n   - Categorizes tokens by type for better organization\n   - Optional parameter to include all CSS custom properties found\n\n### Discovery Tools\n\n9. **get_component_by_purpose**\n   - Search for components by their purpose or function\n   - 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)\n   - Flexible pattern matching for finding components by use case\n   - Supports pagination with `page` and `pageSize` parameters (default: 50 per page)\n\n10. **get_component_composition_examples**\n    - Gets examples of how components are combined together in real-world patterns and layouts\n    - Returns HTML examples showing the component used with other components in forms, cards, layouts, or complex UI patterns\n    - Helps understand how components work together in practice\n    - Optional limit parameter to control number of examples returned\n\n11. **get_external_css** ⚠️ **TOKEN-OPTIMIZED**\n    - **DEFAULT**: Returns ONLY design tokens + file stats (avoids token limits)\n    - **Does NOT return CSS content** by default (prevents 25K token limit errors)\n    - Extracts \u0026 categorizes tokens: colors, spacing, typography, shadows, breakpoints\n    - Use `includeFullCSS: true` only when you specifically need CSS content\n    - Security-protected: only accepts URLs from the same domain as your Storybook\n    - **Perfect for design token extraction without hitting response size limits**\n\n## Example Usage\n\n```typescript\n// List all components (recommended first step)\nawait listComponents({ category: \"all\" });\n\n// Search for all components using wildcard\nawait searchComponents({ query: \"*\", searchIn: \"all\" });\n\n// Search for specific components\nawait searchComponents({ query: \"button\", searchIn: \"name\" });\n\n// Get all variants of a specific component\nawait getComponentVariants({ componentName: \"Button\" });\n\n// Get HTML for a specific button variant (use exact story ID from above)\nawait getComponentHTML({ \n  componentId: \"button--primary\",\n  includeStyles: true \n});\n\n// Get component props documentation\nawait getComponentProps({\n  componentId: \"button--primary\"\n});\n\n// Find components by purpose\nawait getComponentByPurpose({\n  purpose: \"form inputs\"\n});\n\n// Get layout components with examples\nawait getLayoutComponents({\n  includeExamples: true\n});\n\n// Extract theme information\nawait getThemeInfo({\n  includeAll: false\n});\n\n// Analyze component dependencies\nawait getComponentDependencies({\n  componentId: \"card--default\"\n});\n\n// Get composition examples\nawait getComponentCompositionExamples({\n  componentId: \"button--primary\",\n  limit: 3\n});\n\n// RECOMMENDED: Extract design tokens only (small response, avoids token limits)\nawait getExternalCSS({\n  cssUrl: \"https://my-storybook.com/assets/main.css\"\n  // extractTokens: true (default), includeFullCSS: false (default)\n});\n\n// ONLY when you specifically need CSS content (may hit token limits)\nawait getExternalCSS({\n  cssUrl: \"./assets/tokens.css\",\n  includeFullCSS: true,\n  maxContentSize: 10000\n});\n\n// Search with pagination\nawait searchComponents({\n  query: \"button\",\n  page: 1,\n  pageSize: 10\n});\n```\n\n### AI Assistant Usage Tips\n\nWhen using with Claude or other AI assistants:\n\n1. **Start with discovery**: Use `list_components` with `category: \"all\"` or `search_components` with `query: \"*\"` to see all available components\n2. **Get story IDs**: Use `get_component_variants` to find exact story IDs needed for other tools\n3. **Use exact IDs**: Story IDs must be in format \"component-name--story-name\" (e.g., \"button--primary\")\n4. **Explore by purpose**: Use `get_component_by_purpose` to find components by their function\n5. **Debug issues**: Tools now include debug information when no results are found\n\n## How It Works\n\nConnects 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.\n\n## Troubleshooting\n\n- Ensure Storybook is running and `STORYBOOK_URL` is correct\n- Use exact story ID format: \"component-name--story-name\"\n- Try `list_components` first to see available components\n- Check `/index.json` endpoint directly in browser\n- See [DEVELOPMENT.md](./DEVELOPMENT.md) for detailed troubleshooting\n\n## Requirements\n\n- Node.js 18+\n- Chrome/Chromium (for Puppeteer)\n- Running Storybook instance\n\n## Development\n\nSee [DEVELOPMENT.md](./DEVELOPMENT.md) for detailed development instructions.\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreema%2Fmcp-design-system-extractor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffreema%2Fmcp-design-system-extractor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreema%2Fmcp-design-system-extractor/lists"}