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 许可证。