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許可證。