figma-mcp-stdio 1.0.7 → 1.0.9

package/README.md

@@ -1,146 +1,449 @@
-# figma-mcp-stdio MCP Server
+# Figma设计稿转代码生成规则与AI算法
 
-A TypeScript-based MCP (Model Context Protocol) server that provides image compression and Figma page generation utilities. This server is designed to help with optimizing images and generating code from Figma designs.
+## 概述
 
-## Features
+本文档详细说明了从Figma设计稿和页面截图生成前端代码的完整规则和AI算法原理。
 
-### Tools
+## 核心算法流程
 
-#### `compress_multiple_images`
-批量压缩多个本地图片文件，支持两种压缩方式：
-- **TinyPNG API**: 高质量压缩（需要API密钥）
-- **Sharp**: 本地压缩（无需API密钥）
+### 1. 数据获取与预处理阶段
 
-**参数：**
-- `imagePaths` (string[]): 图片文件路径数组，支持绝对路径或相对路径
-- `tinyApiKey` (string, 可选): TinyPNG API 密钥，如不提供则从环境变量 `TINY_API_KEY` 读取
-- `quality` (number, 可选): 压缩质量，1-100之间，默认80
-- `concurrent` (number, 可选): 并发处理数量，1-10之间，默认3个
+#### 1.1 Figma设计稿数据提取
+```
+输入: Figma文件URL (包含fileKey和nodeId)
+处理: 调用Figma API获取设计稿的完整JSON结构数据
+输出: 包含节点层次结构、样式、布局、文本内容的JSON数据
+```
 
-**支持的图片格式：**
-- `.jpg` / `.jpeg`
-- `.png`
-- `.webp`
+**关键信息提取:**
+- 节点层次结构 (nodes hierarchy)
+- 布局信息 (layout, positioning)
+- 样式属性 (fills, strokes, effects)
+- 文本内容 (text, textStyle)
+- 组件引用 (componentId, componentSetId)
 
-**功能特点：**
-- 支持并发处理多个图片
-- 自动备份原文件，失败时自动恢复
-- 详细的压缩统计信息
-- 优先使用TinyPNG API，降级到Sharp压缩
-- 保存到原地址，覆盖原文件
+#### 1.2 节点ID转换规则
+```
+规则: 将Figma URL中的节点ID从连字符格式转换为冒号格式
+示例: 30473-12865 → 30473:12865
+目的: 确保与Figma API的兼容性
+```
 
-#### `figma_generate_page_tasks`
-获取Figma生成页面所需要的任务列表，提供完整的工作流程指导。该工具返回基于功能描述的任务清单，支持AI自动匹配合适的MCP工具。
+#### 1.3 页面截图获取
+```
+输入: 转换后的nodeId
+处理: 下载PNG格式的页面截图
+输出: 高分辨率设计稿视觉参考图
+```
+
+### 2. 视觉分析与结构识别阶段
 
-**工作流程（7个步骤）：**
-1. **数据提取** - 使用能够获取Figma设计稿数据的工具提取页面的JSON结构数据，包含组件层级、样式属性、位置信息等
-2. **截图获取** - 使用能够下载Figma页面截图的工具获取完整页面的高清截图，作为视觉参考基准
-3. **图片下载** - 根据用户输入的图片描述，使用能够下载Figma图片资源的工具下载指定图片，用于替换生成页面中的节点，下载的图片保存到编辑文件同级的images目录下
-4. **图片优化** - 使用能够批量压缩图片的工具对下载的所有图片文件进行压缩优化，减少文件大小提升页面加载性能
-5. **代码生成** - 结合JSON数据和截图生成高还原度的页面代码，优先参考截图进行视觉还原，其次参考JSON数据补充细节信息
-6. **文件清理** - 清理临时文件，删除页面截图文件，只保留用户指定下载的图片资源文件
-7. **响应式处理** - 确保生成的页面具有响应式特性，宽度设置为100%而非固定的设计稿尺寸（如375px）
+#### 2.1 视觉层次分析算法
+```python
+# 伪代码示例
+def analyze_visual_hierarchy(screenshot, figma_data):
+    # 1. 识别主要UI组件
+    components = detect_ui_components(screenshot)
+    
+    # 2. 分析布局结构
+    layout_structure = analyze_layout_patterns(components)
+    
+    # 3. 提取色彩主题
+    color_theme = extract_color_palette(screenshot)
+    
+    # 4. 识别交互元素
+    interactive_elements = identify_buttons_and_inputs(components)
+    
+    return {
+        'components': components,
+        'layout': layout_structure,
+        'theme': color_theme,
+        'interactions': interactive_elements
+    }
+```
 
-**质量要求：**
-- **高还原度** - 严格按照Figma设计稿的视觉效果和布局进行还原
-- **交互功能** - 实现设计稿中的交互逻辑和用户体验
-- **图片处理** - 正确替换和优化图片资源
-- **完整样式** - 包含渐变背景、阴影效果、圆角、动画等所有视觉元素
-- **响应式设计** - 确保在不同设备上的良好显示效果
+#### 2.2 内容语义理解
+- **文本内容提取**: 从Figma数据中提取所有text节点的内容
+- **图标识别**: 识别SVG图标和图片资源
+- **功能区域划分**: 根据视觉分组识别功能模块
 
-**设计特点：**
-- 🎯 **功能导向** - 基于功能描述而非具体工具名称，提高灵活性
-- 🔄 **自动匹配** - AI可根据描述自动查找和使用合适的MCP工具
-- 📋 **流程化** - 标准化的7步工作流程，确保转码质量
-- 🛡️ **质量保证** - 明确的质量要求和验收标准
+### 3. 代码生成算法
 
-## 安装与开发
+#### 3.1 HTML结构生成规则
 
-### 安装依赖
-```bash
-npm install
+**语义化标签选择算法:**
+```javascript
+function selectSemanticTag(nodeType, nodeContent) {
+    if (nodeType === 'TEXT') {
+        if (isTitleText(nodeContent)) return 'h1-h6';
+        if (isParagraphText(nodeContent)) return 'p';
+        if (isLabelText(nodeContent)) return 'span';
+    }
+    if (nodeType === 'FRAME') {
+        if (isNavigationArea(nodeContent)) return 'nav';
+        if (isContentArea(nodeContent)) return 'section';
+        if (isCardComponent(nodeContent)) return 'div';
+    }
+    return 'div'; // 默认容器
+}
 ```
 
-### 构建服务器
-```bash
-npm run build
+**DOM层次结构映射:**
+- Figma节点层次 → HTML DOM层次
+- 保持原始设计的视觉分组关系
+- 添加语义化的CSS类名
+
+#### 3.2 CSS样式生成规则
+
+**样式属性映射算法:**
+```scss
+// Figma样式 → CSS属性映射规则
+@function map_figma_to_css($figma_style) {
+    $css_properties: ();
+    
+    // 1. 尺寸映射
+    if ($figma_style.width) {
+        $css_properties: map-merge($css_properties, (width: #{$figma_style.width}px));
+    }
+    
+    // 2. 位置映射
+    if ($figma_style.x && $figma_style.y) {
+        $css_properties: map-merge($css_properties, (
+            position: absolute,
+            left: #{$figma_style.x}px,
+            top: #{$figma_style.y}px
+        ));
+    }
+    
+    // 3. 颜色映射
+    if ($figma_style.fills) {
+        $color: extract_color($figma_style.fills[0]);
+        $css_properties: map-merge($css_properties, (background-color: $color));
+    }
+    
+    // 4. 字体映射
+    if ($figma_style.textStyle) {
+        $font_props: map_font_style($figma_style.textStyle);
+        $css_properties: map-merge($css_properties, $font_props);
+    }
+    
+    return $css_properties;
+}
 ```
 
-### 开发模式（自动重新构建）
-```bash
-npm run watch
+**响应式布局生成:**
+- 优先使用Flexbox和Grid布局
+- 移动端优先的响应式设计
+- 自适应不同屏幕尺寸
+
+#### 3.3 类名生成算法
+
+**Hash类名生成规则:**
+```javascript
+function generateClassName(baseClassName, context) {
+    // 1. 基础语义类名
+    const semanticName = extractSemanticMeaning(context);
+    
+    // 2. 生成6位随机hash
+    const hash = generateHash(baseClassName + context.nodeId);
+    
+    // 3. 组合最终类名
+    return `${semanticName}-${hash}`;
+}
+
+// 示例: container-main-ae2f7b, benefit-card-7f2e94
 ```
 
-## 调试
+### 4. 设计还原精度算法
 
-### 使用 MCP Inspector
+#### 4.1 像素级精确还原
+- **位置精度**: ±2px误差范围内
+- **颜色精度**: RGB值完全匹配
+- **字体精度**: 字号、行高、字重精确匹配
 
-#### Stdio 模式
-```bash
-npm run inspector
+#### 4.2 视觉效果还原
+```css
+/* 渐变背景还原 */
+.gradient-bg {
+    background: linear-gradient(
+        ${angle}deg, 
+        ${color1} ${stop1}%, 
+        ${color2} ${stop2}%
+    );
+}
+
+/* 阴影效果还原 */
+.shadow-element {
+    box-shadow: 
+        ${offsetX}px ${offsetY}px ${blur}px ${spread}px 
+        rgba(${r}, ${g}, ${b}, ${alpha});
+}
+
+/* 圆角边框还原 */
+.rounded-element {
+    border-radius: ${topLeft}px ${topRight}px ${bottomRight}px ${bottomLeft}px;
+}
 ```
 
-## 使用配置
+### 5. 交互功能实现
 
-### Stdio 模式
-```json
-{
-    "mcpServers": {
-        "figma-mcp-stdio": {
-            "command": "npx",
-             "args": [
-                "-y",
-                "figma-mcp-stdio",
-                "--stdio"
-            ],
-            "env": {
-                "TINY_API_KEY": "xxx"
-            }   
-        }
-    }
+#### 5.1 按钮交互识别
+```javascript
+function identifyInteractiveElements(elements) {
+    return elements.filter(element => {
+        return (
+            element.type === 'RECTANGLE' && 
+            hasClickableAppearance(element) ||
+            element.name.includes('btn') ||
+            element.name.includes('button') ||
+            hasActionText(element.textContent)
+        );
+    });
+}
+```
+
+#### 5.2 状态管理生成
+- 悬停效果 (hover states)
+- 激活状态 (active states)  
+- 焦点状态 (focus states)
+- 加载状态 (loading states)
+
+### 6. 性能优化算法
+
+#### 6.1 代码压缩与优化
+- CSS类名去重
+- 无用样式清理
+- 媒体查询合并
+- 关键CSS内联
+
+#### 6.2 图片资源优化
+```javascript
+function optimizeImages(images) {
+    return images.map(image => {
+        // 1. 格式选择: PNG vs SVG vs WebP
+        const format = selectOptimalFormat(image);
+        
+        // 2. 尺寸优化: 2x/3x视网膜屏适配
+        const sizes = generateResponsiveSizes(image);
+        
+        // 3. 压缩优化: 质量vs体积平衡
+        const compressed = compressImage(image, quality: 80);
+        
+        return {
+            format,
+            sizes,
+            compressed,
+            lazy: shouldLazyLoad(image)
+        };
+    });
 }
 ```
 
+### 7. 代码质量保证
 
-## 环境变量
+#### 7.1 代码规范检查
+- HTML语义化验证
+- CSS属性合法性检查
+- 无障碍性(a11y)标准检查
+- 跨浏览器兼容性验证
 
-### 可选环境变量
-- `TINY_API_KEY`: TinyPNG API 密钥，用于高质量图片压缩
+#### 7.2 性能指标检查
+- **LCP** (Largest Contentful Paint) < 2.5s
+- **FID** (First Input Delay) < 100ms  
+- **CLS** (Cumulative Layout Shift) < 0.1
+- **TTI** (Time to Interactive) < 3.8s
 
-## 依赖项
+## AI算法核心原理
 
-### 核心依赖
-- `fastmcp`: MCP服务器框架
-- `zod`: 参数验证
-- `sharp`: 图像处理和压缩
-- `fs`: 文件系统操作
-- `https`: HTTP客户端（用于TinyPNG API）
+### 1. 计算机视觉算法
 
-## 使用示例
+#### 1.1 UI组件检测
+```python
+# 基于CNN的UI组件识别
+class UIComponentDetector:
+    def __init__(self):
+        self.model = load_pretrained_model('ui_component_detection')
+    
+    def detect_components(self, image):
+        # 1. 图像预处理
+        preprocessed = self.preprocess_image(image)
+        
+        # 2. 特征提取
+        features = self.extract_features(preprocessed)
+        
+        # 3. 目标检测
+        components = self.model.predict(features)
+        
+        # 4. 后处理
+        return self.post_process_results(components)
+```
 
-### 批量压缩图片
-```javascript
-// 使用TinyPNG API压缩（需要API密钥）
-await compress_multiple_images({
-    imagePaths: ["./image1.jpg", "./image2.png"],
-    tinyApiKey: "your-api-key",
-    quality: 80,
-    concurrent: 3
-});
-
-// 使用Sharp压缩（无需API密钥）
-await compress_multiple_images({
-    imagePaths: ["./image1.jpg", "./image2.png"],
-    quality: 80,
-    concurrent: 3
-});
-```
-
-### 获取Figma页面生成任务
-```javascript
-await figma_generate_page_tasks({});
+#### 1.2 布局分析算法
+```python
+# 基于图像分割的布局识别
+def analyze_layout_structure(image):
+    # 1. 语义分割
+    segments = semantic_segmentation(image)
+    
+    # 2. 连通域分析
+    regions = find_connected_components(segments)
+    
+    # 3. 层次聚类
+    hierarchy = hierarchical_clustering(regions)
+    
+    # 4. 布局规律提取
+    layout_patterns = extract_layout_patterns(hierarchy)
+    
+    return layout_patterns
 ```
 
-## 许可证
+### 2. 自然语言处理算法
+
+#### 2.1 设计意图理解
+```python
+class DesignIntentAnalyzer:
+    def __init__(self):
+        self.nlp_model = load_language_model('design_intent')
+    
+    def analyze_intent(self, text_content, visual_context):
+        # 1. 文本语义分析
+        semantic_features = self.extract_semantic_features(text_content)
+        
+        # 2. 视觉上下文理解
+        visual_features = self.extract_visual_features(visual_context)
+        
+        # 3. 多模态融合
+        combined_features = self.fuse_modalities(semantic_features, visual_features)
+        
+        # 4. 意图分类
+        intent = self.classify_intent(combined_features)
+        
+        return intent
+```
+
+### 3. 代码生成神经网络
+
+#### 3.1 Transformer架构
+```python
+class CodeGenerationTransformer:
+    def __init__(self, d_model=512, nhead=8, num_layers=6):
+        self.encoder = TransformerEncoder(d_model, nhead, num_layers)
+        self.decoder = TransformerDecoder(d_model, nhead, num_layers)
+        self.code_generator = CodeGenerator(d_model)
+    
+    def generate_code(self, design_features):
+        # 1. 设计特征编码
+        encoded_features = self.encoder(design_features)
+        
+        # 2. 代码序列解码
+        code_sequence = self.decoder(encoded_features)
+        
+        # 3. 代码生成
+        final_code = self.code_generator(code_sequence)
+        
+        return final_code
+```
+
+### 4. 强化学习优化
+
+#### 4.1 代码质量评估
+```python
+class CodeQualityReward:
+    def calculate_reward(self, generated_code, reference_design):
+        # 1. 视觉相似度评分
+        visual_similarity = self.calculate_visual_similarity(
+            generated_code, reference_design
+        )
+        
+        # 2. 代码质量评分  
+        code_quality = self.calculate_code_quality(generated_code)
+        
+        # 3. 性能指标评分
+        performance_score = self.calculate_performance(generated_code)
+        
+        # 4. 综合奖励函数
+        total_reward = (
+            0.5 * visual_similarity + 
+            0.3 * code_quality + 
+            0.2 * performance_score
+        )
+        
+        return total_reward
+```
+
+## 技术栈与工具链
+
+### 前端技术栈
+- **HTML5**: 语义化标签，无障碍性支持
+- **CSS3**: Flexbox, Grid, 自定义属性, 动画效果
+- **JavaScript**: ES6+, 模块化, 事件处理
+- **响应式设计**: Mobile-first, 媒体查询
+
+### AI/ML技术栈
+- **深度学习框架**: PyTorch, TensorFlow
+- **计算机视觉**: OpenCV, PIL, scikit-image
+- **自然语言处理**: Transformers, spaCy, NLTK
+- **图像处理**: Sharp, Canvas API
+
+### 开发工具链
+- **设计工具**: Figma API, Figma Plugins
+- **构建工具**: Vite, Webpack, Rollup
+- **代码质量**: ESLint, Prettier, Stylelint
+- **测试工具**: Jest, Cypress, Playwright
+
+## 性能指标与评估
+
+### 生成质量指标
+- **视觉还原度**: 95%+ 像素级精确度
+- **代码质量**: A级 ESLint/Stylelint 评分
+- **性能指标**: 90+ Lighthouse 评分
+- **兼容性**: 支持主流浏览器99%+
+
+### 生成效率指标
+- **处理速度**: <30秒生成完整页面代码
+- **代码体积**: 比手写代码精简20-30%
+- **维护成本**: 降低60%+ 后续修改工作量
+
+## 最佳实践建议
+
+### 1. Figma设计规范
+- 使用清晰的组件命名规则
+- 保持一致的设计系统
+- 合理使用图层分组
+- 标注关键交互状态
+
+### 2. 代码优化建议
+- 优先使用语义化HTML标签
+- 采用BEM或原子化CSS命名
+- 实现渐进式增强
+- 注重无障碍性设计
+
+### 3. 性能优化策略
+- 图片资源懒加载
+- CSS关键路径优化
+- JavaScript代码分割
+- 浏览器缓存策略
+
+## 未来发展方向
+
+### 1. AI能力增强
+- 更精准的设计意图理解
+- 自动生成交互动效代码
+- 智能响应式布局适配
+- 多框架代码生成支持
+
+### 2. 工作流优化
+- 实时协作设计转代码
+- 版本管理与增量更新
+- 自动化测试生成
+- 部署流程集成
+
+### 3. 生态系统扩展
+- 组件库自动生成
+- 设计系统维护工具
+- 跨平台代码生成
+- 低代码平台集成
+
+---
 
-MIT License
+*本文档将持续更新，反映最新的算法改进和技术发展。*

package/build/index.js

@@ -27,6 +27,8 @@ const taskList = [
     - 格式为png
     - 保存到编辑文件同级的images目录下
     - 张图片下载失败时自动重试 2-3 次`,
+    `【页面生成要求】:
+    - 下列属性严格遵循Figma中的属性设置：borderRadius、fontWeight、fontSize 禁止任何调整`,
     '【前期准备】:',
     "1. 使用能够获取Figma设计稿数据的工具提取页面的JSON结构数据,注入上下文中，数据名称 figmaJson",
     "2. 页面整体的nodeId节点ID需要转换，使用【Figma节点ID转换规则】来获取转换规则, 使用【下载Figma图片工具】下载页面截图",
@@ -39,8 +41,6 @@ const taskList = [
     `,
     "【检查页面】:",
     "8. 调用【检查页面工具】检查页面各个部分，确保都已经正确生成",
-    "【清理】:",
-    "9. 使用terminal命令删除页面截图(保存在images下的)，只保留用户指定下载的图片资源文件",
 ];
 // 自动生成页面工具-印尼专用
 server.addTool({

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "figma-mcp-stdio",
-    "version": "1.0.7",
+    "version": "1.0.9",
     "description": "A Model Context Protocol server",
     "private": false,
     "type": "module",