Figma MCP PRO

# Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [3.27.0] - 2025-06-05 ### 🔧 **CRITICAL FIX: Dynamic Require Error Eliminated** - **FIXED**: "Dynamic require of 'os' is not supported" error in check_reference tool - **REMOVED**: Complex helper functions that used dynamic require() calls - **SIMPLIFIED**: check_reference tool now only checks if reference.png exists in assets folder - **ELIMINATED**: Unnecessary retry logic, multiple search locations, and fallback directory scanning - **IMPROVED**: Clean, simple workflow - check reference → pass to next step ### 🎯 **Simplified check_reference Tool** - **STREAMLINED**: Simple path resolution and file existence check - **DIRECT**: No more complex search patterns or workspace enforcement - **FAST**: Immediate response - file exists or doesn't, simple as that - **CLEAR**: Clean success/error messages for next step guidance - **RELIABLE**: No more ES module compatibility issues ### 📦 **Bundle Size Optimization** - **REDUCED**: Bundle size from 210KB to 198KB by removing complex helper functions - **CLEANER**: Eliminated unused code paths and dynamic imports - **LIGHTER**: Faster tool execution with simplified logic ### 🚀 **Technical Improvements** - **Static Imports Only**: All imports are now static ES module imports - **No Dynamic Requires**: Eliminated all dynamic require() calls that caused ES module errors - **Simple Logic**: Straightforward file checking without complex fallback chains - **Better Error Handling**: Clear error messages without stack traces from dynamic imports **Result: check_reference tool now works reliably across all MCP environments!** 🎯 ## [3.17.0] - 2025-01-22 ### 🎯 **MAJOR: Direct Download Mode - No More File "Dancing"** - **NEW FEATURE**: `skipWorkspaceEnforcement` parameter added to all download methods - **ELIMINATED**: Workspace enforcement system completely bypassed for direct downloads - **FIXED**: Files now go **directly** to your specified project directory with zero intermediate steps - **REMOVED**: All temporary directory usage and file moving operations - **SIMPLIFIED**: Clean, straightforward download process with no complications ### 🚀 **Direct Download Implementation** - **Enhanced API**: Both `downloadImages()` and `downloadImagesWithExportSettings()` now support direct mode - **Parameter**: `{ skipWorkspaceEnforcement: true }` bypasses all workspace detection and file moving - **Direct Path**: Files download exactly where you specify - `./assets/file.png` stays in `./assets/file.png` - **No Temp Directories**: Eliminates `/Users/username/figma-mcp-workspace/assets/` completely - **Zero Movement**: No file copying, moving, or workspace "enforcement" operations ### ✅ **User Experience** - **Predictable**: Files land exactly where you tell them to - **Simple**: No more checking multiple directories for your files - **Reliable**: No partial failures where some files move and others don't - **Clean**: No leftover files in temporary workspaces - **Direct**: Zero intermediate steps between download and your project ### 🔧 **Technical Changes** - **API Enhancement**: `skipWorkspaceEnforcement?: boolean` parameter added to download options - **Conditional Logic**: Workspace enforcement only runs when `skipWorkspaceEnforcement !== true` - **Default Behavior**: All MCP tool calls now use direct download mode by default - **Backward Compatible**: Existing code without the parameter still works (with enforcement) - **Clean Implementation**: No breaking changes to existing functionality ### 📁 **Download Behavior** - **Before v3.17.0**: Download → Temp Directory → Move to Project → Possible Partial Failures - **After v3.17.0**: Download → Direct to Project Directory → Complete Success ### 🎯 **Perfect For** ✅ **Project Assets**: Files go directly to `./assets/` as specified ✅ **Reference Images**: `reference.png` appears exactly where expected ✅ **Export Assets**: All Figma exports land in your project immediately ✅ **Development Workflow**: No manual file recovery or moving required ✅ **All IDEs**: Works consistently in Cursor, Windsurf, VS Code, any environment **Result: Clean, predictable, direct downloads with zero complications!** 🎯 ## [3.15.0] - 2025-01-22 ### 🎯 **ENHANCED: Cursor IDE Asset Management** - **IMPROVED**: Assets are now **moved** instead of copied from Cursor fallback locations to project directory - **FIXED**: Reference.png naming issue with robust 3-tier fallback system for file renaming - **ENHANCED**: Better error handling and logging for asset management operations - **OPTIMIZED**: Cleaner asset recovery process that removes files from fallback locations ### 🔧 **Robust Reference.png Creation** - **Method 1**: Direct `fs.rename` (fastest, works if same filesystem) - **Method 2**: Copy + delete fallback (handles cross-filesystem operations and Cursor restrictions) - **Method 3**: Graceful fallback (uses original filename with warning if rename fails) - **LOGGING**: Detailed progress tracking: `"Frame_1234.png" → "reference.png"` - **VERIFICATION**: File size validation and success confirmation ### 📦 **Enhanced Asset Recovery** - **MOVE OPERATION**: Files are moved (not copied) from `/Users/username/figma-mcp-workspace/assets/` to project - **CLEAN FALLBACK**: Fallback locations are cleaned up after successful moves - **SMART DETECTION**: Only moves files that don't already exist in project or are newer - **ERROR RESILIENCE**: Continues with remaining files if individual moves fail ### 🛠️ **Cursor IDE Compatibility** - **AUTOMATIC DETECTION**: Finds assets in Cursor's fallback workspace locations - **SEAMLESS RECOVERY**: Automatically moves assets to actual project directory before reference check - **PATH RESOLUTION**: Uses same logic as figma-api.ts for consistent fallback location detection - **CLEAN WORKFLOW**: Users no longer need manual terminal commands to copy assets ### 📝 **Improved Logging** - **PROGRESS TRACKING**: Clear indication of file moving operations - **SUCCESS CONFIRMATION**: Detailed logging of successful reference.png creation methods - **ERROR CONTEXT**: Better error messages with specific failure reasons - **OPERATION SUMMARY**: Summary of how many assets were moved vs skipped ### Technical Implementation - **Unified Logic**: Asset detection uses same fallback locations as download operations - **Robust Renaming**: Three-tier fallback ensures reference.png is created even with filesystem restrictions - **Resource Management**: Files are moved (not duplicated) to save disk space - **Error Recovery**: Graceful handling when filesystem operations fail in restricted environments **Result**: Seamless asset management for Cursor IDE users - no more manual file moving required! 🚀 ## [3.2.0] - 2025-01-22 ### 🧪 **MAJOR: Comprehensive Testing Infrastructure** - **NEW**: Complete test suite with 5 test suites and 51 total tests covering all core functionality - **ADDED**: Framework testing for all 10 supported frameworks (React, Vue, Angular, Svelte, HTML, SwiftUI, UIKit, Electron, Tauri, NW.js) - **ADDED**: URL parsing tests for Figma URL extraction and node ID conversion - **ADDED**: Utility function tests for string manipulation, array operations, object utilities, and validation - **ADDED**: Configuration tests for rule validation and type safety verification - **ADDED**: Server functionality tests for environment variables, tool definitions, and error handling ### 🔧 **ENHANCED: Development Experience** - **NEW**: Quick test runner script (`npm run test:quick`) for complete project validation - **NEW**: Test coverage reports (`npm run test:coverage`) for code quality insights - **NEW**: Fast test execution (~6 seconds) for rapid development cycles - **NEW**: Comprehensive testing documentation in `docs/TESTING.md` - **IMPROVED**: Enhanced npm scripts for better developer workflow ### ⚡ **FIXED: TypeScript 5.8.3 Compatibility** - **UPGRADED**: ESLint packages from v6.21.0 to v8.33.1 for full TypeScript 5.8.3 support - **RESOLVED**: All 40+ ESLint warnings and configuration errors completely eliminated - **REMOVED**: TypeScript version compatibility warnings that cluttered development output - **ENHANCED**: Modern TypeScript tooling ecosystem with latest best practices ### 📚 **EXPANDED: Cross-Platform Documentation** - **ENHANCED**: Universal IDE compatibility documentation with Windows, macOS, and Linux platform support - **ADDED**: Detailed testing matrices for all platforms and IDEs (Cursor, Windsurf, TRAE, VS Code, WebStorm) - **ADDED**: Platform-specific troubleshooting guides for Windows, macOS, and Linux - **IMPROVED**: Installation documentation with modern cross-platform patterns ### 🛠️ **IMPROVED: Code Quality** - **ACHIEVED**: Zero linting warnings through proper ESLint configuration optimization - **ENHANCED**: Better error handling patterns with proper unused variable conventions - **MAINTAINED**: Type safety while preserving flexibility for API responses and configurations - **OPTIMIZED**: Clean build process with consistent 307KB output and proper source maps ### 🚀 **PERFORMANCE: Development Workflow** - **OPTIMIZED**: 6-second complete test cycle for rapid development feedback - **IMPROVED**: Efficient TypeScript compilation and bundling process - **ENHANCED**: Reliable CI/CD pipeline foundation with comprehensive test coverage - **STREAMLINED**: Better development experience with clean, warning-free output ### Technical Highlights - **Test Coverage**: Framework validation, URL parsing, utilities, configuration, server functionality - **Platform Support**: Windows 10/11, macOS 12+, Linux (Ubuntu, Debian, CentOS, Arch) - **IDE Compatibility**: Universal support across all major development environments - **Quality Assurance**: Production-ready codebase with comprehensive validation **Result**: Professional-grade testing infrastructure and cross-platform reliability for enterprise development! 🚀 ## [3.1.5] - 2025-01-22 ### 🎯 **ENHANCED: Comprehensive Framework Rule Optimization** - **OPTIMIZED**: All 10 framework configuration files for reduced text size while maintaining structure - **REMOVED**: All emoji symbols from implementation rules and check lists for cleaner output - **STREAMLINED**: Descriptions reduced by 50-70% while preserving technical accuracy - **ENHANCED**: Implementation examples condensed by removing redundant comments - **SIMPLIFIED**: Check items streamlined to essential points only ### Framework Improvements - **React**: Optimized 10 implementation rules including modern patterns, custom hooks, performance - **Vue**: Streamlined 9 implementation rules with Composition API, Pinia stores, accessibility - **Angular**: Enhanced 10 implementation rules with standalone components, Signals, modern templates - **Svelte**: Optimized 4 implementation rules with Svelte 5 runes, SvelteKit, accessibility - **HTML/CSS/JS**: Comprehensive 7 implementation rules with design tokens, modern CSS architecture - **SwiftUI**: Enhanced with state management, MVVM patterns, accessibility, performance - **UIKit**: Modern concurrency, SwiftUI interop, programmatic layouts, accessibility - **Electron**: Security hardening, IPC patterns, performance optimization, native integration - **Tauri**: Rust commands, event system, security, cross-platform builds - **NW.js**: Unified context, Node.js integration, Chromium APIs, file system access ### Technical Improvements - **Text Reduction**: 50-70% reduction in framework rule text size - **Maintained Functionality**: All implementation rules and priorities preserved - **Enhanced Readability**: Concise examples with modern syntax and best practices - **Clean Output**: Professional appearance without emoji clutter - **Bundle Optimization**: Smaller configuration files for faster processing ### Code Quality - **Modern Patterns**: Updated all examples to use latest framework features and patterns - **TypeScript Integration**: Enhanced TypeScript examples across all frameworks - **Accessibility Focus**: Improved accessibility guidelines across all frameworks - **Performance Optimization**: Better performance patterns documented - **Security**: Enhanced security practices especially for desktop frameworks **Result**: All framework configurations now provide the same comprehensive guidance in a much more compact, professional format! 🚀 ## [3.1.4] - 2025-01-22 ### 🚀 **FINAL UNIVERSAL RELEASE: Cross-Platform Compatibility** - **CONFIRMED**: Universal solution working across Windows, macOS, and Linux - **TESTED**: ES module imports properly handle all platform-specific path formats - **VALIDATED**: Path resolution works in all IDEs (Cursor, Windsurf, TRAE, VS Code, WebStorm) ## [3.1.3] - 2025-01-22 ### 🌟 **UNIVERSAL: Cross-Platform ES Module Solution** - **FIXED**: Windows ES module error `ERR_UNSUPPORTED_ESM_URL_SCHEME` with protocol 'c:' - **ENHANCED**: Universal ES module importer using `pathToFileURL()` for all platforms - **ADDED**: Cross-platform utility module (`UniversalESM`) for future compatibility - **IMPROVED**: Enhanced bin script with universal module loading and detailed error reporting - **SOLVED**: Windows absolute path issues in ES module contexts - **PLATFORM**: Full compatibility across Windows, macOS, and Linux ### Technical Improvements - **Universal Import**: `pathToFileURL()` conversion for Windows file:// URL requirements - **Fallback Strategy**: Multiple import attempts with detailed error reporting - **Platform Detection**: Built-in OS detection and platform-specific handling - **Debug Logging**: Comprehensive platform and path debugging information ## [3.1.2] - 2025-01-22 ### 🔧 **CRITICAL FIX: Cursor MCP Environment** - **FIXED**: Cursor MCP issue where `process.cwd()` returns `/` causing "ENOENT: no such file or directory, mkdir '/assets'" - **ENHANCED**: Smart detection of Cursor MCP problematic environment (when cwd='/' and PWD='/') - **ADDED**: Cursor MCP-specific working directory resolution with multiple fallback strategies - **IMPROVED**: Alternative environment variable scanning for MCP workspace detection - **SOLVED**: Universal compatibility - now works in ALL IDEs including Cursor, Windsurf, TRAE, VS Code ## [3.1.1] - 2025-01-22 ### 🔧 **TypeScript Fix** - **FIXED**: TypeScript compilation error with environment variable types (`string | undefined` vs `string | null`) ## [3.1.0] - 2025-01-22 ### 🌟 **MAJOR: Universal IDE Compatibility - Works Everywhere!** - **BRILLIANT SOLUTION**: Created universal path resolution system that works across ALL IDEs - **FIXED**: Image download issues in Windsurf, TRAE, and other IDEs that previously failed - **ENHANCED**: Comprehensive fallback chain for different IDE environment variables - **ADDED**: Asset verification system to confirm downloads work correctly - **IMPROVED**: Enhanced user feedback with relative paths and verification status ### 🔧 **Universal Path Resolution System** - **Multi-Environment Support**: Works in Cursor, Windsurf, TRAE, VS Code, WebStorm, and any IDE - **Smart Fallback Chain**: 1. `process.cwd()` - Standard Node.js working directory 2. `process.env.PWD` - Unix/Linux current directory 3. `process.env.INIT_CWD` - npm initial directory 4. `process.env.PROJECT_ROOT` - Custom project root (some IDEs) 5. `process.env.WORKSPACE_ROOT` - Workspace root (some IDEs) 6. `process.env.npm_config_prefix` - npm configuration prefix 7. `/tmp/figma-assets` - Final fallback - **Cross-Platform**: Consistent behavior on macOS, Windows, and Linux - **Safety Features**: Prevents dangerous directory creation in system locations ### 🛡️ **Enhanced Directory Creation & Verification** - **Permission Testing**: Verifies write access with temporary file creation - **Directory Validation**: Confirms directories exist and are accessible after creation - **Full Permissions**: Sets `mode: 0o755` for universal compatibility - **Safety Blocks**: Enhanced protection against dangerous paths (`/bin`, `/usr`, `/etc`, `/root`, `/var`, `/sys`, `/proc`) - **Error Context**: Comprehensive debugging information with environment variables ### ✅ **New Asset Verification System** - **Post-Download Verification**: Confirms all files exist at expected locations - **Relative Path Generation**: Provides cross-IDE compatible paths (e.g., `./assets/image.svg`) - **File Size Information**: Reports file sizes for verification - **Status Indicators**: Clear ✅/⚠️ indicators for successful/failed downloads - **Verification Logging**: Detailed confirmation of asset availability ### 📝 **Enhanced User Experience** - **Relative Paths**: All output uses relative paths for IDE compatibility - **Verification Status**: Shows which files were successfully verified - **File Information**: Displays file sizes and relative paths - **Universal Workflow**: Clear instructions for cross-IDE development - **Better Error Messages**: Informative error context with environment details ### 🏢 **IDE Compatibility Matrix** | IDE | Status | Notes | |-----|--------|-------| | Cursor | ✅ Working | Primary development environment | | Windsurf | ✅ Fixed | Now works with universal path resolution | | TRAE | ✅ Fixed | Environment variable fallbacks resolve issues | | VS Code | ✅ Working | Compatible with existing logic | | WebStorm | ✅ Working | npm_config_prefix fallback helps | ### 🔄 **Migration & Backward Compatibility** - **No Breaking Changes**: All existing functionality preserved - **Automatic Upgrading**: Existing absolute paths still work when valid - **Enhanced Results**: Additional verification info in download results - **Recommendation**: Use relative paths like `./assets` for best compatibility ### 📋 **Usage Recommendations** - **For Users**: Always use relative paths (`./assets` instead of `/absolute/path`) - **For Developers**: Check `relativePath` and `verified` properties in results - **For Troubleshooting**: Review verification status and use relative paths shown in output ### 📊 **Technical Improvements** - **Path Resolution**: Universal `resolvePath()` method with comprehensive fallbacks - **Directory Safety**: Enhanced `createDirectorySafely()` with verification testing - **Asset Verification**: New `verifyAssetsLocation()` method for post-download confirmation - **Error Handling**: Better error context with environment variable debugging - **Performance**: No runtime overhead, all verification happens after successful downloads ### 🎯 **Key Benefits** ✅ **Universal Compatibility**: Works in ANY IDE or development environment ✅ **Automatic Fallbacks**: Handles different IDE configurations seamlessly ✅ **Asset Verification**: Confirms downloads actually work in your environment ✅ **Better UX**: Clear relative paths and verification status for confident development ✅ **Safety First**: Prevents dangerous system directory creation ✅ **Future-Proof**: Supports new IDEs through comprehensive environment variable checking **Result**: The Figma MCP Server now works flawlessly across ALL development environments! No more IDE-specific issues with image downloads. 🚀** ## [3.0.15] - 2025-01-21 ### 🔧 **CRITICAL FIX: Cursor MCP Path Resolution Issue** - **FIXED**: Critical path resolution bug in Cursor MCP environment causing `mkdir '/assets'` errors - **ROOT CAUSE**: Cursor MCP environment returns `process.cwd() === '/'` instead of workspace directory - **ISSUE**: Relative paths like `./assets` or `assets` were being resolved to filesystem root `/assets` - **SOLUTION**: Enhanced path resolution with MCP environment detection and safe fallbacks ### What Was Fixed - **Before**: `./assets` → `/assets` (filesystem root) ❌ ENOENT error - **After**: `./assets` → `/workspace/path/assets` (correct location) ✅ Works reliably ### Technical Implementation - **🛡️ Environment Detection**: Detects when `process.cwd()` returns `/` (MCP issue indicator) - **🔄 Safe Fallbacks**: Uses `PWD`, `INIT_CWD` environment variables to find real workspace - **⚠️ Safety Blocks**: Prevents dangerous directory creation at `/`, `/bin`, `/usr`, `/etc` - **🧹 Path Sanitization**: Forces relative paths by stripping leading slashes - **📝 Enhanced Debugging**: Comprehensive logging for environment and path resolution ### Environment Handling - **Normal environments**: Standard `path.resolve(cwd, cleanPath)` - **MCP environments**: Uses `process.env.PWD || process.env.INIT_CWD || '/tmp/figma-mcp'` - **Fallback defaults**: Safe directory names like `assets` or `figma-assets` - **Safety validation**: Blocks creation of directories in system locations ### Debugging Enhancements - **Environment info**: Logs `cwd`, `PWD`, `INIT_CWD` values for diagnosis - **Path tracking**: Shows original input → normalized → cleaned → resolved path chain - **Error context**: Detailed error information with environment variables ### MCP Client Compatibility ✅ **Cursor**: Fixed `/assets` root creation error ✅ **Other MCP Clients**: Improved compatibility across different environments ✅ **Path Safety**: No more dangerous system directory creation attempts ✅ **Error Diagnosis**: Clear logging for troubleshooting path issues in any environment **Result**: Directory creation now works reliably in all MCP environments, especially Cursor! 🛠️ ## [3.0.14] - 2025-01-21 ### 🔧 **CRITICAL FIX: Complete Dynamic Import Removal** - **FIXED**: Remaining dynamic imports causing path resolution failures in both `createVisualReference` and `handleCheckReference` methods - **ISSUE**: Previous fix in v3.0.13 missed dynamic imports in the actual tool handlers, still causing `/assets` vs `./assets` path resolution errors - **SOLUTION**: - Added static imports for `path` and `fs` at top of `src/index.ts` - Removed all remaining `await import('path')` and `await import('fs/promises')` dynamic imports - Fixed both `createVisualReference` method and `handleCheckReference` method to use static imports - All path resolution now uses consistent, reliable static module imports ### What Was Fixed - **Before**: Dynamic imports in 3 places causing path resolution to fail ❌ - **After**: All static imports, consistent path resolution across all methods ✅ ### Technical Details - **Static Imports Added**: `import path from 'path'` and `import fs from 'fs/promises'` in `src/index.ts` - **Removed Dynamic Imports**: All `await import('path')` and `await import('fs/promises')` calls - **Methods Fixed**: Both `createVisualReference` and `handleCheckReference` methods - **Consistent Resolution**: All path operations now use the same reliable static module imports **Result**: Directory creation now works reliably - no more `/assets` at filesystem root errors! 📁 ## [3.0.12] - 2025-01-01 ### 🔧 **FIXED: check_reference Tool Improvements** - **REMOVED**: All emoji from design analysis guidance (clean professional output) - **FIXED**: Use relative paths instead of absolute paths in responses - **SIMPLIFIED**: Removed unnecessary "assets" section - focus only on reference.png inspection - **CLEANER**: Streamlined output to tell AI exactly what to do with reference.png - **REDUCED**: Bundle size from 146.71 KB to 143.94 KB ### Technical Changes - **Path Handling**: `./assets/reference.png` instead of `/absolute/path/to/assets/reference.png` - **Response Format**: Simplified JSON structure with essential information only - **Analysis Guidance**: Single clean array instead of complex nested object with emoji - **Message**: Clear instruction for AI to inspect reference.png file **Result**: Much cleaner check_reference tool output focused on AI workflow! 🔧 ## [3.0.11] - 2025-01-01 ### 📝 **IMPROVED: Minimized README & Added Claude Code Support** - **SIMPLIFIED**: README reduced from 500+ lines to ~200 lines with only essential information - **ENHANCED**: Cleaner framework selection text (50% shorter, scannable format) - **NEW**: Added Claude Code (VS Code Extension) connection instructions - **ORGANIZED**: Better structure with clear step-by-step workflow - **FOCUSED**: Removed verbose development details, kept only user-facing features - **PROFESSIONAL**: Clean tool descriptions without emoji ### Documentation Improvements - **Concise Framework List**: Changed from verbose descriptions to key technologies only - **Unified MCP Setup**: Clear instructions for Claude Desktop, Claude Code, Cursor, Windsurf, TRAE - **Essential Tools**: Focused documentation on the 5-step workflow - **Quick Reference**: What you get from each tool type (Design Data, Smart Comments, Asset Downloads) ### Technical Changes - **Removed**: Unused `frameworkDescriptions` import and export - **Updated**: Framework response format to be more concise - **Improved**: Tool descriptions for better clarity **Result**: Much cleaner, focused README that gets users up and running quickly with Claude Code support! 📝 ## [3.0.10] - 2025-01-01 ### 🔧 **CRITICAL FIX: Path Resolution Bug** - **FIXED**: Critical path resolution issue causing "•/path" character encoding errors in MCP clients - **ISSUE**: Relative paths like `./cv-assets` were being corrupted and resolved incorrectly - **ROOT CAUSE**: Character encoding problems and inconsistent path handling between different methods - **SOLUTION**: Comprehensive path resolution refactoring with robust error handling ### Technical Fixes - **🛠️ Path Normalization**: Remove non-ASCII characters that could cause encoding issues - **🔄 Unified Resolution**: Added `resolvePath()` and `createDirectorySafely()` helper methods - **✅ Better Validation**: Validate resolved paths before directory creation - **📝 Enhanced Logging**: Structured error logging to avoid character corruption - **🔗 Consistency**: Same path logic across all download and check methods ### Path Resolution Improvements - **Before**: `./cv-assets` → `•/cv-assets` (corrupted) - **After**: `./cv-assets` → `/full/path/to/cv-assets` (clean resolution) ### Error Message Improvements - **Before**: `Failed to create directory •/cv-assets: ENOENT` - **After**: `Failed to create directory: ENOENT: no such file or directory` ### Files Updated - **`src/services/figma-api.ts`**: Added helper methods and updated both download functions - **`src/index.ts`**: Updated `check_reference` handler with same robust path resolution - **Unified Logic**: All path resolution now uses the same tested, reliable approach ### MCP Client Compatibility ✅ **Cursor**: Relative paths now work correctly ✅ **Other MCP Clients**: Better compatibility across different environments ✅ **Character Encoding**: No more `•` or other character corruption issues ✅ **Error Messages**: Clear, readable error messages without path corruption **Result**: Path resolution now works reliably across all MCP clients and environments! 🛠️ ## [3.0.9] - 2025-01-21 ### 🎯 **MAJOR: Added Visual Design Analysis Tool - STEP 5** - **NEW TOOL**: `check_reference` - Analyze reference.png before development - **5-STEP WORKFLOW**: Added design analysis step after downloads for better development planning - **VISUAL CONTEXT**: Examines reference.png file and provides design understanding guidance - **FRAMEWORK-AWARE**: Provides framework-specific analysis guidance for optimal development approach ### New Tool: check_reference - **Purpose**: Analyze the reference.png file created by download_design_assets - **Input**: Path to assets folder containing reference.png + optional framework choice - **Output**: Design analysis guidance, file information, and development planning steps - **Analysis**: What to look for, layout patterns, component structure, and framework-specific guidance ### Framework-Specific Design Analysis - **React**: Component boundaries, state management, prop passing, React patterns - **Vue**: Component composition, reactive data, directives, Composition API - **Angular**: Component architecture, services, directives, reactive forms - **Svelte**: Component boundaries, stores, reactive statements, transitions - **HTML**: Semantic structure, CSS Grid/Flexbox, custom properties, accessibility ### Enhanced 5-Step Workflow 1. **STEP 1**: `show_frameworks` - Choose target framework 2. **STEP 2**: `get_figma_data` - Get design data with framework optimization 3. **STEP 3**: `process_design_comments` - Analyze designer comments and instructions 4. **STEP 4**: `download_design_assets` - Download export-ready assets + reference.png 5. **STEP 5**: `check_reference` - Analyze design visually before development ### What You Get ✅ **Visual Analysis**: Comprehensive design understanding from reference.png ✅ **Development Planning**: Step-by-step guidance for approaching the design ✅ **Framework Optimization**: Targeted advice based on your chosen framework ✅ **Asset Overview**: Complete inventory of downloaded assets and reference file ✅ **Context Understanding**: Layout patterns, components, and visual hierarchy analysis ### Technical Implementation - **File Validation**: Checks if reference.png exists in assets folder - **Asset Scanning**: Lists all available asset files (SVG, PNG, JPG, PDF) - **Framework Guidance**: Dynamic analysis recommendations based on framework choice - **Error Handling**: Clear guidance if reference.png is missing (suggests running download_design_assets first) - **Bundle Size**: 147.09 KB (from 139.37 KB) for comprehensive visual analysis **Perfect workflow: Now includes visual design understanding before code development!** 🎨 ## [3.0.13] - 2025-01-21 ### 🔧 **CRITICAL FIX: Directory Creation Path Resolution** - **FIXED**: Directory creation failure in `download_design_assets` tool - **ISSUE**: Tool was trying to create directories at filesystem root (e.g., `/assets`) instead of workspace relative paths - **ROOT CAUSE**: Dynamic imports of `path` and `fs` modules in MCP environment causing path resolution issues - **SOLUTION**: - Moved `path` and `fs` imports to static top-level imports - Fixed `resolvePath()` method to be synchronous instead of async - Improved path normalization and resolution logic - Added comprehensive debug logging for path resolution ### What Was Wrong - **Before**: `mkdir '/assets'` → Failed with ENOENT error ❌ - **After**: `mkdir './assets'` → Works correctly in workspace ✅ ### Technical Details - Replaced dynamic `await import('path')` with static `import path from 'path'` - Removed async from `resolvePath()` method signature - Enhanced path cleaning with empty path fallback to `'.'` - Added detailed logging for path resolution debugging ### Bundle Impact - **Bundle Size**: 433.0 kB unpacked (from 432.8 kB) - minimal increase for robust path handling - **Files**: 6 core files maintained - **Performance**: Improved (no dynamic imports during runtime) **Directory creation now works reliably across all MCP environments!** 📁 ## [3.0.8] - 2025-01-21 ### 🔧 **CRITICAL FIX: PNG Reference Format Actually Working** - **FIXED**: Changed default format in `downloadImages` method from `'svg'` to `'png'` - **ISSUE**: Even though v3.0.7 specified PNG format, the download method was defaulting to SVG - **ROOT CAUSE**: `figma-api.ts` line 543 had `(options.format || 'svg')` overriding our PNG format - **SOLUTION**: Updated default to `(options.format || 'png')` to ensure PNG is actually used ### What Was Wrong - **v3.0.7**: We set `format: 'png'` in createVisualReference ✅ - **v3.0.7**: But downloadImages method defaulted to SVG when format was undefined ❌ - **v3.0.8**: Now downloadImages method defaults to PNG ✅ ### Now Fixed ✅ **Reference files**: Now actually created as `reference.png` ✅ **High quality**: 2x scale PNG images for clear visual context ✅ **No more SVG**: Default format changed from SVG to PNG throughout **This time the PNG format really works!** 🖼️ ## [3.0.7] - 2025-01-21 ### 🖼️ **CHANGED: Reference Format from SVG to PNG** - **UPDATED**: Visual reference format changed from `reference.svg` to `reference.png` - **ENHANCED**: Better image quality with 2x scale (previously 1x for SVG) - **IMPROVED**: PNG format provides better preview for visual context - **CONSISTENT**: All references, logs, and instructions updated to use PNG format ### Changes Made - **Reference Download**: Changed from SVG 1x scale to PNG 2x scale - **Filename**: `reference.svg` → `reference.png` - **Tool Description**: Updated to reflect PNG format - **Instructions**: All workflow steps now reference PNG format - **Messages**: Updated success/error messages to use PNG ### Benefits of PNG Format ✅ **Better Quality**: 2x scale provides crisp preview images ✅ **Universal Support**: PNG works in all image viewers and browsers ✅ **Clear Visual Context**: Higher resolution for better design understanding ✅ **Consistent Format**: Matches common image export expectations **Result**: Visual reference files are now high-quality PNG images instead of SVG! 🖼️ ## [3.0.6] - 2025-01-21 ### 🎯 **MAJOR: Simplified Comment Processing Response** - **STREAMLINED**: Drastically simplified response structure - just what you need! - **CLEAN OUTPUT**: Removed verbose analysis, matching details, and redundant metadata - **FOCUSED**: Shows only: `instruction` + `targetElement` + `author` + `coordinates` - **ENHANCED**: Better coordinate extraction directly from `client_meta.node_offset` - **OPTIMIZED**: Bundle size reduced from 150.70 KB to 139.37 KB (-11.33 KB) ### New Clean Response Structure **Before** (v3.0.5 - Complex): ```json { "summary": {...}, "comments": [{ "comment": {...}, "targetElement": {...}, "matching": {...}, "instruction": {...}, "aiPrompt": "..." }], "framework": "...", "nodeSelection": "..." } ``` **After** (v3.0.6 - Simple): ```json { "implementations": [{ "instruction": "Jumping animation on hover.", "targetElement": "Button Component", "author": "Designer Name", "coordinates": { "x": 100, "y": 200 } }], "framework": "html", "nodeContext": "Comments for node: 1530-166" } ``` ### What You Get Now ✅ **Just the essentials**: What to implement and where ✅ **Clear targeting**: Specific element names instead of complex matching data ✅ **Real coordinates**: Proper extraction from Figma API structure ✅ **Cleaner workflow**: No analysis noise, just actionable instructions ✅ **Smaller bundle**: 11KB smaller for faster loading **Perfect for direct implementation - no more information overload!** 🎯 ## [3.0.5] - 2025-01-21 ### 🔧 **FIXED: Comment Processing Response Structure & Coordinate Extraction** - **REMOVED**: Duplicate `aiPrompts` array from response (was redundant with individual `comment.aiPrompt` fields) - **FIXED**: Comment coordinate extraction to use proper Figma API structure (`client_meta.node_offset.x/y`) - **ENHANCED**: Coordinate detection with proper fallback hierarchy: - Primary: `client_meta.node_offset.x/y` (standard Figma comment positioning) - Fallback: `client_meta.x/y` (alternative structure) - Last resort: root level `x/y` (rare cases) - **IMPROVED**: Better debugging output for coordinate issues - **CLEANED**: Removed unused imports and methods for cleaner codebase ### Response Structure Changes **Before** (v3.0.4): ```json { "summary": { "aiPrompts": 1 }, "comments": [{ "aiPrompt": "..." }], "aiPrompts": ["..."], // ❌ Duplicate data "coordinates": null // ❌ Always null } ``` **After** (v3.0.5): ```json { "summary": { "elementsFound": 15 }, "comments": [{ "aiPrompt": "...", "coordinates": { "x": 100, "y": 200 }, // ✅ Real coordinates "targetElement": { ... } // ✅ Matched elements }] } ``` ### Technical Improvements - **Fixed**: Proper Figma API comment structure parsing - **Enhanced**: Element matching with actual coordinates instead of always null - **Improved**: TypeScript compliance by removing unused variables - **Cleaner**: Bundle size reduced from 152.11 KB to 150.70 KB **Result**: Comment processing now properly matches comments to specific design elements using real coordinates! 🎯 ## [3.0.4] - 2025-01-21 ### ✨ **ENHANCED: No README.md Generation for HTML Framework** - **ADDED**: "No README.md generation" rule to HTML framework for cleaner project structure - **PRIORITY**: Medium priority rule focusing on code quality over documentation files - **PHILOSOPHY**: HTML/CSS/JS projects should focus on clean code structure and comments - **VALIDATION**: Added to validation checklist to ensure compliance ### New Implementation Rule - **Rule**: No README.md generation - **Description**: Do not generate README.md files for HTML/CSS/JS projects - focus on clean code structure and comments instead - **Priority**: Medium - **Benefits**: - Cleaner project structure without unnecessary documentation files - Focus on self-documenting code through clear HTML structure and CSS organization - Less clutter in simple HTML/CSS/JS projects - Code quality takes precedence over documentation files ### Enhanced Validation - **Updated Checklist**: Added "✓ No README.md file generated - focus on code quality and structure" - **Total Rules**: Now 13 comprehensive implementation rules for HTML framework - **Focus**: Emphasizes clean code and structure over documentation generation ### Philosophy For HTML/CSS/JS projects, the code should be self-documenting through: - Clear BEM methodology class naming - Semantic HTML structure - Well-organized CSS with meaningful comments - Clean, readable JavaScript code **Result**: HTML framework now avoids generating unnecessary README.md files, focusing purely on code quality and structure! 📝 ## [3.0.3] - 2025-01-21 ### ✨ **ENHANCED: BEM Methodology for Clear CSS Structure** - **ADDED**: BEM (Block Element Modifier) naming convention rule to HTML framework - **PRIORITY**: High priority rule for maintainable, scalable CSS architecture - **ENHANCED**: Semantic HTML rule to work with BEM for optimal structure - **VALIDATION**: Added BEM verification to validation checklist ### New BEM Implementation Rule - **Rule**: BEM methodology - **Description**: Use BEM naming convention: `block-name`, `block__element`, `block--modifier`, `block__element--modifier` - **Priority**: High - **Benefits**: - Clear component structure and hierarchy - Reusable and modular CSS components - Easier maintenance and debugging - Better team collaboration and code understanding - Scalable architecture for large projects ### BEM Naming Convention Examples ```html <!-- Block --> <article class='product-card'> <!-- Elements --> <h2 class='product-card__title'>Product Name</h2> <p class='product-card__description'>Description</p> <button class='product-card__button'>Add to Cart</button> </article> <!-- Block with Modifier --> <article class='product-card product-card--featured'> <!-- Element with Modifier --> <button class='product-card__button product-card__button--large'>Buy Now</button> </article> ``` ### Enhanced Semantic HTML - **Updated**: Semantic HTML rule now emphasizes combining semantic tags with BEM class names - **Example**: `<section class='hero'><article class='hero__content'><header class='hero__header'></header></article></section>` ### Enhanced Validation - **Updated Checklist**: Added "✓ BEM methodology applied for class naming (block__element--modifier)" - **Total Rules**: Now 12 comprehensive implementation rules for HTML framework - **Code Quality**: Ensures professional CSS architecture and maintainability **Result**: HTML framework now enforces BEM methodology for crystal-clear, maintainable CSS structure that scales perfectly with project complexity! 🎯 ## [3.0.2] - 2025-01-21 ### ✨ **ENHANCED: No Inline Styles Rule** - **ADDED**: "No inline CSS styles" rule to HTML framework for clean, maintainable code - **PRIORITY**: High priority rule enforcing separation of concerns - **VALIDATION**: Added to validation checklist to ensure compliance ### New Implementation Rule - **Rule**: No inline CSS styles - **Description**: Use only external CSS files and class names; avoid inline style attributes - **Priority**: High - **Benefits**: Better maintainability, separation of concerns, cleaner HTML markup - **Example**: - ✅ Good: `<div class='hero-section'>` - ❌ Bad: `<div style='padding: 16px; color: #1f2937;'>` ### Enhanced Validation - **Updated Checklist**: Added verification step for inline styles - **Total Rules**: Now 11 comprehensive implementation rules for HTML framework - **Code Quality**: Ensures clean, professional HTML/CSS separation **Result**: HTML framework now enforces external CSS files only, promoting better code organization and maintainability! 📝 ## [3.0.1] - 2025-01-21 ### ✨ **ENHANCED: HTML Framework Implementation Rules** - **ADDED**: Comprehensive Figma-to-HTML implementation rules for pixel-perfect accuracy - **ENHANCED**: HTML framework configuration with detailed implementation guidelines - **IMPROVED**: First-attempt accuracy by prioritizing metadata fidelity ### New HTML Implementation Rules #### 🎯 **Critical Priority Rules** 1. **Metadata Fidelity**: Use exact padding, margins, font-sizes, colors, and dimensions from Figma data 2. **Typography Precision**: Apply exact font-size, line-height, and letter-spacing from metadata 3. **Color Accuracy**: Use exact hex/rgba values from design tokens 4. **Validation Checklist**: 8-point verification system before completion #### 📐 **High Priority Rules** 5. **Flexible Containers**: Child elements use width: 100% or flex: 1; containers use max-width 6. **Margin Conflicts**: Remove conflicting margins in flexbox/grid; let containers handle spacing 7. **Responsive by Default**: Mobile-first implementation with proper breakpoints 8. **Semantic HTML**: Proper tags (`<section>`, `<article>`, `<header>`) with meaningful classes #### 🎨 **Medium Priority Rules** 9. **Box-shadow over Border**: Use `box-shadow: 0 0 0 1px color` for pixel-perfect rendering 10. **Animation Integration**: Add hover effects and transitions as specified in design ### Implementation Examples ```css /* Metadata Fidelity */ padding: 16px; /* exact from Figma metadata */ /* Flexible Containers */ .child { width: 100%; } .container { max-width: 1200px; } /* Box-shadow Borders */ box-shadow: 0 0 0 1px #e5e7eb; /* instead of border */ /* Typography Precision */ font-size: 16px; line-height: 1.5; letter-spacing: -0.01em; ``` ### Validation Checklist - ✓ All dimensions match Figma metadata exactly - ✓ Colors use exact hex/rgba values - ✓ Typography matches font-size, line-height, letter-spacing - ✓ Responsive behavior works on mobile, tablet, desktop - ✓ Container containment prevents overflow - ✓ Semantic HTML structure is meaningful - ✓ Accessibility attributes are present - ✓ Hover states and animations work as designed ### Technical Implementation - **Enhanced**: `HTMLOptimizations` interface with `implementationRules` property - **Structured**: Rules with priority levels, descriptions, and examples - **Type-safe**: Full TypeScript support for implementation guidelines - **Framework-specific**: Rules integrated into HTML framework configuration **Result**: HTML framework now includes comprehensive implementation rules that ensure first-attempt accuracy and pixel-perfect Figma-to-code conversion! 🎯 ## [3.0.0] - 2025-01-21 ### 🚀 **MAJOR: Automatic Export Asset Discovery & Download** - **BREAKING**: Completely redesigned `download_design_assets` tool for automatic asset discovery - **NEW WORKFLOW**: Takes Figma URL → Scans selected area → Finds ALL export-ready assets → Downloads with Figma settings - **INTELLIGENT**: No more manual node ID specification - automatically finds what's meant to be exported ### Revolutionary Asset Download Workflow #### Before (Manual, Error-Prone) ```json { "fileKey": "ABC123", "nodeIds": ["1530-166", "1530-167", "1530-168"], // Manual specification "localPath": "./assets" } ``` #### After (Automatic, Intelligent) ```json { "url": "https://figma.com/design/ABC123/Design?node-id=1530-166", "localPath": "./assets" } ``` ### How It Works 1. **URL Parsing**: Extracts file key and selected area from Figma URL 2. **Deep Scan**: Recursively searches selected area for nodes with `exportSettings` 3. **Figma Export Settings**: Downloads each asset with its configured export settings (format, scale, suffix) 4. **Reference Creation**: Creates `reference.svg` of the entire selected area for context 5. **Smart Reporting**: Shows exactly what was found and downloaded ### New Features - **🔍 Export Settings Detection**: Automatically finds nodes with Figma export settings configured - **📱 Figma URL Support**: Direct URL input like other tools - no manual file key extraction needed - **🎯 Area Scanning**: Scans only the selected area, not entire document - **⚙️ Native Export Settings**: Uses actual Figma export settings (format, scale, naming) - **📄 Visual Reference**: Creates `reference.svg` showing the selected area context - **📊 Detailed Reporting**: Shows scope, found assets, download results ### API Changes (BREAKING) - **Removed**: `nodeIds` array parameter (manual specification) - **Added**: `url` parameter for direct Figma URL input - **Added**: `nodeId` parameter for specific area selection - **Changed**: `fileKey` now optional if `url` provided - **Changed**: `scale` and `format` now fallback values (export settings take precedence) ### Enhanced Output ```json { "downloads": [...], // Actual downloaded assets with export settings "reference": {...}, // reference.svg creation details "exportSettings": { "found": 12, // Total nodes with export settings found "downloaded": 10, // Successfully downloaded "scope": "Selected area: 1530-166" // What area was scanned }, "instructions": [...] // Step-by-step usage instructions } ``` ### User Experience Revolution ✅ **Just like Figma**: Select area → Copy URL → Auto-download all export-ready assets ✅ **No more guessing**: Finds exactly what designers marked for export ✅ **Perfect integration**: Works with Figma's native export workflow ✅ **Visual context**: Reference shows how assets fit in overall design ✅ **Proper naming**: Uses Figma's export naming conventions **Result**: The download tool now works exactly like a developer would expect - point to an area, get all the assets that are meant to be exported! 🎯 ## [2.9.2] - 2025-01-21 ### 🔧 **CRITICAL FIX: get_figma_data URL Support** - **FIXED**: `get_figma_data` now accepts full Figma URLs and automatically extracts node selection - **ISSUE**: Users were calling `get_figma_data` with only `fileKey`, missing `nodeId` from URL - **SOLUTION**: Added URL parsing to automatically extract both file key and node selection ### New URL Parameter Support - **New Parameter**: `url` - Full Figma URL with file and node selection - **Alternative Usage**: Can use `url` instead of separate `fileKey` + `nodeId` parameters - **Automatic Extraction**: Parses URLs like `https://figma.com/design/ZVnXdidh7cqIeJuI8e4c6g/Name?node-id=1530-166` - **Smart Detection**: Extracts `fileKey` from path and `nodeId` from query parameters ### Updated API **Before** (manual extraction required): ```json { "fileKey": "ZVnXdidh7cqIeJuI8e4c6g", "nodeId": "1530-166", "framework": "html" } ``` **After** (direct URL usage): ```json { "url": "https://figma.com/design/ZVnXdidh7cqIeJuI8e4c6g/Name?node-id=1530-166", "framework": "html" } ``` ### Backward Compatibility - **Maintained**: All existing `fileKey` + `nodeId` usage still works - **Flexible**: Can use either approach - URL or manual parameters - **Validation**: Requires either `url` OR `fileKey` to be provided ### Enhanced Logging - Shows whether URL was parsed or direct parameters were used - Logs extracted fileKey and nodeId from URLs for debugging - Clear error messages for invalid URLs ### Result ✅ **Perfect URL workflow**: Copy Figma link → Paste directly into `get_figma_data` → Works with selected node ✅ **No manual extraction**: No need to manually extract file keys and node IDs ✅ **Consistent with other tools**: Same URL-first approach as `process_design_comments` ✅ **Node selection respected**: Automatically processes only the selected node from URL **User Experience**: Copy any Figma URL with selection → Works immediately! 🎯 ## [2.9.1] - 2025-01-21 ### 🔧 **CRITICAL FIX: Node Selection Scope for All Tools** - **FIXED**: All tools now properly respect specific node selections from URLs - **ISSUE**: When user copies link to small section, tools were showing entire page data instead of just selected node - **SOLUTION**: Enhanced node-specific filtering and context detection across all tools ### Fixed Tools #### 1. ✅ `get_figma_data` - **Already working**: Correctly fetches only selected node when `nodeId` provided - **Verified**: Uses `getFileNodes()` with specific node ID vs `getFile()` for entire document #### 2. 🔧 `process_design_comments` - **FIXED**: Now filters comments to only those within selected node bounds - **Before**: Fetched ALL comments from entire file regardless of selection - **After**: Smart filtering based on: - Comments directly attached to selected node (`client_meta.node_id`) - Comments with coordinates within selected node bounds - Coordinate-based bounds checking with proper fallback #### 3. 🔧 `download_design_assets` (Visual Reference) - **FIXED**: Visual reference now uses selected node as context, not page fallback - **Before**: Always fell back to page-level or document context - **After**: Uses actual selected node as reference context: - Single selection → Uses that specific node as reference - Multiple selections → Uses first selected node as context - Only falls back to page if no selection available ### Enhanced Comment Filtering - **Bounds-based filtering**: Gets selected node's `absoluteBoundingBox` for precise filtering - **Coordinate sources**: Checks multiple coordinate fields (`node_offset.x/y`, `client_meta.x/y`, `x/y`) - **Smart inclusion**: Only includes comments that are: - Directly attached to selected node, OR - Positioned within selected node's visual bounds - **Better logging**: Shows exactly which comments are included/excluded and why ### Enhanced Visual Reference - **Node-specific context**: Reference SVG shows the selected area, not entire page - **Accurate context**: `reference.svg` now represents what user actually selected - **Better naming**: Context type reflects actual selection (`parent-frame` vs generic `page`) ### Result ✅ **Perfect node scoping**: Copy link to small section → All tools work only with that section ✅ **No more page leakage**: Tools don't accidentally process entire pages when specific nodes selected ✅ **Precise comment matching**: Comments analysis only for selected area ✅ **Focused visual reference**: Reference shows selected context, not entire page **User Experience**: Select small component → Get data/comments/assets only for that component! 🎯 ## [2.9.0] - 2025-01-21 ### 🎯 **MAJOR NEW FEATURE: Visual Context Reference Generation** - **NEW**: Automatic `reference.svg` creation with every download for visual context - **SMART CONTEXT**: Automatically detects parent frame, page, or document context - **VISUAL GUIDANCE**: Provides overall design layout reference alongside individual assets - **WORKFLOW ENHANCEMENT**: Detailed instructions on how to use reference for development ### New Visual Reference Features - **Automatic Context Detection**: - Single selection → Uses parent frame or page context - Multiple selections → Uses page-level context - Fallback → Uses document context - **Smart Naming**: Always saved as `reference.svg` in assets folder - **Optimized Format**: SVG at 1x scale for lightweight overview - **Context Types**: `parent-frame`, `page`, or `document` based on selection ### Enhanced Download Response - **Reference Metadata**: Success status, file path, context type, and context name - **Visual Instructions**: Step-by-step workflow for using reference + assets - **File Mapping**: Clear overview of downloaded assets and reference file - **Error Handling**: Downloads continue even if reference creation fails ### Developer Workflow ``` 📁 Asset Files Downloaded: ✅ Button Component → button.svg ✅ Icon Set → icons.svg 🎯 Visual Context Reference: 📄 reference.svg → Shows parent-frame context: "Main Dashboard" 💡 Use this reference to understand how assets fit in overall design 🔍 Open reference.svg to see layout, positioning, and relationships 🛠️ Development Workflow: 1. Open reference.svg to understand design context and layout 2. Use individual asset files for implementation 3. Reference the SVG for accurate positioning and relationships 4. Maintain design consistency using visual context ``` ### Technical Implementation - **Robust Error Handling**: Reference creation failures don't break main downloads - **Context Detection Logic**: Intelligent parent/page detection based on selection - **File Management**: Automatic renaming and organization in assets folder - **TypeScript Safety**: Full type definitions and null safety **Result**: Every download now includes perfect visual context for understanding how individual assets fit into the overall design! 🎨 ## [2.8.2] - 2025-01-21 ### 🔧 **CRITICAL FIX: Node ID Format Conversion for Downloads** - **FIXED**: "Node 1530-166 not found" error in download tool - **ROOT CAUSE**: Download tool wasn't converting node IDs from URL format to API format - **SOLUTION**: Added node ID conversion from `1530-166` (URL) to `1530:166` (API) format - **RESULT**: Downloads now work correctly with node IDs from Figma URLs ### Technical Details - **Problem**: User selects frame in Figma → URL shows `node-id=1530-166` → Download tool passes `1530-166` directly to API → API can't find node - **Fix**: Convert `1530-166` → `1530:166` before API calls, then convert back in response - **Same logic**: Now matches the working conversion in `get_figma_data` tool - **User experience**: User still sees original `1530-166` format in responses ### Enhanced Debugging - Added logging to show node ID conversions: `"1530-166 -> 1530:166"` - Shows exactly which node IDs are being converted and passed to API - Helps troubleshoot any future node ID issues **Result**: Download tool now works perfectly with selected frames marked for export! ✅ ## [2.8.1] - 2025-01-21 ### 🔍 **CRITICAL DEBUG: Enhanced Comment Processing Diagnostics** - **ENHANCED**: Comprehensive debugging for comment processing failures - **ROBUST**: Multiple coordinate extraction sources (7 different locations) - **RESILIENT**: Fallback processing ensures comments are never lost - **DIAGNOSTIC**: Detailed logging of comment structure and processing steps ### New Debugging Features - **Extended coordinate sources**: Tries 7 different coordinate field patterns - **Error handling**: Catches and handles processing exceptions gracefully - **Fallback processing**: Generates AI prompts even when processing fails - **Detailed logging**: Shows comment structure, coordinate extraction, and element matching - **Field inspection**: Logs available fields when expected data is missing ### Coordinate Sources Checked 1. `client_meta.node_offset.x/y` 2. `client_meta.x/y` 3. `x/y` (root level) 4. `position.x/y` 5. `node_offset.x/y` 6. `offset.x/y` 7. `coordinates.x/y` ### Robust Processing - **No more null results**: Every comment gets processed with fallback data - **Error resilience**: Catches exceptions and creates error fallback prompts - **Guaranteed output**: processedComments will always equal totalComments - **Debug visibility**: Extensive logging to identify processing issues ### Use Case Support ✅ **Comment found but no coordinates**: Creates general AI prompt ✅ **Processing error**: Creates error fallback with implementation instruction ✅ **Partial data**: Handles missing fields gracefully ✅ **Different structures**: Tries multiple coordinate field patterns **Result**: No more "0 processedComments" - every comment will be processed with maximum debugging information! 🔍 ## [2.8.0] - 2025-01-21 ### 🎯 **MAJOR: Enhanced Comment Processing with Smart Coordinate Matching** - **FIXED**: Comment processing now works correctly (was showing 1 comment but 0 processed) - **ENHANCED**: Multiple coordinate extraction methods for robust comment positioning - **IMPROVED**: Better element bounds detection from Figma design data - **ADDED**: Comprehensive debugging for comment-to-element matching ### New Comment Processing Features - **Multi-source coordinates**: Tries `client_meta.node_offset`, `client_meta.x/y`, `x/y`, `position.x/y` - **Robust bounds extraction**: Handles `bounds`, `absoluteBoundingBox`, `relativeTransform + size` - **Fallback processing**: Generates AI prompts even when coordinates aren't available - **Smart matching**: Finds closest element within 100px tolerance ### AI Prompt Generation - **Simple format**: "Please add 'Hover effect 50% opacity' to Button element" - **Element details**: Position, size, path, and framework context - **Instruction analysis**: Type detection (animation, interaction, behavior, style) - **Confidence scoring**: Keywords analysis with confidence percentage ### Use Case Implementation ✅ **Designer leaves comment**: "Hover effect 50% opacity" on button ✅ **System finds coordinates**: Comment position (x, y) ✅ **Matches to element**: Button element at same/nearby coordinates ✅ **Generates AI prompt**: "Please add 'Hover effect 50% opacity' to Button element" ### Technical Improvements - **Extensive debugging**: Logs comment structure, coordinates, and element matching - **Error resilience**: Handles missing coordinates gracefully - **Performance**: Efficient coordinate-based element lookup - **Framework awareness**: Tailored prompts for React, Vue, Angular, Svelte, HTML ### Result 🎯 **Perfect comment workflow**: Comments → Coordinates → Element matching → AI prompts 🔍 **Smart detection**: Finds target elements even with imperfect coordinate data 📝 **Actionable prompts**: Clear instructions for implementing designer feedback 🛠️ **Robust processing**: Works even when some data is missing or malformed ## [2.7.3] - 2025-01-21 ### 🔧 **FIX: MCP Parameter Handling for Windsurf** - **FIXED**: MCP error -32602 "Invalid parameters" in Windsurf - **ISSUE**: Windsurf passes `undefined` instead of `{}` for tools with no parameters - **SOLUTION**: Added `args || {}` fallback in `handleShowFrameworks` - **DEBUG**: Added logging to understand parameter passing differences between MCP clients ### Technical Details - **Problem**: `z.object({})` schema rejects `undefined` (Windsurf behavior) - **Expected**: Empty object `{}` (standard MCP behavior) - **Fix**: Handle both cases with `args || {}` fallback - **Result**: Works in both Windsurf and other MCP clients ### Debugging - Added detailed logging to see exactly what parameters MCP clients send - Confirmed zod behavior: `z.object({})` only accepts actual objects, not `undefined` ## [2.7.2] - 2025-01-21 ### 🚨 **CRITICAL FIX: True User-Driven Framework Selection** - **REPLACED**: `select_framework` with `show_frameworks` tool - **ELIMINATED**: Auto-proceeding issue completely - **NEW WORKFLOW**: Show options → User chooses naturally → Direct to get_figma_data - **USER CONTROL**: Framework selection is now truly user-driven ### Problem Solved - **Before**: AI would auto-select framework after showing options ❌ - **After**: AI shows frameworks, stops, waits for user choice, then proceeds ✅ ### New Simple Workflow 1. **AI calls**: `show_frameworks()` - Shows all options and stops 2. **User says**: "I want to use React" (natural language) 3. **AI proceeds**: Directly to `get_figma_data` with user's chosen framework 4. **No confusion**: No second tool call that could auto-proceed ### Technical Changes - **Removed**: Complex two-step `select_framework` logic - **Added**: Simple `show_frameworks` that only displays options - **Simplified**: User choice now happens through natural conversation - **Fixed**: No more tool calls until user explicitly provides their choice ### Result ✅ **Perfect user control**: Users see options and choose naturally ✅ **No auto-proceeding**: AI physically cannot proceed without user input ✅ **Simpler workflow**: One tool call, user response, then continue ✅ **Clear separation**: Framework display vs. framework selection are separate actions ## [2.7.1] - 2025-01-21 ### 🚨 **CRITICAL FIX: Proper Framework Selection UX** - **FIXED**: `select_framework` tool now asks user to choose instead of auto-selecting - **PROPER WORKFLOW**: Call `select_framework` WITHOUT parameters to see options, then call again with choice - **USER CHOICE**: Framework selection is now truly user-driven, not automatic ### Before (Broken) ```json // AI automatically called with framework pre-selected { "framework": "react" } ← Wrong! No user choice ``` ### After (Fixed) ```json // Step 1: Call without parameters to see options {} ← Shows available frameworks to user // Step 2: User chooses, AI calls again with selection { "framework": "react" } ← User's choice! ``` ### Technical Changes - **Schema**: Made `framework` parameter optional in `SelectFrameworkSchema` - **Logic**: Show available frameworks when no parameter provided - **UX**: Clear instructions for two-step selection process - **Tool Description**: Updated to clarify the proper calling pattern ### Result ✅ **True user choice**: Users now see all frameworks and choose themselves ✅ **No auto-selection**: AI won't assume framework preferences ✅ **Clear workflow**: Two-step process makes selection explicit and intentional ## [2.7.0] - 2025-01-21 ### 🎯 **MAJOR: 4-Step Framework-First Workflow** - **NEW**: `select_framework` tool as STEP 1 - Choose framework before any code generation - **FRAMEWORK-SPECIFIC RULES**: Separate rule files for each framework (React, Vue, Angular, Svelte, HTML) - **PROPER WORKFLOW**: Framework selection → Design analysis → Comments → Downloads - **NO MORE DEFAULTS**: Framework is now required, no more defaulting to HTML ### Core Changes - **STEP 1**: `select_framework` - Choose target framework with features overview - **STEP 2**: `get_figma_data` - Framework-optimized design analysis - **STEP 3**: `process_design_comments` - Comment processing with framework context - **STEP 4**: `download_design_assets` - Asset downloads ### Framework-Specific Rules System - **React Rules**: JSX, TypeScript, Hooks, TailwindCSS optimizations - **Vue Rules**: SFC, Composition API, TypeScript, Scoped Styles - **Angular Rules**: Components, Standalone, TypeScript, Signals - **Svelte Rules**: Components, TypeScript, Reactive statements - **HTML Rules**: Semantic HTML, Modern CSS, Accessibility focus ### Technical Implementation - **Framework Rules**: `src/config/frameworks/` directory with separate files - **Type Safety**: All framework rules use `Partial<ContextRules>` type - **Rule Merging**: Framework rules merged with custom rules support - **Context Processor**: Updated to use framework-specific optimizations ### Result ✅ **Perfect workflow control**: Framework choice drives all optimizations ✅ **No confusion**: AI must select framework before generating code ✅ **Framework expertise**: Each framework gets specialized treatment ✅ **Clean architecture**: Separate concerns, maintainable codebase ## [2.6.3] - 2025-01-21 ### 🎯 **CRITICAL: AI Workflow Guidance Fix** - **MOVED**: Metadata with workflow guidance to the BEGINNING of response - **ENHANCED**: Made workflow guidance more prominent with caps and clear instructions - **RESULT**: AI now sees workflow guidance FIRST instead of jumping to code generation ### Before vs After **Before**: `data: {...}, metadata: { nextSteps: {...} }` ← AI missed guidance at end **After**: `metadata: { IMPORTANT_NEXT_STEPS: {...} }, data: {...}` ← AI sees guidance first ### New AI Guidance Structure ```json { "metadata": { "IMPORTANT_NEXT_STEPS": { "FOR_COMMENTS": "BEFORE generating code, call process_design_comments tool if there are designer comments in Figma", "FOR_IMAGES": "BEFORE generating code, call download_design_assets tool if you need images", "WORKFLOW": "Design data → Comments analysis → Image downloads → THEN generate code" } }, "data": "... design data ..." } ``` ### Result ✅ AI will now follow proper workflow instead of jumping to HTML generation ✅ AI will call `process_design_comments` when it sees there are comments ✅ Clear workflow guidance prevents premature code generation ## [2.6.2] - 2025-01-21 ### 🔧 **CRITICAL FIX: Clean Tool Separation** - **FIXED**: `get_figma_data` no longer returns comment data in response - **FIXED**: AI now correctly understands it needs to call `process_design_comments` for comment analysis - **CLEAN WORKFLOW**: Perfect tool separation achieved: - `get_figma_data` = STEP 1: Pure design data only - `process_design_comments` = STEP 2: Comment analysis only - `download_design_assets` = STEP 3: Asset downloads only ### Technical - **Removed**: `includeComments` parameter from `get_figma_data` schema - **Removed**: All comment processing logic from `get_figma_data` handler - **Added**: Clear "nextSteps" guidance in `get_figma_data` response metadata - **Smaller Bundle**: Reduced size to 114.17 KB (from 116.58 KB) ### Result - ✅ AI no longer gets confused by comment data in design response - ✅ AI will now call `process_design_comments` when it sees comments in Figma - ✅ Perfect workflow: Design → Comments → Downloads (3 separate tools) ## [2.6.0] - 2025-01-21 ### 🎯 **MAJOR: Ultra-Clean 3-Tool Architecture** - **COMPLETE REDESIGN**: Streamlined to exactly 3 core tools as requested - **REMOVED**: All legacy and utility tools (`analyze_figma_design`, `optimize_for_framework`, `get_server_stats`, `clear_cache`) - **FOCUS**: Clean, minimal, purpose-driven tool set ### Core Tools (Final Implementation) 1. **`get_figma_data`** ✅ - Well-structured, AI-optimized Figma design data - Layout, components, coordinates, visual effects (shadows, borders) - Design tokens and framework-specific optimizations - Latest Figma REST API implementation 2. **`process_design_comments`** ✅ - Scan Figma URL for comments with smart coordinate matching - Convert designer comments to actionable AI implementation instructions - Framework-specific code suggestions with confidence scoring - Element-to-comment coordinate matching system 3. **`download_design_assets`** ✅ - Download Figma export-marked assets with original settings - All formats (PNG, JPG, SVG, PDF) with proper scaling and naming - Respects Figma export configurations and file naming ### Technical Improvements - **✅ REST API Verification**: Confirmed compatibility with latest Figma REST API endpoints - **✅ Path Resolution**: Fixed absolute/relative path issues in downloads - **✅ Clean Build**: No dead code, optimized TypeScript compilation - **✅ Proper Error Handling**: Comprehensive error management throughout ### Removed (No Longer Needed) - ❌ `analyze_figma_design` - Redundant with `get_figma_data` - ❌ `optimize_for_framework` - Integrated into core tools - ❌ `get_server_stats` / `clear_cache` - Utility tools not needed - ❌ Legacy workflow complexity - Now simple and direct ### Documentation - **Updated README**: Reflects new 3-tool architecture - **NPM Description**: "Ultra-clean 3-tool workflow: get_figma_data, process_design_comments, and download_design_assets" - **API Compliance**: Verified against Figma REST API documentation **Result**: Minimal, powerful, easy-to-understand MCP server focused on core Figma functionality! 🚀 ## [1.4.0] - 2024-12-19 ### Added - **🎯 MAJOR**: Figma Comments Integration for Designer Implementation Instructions - NEW: `includeComments` parameter in `get_figma_data` tool - Automatic fetching and analysis of Figma comments attached to design elements - AI-powered comment analysis for detecting implementation instructions - Smart categorization: animation, interaction, behavior, and general comments - Confidence scoring system (0-1) to filter implementation-relevant comments - Support for keywords: animate, transition, hover, click, should, when, etc. - Enhanced node data includes both raw comments and parsed instructions - Seamless integration with AI code generation workflows ### Enhanced - **Comment Analysis**: Sophisticated keyword detection and pattern matching - Animation instructions: fade, slide, bounce, scale, rotate, duration, easing - Interaction instructions: hover, click, focus, active, disabled, state - Behavior instructions: toggle, show, hide, expand, collapse, open, close - Technical boost: References to CSS, JavaScript, React increase confidence - Measurement boost: Values like "300ms", "20px" increase confidence ### Integration - **Workflow Enhancement**: Bridges design-development gap with actionable instructions - **AI-Ready**: Structured comment data optimized for AI coding assistants - **Error Handling**: Graceful fallback when comments API is unavailable - **Performance**: Comments fetched only when requested, minimal overhead - **Rate Limiting**: Respects Figma API limits (300 req/min for comments) ### Documentation - Comprehensive documentation in `docs/FIGMA_COMMENTS_INTEGRATION.md` - Usage examples and integration patterns - Troubleshooting guide for common issues - Performance considerations and best practices ### Technical - New TypeScript interfaces: `FigmaComment`, `CommentInstruction`, `EnhancedFigmaNodeWithComments` - Comment processing methods in `ContextProcessor` - Enhanced response metadata with comment statistics - Backward compatibility maintained for existing workflows ## [1.3.14] - 2024-12-19 ### Improved - **Documentation**: Unified MCP configuration section for all supported clients - **Client Support**: Combined configuration instructions for Cursor, Windsurf, TRAE, and Claude Desktop - **Simplified Setup**: Single configuration example instead of duplicate sections - **Better Organization**: Clearer configuration file location guidance ### Documentation - Streamlined installation instructions to reduce redundancy - Added comprehensive client support list with file location details ## [1.3.13] - 2024-12-19 ### Updated - **README & Documentation**: Updated NPM package documentation to match latest features - **Cursor Instructions**: Fixed Cursor MCP configuration to use `--yes` instead of `-y` - **Documentation Cleanup**: Removed unnecessary "Selection vs Full Document" and "Response Metadata" sections - **Feature Documentation**: Added comprehensive documentation for MCP JSON protocol fix and Figma effects support - **Tool Descriptions**: Updated `download_figma_images` description to reflect direct download capability ### Enhanced - **Package Documentation**: Better organized feature descriptions with latest v1.3.12 updates - **Installation Guide**: Clearer setup instructions for both Cursor and Claude Desktop - **Effects Documentation**: Highlighted advanced CSS generation with comprehensive Figma effects support ## [1.3.12] - 2024-12-19 ### Fixed - **CRITICAL**: Fixed MCP JSON protocol interference issue - All console.log statements changed to console.error to prevent stdout corruption - MCP servers now properly communicate via JSON without "[Figma API]" text interfering - Resolves "Unexpected token 'F'" JSON parsing errors in Cursor MCP ### Added - **Comprehensive Figma Effects Support**: Major enhancement to handle all Figma layer effects - Inner shadows support (up to 8 per element) - Multiple drop shadows support (up to 8 per element) - Layer blur effects (`filter: blur()`) - Background blur effects (`backdrop-filter: blur()`) - Individual corner radius for each corner - Stroke/border properties with proper alignment handling - Individual stroke weights per side - Basic stroke dash support - Shadow and border design token extraction ### Enhanced - **CSS Generation**: Improved CSS property generation for all Figma effects - Smart stroke alignment handling (inside/center/outside) - Combined multiple shadows into single `box-shadow` declaration - Proper handling of effect visibility states - Better color conversion with alpha support ### Fixed - **Stroke Position Mismatch**: Solved the common Figma-to-CSS border position issue - Inside strokes use `box-shadow: inset` to maintain layout - Outside strokes use regular `box-shadow` to extend beyond bounds - Center strokes use standard CSS `border` property ### Documentation - Added comprehensive effects handling documentation in `docs/FIGMA_EFFECTS_HANDLING.md` - Enhanced TypeScript types for all new properties - Added extensive test coverage for effects handling ## [1.3.11] - 2024-12-19 ### Fixed - **CRITICAL**: Fixed filename sanitization to handle special characters like slashes in node names - Nodes with names like "feature/3" will now be saved as "feature-3.svg" - Prevents file save errors when node names contain filesystem-incompatible characters - Sanitizes: / \ : * ? " < > | characters by replacing with dashes ## [1.3.10] - 2024-12-19 ### Fixed - **CRITICAL**: Fixed hardcoded version numbers in source code that were causing old version to be reported - CLI now correctly reports version 1.3.10 - Ensures all improvements from 1.3.5 are properly available ## [1.3.9] - 2024-12-19 ### Published - **CRITICAL**: Published all improvements from 1.3.5 that were never released to npm - Includes removal of extract_url_info tool - Includes enhanced image download with original node names - Includes all debugging improvements for filename generation ### Fixed - npm package now includes all recent improvements - Compiled dist files now properly include downloadImages method - Build and publish process verified ## [1.3.5] - 2024-12-19 ### Removed - **extract_url_info tool**: Removed as requested - no longer needed for workflow - Cleaned up unused URL extraction functionality from tool handlers ### Enhanced - **Debug Logging**: Added detailed debug logging to understand filename generation in image downloads - **Error Handling**: Improved null safety for node name extraction - **Type Safety**: Fixed TypeScript strict mode compliance for optional properties ### Fixed - **Filename Issue Investigation**: Added logging to debug why filenames might show as node IDs instead of actual names - **Null Safety**: Added proper null checks for document.name property access ## [1.3.4] - 2024-12-19 ### Enhanced - **Package Description**: Updated NPM package description to better reflect current capabilities - **Keywords**: Added more relevant keywords for better discoverability (export-settings, image-download, design-tokens, code-generation, claude, context-processing) - **Documentation**: Enhanced README with detailed export settings constraint handling documentation ### Verified - **Export Settings Logic**: Confirmed correct handling of SCALE, WIDTH, and HEIGHT constraints - **SVG Scale Limitation**: Verified proper handling of Figma's SVG 1x scale limitation - **Filename Preservation**: Confirmed original node names are preserved (e.g., "EPAM Systems.svg") - **Batch Processing**: Verified efficient API call grouping by format and scale ## [1.3.3] - 2024-12-19 ### Fixed - **CRITICAL**: Fixed MCP image download functionality that was not working properly - **MAJOR**: Added direct node download capability without requiring export settings - **MAJOR**: Fixed filename logic to use actual node names (e.g., "EPAM Systems.svg") instead of sanitized versions - Resolved issue where download_figma_images tool reported success but didn't actually save files ### Added - New `downloadImages` method for direct node downloads without export settings requirement - Support for scale and format parameters in download_figma_images tool - Proper filename preservation using original Figma node names ### Enhanced - **Filename Logic**: Now uses actual node names as filenames, preserving original naming - **Direct Downloads**: Can download any node as an image, not just those with export settings - **Better Parameters**: Added scale (0.5x-4x) and format (jpg, png, svg, pdf) options - **Improved Tool Description**: Updated to reflect actual functionality ### Changed - download_figma_images tool now works for any node, not just those with export settings - Tool description updated to clarify it uses original node names as filenames - Default format changed to SVG for better scalability ## [1.3.2] - 2024-12-19 ### Fixed - **MAJOR**: Fixed image download functionality to properly respect Figma export settings - Improved batch processing for downloads grouped by format and scale - Enhanced filename generation with proper suffix handling and scale indicators - Fixed TypeScript compilation errors in download implementation - Resolved API batching issues that caused incorrect format/scale application ### Enhanced - **Export Settings Respect**: Downloads now properly honor individual export settings per node - **Batch Optimization**: Efficient grouping of downloads by format and scale for better API usage - **Smart Naming**: Automatic filename generation with @2x scale suffixes when appropriate - **Recursive Search**: Automatically finds export settings in child nodes - **Better Error Handling**: Detailed error reporting for each download attempt with file sizes - **Progress Logging**: Enhanced logging with download progress and file size information ### Changed - Updated tool description to better reflect export settings functionality - Improved README documentation for download_figma_images tool - Enhanced error messages for better debugging ## [1.3.0] - 2024-06-02 ### Added - **MAJOR**: Proper export settings support - only downloads images marked for export in Figma - **MAJOR**: Actual file downloads to local directory instead of just returning URLs - **MAJOR**: Respects Figma export settings (format, scale, suffix) from the design file - New `downloadImagesWithExportSettings` method in FigmaApiService - Automatic directory creation for download paths - Batch processing for efficient API usage ### Changed - **BREAKING**: `download_figma_images` now requires nodes to have export settings configured in Figma - **BREAKING**: Removed manual scale and format parameters - now uses Figma export settings - **BREAKING**: Tool now actually downloads files instead of returning URLs - Improved error handling and reporting for download operations - Better filename generation based on node names and export suffixes ### Technical - Added fs/promises for file system operations - Enhanced batch processing with proper error handling - Improved TypeScript type safety for export settings - Added comprehensive logging for download operations ## [1.2.5] - 2024-06-02 ### Fixed - **CRITICAL**: Updated README.md with correct MCP configuration format - Fixed Cursor and Claude Desktop installation instructions - Removed duplicate API key configuration from documentation - Updated INSTALL.md to use consistent server naming ### Documentation - Corrected MCP configuration to use `npx -y figma-mcp-pro --stdio` - Removed outdated node path references for Claude Desktop - Updated troubleshooting section with correct version numbers ## [1.2.4] - 2024-06-02 ### Fixed - **CRITICAL**: Fixed bin script path resolution for npm package installation - Improved executable wrapper script with proper __dirname resolution - Fixed npx execution issues with relative path imports ### Technical - Enhanced bin/figma-mcp-pro.js with fileURLToPath and proper path joining - Resolved npm package structure for cross-platform compatibility ## [1.2.3] - 2024-06-02 ### Fixed - **CRITICAL**: Fixed ES module shebang syntax error that prevented npx execution - Removed shebang from main ES module file to avoid Node.js import errors - Created separate executable wrapper script in bin/ directory - Fixed package.json bin configuration to use proper executable wrapper ### Technical - Separated executable script from ES module to resolve import conflicts - Updated package structure to include bin/ directory in published files - Improved npm package executable handling ## [1.2.2] - 2024-06-02 ### Fixed - **CRITICAL**: Fixed MCP JSON protocol interference caused by console.log statements going to stdout - **CRITICAL**: All logging now properly uses stderr to avoid corrupting MCP communication - Added proper executable shebang for npm binary - Improved error handling and logging strategy ### Technical - Implemented separate log() and logError() methods using stderr - Only MCP JSON responses now use stdout - Debug logging only enabled when DEBUG environment variable is set - Better separation of concerns for MCP protocol compliance ## [1.2.1] - 2024-06-02 ### Fixed - Enhanced error handling and debugging output for better troubleshooting - Improved API error messages with more detailed information - Better validation error reporting for invalid requests ### Improved - Added comprehensive debug logging for request processing - Enhanced error context for Figma API failures - Better identification of authentication vs validation issues ## [1.2.0] - 2024-06-02 ### Fixed - **CRITICAL**: Fixed URL extraction for Figma node IDs with dash format (1459-57 → 1459:57) - **CRITICAL**: Fixed selection handling to properly analyze specific Figma elements instead of entire documents - Removed unused TypeScript imports to eliminate compilation warnings - Fixed ES module compatibility issues in context processor ### Improved - Enhanced URL parsing to handle all Figma URL formats correctly - Better error handling and validation for node ID formats - Improved selection detection logic with clear metadata indicators - Added comprehensive test scripts for URL extraction and selection handling - Optimized processing for specific node selections vs full document analysis ### Added - Test scripts for validating URL extraction and selection functionality - Better debugging output for selection vs full document processing - Enhanced metadata in responses to clearly indicate selection type ### Technical - Fixed TypeScript strict mode compliance - Improved code organization and removed dead code - Enhanced type safety throughout the codebase ## [1.1.1] - 2024-01-XX ### Fixed - ES module import issues - Build process improvements - CLI execution fixes ## [1.0.0] - 2024-01-XX ### Added - Initial release of Custom Figma MCP Server - Enhanced context processing with AI optimization - Custom rules engine for data transformation - Framework-specific optimizations (React, Vue, Angular, Svelte, HTML) - Semantic analysis for UI component detection - CSS property generation from Figma properties - Accessibility information enhancement - Design token extraction - Component variant detection - Interaction state generation - Comprehensive caching and rate limiting - TypeScript support with full type definitions - MCP tools for Figma data access and image download - Extensive configuration options - Performance monitoring and statistics - CLI interface with environment variable support ### Features - **get_figma_data**: Fetch and process Figma design data with AI optimization - **download_figma_images**: Download images from Figma nodes - **extract_url_info**: Parse Figma URLs for file keys and node IDs - **get_server_stats**: Performance and usage statistics - **clear_cache**: Cache management ### Technical - Built with TypeScript and modern ES modules - Comprehensive test suite with Jest - ESLint and Prettier configuration - Automated build and publishing pipeline - Docker support (planned) - Extensive documentation and examples ## [2.3.0] - 2024-12-XX ### 🚨 **CRITICAL: Strengthened AI Behavior Control + Automatic Image Downloads** **ISSUE**: Previous fixes were too subtle - AI continued using broken workflow (get_figma_data + separate download_figma_images calls) ### Fixed - **🎯 Much stronger tool descriptions** with clear priorities and emojis - **⚠️ Marked get_figma_data as LEGACY** - forces AI to use analyze_figma_url for URLs - **📁 Made analyze_figma_url include automatic image downloads** - complete workflow in one tool - **📝 Added explicit step-by-step workflow** in tool descriptions ### Tool Description Changes - **analyze_figma_url**: "🎯 PRIMARY TOOL - Automatically downloads images and analyzes design" - **get_figma_data**: "⚠️ LEGACY TOOL - Use analyze_figma_url instead when user provides Figma URLs!" - **download_figma_images**: "📁 ADDITIONAL DOWNLOADS - For extra downloads beyond analyze_figma_url" - **optimize_for_framework**: "🔄 SECONDARY TOOL - Use only to change framework AFTER initial analysis" ### Enhanced Workflow - **analyze_figma_url now defaults to includeImages=true** - automatic downloads included - **Single integrated tool call** instead of separate get_figma_data + download_figma_images - **Complete workflow**: URL → Framework selection → Analysis + Downloads in one step ### Added Documentation - **docs/CORRECT_WORKFLOW.md**: Updated to show integrated workflow with automatic downloads - Clear examples of single tool call vs broken separate calls - Step-by-step workflow rules **Perfect integrated workflow: Framework selection + Analysis + Image downloads in one tool! 🎯** ## [2.2.2] - 2024-12-XX ### 🚀 **NEW: Framework-First URL Analysis + Fixed AI Auto-Behavior + Fixed Comment Positioning** **FIXED MULTIPLE CRITICAL ISSUES!** ### Added - **`analyze_figma_url` tool**: New primary tool that takes full Figma URLs + framework preference - **Framework-first workflow**: Choose framework BEFORE data fetching (React/Vue/Angular/Svelte/HTML) - **Smart URL parsing**: Automatically extracts fileKey and nodeId from any Figma URL - **AI framework question**: AI now asks "What framework would you like me to optimize for?" when unclear - **New documentation**: `docs/AI_BEHAVIOR_GUIDE.md` for proper AI tool usage ### Fixed - **🚨 CRITICAL**: AI no longer automatically calls `download_figma_images` when using `optimize_for_framework` - **🚨 CRITICAL**: AI asks for framework preference instead of silently defaulting to HTML - **🚨 CRITICAL**: Fixed comment coordinate mapping - instructions now attached to **specific elements** instead of dumped at end - **❌ OLD BROKEN**: AI immediately calls `get_figma_data` + `download_figma_images` when seeing URLs - **✅ NEW FIXED**: AI calls `analyze_figma_url` with user's framework preference upfront - **✅ NEW FIXED**: Comments mapped to most specific element using bottom-up coordinate matching - **Auto-behavior prevented**: Added explicit AI guidance in tool descriptions to prevent unwanted automatic behavior - **TypeScript error**: Fixed fileKey type assignment error in URL parsing ### Improved - **Precise comment positioning**: Instructions appear in the exact element they belong to, not at end of response - **Bottom-up coordinate matching**: Children elements get priority over parent containers for comment assignment - **Predictable AI behavior**: AI only calls tools user explicitly requests - **Framework questions**: AI asks for clarification when framework preference is unclear - **One-step analysis**: URL + framework → perfectly optimized data - **Better IDE experience**: "Analyze this for React: [URL]" works perfectly - **Controlled image downloads**: Only when user explicitly requests images - **No more "helpful" auto-calls**: AI won't automatically call extra tools ### Technical - **Smart coordinate matching**: Uses bottom-up approach to find most specific element for each comment - **Instruction deduplication**: Prevents comments from being attached to multiple elements - **Enhanced comment processing**: Instructions appear directly in element metadata where they belong - Added URL parsing logic for Figma design links with proper type safety - Framework selection happens before API calls - Enhanced tool descriptions with explicit AI behavior guidance - Maintains all existing tools for backwards compatibility - Added protective descriptions: "DO NOT automatically call...", "ONLY call when user EXPLICITLY requests" ## [2.1.0] - 2024-12-17 // ... existing code ... ## [Unreleased] ### Planned - Real-time Figma webhook integration - Advanced machine learning for component detection - Distributed caching support - Plugin system for custom processors - Web dashboard for monitoring and configuration - Docker container distribution - GitHub Actions CI/CD pipeline