# HTML to Design MCP 服务器

一个功能完整的 MCP（Model Context Protocol）服务器，可以将网页 URL、HTML/CSS 代码或浏览器扩展捕获的文件转换为 Figma 设计稿，功能与 [html.to.design](https://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. **克隆或下载项目**

```bash
cd figmaToDesign
```

2. **安装依赖**

```bash
npm install
```

3. **构建项目**

```bash
npm run build
```

4. **配置 MCP 客户端**

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

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

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

### 环境变量（可选）

```bash
# 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 文件的路径

**示例**:
```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 文件的路径

**示例**:
```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 文件的路径

**示例**:
```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](extension/README.md)

### .h2d 文件格式

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

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

## 💻 开发指南

### 开发模式

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

### 构建

```bash
# 编译 TypeScript
npm run build
```

### 运行

```bash
# 运行编译后的代码
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](https://modelcontextprotocol.io/)
- [Figma API 文档](https://www.figma.com/developers/api)
- [html.to.design](https://html.to.design)

---

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