用途
mcp-design-system-extractor 是一个模型上下文协议（MCP）服务器，让 AI 助手能够与 Storybook 设计系统交互，从 Storybook 实例中提取组件信息，帮助设计系统的采用与重构。
它连接 Storybook 实例，提取 HTML、样式和组件元数据。采用 Puppeteer 无头 Chrome 进行动态 JavaScript 组件渲染，可用于已构建的 Storybook 发行版。
主要能力
服务器共提供 9 个工具：
组件发现
- list_components：列出 Storybook 实例中所有可用组件。可使用 compact: true 精简输出（减小响应体积）；可按 category 参数过滤；支持分页，使用 page 和 pageSize（默认 20）。
- search_components：按名称、标题、类别或用途搜索组件。query 为搜索词（使用 "*" 表示全部）；purpose 可按功能查找（"form inputs"、"navigation"、"feedback"、"buttons" 等）；searchIn 可取 "name"、"title"、"category" 或 "all"（默认）；支持分页。
组件提取
- get_component_html：从指定组件 story 提取 HTML。默认异步：返回 job_id，用 job_status 轮询结果；可设置 async: false 切换同步模式（使用 timeout 参数）；使用 variantsOnly: true 可获取可用变体列表（同步、快速）；可选 includeStyles: true 提取 CSS（会过滤掉 Storybook 自身 CSS）。Story ID 格式为 "component-name--story-name"，或仅 "component-name"（自动解析为默认变体）。
组件分析
- get_component_dependencies：分析渲染后的 HTML，找出内部使用了哪些其他组件。可检测 React 组件、Web Components 和 CSS 类模式。需要 story ID 格式 "component-name--story-name"。
设计系统
- get_theme_info：提取设计系统主题（颜色、间距、字体、断点），获取 CSS 自定义属性/变量。使用 includeAll: true 可获取所有 CSS 变量。
- get_external_css：默认仅返回设计令牌 + 文件统计（避免令牌限制）；提取并分类令牌：颜色、间距、字体、阴影；仅在需要完整 CSS 内容时使用 includeFullCSS: true；受安全保护，只接受与 Storybook 同一域名的 URL。
任务管理
- job_status：检查异步任务状态，返回 status、result（完成时）、error（失败时）。在异步模式调用 get_component_html 后轮询。
- job_cancel：取消排队或运行中的任务，返回取消是否成功。
- job_list：列出所有任务及其状态。可按 status 过滤："all"（默认）、"active"（排队/运行中）、"completed"。返回任务列表 + 队列统计。
使用方式
可通过 Claude CLI 使用（推荐方式），支持自签名证书。随后在 MCP 客户端中配置（参见环境变量）。
关键依赖：
- Puppeteer：使用无头 Chrome 进行动态 JavaScript 组件渲染
- Chrome/Chromium：Puppeteer 需要（Docker 中自动处理）
连接机制：通过 /index.json 和 /iframe.html 端点连接 Storybook；使用 Puppeteer 无头 Chrome 进行动态 JavaScript 渲染；长时间运行的操作使用内存任务队列，最多 2 个并发任务，完成任务保留 1 小时 TTL。
环境变量包括 STORYBOOK_URL 等，自签名证书场景可设置 NODE_TLS_REJECT_UNAUTHORIZED=0。
适用场景
- 组件发现
- 构建新功能
- 设计系统分析
- 组件迁移
- 多工具工作流
限制与要求
- 需要 Chrome/Chromium（用于 Puppeteer）
- 需要运行中的 Storybook 实例
- 支持的 Storybook 版本：Storybook 7、8、9、10。服务器从 /index.json 读取 story 索引，回退到 /stories.json，并通过 /iframe.html?id=<storyId> 渲染 story——这些端点在四个主要版本中保持稳定。
- 不支持 Storybook 6 及更早版本：它们早于 /index.json，且使用不同的 story-id 方案。
- 开发服务器（npm run storybook）和通过 HTTP 提供的已构建静态 Storybook 均可工作。
使用建议
- 从发现开始：使用 list_components 并设置 compact: true
- 先获取变体：使用 get_component_html 并设置 variantsOnly: true
- HTML 使用异步：默认异步模式可避免大组件超时
- 轮询 job_status：在读取结果前检查任务完成情况
- 按用途搜索：使用 search_components 的 purpose 参数
故障排除
- 确保 Storybook 正在运行且 STORYBOOK_URL 正确
- 先用 list_components 查看可用组件
- 对于大组件，使用异步模式（默认）并轮询 job_status
- 在浏览器中直接检查 /index.json 端点
- SSL 证书错误：为自签名证书设置 NODE_TLS_REJECT_UNAUTHORIZED=0
更多详细开发与设置说明参见 DEVELOPMENT.md。
