Figma Restore MCP Enhanced

增强版 Figma 设计稿自动化还原 MCP 服务，集成 Cursor Rules，支持 Vue3 组件生成和像素级对比测试。

✨ 特性

• 🎨 Figma 设计稿分析: 自动分析节点结构，智能识别组件类型
• 🚀 Vue3 组件生成: 支持 Composition API 和 Options API
• 🔍 增强截图服务: 优先使用本地浏览器，无需安装 Puppeteer
• 📏 规则集成: 自动应用 Cursor Rules，保证代码规范
• 🛠️ SVG 优化: 自动下载和优化 SVG 图标
• 📦 批量处理: 支持批量还原多个组件
• 📊 质量报告: 详细的还原质量分析报告
• 🌐 智能浏览器检测: 自动检测和使用系统浏览器

📦 安装

基础安装

1npm install figma-restore-mcp-enhanced

完整功能安装（推荐）

1npm install figma-restore-mcp-enhanced puppeteer pixelmatch pngjs svgo

🚀 快速开始

1. 配置 Cursor MCP

将以下配置添加到你的 ~/.cursor/mcp.json:

1{
2  "mcpServers": {
3    "figma-restore-enhanced": {
4      "command": "npx",
5      "args": ["figma-restore-mcp-enhanced"],
6      "env": {
7        "FIGMA_TOKEN": "your-figma-token-here"
8      }
9    }
10  }
11}

2. 获取 Figma Token

1. 登录 Figma
2. 进入 Settings → Account → Personal access tokens
3. 生成新的 token
4. 将 token 配置到环境变量中

3. 在 Cursor 中使用

现在你可以在 Cursor 中使用以下工具：

• 分析设计稿: analyze_figma_design
• 生成组件: generate_vue_component
• 像素对比: run_pixel_comparison
• 批量还原: batch_restore_components
• 质量报告: get_restore_report
• 增强截图: take_enhanced_screenshot (优先使用本地浏览器)
• 浏览器状态: check_browser_status

🛠️ 可选依赖说明

本包使用了可选依赖策略，你可以根据需要安装：

核心功能（总是可用）

• Figma 设计稿分析
• Vue 组件代码生成
• 规则集成和验证

扩展功能（需要额外依赖）

增强截图服务（推荐）

优先使用本地浏览器，无需安装 Puppeteer：

1# 启动本地浏览器调试模式
2google-chrome --remote-debugging-port=9222 --headless
3# 或 Microsoft Edge
4msedge --remote-debugging-port=9222 --headless

可选增强（更好的本地浏览器支持）：

1npm install chrome-remote-interface ws

传统方式（完整功能但体积大）：

1npm install puppeteer pixelmatch pngjs

功能：

• 智能选择截图方法（本地浏览器 → Puppeteer）
• 自动检测可用浏览器
• 像素级差异对比
• 详细的差异分析报告

SVG 优化

需要安装：

1npm install svgo

功能：

• SVG 文件优化压缩
• 路径合并和清理
• 减小文件体积

📋 使用示例

分析 Figma 设计稿

1// 在 Cursor 中调用
2analyze_figma_design({
3  fileKey: "your-figma-file-key",
4  nodeId: "optional-node-id"
5})

生成 Vue 组件

1generate_vue_component({
2  fileKey: "your-figma-file-key",
3  nodeId: "target-node-id",
4  componentName: "MyComponent",
5  outputFormat: "vue3-composition",
6  includePixelTest: true
7})

运行像素对比测试

1run_pixel_comparison({
2  componentName: "MyComponent",
3  autoFix: false
4})

增强截图服务

1// 检查浏览器状态
2check_browser_status()
3
4// 使用增强截图（自动选择最佳方法）
5take_enhanced_screenshot({
6  url: "http://localhost:3000/component-preview",
7  width: 1920,
8  height: 1080,
9  fullPage: false,
10  format: "png",
11  quality: 90
12})

🔧 配置选项

环境变量

• FIGMA_TOKEN: Figma API Token（必需）
• PUPPETEER_EXECUTABLE_PATH: 自定义 Chrome 路径（可选）

项目配置

项目中可以创建 .cursorrc 文件来定义项目特定的规则：

1# Figma 设计稿还原项目 - Cursor Rules
2
3## 基础配置
4### 包管理工具
5- 项目使用 **yarn** 作为包管理工具
6
7### Element Plus 配置
8- Element Plus 的 namespace 被设置为 **'cs'**
9- 所有组件类名都是 `cs-` 开头

📊 质量等级

像素对比测试会给出质量等级：

• A+ (≥98%): 像素级还原，可以提交
• A (≥95%): 高质量还原，小细节需优化
• B+ (≥90%): 需要修改，关注红色区域
• B (≥80%): 需要大幅修改
• C (<80%): 必须重新实现

🔍 故障排除

检查依赖状态

1npx figma-restore-mcp-enhanced --check-deps

常见问题

1. 截图功能不可用

原因: 没有可用的浏览器或 Puppeteer 解决:

• 方案1（推荐）: 启动本地浏览器 google-chrome --remote-debugging-port=9222 --headless
• 方案2: 安装 Puppeteer npm install puppeteer pixelmatch pngjs
• 检查状态: 运行 check_browser_status 工具

2. 本地浏览器连接失败

原因: 浏览器未启动调试模式或端口被占用 解决:

• 确保浏览器以调试模式启动
• 尝试不同端口: --remote-debugging-port=9223
• 检查防火墙设置

3. SVG 优化失败

原因: 缺少 svgo 依赖 解决: npm install svgo

4. Figma API 调用失败

原因: FIGMA_TOKEN 未配置或无效 解决: 检查环境变量配置

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT © CamScanner Team

🔗 相关资源

• Figma API 文档
• MCP 协议文档
• Vue 3 文档
• Element Plus 文档