Figma

Figma Context MCP

Servidor MCP para integração perfeita de designs do Figma com ferramentas de codificação com IA

Recursos • Início Rápido • Capacidades MCP • Arquitetura • Documentação • 中文文档

O que é isto?

Figma Context MCP é um servidor Model Context Protocol (MCP) que conecta designs do Figma a assistentes de codificação com IA como Cursor, Windsurf e Cline.

Quando ferramentas de IA têm acesso direto aos dados de design do Figma, elas geram código mais preciso na primeira tentativa — muito melhor do que usar capturas de tela.

Nota: Este projeto é baseado no Figma-Context-MCP, com estruturas de dados otimizadas e algoritmos inteligentes de detecção de layout.

Recursos

Capacidades Principais

Principais Melhorias

Início Rápido

Pré-requisitos

• Node.js >= 18.0.0
• Uma conta Figma com acesso à API

Instalação

Via Smithery (Recomendado)

npx -y @smithery/cli install @1yhy/Figma-Context-MCP --client claude

Via npm

npm install -g @yhy2001/figma-mcp-server

A partir do código-fonte

git clone https://github.com/1yhy/Figma-Context-MCP.git
cd Figma-Context-MCP
pnpm install
pnpm build

Configuração

1. Obter Token da API do Figma

1. Acesse Configurações da Conta Figma
2. Role até "Personal access tokens"
3. Clique em "Create new token"
4. Copie o token

2. Configurar Sua Ferramenta de IA

{
  "mcpServers": {
    "Figma": {
      "command": "npx",
      "args": ["-y", "@yhy2001/figma-mcp-server", "--stdio"],
      "env": {
        "FIGMA_API_KEY": "your-figma-api-key"
      }
    }
  }
}

# From source (development)
cp .env.example .env  # Add FIGMA_API_KEY to .env
pnpm install && pnpm build
pnpm start            # Starts on port 3333

# Or with environment variable
FIGMA_API_KEY=<your-key> pnpm start

# Or via global install
figma-mcp --figma-api-key=<your-key> --port=3333

# Connect via SSE
# URL: http://localhost:3333/sse

Exemplo de Uso

Please implement this Figma design: https://www.figma.com/design/abc123/MyDesign?node-id=1:234

Use React and Tailwind CSS.

Capacidades MCP

Este servidor oferece suporte completo às capacidades MCP:

┌─────────────────────────────────────────────────────────────┐
│                  Figma MCP Server v1.1.0                    │
├─────────────────────────────────────────────────────────────┤
│  Tools (2)                        AI-invoked operations     │
│  ├── get_figma_data              Fetch design data          │
│  └── download_figma_images       Download image assets      │
├─────────────────────────────────────────────────────────────┤
│  Prompts (3)                      User-selected templates   │
│  ├── design_to_code              Full design-to-code flow   │
│  ├── analyze_components          Component structure        │
│  └── extract_styles              Style token extraction     │
├─────────────────────────────────────────────────────────────┤
│  Resources (5)                    Lightweight data sources  │
│  ├── figma://help                Usage guide                │
│  ├── figma://file/{key}          File metadata (~200 tok)   │
│  ├── figma://file/{key}/styles   Design tokens (~500 tok)   │
│  ├── figma://file/{key}/components Component list (~300 tok)│
│  └── figma://file/{key}/assets   Asset inventory (~400 tok) │
└─────────────────────────────────────────────────────────────┘

Ferramentas

Prompts

Modelos de prompt profissionais integrados para ajudar a IA a gerar código de alta qualidade:

O fluxo de trabalho design_to_code inclui:

1. Análise do Projeto - Ler configuração de tema, estilos globais, biblioteca de componentes
2. Análise de Estrutura - Identificar padrões de página, estratégia de divisão de componentes
3. Blueprint de Layout ASCII - Gerar diagrama de layout com anotações de componentes e ativos
4. Gerenciamento de Ativos - Analisar, baixar e organizar imagens/ícones
5. Geração de Código - Gerar código seguindo as convenções do projeto
6. Otimização de Acessibilidade - HTML semântico, rótulos ARIA
7. Adaptação Responsiva - Ajustes de layout para dispositivos móveis

Recursos

Acesso leve a dados para economizar tokens:

# Get file metadata (~200 tokens)
figma://file/abc123

# Get design tokens (~500 tokens)
figma://file/abc123/styles

# Get component list (~300 tokens)
figma://file/abc123/components

# Get asset inventory (~400 tokens)
figma://file/abc123/assets

Comparação entre Recursos e Ferramentas:

Arquitetura

┌──────────────────────────────────────────────────────────────┐
│                        MCP Server                            │
├──────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐   │
│  │   Tools     │  │   Prompts   │  │     Resources       │   │
│  │ (2 tools)   │  │ (3 prompts) │  │   (5 resources)     │   │
│  └──────┬──────┘  └─────────────┘  └──────────┬──────────┘   │
│         │                                      │              │
│         └──────────────────┬───────────────────┘              │
│                            ▼                                  │
│  ┌────────────────────────────────────────────────────────┐  │
│  │                   FigmaService                         │  │
│  │          API Calls • Validation • Error Handling       │  │
│  └────────────────────────┬───────────────────────────────┘  │
│                           │                                  │
│         ┌─────────────────┴─────────────────┐                │
│         ▼                                   ▼                │
│  ┌─────────────────┐              ┌─────────────────────┐    │
│  │   CacheManager  │              │    Parser + Algo    │    │
│  │  L1: LRU Memory │              │  • Layout Detection │    │
│  │  L2: Disk Store │              │  • Icon Merging     │    │
│  └─────────────────┘              │  • CSS Generation   │    │
│                                   └─────────────────────┘    │
└──────────────────────────────────────────────────────────────┘

Sistema de Cache

Arquitetura de cache em duas camadas que reduz significativamente as chamadas de API:

Algoritmo de Detecção de Layout

Converte automaticamente posicionamento absoluto em layouts semânticos Flexbox/Grid:

Input (Figma absolute positioning):
┌─────────────────────────┐
│ ■ (10,10)  ■ (110,10)   │
│ ■ (10,60)  ■ (110,60)   │
└─────────────────────────┘

Output (Inferred Grid):
display: grid
grid-template-columns: 100px 100px
grid-template-rows: 50px 50px
gap: 10px

Estrutura do Projeto

src/
├── algorithms/           # Smart algorithms
│   ├── layout/          # Layout detection (Flex/Grid inference)
│   └── icon/            # Icon merge detection
├── core/                 # Core parsing
│   ├── parser.ts        # Figma data parser
│   ├── style.ts         # CSS style generation
│   ├── layout.ts        # Layout processing
│   └── effects.ts       # Effects handling
├── services/             # Service layer
│   ├── figma.ts         # Figma API client
│   └── cache/           # Multi-layer cache system
├── prompts/              # MCP prompt templates
├── resources/            # MCP resource handlers
├── types/                # TypeScript type definitions
├── utils/                # Utility functions
├── server.ts             # MCP server main entry
└── index.ts              # CLI entry

tests/
├── fixtures/             # Test data
│   ├── figma-data/      # Raw JSON from Figma API
│   └── expected/        # Expected output snapshots
├── integration/          # Integration tests
│   ├── layout-optimization.test.ts  # Layout optimization tests
│   ├── output-quality.test.ts       # Output quality validation
│   └── parser.test.ts               # Parser tests
└── unit/                 # Unit tests
    ├── algorithms/      # Algorithm tests (layout, icon detection)
    ├── resources/       # Resource handler tests
    └── services/        # Service layer tests

scripts/
└── fetch-test-data.ts   # Figma test data fetcher

Documentação

Algoritmos Principais

Documentos de Pesquisa

Documentos de Arquitetura

Opções de Linha de Comando

Contribuição

Contribuições são bem-vindas!

# Setup
git clone https://github.com/1yhy/Figma-Context-MCP.git
cd Figma-Context-MCP
pnpm install

# Development
pnpm dev          # Watch mode
pnpm test         # Run tests (272 test cases)
pnpm lint         # Lint code
pnpm build        # Build

# Debug
pnpm inspect      # MCP Inspector

# Test with your own Figma data
pnpm tsx scripts/fetch-test-data.ts <fileKey> <nodeId> <outputName>

# Commit (uses conventional commits)
git commit -m "feat: add new feature"

Tipos de Commit

Processo de Release (Mantenedores)

# 1. Update version in package.json and CHANGELOG.md

# 2. Commit version bump
git add -A
git commit -m "chore: bump version to x.x.x"

# 3. Publish to npm (auto runs: type-check → lint → test → build)
npm login --scope=@yhy2001  # if not logged in
pnpm run pub:release

# 4. Create git tag and push
git tag vx.x.x
git push origin main --tags

# 5. Create GitHub Release (optional)
# Go to https://github.com/1yhy/Figma-Context-MCP/releases/new

Testando com Seus Próprios Dados do Figma

Você pode testar a detecção de layout e a otimização com seus próprios designs do Figma:

1. Configurar Variáveis de Ambiente

# Copy the environment template
cp .env.example .env

# Edit .env file with your configuration
FIGMA_API_KEY=your_figma_api_key_here
TEST_FIGMA_FILE_KEY=your_file_key      # Optional
TEST_FIGMA_NODE_ID=your_node_id        # Optional

2. Buscar Dados de Nó do Figma

# Method 1: Using command line arguments (recommended)
pnpm tsx scripts/fetch-test-data.ts <fileKey> <nodeId> <outputName>

# Example: Fetch a specific node
pnpm tsx scripts/fetch-test-data.ts UgtwrncR3GokKDIS7dpm4Z 402-34955 my-design

# Method 2: Using environment variables
TEST_FIGMA_FILE_KEY=xxx TEST_FIGMA_NODE_ID=123-456 pnpm tsx scripts/fetch-test-data.ts

Parâmetros:

Exemplo de Análise de URL:

https://www.figma.com/design/UgtwrncR3GokKDIS7dpm4Z/MyProject?node-id=402-34955
                            ↑ fileKey                              ↑ nodeId

3. Executar Testes para Validar a Saída

# Run all tests
pnpm test

# Run only integration tests (validate layout optimization)
pnpm test tests/integration/

# View output JSON files
ls tests/fixtures/figma-data/

4. Analisar Resultados da Otimização

Os testes validam automaticamente:

• Compressão de Dados - Normalmente >50% de compressão
• Detecção de Layout - Taxa de reconhecimento de layouts Flex/Grid
• Propriedades CSS - Limpeza de propriedades redundantes
• Qualidade da Saída - Verificações de consistência estrutural

Se os testes falharem, a saída pode não atender às expectativas. Verifique as mensagens de erro para ajustar ou reportar um problema.

Licença

MIT © 1yhy

Agradecimentos

• Figma-Context-MCP - Projeto original
• Model Context Protocol - Especificação MCP
• Best-README-Template - Referência de modelo de README

Feito com ❤️ para a comunidade de codificação com IA