# Figma MCP Server - Project Summary
## 📁 Project Structure (Clean & Organized)
```
figma-mcp/
├── 📄 README.md # Main documentation
├── 📄 package.json # Dependencies and scripts
├── 📄 tsconfig.json # TypeScript configuration
├── 🔒 .env # Environment variables (FIGMA_TOKEN)
├── 🚫 .gitignore # Git ignore rules
│
├── 📂 src/
│ └── index.ts # Main MCP server with 7 tools
│
├── 📂 tests/
│ ├── README.md # Test documentation
│ ├── test-tool.ts # HTML/CSS generation test
│ ├── test-image.ts # Screenshot capture test
│ └── test-token.ts # Token validation test
│
├── 📂 docs/
│ ├── README.md # Documentation index
│ ├── TROUBLESHOOTING.md # Common issues & solutions
│ ├── CSS-IMPROVEMENTS.md # CSS generation details
│ └── IMAGE-FEATURE.md # Screenshot feature guide
│
├── 📂 build/
│ └── index.js # Compiled JavaScript (generated)
│
└── 📂 .vscode/
└── mcp.json # VS Code MCP configuration
```
## 🛠️ Available Tools (7 Total)
1. **getFile** - Fetch complete Figma file data
2. **getNode** - Fetch specific node from file
3. **analyzeDesign** - Extract design properties
4. **generateCSS** - Generate CSS styles
5. **generateHTML** - Generate HTML structure
6. **generateFullDesign** - Complete HTML/CSS output
7. **getImage** - Capture screenshots (PNG/JPG/SVG/PDF)
## 🚀 Quick Start Commands
```bash
# Install dependencies
npm install
# Build the server
npm run build
# Start the MCP server
npm start
# Run tests
npx tsx tests/test-tool.ts # HTML/CSS generation
npx tsx tests/test-image.ts # Screenshot capture
npx tsx tests/test-token.ts # Token validation
```
## 📝 Key Features
### ✅ Design-to-Code
- Extract complete HTML/CSS from Figma designs
- Normalized CSS class names (no invalid characters)
- Responsive styling and proper layout
- Typography and color conversion
### ✅ Screenshot Capture
- PNG, JPG, SVG, PDF formats
- Scalable (0.01x to 4x)
- Automatic download
- High-quality renders
### ✅ Design Analysis
- Component hierarchy inspection
- Style property extraction
- Color and typography analysis
- Dimension and positioning data
### ✅ AI Integration
- Works with Claude Desktop
- VS Code MCP support
- Stdio transport for communication
- Zod schema validation
## 🔧 Configuration
### Environment Variables (.env)
```bash
FIGMA_TOKEN=your_personal_access_token_here
```
### MCP Server Config (Claude Desktop)
```json
{
"mcpServers": {
"figma": {
"command": "node",
"args": ["C:\\path\\to\\figma-mcp\\build\\index.js"]
}
}
}
```
## 📚 Documentation Structure
### Main Docs
- **README.md** - Complete feature overview and usage
- **tests/README.md** - Test scripts documentation
- **docs/README.md** - Documentation index
### Guides
- **TROUBLESHOOTING.md** - Common issues (auth, tokens, node access)
- **CSS-IMPROVEMENTS.md** - CSS generation technical details
- **IMAGE-FEATURE.md** - Screenshot feature comprehensive guide
## 🎯 Common Workflows
### 1. Convert Design to HTML/CSS
```bash
# Edit tests/test-tool.ts with your fileKey and nodeId
npx tsx tests/test-tool.ts
# Output: output.html
```
### 2. Capture Design Screenshot
```bash
# Edit tests/test-image.ts with your fileKey and nodeId
npx tsx tests/test-image.ts
# Output: figma-screenshot-{nodeId}.png
```
### 3. Validate API Access
```bash
npx tsx tests/test-token.ts
# Checks: token validity, file access, node access
```
### 4. Use with Claude Desktop
1. Build: `npm run build`
2. Add to Claude config (see README)
3. Restart Claude Desktop
4. Use tools in conversation
## 🔐 Security Notes
- ✅ `.env` file is git-ignored
- ✅ Token never committed to repository
- ✅ Use Personal Access Tokens only
- ✅ Follow MCP authorization best practices
## 📊 Supported Figma Properties
### Layout
- Width, height, positioning
- Padding, margins
- Border radius
### Colors
- Fill colors (solid)
- Stroke/border colors
- RGBA format output
### Typography
- Font family, size, weight
- Line height, alignment
- Text content
### Effects
- Drop shadows
- Box shadows
- Border styles
## 🐛 Common Issues & Solutions
### "Invalid token"
→ Use Personal Access Token from Figma Settings
### Node not found
→ Check node ID format (8384-4 or 8384:4 both work)
### CSS classes not working
→ Already fixed! Classes are normalized (no colons)
See **docs/TROUBLESHOOTING.md** for detailed solutions.
## 🎨 Design Philosophy
1. **Clean Structure** - Organized into logical directories
2. **Comprehensive Docs** - README for each major section
3. **Easy Testing** - Simple test scripts for all features
4. **Production Ready** - Proper TypeScript, error handling
5. **Well Documented** - Examples and guides for everything
## 📈 Future Enhancements (Ideas)
- [ ] Batch export multiple nodes
- [ ] Component variation detection
- [ ] CSS variable extraction
- [ ] Tailwind CSS output option
- [ ] React/Vue component generation
- [ ] Design token extraction
- [ ] Animation/interaction export
- [ ] Accessibility analysis
## 🤝 Contributing
1. Fork the repository
2. Create feature branch
3. Add tests for new features
4. Update documentation
5. Submit pull request
## 📄 License
MIT - See LICENSE file for details
---
**Last Updated:** November 14, 2025
**Version:** 1.0.0
**Status:** ✅ Production Ready
