MCP Design System Extractor

MCP设计系统提取器

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

Demo

安装

使用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

关键依赖关系

• 操纵者：使用无头Chrome进行动态JavaScript组件渲染
• 铬/铬：Puppeteer需要（在Docker中自动处理）
• 适用于已构建的故事书发行版

特性

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

环境变量

自签名证书示例：

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

用法

看 Developpent.md 有关详细的设置说明。

可用工具（共9个）

核心工具

1. 列表_组件

- 列出Storybook实例中的所有可用组件 - 使用 compact: true 实现最小输出（减小响应大小） - 筛选依据 category 参数 - 支持分页 page 和 pageSize （默认值：20）

1. 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" （自动解析为默认变量）

1. 搜索组件

- 按名称、标题、类别或目的搜索组件 - query：搜索词（使用 "*" 为所有人） - purpose：按功能查找（“表单输入”、“导航”、“反馈”、“按钮”等） - searchIn：“名称”、“标题”、“类别”或“全部”（默认） - 支持分页 page 和 pageSize

组件分析工具

1. get_组件依赖关系

- 分析渲染的HTML，找出内部使用的其他组件 - 检测React组件、web组件和CSS类模式 - 需要故事ID格式： "component-name--story-name"

设计系统工具

1. 获取主题信息

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

1. get_external_css

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

作业管理工具

1. job_status

- 检查异步作业的状态 - 退货： status, result （当完成时）， error （失败时） - 打电话后投票 get_component_html 在异步模式下

1. job_取消

- 取消排队或正在运行的作业 - 返回取消是否成功

1. job_list

- 列出所有作业及其状态 - 筛选依据 status：“全部”（默认）、“活动”（已排队/正在运行）、“已完成” - 返回作业列表+队列统计信息

示例用法

// 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. 投票作业_状态：在读取结果之前检查作业完成情况
5. 按目的搜索：使用 search_components 随着 purpose 参数

示例提示

连接后，您可以使用Claude的自然语言提示：

MCP Servers Connected

组件发现：

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 端点。使用Puppeteer和无头Chrome进行动态JavaScript渲染。长时间运行的操作使用内存中的作业队列，最多2个并发作业，完成作业的TTL为1小时。

故障排除

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

需求

• Node.js 18+
• 铬/铬（用于Puppeter）
• 正在运行故事书实例

发展

看 Developpent.md 详细的开发说明。

作者

由...创建 托马斯 格拉斯尔

许可证

麻省理工学院