mcp-design-system-extractor

MCP 设计系统提取器

一个用于从 Storybook 设计系统中提取组件信息的模型上下文协议（MCP）服务。连接到 Storybook 实例并提取 HTML、样式和组件元数据。

安装

使用 Claude CLI（推荐）

claude mcp add design-system npx mcp-design-system-extractor@latest \
  --env STORYBOOK_URL=http://localhost:6006

使用自签名证书：

claude mcp add design-system npx mcp-design-system-extractor@latest \
  --env STORYBOOK_URL=https://my-storybook.example.com \
  --env NODE_TLS_REJECT_UNAUTHORIZED=0

使用 npm

npm install -g mcp-design-system-extractor

然后在 MCP 客户端中配置（参见环境变量）。

从源代码安装

git clone https://github.com/freema/mcp-design-system-extractor.git
cd mcp-design-system-extractor
npm install && npm run build
npm run setup  # Interactive setup for Claude Desktop

主要依赖项

• Puppeteer：使用无头 Chrome 动态渲染 JavaScript 组件
• Chrome/Chromium：Puppeteer 所需（在 Docker 中自动处理）
• 兼容已构建的 Storybook 分发包

功能

• 列出组件：获取 Storybook 中所有可用组件，并支持紧凑模式
• 提取 HTML：获取任意组件渲染后的 HTML（异步或同步模式）
• 搜索组件：按名称、标题、类别或用途查找组件
• 组件依赖关系：分析其他组件中使用了哪些组件
• 主题信息：提取设计系统主题（颜色、间距、排版）
• 外部 CSS 分析：获取并分析 CSS 文件以提取设计令牌
• 异步任务队列：长时间运行的操作在后台执行，并跟踪任务状态

环境变量

变量	说明	默认值
STORYBOOK_URL	Storybook 实例的 URL	http://localhost:6006
NODE_TLS_REJECT_UNAUTHORIZED	设为 0 可跳过 SSL 证书验证（用于自签名证书）	1

自签名证书示例：

{
  "mcpServers": {
    "design-system": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "STORYBOOK_URL": "https://my-storybook.example.com",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

用法

详细的设置说明请参见 DEVELOPMENT.md。

可用工具（共 9 个）

核心工具

1. list_components

   • 列出 Storybook 实例中的所有可用组件
   • 使用 compact: true 获取精简输出（减少响应大小）
   • 按 category 参数筛选
   • 支持使用 page 和 pageSize 分页（默认值：20）

2. get_component_html

   • 从特定组件故事中提取 HTML
   • 默认异步：返回 job_id，使用 job_status 轮询结果
   • 将 async: false 设为同步模式（使用 timeout 参数）
   • 使用 variantsOnly: true 获取可用变体列表（同步、快速）
   • 可选的 includeStyles: true 用于提取 CSS（会过滤掉 Storybook CSS）
   • 故事 ID 格式："component-name--story-name" 或仅 "component-name"（自动解析为默认变体）

3. search_components

   • 按名称、标题、类别或用途搜索组件
   • query：搜索词（使用 "*" 搜索全部）
   • purpose：按功能查找（"表单输入"、"导航"、"反馈"、"按钮"等）
   • searchIn："name"、"title"、"category" 或 "all"（默认值）
   • 支持使用 page 和 pageSize 分页

组件分析工具

4. get_component_dependencies
   • 分析渲染后的 HTML，查找内部使用的其他组件
   • 检测 React 组件、Web 组件和 CSS 类模式
   • 要求故事 ID 格式为："component-name--story-name"

设计系统工具

5. get_theme_info

   • 提取设计系统主题（颜色、间距、排版、断点）
   • 获取 CSS 自定义属性/变量
   • 使用 includeAll: true 获取所有 CSS 变量

6. get_external_css

   • 默认：仅返回设计令牌和文件统计信息（避免超出令牌限制）
   • 提取并分类令牌：颜色、间距、排版、阴影
   • 仅在需要完整 CSS 内容时使用 includeFullCSS: true
   • 安全保护：仅接受与 Storybook 同域的 URL

任务管理工具

7. job_status

   • 检查异步任务的状态
   • 返回：status、result（任务完成时）、error（任务失败时）
   • 在异步模式下调用 get_component_html 后轮询此工具

8. job_cancel

   • 取消已排队或正在运行的任务
   • 返回是否成功取消

9. job_list

   • 列出所有任务及其状态
   • 按 status 筛选："all"（默认）、"active"（排队中/运行中）、"completed"
   • 返回任务列表和队列统计信息

使用示例

// List all components (compact mode recommended)
await list_components({ compact: true });

// Search for components
await search_components({ query: "button", searchIn: "name" });

// Find components by purpose
await search_components({ purpose: "form inputs" });

// Get variants for a component
await get_component_html({
  componentId: "button",
  variantsOnly: true
});
// Returns: { variants: ["primary", "secondary", "disabled"] }

// Get HTML (async mode - default)
await get_component_html({ componentId: "button--primary" });
// Returns: { job_id: "job_xxx", status: "queued" }

// Poll for result
await job_status({ job_id: "job_xxx" });
// Returns: { status: "completed", result: { html: "...", classes: [...] } }

// Get HTML (sync mode)
await get_component_html({
  componentId: "button--primary",
  async: false,
  timeout: 30000
});
// Returns: { html: "...", classes: [...] }

// Get HTML with styles
await get_component_html({
  componentId: "button--primary",
  async: false,
  includeStyles: true
});

// Check all running jobs
await job_list({ status: "active" });

// Extract theme info
await get_theme_info({ includeAll: false });

// Get design tokens from CSS
await get_external_css({
  cssUrl: "https://my-storybook.com/assets/main.css"
});

AI 助手使用技巧

1. 从发现开始：使用 list_components 并设置 compact: true
2. 先获取变体：使用 get_component_html 并设置 variantsOnly: true
3. 获取 HTML 时使用异步模式：默认异步模式可避免大型组件导致超时
4. 轮询 job_status：在读取结果前检查任务是否完成
5. 按用途搜索：使用 search_components 并设置 purpose 参数

示例提示词

连接后，你可以使用自然语言提示词与 Claude 交互：

组件发现：

Show me all available button components in the design system

构建新功能：

I need to create a user profile card. Find relevant components
from the design system and show me their HTML structure.

设计系统分析：

Extract the color palette and typography tokens from the design system.
I want to ensure my new component matches the existing styles.

组件迁移：

Get the HTML and styles for the "alert" component. I need to
recreate it in a different framework while keeping the same look.

多工具工作流：

First list all form-related components, then get the HTML for
the input and select components. I'm building a registration form.

工作原理

通过 /index.json 和 /iframe.html 端点连接到 Storybook。使用 Puppeteer 配合无头 Chrome 动态渲染 JavaScript。长时间运行的操作使用内存中的任务队列，最多同时运行 2 个任务，已完成任务的 TTL 为 1 小时。

故障排除

• 确保 Storybook 正在运行，并且 STORYBOOK_URL 正确
• 先使用 list_components 查看可用组件
• 对于大型组件，使用异步模式（默认），并轮询 job_status
• 直接在浏览器中检查 /index.json 端点
• SSL 证书错误：对于自签名证书，请设置 NODE_TLS_REJECT_UNAUTHORIZED=0
• 详细的故障排除说明请参阅 DEVELOPMENT.md

要求

• Node.js 20+
• Chrome/Chromium（用于 Puppeteer）
• 正在运行的 Storybook 实例（支持的版本见下文）

支持的 Storybook 版本

Storybook 7、8、9 和 10。 服务会从 /index.json 读取故事索引，若无法读取则回退到 /stories.json，并通过 /iframe.html?id=<storyId> 渲染故事。这些端点在这四个主版本中一直保持稳定。

不支持 Storybook 6 及更早版本：这些版本早于 /index.json，并采用不同的故事 ID 方案。

开发服务器（npm run storybook）和通过 HTTP 提供服务的已构建静态 Storybook 均可正常使用。

开发

详细的开发说明请参阅 DEVELOPMENT.md。

作者

由 Tomáš Grasl 创建

许可证

MIT