MCP Design System Extractor

🚀 MCP设计系统提取器

MCP设计系统提取器是一个基于模型上下文协议（MCP）的服务器，可从Storybook设计系统中提取组件信息。它能连接到Storybook实例（包括https://storybook.js.org 分发的实例），并提取HTML、样式和组件元数据。

✨ 主要特性

• 🔍 列出组件：从你的Storybook中获取所有可用组件。
• 📄 提取HTML：获取任何组件变体的渲染HTML，并支持动态JavaScript。
• 🔎 搜索组件：按名称、标题或类别查找组件。
• 🎛️ 组件属性：获取组件属性/API文档，包括类型和默认值。
• 🔗 组件依赖：分析一个组件内部使用了哪些其他组件。
• 📐 布局组件：获取所有布局组件（如网格、容器、堆栈等）及其使用示例。
• 🎨 主题信息：提取设计系统主题（颜色、间距、排版、断点）。
• 🎯 按用途搜索：按组件用途（表单输入、导航、反馈等）查找组件。
• 🧩 组合示例：获取组件组合在一起的示例。
• 📝 外部CSS分析：获取并分析CSS文件，以提取设计标记和变量。

🚀 快速开始

npm install && npm run build
npm run setup  # 为Claude Desktop进行交互式设置

或者手动设置：

export STORYBOOK_URL=http://localhost:6006

📦 安装指南

本项目的运行需要满足以下条件：

• Node.js 18+
• Chrome/Chromium（供Puppeteer使用）
• 正在运行的Storybook实例

💻 使用示例

基础用法

// 列出所有组件（推荐第一步）
await listComponents({ category: "all" });

// 使用通配符搜索所有组件
await searchComponents({ query: "*", searchIn: "all" });

// 搜索特定组件
await searchComponents({ query: "button", searchIn: "name" });

// 获取特定组件的所有变体
await getComponentVariants({ componentName: "Button" });

// 获取特定按钮变体的HTML（使用上述的准确故事ID）
await getComponentHTML({ 
  componentId: "button--primary",
  includeStyles: true 
});

// 获取组件属性文档
await getComponentProps({
  componentId: "button--primary"
});

// 按用途查找组件
await getComponentByPurpose({
  purpose: "form inputs"
});

// 获取带有示例的布局组件
await getLayoutComponents({
  includeExamples: true
});

// 提取主题信息
await getThemeInfo({
  includeAll: false
});

// 分析组件依赖
await getComponentDependencies({
  componentId: "card--default"
});

// 获取组合示例
await getComponentCompositionExamples({
  componentId: "button--primary",
  limit: 3
});

// 推荐：仅提取设计标记（响应小，避免标记限制）
await getExternalCSS({
  cssUrl: "https://my-storybook.com/assets/main.css"
  // extractTokens: true (默认), includeFullCSS: false (默认)
});

// 仅在你特别需要CSS内容时使用（可能会达到标记限制）
await getExternalCSS({
  cssUrl: "./assets/tokens.css",
  includeFullCSS: true,
  maxContentSize: 10000
});

// 带分页搜索
await searchComponents({
  query: "button",
  page: 1,
  pageSize: 10
});

高级用法

在与Claude或其他AI助手一起使用时：

1. 从发现开始：使用 list_components 并设置 category: "all" 或使用 search_components 并设置 query: "*" 来查看所有可用组件。
2. 获取故事ID：使用 get_component_variants 来查找其他工具所需的准确故事ID。
3. 使用准确ID：故事ID必须采用 "component-name--story-name" 格式（例如，"button--primary"）。
4. 按用途探索：使用 get_component_by_purpose 按组件功能查找组件。
5. 调试问题：当没有找到结果时，工具现在会包含调试信息。

📚 详细文档

可用工具

核心工具

1. list_components

   • 列出Storybook实例中的所有可用组件。
   • 返回包含组件名称、类别和相关故事的信息。
   • 使用 category: "all" 或省略类别参数以列出所有组件。
   • 按特定类别路径过滤（例如，"Components/Buttons"，"Layout"）。
   • 支持使用 page 和 pageSize 参数进行分页（默认每页50条）。

2. get_component_html

   • 从Storybook中的特定组件故事中提取HTML。
   • 需要故事ID格式为："component-name--story-name"（例如，"button--primary"）。
   • 先使用 list_components 或 get_component_variants 来查找有效的故事ID。
   • 可选的CSS样式提取，用于理解组件样式。
   • 支持动态JavaScript渲染的内容。

3. get_component_variants

   • 获取特定组件的所有故事变体/状态。
   • 返回组件的所有故事（变体）及其ID、名称和参数。
   • 组件名称必须与 list_components 中显示的完全匹配（区分大小写）。

4. search_components

   • 使用不区分大小写的部分匹配按名称、标题或类别搜索组件。
   • 名称仅指组件名称（例如，"Button"）。
   • 标题是完整的故事路径（例如，"Components/Forms/Button"）。
   • 类别是分组（例如，"Components/Forms"）。
   • 使用 query: "*" 列出所有组件。
   • 在特定字段中搜索："name"、"title"、"category" 或 "all"（默认）。
   • 支持使用 page 和 pageSize 参数进行分页（默认每页50条）。

组件分析工具

5. get_component_props

   • 从Storybook的argTypes配置中提取组件属性/API文档。
   • 包括属性名称、类型、默认值、必需状态和控制选项。
   • 需要故事ID格式为："component-name--story-name"。

6. get_component_dependencies

   • 分析渲染的HTML以找出给定组件内部使用了哪些其他组件。
   • 检测React组件、Web组件和CSS类模式。
   • 有助于理解组件关系和组合。
   • 需要故事ID格式为："component-name--story-name"。

设计系统工具

7. get_layout_components

   • 获取所有布局组件（网格、容器、堆栈、盒子）及其使用示例。
   • 每个布局组件可选的HTML示例。
   • 有助于理解页面结构和组合模式。

8. get_theme_info

   • 获取设计系统主题信息（颜色、间距、排版、断点）。
   • 从设计系统中提取CSS自定义属性/变量。
   • 按类型对标记进行分类，以便更好地组织。
   • 可选参数，用于包含找到的所有CSS自定义属性。

发现工具

9. get_component_by_purpose

   • 按组件的用途或功能搜索组件。
   • 可用的用途包括："form inputs"（输入字段、选择框、复选框）、"navigation"（菜单、面包屑、标签）、"feedback"（警报、吐司、模态框）、"data display"（表格、卡片、列表）、"layout"（网格、容器、分隔符）、"buttons"（所有按钮类型）、"progress"（加载器、旋转器）、"media"（图像、视频、轮播）。
   • 灵活的模式匹配，用于按用例查找组件。
   • 支持使用 page 和 pageSize 参数进行分页（默认每页50条）。

10. get_component_composition_examples

    • 获取组件在实际模式和布局中组合在一起的示例。
    • 返回显示组件与其他组件在表单、卡片、布局或复杂UI模式中使用的HTML示例。
    • 有助于理解组件在实践中的协同工作方式。
    • 可选的限制参数，用于控制返回的示例数量。

11. get_external_css ⚠️ TOKEN-OPTIMIZED

    • 默认：仅返回设计标记 + 文件统计信息（避免标记限制）。
    • 默认情况下不返回CSS内容（防止25K标记限制错误）。
    • 提取并分类标记：颜色、间距、排版、阴影、断点。
    • 仅在你特别需要CSS内容时使用 includeFullCSS: true。
    • 安全保护：仅接受与你的Storybook相同域名的URL。
    • 非常适合在不达到响应大小限制的情况下提取设计标记。

🔧 技术细节

该工具通过 /index.json 和 /iframe.html 端点连接到Storybook，使用Puppeteer和无头Chrome进行动态JavaScript渲染，通过智能缓存和超时保护来提取组件HTML、样式、属性、依赖项和设计标记。

🛠️ 故障排除

• 确保Storybook正在运行，并且 STORYBOOK_URL 正确。
• 使用准确的故事ID格式："component-name--story-name"。
• 先尝试使用 list_components 查看可用组件。
• 直接在浏览器中检查 /index.json 端点。
• 有关详细的故障排除信息，请参阅 DEVELOPMENT.md。

📄 许可证

本项目采用MIT许可证。