{ "markdown": "# MCP Design System Extractor\n\nA Model Context Protocol (MCP) server that extracts component information from Storybook design systems. Connects to Storybook instances and extracts HTML, styles, and component metadata.\n\n![Demo](assets/demo.gif)\n\n## Installation\n\n### Using Claude CLI (Recommended)\n\n```bash\nclaude mcp add design-system npx mcp-design-system-extractor@latest \\\n --env STORYBOOK_URL=http://localhost:6006\n```\n\nWith self-signed certificate:\n```bash\nclaude mcp add design-system npx mcp-design-system-extractor@latest \\\n --env STORYBOOK_URL=https://my-storybook.example.com \\\n --env NODE_TLS_REJECT_UNAUTHORIZED=0\n```\n\n### Using npm\n\n```bash\nnpm install -g mcp-design-system-extractor\n```\n\nThen configure in your MCP client (see [Environment Variables](#environment-variables)).\n\n### From Source\n\n```bash\ngit clone https://github.com/freema/mcp-design-system-extractor.git\ncd mcp-design-system-extractor\nnpm install && npm run build\nnpm run setup # Interactive setup for Claude Desktop\n```\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\n\n\n \"Design\n\n\n## Features\n\n- **List Components**: Get all available components from your Storybook with compact mode\n- **Extract HTML**: Get the rendered HTML of any component (async or sync mode)\n- **Search Components**: Find components by name, title, category, or purpose\n- **Component Dependencies**: Analyze which components are used within other components\n- **Theme Information**: Extract design system theme (colors, spacing, typography)\n- **External CSS Analysis**: Fetch and analyze CSS files to extract design tokens\n- **Async Job Queue**: Long-running operations run in background with job tracking\n\n## Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `STORYBOOK_URL` | URL of your Storybook instance | `http://localhost:6006` |\n| `NODE_TLS_REJECT_UNAUTHORIZED` | Set to `0` to skip SSL certificate verification (for self-signed certs) | `1` |\n\n**Example with self-signed certificate:**\n```json\n{\n \"mcpServers\": {\n \"design-system\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/dist/index.js\"],\n \"env\": {\n \"STORYBOOK_URL\": \"https://my-storybook.example.com\",\n \"NODE_TLS_REJECT_UNAUTHORIZED\": \"0\"\n }\n }\n }\n}\n```\n\n## Usage\n\nSee [DEVELOPMENT.md](./DEVELOPMENT.md) for detailed setup instructions.\n\n## Available Tools (9 total)\n\n### Core Tools\n\n1. **list_components**\n - Lists all available components from the Storybook instance\n - Use `compact: true` for minimal output (reduces response size)\n - Filter by `category` parameter\n - Supports pagination with `page` and `pageSize` (default: 20)\n\n2. **get_component_html**\n - Extracts HTML from a specific component story\n - **Async by default**: Returns `job_id`, use `job_status` to poll for results\n - Set `async: false` for synchronous mode (uses `timeout` parameter)\n - Use `variantsOnly: true` to get list of available variants (sync, fast)\n - Optional `includeStyles: true` for CSS extraction (Storybook CSS filtered out)\n - Story ID format: `\"component-name--story-name\"` or just `\"component-name\"` (auto-resolves to default variant)\n\n3. **search_components**\n - Search components by name, title, category, or purpose\n - `query`: Search term (use `\"*\"` for all)\n - `purpose`: Find by function (\"form inputs\", \"navigation\", \"feedback\", \"buttons\", etc.)\n - `searchIn`: \"name\", \"title\", \"category\", or \"all\" (default)\n - Supports pagination with `page` and `pageSize`\n\n### Component Analysis Tools\n\n4. **get_component_dependencies**\n - Analyzes rendered HTML to find which other components are used internally\n - Detects React components, web components, and CSS class patterns\n - Requires story ID format: `\"component-name--story-name\"`\n\n### Design System Tools\n\n5. **get_theme_info**\n - Extracts design system theme (colors, spacing, typography, breakpoints)\n - Gets CSS custom properties/variables\n - Use `includeAll: true` for all CSS variables\n\n6. **get_external_css**\n - **DEFAULT**: Returns only design tokens + file stats (avoids token limits)\n - Extracts & categorizes tokens: colors, spacing, typography, shadows\n - Use `includeFullCSS: true` only when you need full CSS content\n - Security-protected: only accepts URLs from same domain as Storybook\n\n### Job Management Tools\n\n7. **job_status**\n - Check status of an async job\n - Returns: `status`, `result` (when completed), `error` (when failed)\n - Poll this after calling `get_component_html` in async mode\n\n8. **job_cancel**\n - Cancel a queued or running job\n - Returns whether cancellation was successful\n\n9. **job_list**\n - List all jobs with their status\n - Filter by `status`: \"all\" (default), \"active\" (queued/running), \"completed\"\n - Returns job list + queue statistics\n\n## Example Usage\n\n```typescript\n// List all components (compact mode recommended)\nawait list_components({ compact: true });\n\n// Search for components\nawait search_components({ query: \"button\", searchIn: \"name\" });\n\n// Find components by purpose\nawait search_components({ purpose: \"form inputs\" });\n\n// Get variants for a component\nawait get_component_html({\n componentId: \"button\",\n variantsOnly: true\n});\n// Returns: { variants: [\"primary\", \"secondary\", \"disabled\"] }\n\n// Get HTML (async mode - default)\nawait get_component_html({ componentId: \"button--primary\" });\n// Returns: { job_id: \"job_xxx\", status: \"queued\" }\n\n// Poll for result\nawait job_status({ job_id: \"job_xxx\" });\n// Returns: { status: \"completed\", result: { html: \"...\", classes: [...] } }\n\n// Get HTML (sync mode)\nawait get_component_html({\n componentId: \"button--primary\",\n async: false,\n timeout: 30000\n});\n// Returns: { html: \"...\", classes: [...] }\n\n// Get HTML with styles\nawait get_component_html({\n componentId: \"button--primary\",\n async: false,\n includeStyles: true\n});\n\n// Check all running jobs\nawait job_list({ status: \"active\" });\n\n// Extract theme info\nawait get_theme_info({ includeAll: false });\n\n// Get design tokens from CSS\nawait get_external_css({\n cssUrl: \"https://my-storybook.com/assets/main.css\"\n});\n```\n\n### AI Assistant Usage Tips\n\n1. **Start with discovery**: Use `list_components` with `compact: true`\n2. **Get variants first**: Use `get_component_html` with `variantsOnly: true`\n3. **Use async for HTML**: Default async mode prevents timeouts on large components\n4. **Poll job_status**: Check job completion before reading results\n5. **Search by purpose**: Use `search_components` with `purpose` parameter\n\n## Example Prompts\n\nOnce connected, you can use natural language prompts with Claude:\n\n![MCP Servers Connected](assets/mcp-servers.png)\n\n**Component Discovery:**\n```\nShow me all available button components in the design system\n```\n\n**Building New Features:**\n```\nI need to create a user profile card. Find relevant components\nfrom the design system and show me their HTML structure.\n```\n\n**Design System Analysis:**\n```\nExtract the color palette and typography tokens from the design system.\nI want to ensure my new component matches the existing styles.\n```\n\n**Component Migration:**\n```\nGet the HTML and styles for the \"alert\" component. I need to\nrecreate it in a different framework while keeping the same look.\n```\n\n**Multi-Tool Workflow:**\n```\nFirst list all form-related components, then get the HTML for\nthe input and select components. I'm building a registration form.\n```\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. Long-running operations use an in-memory job queue with max 2 concurrent jobs and 1-hour TTL for completed jobs.\n\n## Troubleshooting\n\n- Ensure Storybook is running and `STORYBOOK_URL` is correct\n- Use `list_components` first to see available components\n- For large components, use async mode (default) and poll `job_status`\n- Check `/index.json` endpoint directly in browser\n- **SSL certificate errors**: Set `NODE_TLS_REJECT_UNAUTHORIZED=0` for self-signed certificates\n- See [DEVELOPMENT.md](./DEVELOPMENT.md) for detailed troubleshooting\n\n## Requirements\n\n- Node.js 20+\n- Chrome/Chromium (for Puppeteer)\n- Running Storybook instance (see below for supported versions)\n\n### Supported Storybook versions\n\n**Storybook 7, 8, 9 and 10.** The server reads the story index from\n`/index.json`, falling back to `/stories.json`, and renders stories through\n`/iframe.html?id=` — endpoints that have been stable across all four\nmajor versions.\n\nStorybook 6 and earlier are not supported: they predate `/index.json` and use\na different story-id scheme.\n\nBoth a dev server (`npm run storybook`) and a built static Storybook served\nover HTTP will work.\n\n## Development\n\nSee [DEVELOPMENT.md](./DEVELOPMENT.md) for detailed development instructions.\n\n## Author\n\nCreated by [Tomáš Grasl](https://www.tomasgrasl.cz/)\n\n## License\n\nMIT\n", "bytes": 9291, "sha": "bf186492e833446760f232e79c2a0dcf58f306de0f9df06d14446fc0845946c4", "repo_slug": "freema/mcp-design-system-extractor", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_freema_mcp_design_system_extra_8356e75d/readme" }