HTML to Design MCP 服务器

一个功能完整的 MCP（Model Context Protocol）服务器，可以将网页 URL、HTML/CSS 代码或浏览器扩展捕获的文件转换为 Figma 设计稿，功能与 html.to.design 类似。

📋 目录

• 功能特性
• 技术架构
• 安装配置
• 使用方法
• 项目结构
• 核心模块
• 浏览器扩展
• 开发指南
• 常见问题

✨ 功能特性

核心功能

• ✅ 从网页 URL 导入：支持将任意公开网页转换为 Figma 设计稿
• ✅ 从 HTML + CSS 代码导入：支持直接粘贴代码片段转换为设计稿
• ✅ 从 .h2d 文件导入：支持导入浏览器扩展捕获的网页数据
• ✅ 视口支持：可自定义视口大小（移动端、平板、桌面）
• ✅ 主题支持：支持明亮/暗黑主题切换

增强功能

• ✅ SVG 图标转换：自动识别并转换 SVG 元素为 Figma VECTOR 节点
• ✅ 图片自动下载和嵌入：自动下载网页中的图片并嵌入到 Figma 设计稿
• ✅ 字体自动检测和替换：检测页面字体并映射到 Figma 支持的字体
• ✅ 动画和交互效果：提取 CSS 动画、过渡和交互状态（hover、focus、active 等）
• ✅ 更好的 CSS 选择器匹配：使用 css-select 库支持复杂选择器（后代、子代、兄弟、属性、伪类等）
• ✅ 浏览器扩展：完整的 Chrome/Edge 扩展，用于捕获私有网页

样式和布局

• ✅ 样式提取：自动提取文字样式和颜色样式
• ✅ 布局转换：将 CSS Flexbox 转换为 Figma Auto Layout
• ✅ 响应式支持：支持不同视口大小的转换

🏗️ 技术架构

技术栈

• 语言: TypeScript (ES2022)
• 运行时: Node.js
• 协议: Model Context Protocol (MCP)
• 核心库:
  • @modelcontextprotocol/sdk: MCP 服务器框架
  • puppeteer: 无头浏览器，用于网页渲染和内容提取
  • cheerio: HTML 解析和操作
  • css-tree: CSS 解析
  • css-select: 强大的 CSS 选择器匹配
  • svg-parser: SVG 解析
  • axios: HTTP 请求（图片下载）
  • sharp: 图片处理（可选）

架构设计

┌─────────────────────────────────────────────────┐
│           MCP 服务器 (index.ts)                  │
│  - 工具注册和请求处理                            │
│  - 错误处理和日志                                │
└─────────────────────────────────────────────────┘
                    │
        ┌───────────┴───────────┐
        │                       │
┌───────▼────────┐    ┌────────▼────────┐
│ WebToFigma     │    │ CodeToFigma     │
│ Converter      │    │ Converter        │
│ - Puppeteer    │    │ - HTML/CSS 解析 │
│ - 网页渲染     │    │ - 代码转换       │
└───────┬────────┘    └────────┬────────┘
        │                       │
        └───────────┬───────────┘
                    │
        ┌───────────▼───────────┐
        │   BaseConverter        │
        │  - HTML/CSS 解析       │
        │  - 元素转换            │
        │  - 样式计算            │
        └───────────┬───────────┘
                    │
    ┌───────────────┼───────────────┐
    │               │               │
┌───▼───┐   ┌──────▼──────┐  ┌────▼────┐
│ SVG   │   │ Image       │  │ Font     │
│ Conv  │   │ Processor   │  │ Manager  │
└───────┘   └─────────────┘  └──────────┘

📦 安装配置

前置要求

• Node.js >= 18.0.0
• npm 或 yarn
• Chrome/Chromium（用于 Puppeteer）

安装步骤

1. 克隆或下载项目

cd figmaToDesign

2. 安装依赖

npm install

3. 构建项目

npm run build

4. 配置 MCP 客户端

在你的 MCP 客户端配置文件中添加（例如 Cursor 的配置文件）：

{
  "mcpServers": {
    "html-to-design": {
      "command": "node",
      "args": ["C:... .../figmaToDesign/dist/index.js"]
    }
  }
}

注意: 请将路径替换为你的实际项目路径。

环境变量（可选）

# Figma Personal Access Token（用于 create_figma_file 工具）
FIGMA_ACCESS_TOKEN=your_token_here

获取 Figma Access Token:

1. 访问 https://www.figma.com/developers/api#access-tokens
2. 创建新的 Personal Access Token
3. 设置环境变量或在使用工具时提供

🚀 使用方法

MCP 工具

项目提供 4 个 MCP 工具，可通过支持 MCP 的客户端（如 Cursor）调用。

1. import_web_to_figma

从网页 URL 导入并转换为 Figma 设计稿。

参数:

• url (必需): 要导入的网页 URL
• viewport (可选): 视口设置
  • width: 宽度（像素，默认 1440）
  • height: 高度（像素，默认 900）
• theme (可选): 主题模式，light 或 dark（默认 light）
• outputPath (可选): 输出 JSON 文件的路径

示例:

{
  "url": "https://example.com",
  "viewport": {
    "width": 1440,
    "height": 900
  },
  "theme": "light",
  "outputPath": "./output/example.figma.json"
}

2. import_code_to_figma

从 HTML + CSS 代码导入并转换为 Figma 设计稿。

参数:

• html (必需): HTML 代码
• css (可选): CSS 代码
• viewport (可选): 视口设置
• outputPath (可选): 输出 JSON 文件的路径

示例:

{
  "html": "<div class='container'><h1>Hello World</h1></div>",
  "css": ".container { padding: 20px; background: #f0f0f0; }",
  "viewport": {
    "width": 1440,
    "height": 900
  }
}

3. import_h2d_file

从 .h2d 文件导入并转换为 Figma 设计稿（浏览器扩展捕获的文件）。

参数:

• filePath (必需): .h2d 文件路径
• outputPath (可选): 输出 JSON 文件的路径

示例:

{
  "filePath": "./captures/page.h2d",
  "outputPath": "./output/page.figma.json"
}

4. create_figma_file

使用 Figma API 创建新的设计文件（需要 Figma Access Token）。

参数:

• figmaJson (必需): Figma JSON 数据
• fileName (可选): Figma 文件名称（默认 "Imported Design"）
• teamId (可选): Figma 团队 ID
• accessToken (可选): Figma Personal Access Token

注意: Figma API 不直接支持通过 API 创建文件，生成的 JSON 需要通过 Figma Plugin 导入。

📁 项目结构

figmaToDesign/
├── src/                          # 源代码目录
│   ├── index.ts                 # MCP 服务器主入口
│   ├── converters/              # 转换器模块
│   │   ├── base-converter.ts   # 基础转换器（HTML/CSS 解析和转换）
│   │   ├── web-to-figma.ts     # 网页 URL 转 Figma
│   │   ├── code-to-figma.ts    # HTML+CSS 代码转 Figma
│   │   ├── svg-converter.ts    # SVG 转换器
│   │   ├── animation-extractor.ts  # 动画提取器
│   │   └── selector-matcher.ts  # CSS 选择器匹配器
│   ├── utils/                   # 工具模块
│   │   ├── image-processor.ts  # 图片处理器
│   │   └── font-manager.ts      # 字体管理器
│   ├── figma/                   # Figma API 相关
│   │   └── api-client.ts        # Figma API 客户端
│   └── types/                   # 类型定义
│       └── h2d-format.ts        # .h2d 文件格式定义
├── extension/                    # 浏览器扩展
│   ├── manifest.json            # 扩展配置
│   ├── popup.html               # 弹出窗口 UI
│   ├── popup.js                 # 弹出窗口逻辑
│   ├── content-script.js        # 内容脚本
│   ├── background.js            # 后台服务工作者
│   ├── styles.css               # 扩展样式
│   └── icons/                   # 扩展图标
├── examples/                     # 示例文件
│   ├── simple-html.html        # 示例 HTML
│   └── test-code.json          # 测试代码
├── dist/                        # 编译输出目录
├── package.json                 # 项目配置
├── tsconfig.json               # TypeScript 配置
├── README.md                    # 本文档
└── USAGE.md                     # 详细使用指南

🔧 核心模块

BaseConverter (基础转换器)

src/converters/base-converter.ts 是核心转换器，负责：

• HTML 解析和遍历
• CSS 规则解析和应用
• 元素类型判断和转换
• 样式计算和映射
• 布局属性转换（Flexbox → Auto Layout）
• 文本样式处理
• 颜色转换

关键方法:

• htmlToFigma(): 主转换方法
• convertElement(): 递归转换元素
• computeStyles(): 计算元素样式
• getLayoutProperties(): 获取布局属性

WebToFigmaConverter (网页转换器)

src/converters/web-to-figma.ts 负责从网页 URL 转换：

• 使用 Puppeteer 启动无头浏览器
• 导航到目标网页
• 提取 HTML 和 CSS
• 处理图片和字体
• 提取动画和交互状态
• 调用基础转换器进行转换

CodeToFigmaConverter (代码转换器)

src/converters/code-to-figma.ts 负责从代码转换：

• 组合 HTML 和 CSS
• 创建完整的 HTML 文档结构
• 调用基础转换器进行转换

SVGConverter (SVG 转换器)

src/converters/svg-converter.ts 负责 SVG 转换：

• 识别 SVG 元素
• 解析 SVG 内容
• 转换为 Figma VECTOR 节点
• 处理 SVG 路径、样式、变换

AnimationExtractor (动画提取器)

src/converters/animation-extractor.ts 负责动画提取：

• 解析 CSS @keyframes 规则
• 提取 animation 和 transition 属性
• 检测交互状态（hover、focus、active）
• 检测 JavaScript 动画
• 生成动画元数据

ImageProcessor (图片处理器)

src/utils/image-processor.ts 负责图片处理：

• 检测所有图片源（<img>、CSS background-image）
• 下载图片到本地
• 转换为 base64 编码
• 处理相对路径和绝对路径
• 图片缓存机制

FontManager (字体管理器)

src/utils/font-manager.ts 负责字体管理：

• 检测页面使用的字体
• 映射 Web 字体到 Figma 字体
• 字体回退机制
• 生成 Figma 文本样式

SelectorMatcher (选择器匹配器)

src/converters/selector-matcher.ts 负责 CSS 选择器匹配：

• 使用 css-select 库进行匹配
• 支持复杂选择器（后代、子代、兄弟、属性、伪类等）
• 选择器优先级计算

🌐 浏览器扩展

项目包含完整的 Chrome/Edge 浏览器扩展，位于 extension/ 目录。

功能

• 捕获当前页面的 HTML/CSS
• 提取所有资源（图片、字体等）
• 保存为 .h2d 文件格式
• 支持自定义视口大小和主题

安装

1. 打开 Chrome/Edge 浏览器
2. 访问 chrome://extensions/ 或 edge://extensions/
3. 启用"开发者模式"
4. 点击"加载已解压的扩展程序"
5. 选择项目中的 extension 目录

使用

1. 访问要捕获的网页
2. 点击扩展图标
3. 配置视口大小和选项
4. 点击"捕获页面"
5. 保存的 .h2d 文件可在 MCP 服务器中使用 import_h2d_file 工具导入

详细说明请参考 extension/README.md

.h2d 文件格式

.h2d 文件是浏览器扩展捕获的网页数据格式，包含：

{
  "version": "1.0",
  "html": "...",
  "css": "...",
  "resources": {
    "images": [...],
    "fonts": [...],
    "stylesheets": [...],
    "scripts": [...]
  },
  "viewport": {
    "width": 1440,
    "height": 900
  },
  "metadata": {
    "url": "...",
    "title": "...",
    "timestamp": "...",
    "theme": "light",
    "interactions": [...],
    "animations": [...]
  }
}

💻 开发指南

开发模式

# 监听模式，自动重新编译
npm run dev

构建

# 编译 TypeScript
npm run build

运行

# 运行编译后的代码
npm start

代码规范

• 使用 TypeScript 严格模式
• 所有异步操作使用 async/await
• 错误处理必须明确和详细
• 代码注释使用中文

添加新功能

1. 在相应的模块中添加功能
2. 更新类型定义（如需要）
3. 在 src/index.ts 中添加新的 MCP 工具（如需要）
4. 更新文档

❓ 常见问题

Q: 为什么某些样式没有转换？

A: 某些复杂的 CSS 特性（如 Grid、复杂的 Flexbox、动画等）可能无法完美转换。建议：

• 使用标准的 CSS 属性
• 避免使用过于复杂的布局
• 转换后手动调整

Q: 图片没有显示？

A: 图片需要额外处理。当前版本会下载图片并转换为 base64，但在 Figma 中需要手动上传图片资源。

Q: 字体不正确？

A: 确保 Figma 中安装了相应的字体，或者使用 Figma 支持的默认字体（如 Inter、Roboto）。字体管理器会自动映射常见字体。

Q: 如何提高转换质量？

A:

• 使用语义化的 HTML 结构
• 使用标准的 CSS 属性
• 避免使用 JavaScript 动态生成的内容
• 确保 CSS 选择器简洁明了

Q: Puppeteer 无法启动？

A:

• 确保已安装所有依赖：npm install
• 检查系统权限
• 在 Linux 上可能需要安装额外的依赖：sudo apt-get install -y chromium-browser

Q: 网页加载超时？

A:

• 增加超时时间（在 web-to-figma.ts 中修改 timeout 参数）
• 检查网络连接
• 某些网站可能阻止自动化访问

Q: CSS 解析失败？

A:

• 检查 CSS 语法是否正确
• 某些 CSS 特性可能不被支持
• 查看控制台错误信息

📝 许可证

MIT

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📚 相关资源

• Model Context Protocol
• Figma API 文档
• html.to.design

---

注意: 本项目是一个 MCP 服务器实现，需要配合支持 MCP 的客户端使用（如 Cursor IDE）。