Storybook MCP

🚀 Storybook MCP 服務器

Storybook MCP 服務器是一個基於模型上下文協議（MCP）的服務器，它提供了與 Storybook 文檔和組件信息進行交互的工具，幫助開發者更高效地獲取組件相關信息。

🚀 快速開始

你可以按照以下步驟安裝和配置 Storybook MCP 服務器：

MCP 設置

在 MCP 設置中添加以下配置：

{
  "mcpServers": {
    "storybook": {
      "command": "npx",
      "args": ["-y", "storybook-mcp"],
      "env": {
        "STORYBOOK_URL": "<your_storybook_url>/index.json"
      }
    }
  }
}

環境變量

• STORYBOOK_URL（必需）：Storybook 的 index.json 文件的 URL。
• CUSTOM_TOOLS（可選）：用於從 Storybook 中提取特定信息的自定義工具定義的 JSON 數組。

✨ 主要特性

• getComponentList：從配置好的 Storybook 中獲取所有組件的列表。
• getComponentsProps：使用無頭瀏覽器自動化獲取多個組件的詳細屬性信息。
• 自定義工具：使用 JavaScript 創建自定義工具，從 Storybook 頁面中提取任何信息。

📦 安裝指南

本地開發

1. 克隆倉庫：

   git clone <repository_url>
   

2. 安裝依賴：

   yarn install
   

3. 安裝 Playwright 瀏覽器：

   npx playwright install chromium
   

4. 設置環境變量：

   export STORYBOOK_URL="your-storybook-url"
   

5. 以開發模式運行：

   yarn dev
   

⚠️ 重要提示

你也可以使用 npx @modelcontextprotocol/inspector tsx src/index.ts 代替 yarn dev。

構建

yarn build

測試

yarn test

💻 使用示例

內置工具

1. getComponentList

從配置好的 Storybook 中檢索所有可用組件的列表。 示例：

可用組件:
Accordion
Avatar
Badge
Button
...

2. getComponentsProps

獲取多個組件的詳細屬性信息，包括：

• 屬性名稱
• 類型
• 默認值
• 描述
• 必需/可選狀態

參數：

• componentNames（字符串數組）：要獲取屬性信息的組件名稱數組。

使用示例：

工具: getComponentsProps
參數: { "componentNames": ["Button", "Input", "Avatar"] }

自定義工具

你可以定義自定義工具，從 Storybook 頁面中提取特定信息。每個自定義工具可以：

• 導航到 Storybook 中的任何頁面。
• 執行自定義 JavaScript 代碼以提取數據。
• 將結構化數據返回給 AI 助手。

自定義工具結構：

interface CustomTool {
  name: string;           // 唯一的工具名稱
  description: string;    // 工具的描述，供 AI 使用
  parameters: object;     // 輸入參數模式（可選）
  page: string;          // 要導航到的頁面 URL
  handler: string;       // 在頁面上執行的 JavaScript 代碼
}

自定義工具示例：

[
  {
    "name": "getIconList",
    "description": "從圖標頁面獲取所有圖標",
    "parameters": {},
    "page": "https://your-storybook.com/?path=/docs/icon--docs",
    "handler": "Array.from(document.querySelectorAll('.icon-name')).map(i => i.textContent)"
  },
  {
    "name": "getColorPalette",
    "description": "從設計令牌中提取調色板",
    "parameters": {},
    "page": "https://your-storybook.com/?path=/docs/design-tokens--colors",
    "handler": "Array.from(document.querySelectorAll('.color-swatch')).map(el => ({ name: el.getAttribute('data-color-name'), value: el.style.backgroundColor }))"
  }
]

更多示例和詳細文檔，請參閱 examples/custom-tools-example.md。

🔧 技術細節

工作原理

1. 組件列表：服務器獲取 Storybook 的 index.json 文件（v3 是 stories.json），並提取所有標記為 “docs” 類型的組件。
2. 屬性信息：對於組件屬性，服務器：
   • 從 index.json 中找到組件的文檔 ID。
   • 構建組件文檔頁面的 iframe URL。
   • 使用 Playwright 在無頭瀏覽器中加載頁面。
   • 從文檔中提取屬性表 HTML。

支持的 Storybook URL

該服務器適用於任何公開 index.json 文件（v3 是 stories.json）的 Storybook。常見模式如下：

• https://your-storybook-domain.com/index.json
• https://your-storybook-domain.com/storybook/index.json

📚 詳細文檔

要求

• Node.js 18.0.0 或更高版本。
• Chromium 瀏覽器（使用 Playwright 自動安裝）。

錯誤處理

服務器包含全面的錯誤處理，用於處理以下情況：

• Storybook URL 缺失或無效。
• 網絡連接問題。
• 組件未找到的情況。
• Playwright 瀏覽器自動化失敗。

📄 許可證

Storybook MCP 採用 MIT 許可證。