Design Tokens - MCP Server

Este projeto fornece um servidor MCP (Model Context Protocol) para extrair tokens de design do Figma e convertê-los em um formato estruturado para uso em aplicações Flutter e React.

🚀 Recursos

• Extração de Tokens do Figma: Analisa designs do Figma e extrai tokens de cores, tipografia, espaçamento, etc.
• Geração de JSON Estruturado: Cria um arquivo JSON de tokens de design seguindo as melhores práticas da indústria
• Suporte a Múltiplos Temas: Inclui suporte para temas claro e escuro
• Configurações Específicas de Plataforma: Fornece configurações para Web (CSS/SCSS), iOS (SwiftUI) e Android (Jetpack Compose)
• Documentação Integrada: Inclui metadados e descrições para facilitar o uso pelos desenvolvedores

📋 Pré-requisitos

• Node.js v18.0.0 ou superior
• Chave de API do Figma (obtenha em https://www.figma.com/developers/api)

🔧 Instalação

Instalando via Smithery

Para instalar Design Tokens Server for Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @joao-loker/jhony-mcp --client claude

Método 1: Instalação Rápida Diretamente do GitHub

Você pode executar o servidor MCP diretamente do GitHub sem precisar clonar o repositório:

npx --yes git+https://github.com/joao-loker/jhony-mcp.git --env FIGMA_API_KEY=sua_chave_api_figma_aqui & disown

Para usuários Windows, execute em um terminal separado sem o & disown:

npx --yes git+https://github.com/joao-loker/jhony-mcp.git --env FIGMA_API_KEY=sua_chave_api_figma_aqui

Método 2: Instalação Local

1. Clone este repositório:

   git clone https://github.com/joao-loker/jhony-mcp.git
   cd jhony-mcp
   

2. Instale as dependências:

   npm install
   

3. Configure o arquivo .env com sua chave de API do Figma:

   FIGMA_API_KEY=sua_chave_api_figma_aqui
   

🚀 Iniciando o Servidor

Se você instalou localmente:

Execute o script de inicialização:

./start-server.sh

Este script irá:

• Verificar se o Node.js está instalado
• Instalar dependências se necessário
• Configurar o arquivo .env se não existir
• Compilar o TypeScript
• Iniciar o servidor MCP

Usando com o Cursor

Para usar este MCP com o Cursor, você tem várias opções:

1. Método Direto: Configure o Cursor para usar o comando:

   npx --yes git+https://github.com/joao-loker/jhony-mcp.git --env FIGMA_API_KEY=sua_chave_api_figma_aqui
   

2. Método CommonJS: Use o script CommonJS para melhor compatibilidade:

   node -e "require('child_process').execSync('export FIGMA_API_KEY=sua_chave_api_figma_aqui && npx tsx src/mcp-server-new.ts', {stdio: 'inherit'})"
   

3. Método Smithery: Se estiver enfrentando problemas com os métodos acima, considere usar o Smithery:

   npx -y @smithery/cli@latest run @seu-usuario/jhony-mcp --config '{"figmaApiKey":"sua_chave_api_figma_aqui"}'
   

🔒 Segurança

Proteção de Chaves de API

Este repositório inclui um script para limpar chaves de API antes de enviar o código para o GitHub:

./clean-api-keys.sh

Este script:

• Substitui todas as ocorrências da sua chave de API real por um placeholder
• Cria backups dos arquivos modificados
• Exibe um relatório dos arquivos alterados

Importante: Execute este script antes de enviar seu código para o GitHub para evitar expor suas chaves de API.

🔍 Como Usar

Analisando um Design do Figma

1. Obtenha o link do seu design no Figma, que deve ter o formato:

   https://www.figma.com/design/[file_key]/[project_name]?node-id=[node_id]
   

2. Use a ferramenta figma_url_analysis para analisar o design e extrair os tokens:

   Exemplo de URL: https://www.figma.com/design/SEU_FILE_KEY_AQUI/Seu-Projeto?node-id=1234-5678
   

3. O servidor processará o design e retornará um JSON estruturado com os tokens de design.

Estrutura do JSON de Tokens

O JSON gerado segue uma estrutura organizada:

{
  "$schema": "https://json-schema.org/draft-07/schema",
  "meta": {
    "version": "1.0.0",
    "description": "Design Tokens",
    "platform": "mobile",
    "figmaSource": "https://www.figma.com/design/SEU_FILE_KEY_AQUI/Seu-Projeto?node-id=1234-5678",
    "themes": ["light", "dark"],
    "lastUpdated": "2024-03-12"
  },
  "colors": { ... },
  "typography": { ... },
  "spacing": { ... },
  "borders": { ... },
  "shadows": { ... },
  "motion": { ... },
  "components": { ... }
}

🛠️ Ferramentas Disponíveis

O servidor MCP fornece as seguintes ferramentas:

Ferramentas do Figma

• figma_smart_analysis: Analisa um design do Figma com opções avançadas
• figma_url_analysis: Analisa um design do Figma a partir de uma URL completa
• figma_get_image: Obtém uma imagem de um nó específico do Figma

📊 Exemplo de Uso

Analisando um Design do Figma

URL do Figma: https://www.figma.com/design/SEU_FILE_KEY_AQUI/Seu-Projeto?node-id=1234-5678

O servidor analisará o design e retornará um JSON estruturado com os tokens de design.

Exemplo de Implementação em Flutter

// Exemplo de uso dos tokens de design em Flutter
import 'package:flutter/material.dart';

class AppTheme {
  static const colors = {
    'primary': Color(0xFF121212),
    'secondary': Color(0xFF323232),
    'accent': Color(0xFFC7C7C7),
  };
  
  static const typography = {
    'heading': TextStyle(
      fontFamily: 'Inter',
      fontWeight: FontWeight.w500,
      fontSize: 24,
    ),
    'body': TextStyle(
      fontFamily: 'Inter',
      fontWeight: FontWeight.w400,
      fontSize: 16,
    ),
  };
  
  static const spacing = {
    'xs': 8.0,
    'sm': 16.0,
    'md': 24.0,
    'lg': 32.0,
    'xl': 48.0,
  };
}

Exemplo de Implementação em React

// Exemplo de uso dos tokens de design em React
import { createGlobalStyle } from 'styled-components';

const GlobalStyle = createGlobalStyle`
  :root {
    /* Colors */
    --color-primary: #121212;
    --color-secondary: #323232;
    --color-accent: #C7C7C7;
    
    /* Typography */
    --font-family: 'Inter', sans-serif;
    --font-weight-medium: 500;
    --font-size-heading: 24px;
    --font-size-body: 16px;
    
    /* Spacing */
    --spacing-xs: 8px;
    --spacing-sm: 16px;
    --spacing-md: 24px;
    --spacing-lg: 32px;
    --spacing-xl: 48px;
  }
`;

export default GlobalStyle;

🔄 Fluxo de Trabalho Recomendado

1. Design no Figma: Crie seu design no Figma seguindo as diretrizes de design system
2. Extração de Tokens: Use o servidor MCP para extrair os tokens de design
3. Implementação: Utilize os tokens extraídos em suas aplicações Flutter ou React
4. Atualização: Quando o design for atualizado, repita o processo para manter os tokens sincronizados

❓ Solução de Problemas

O servidor não inicia

• Verifique se o Node.js está instalado e é v18.0.0 ou superior
• Verifique se todas as dependências foram instaladas corretamente
• Verifique se o arquivo .env está configurado corretamente

Erro ao analisar o design do Figma

• Verifique se a chave de API do Figma está configurada corretamente
• Verifique se a URL do Figma está no formato correto
• Verifique se o design do Figma está acessível com sua conta

Erro "Failed to create client" no Cursor

Se você estiver enfrentando o erro "Failed to create client" ao usar o MCP com o Cursor:

1. Tente usar o método CommonJS mencionado acima
2. Verifique se a chave de API do Figma está correta
3. Considere usar o Smithery como alternativa
4. Certifique-se de que o Node.js está na versão 18.0.0 ou superior

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

🙏 Agradecimentos

• Figma API por fornecer acesso aos designs
• Model Context Protocol por fornecer a infraestrutura para o servidor MCP
• Style Dictionary por inspirar a estrutura de tokens de design