Servidor MCP de Figma

Un servidor de Protocolo de Contexto de Modelo (MCP) que se integra con la API de Figma a través de Claude y otros clientes compatibles con MCP. Actualmente admite acceso de solo lectura a archivos y proyectos de Figma, con una arquitectura del lado del servidor que admite funciones más avanzadas de gestión de tokens de diseño y temas (pendiente de mejoras en la API de Figma o desarrollo de plugins).

Estado del proyecto

Progreso actual

• ✅ Implementación principal : se construyó con éxito un servidor TypeScript siguiendo el Protocolo de contexto de modelo (MCP)
• ✅ Integración con Claude Desktop : probada y funcional con Claude Desktop
• ✅ Operaciones de lectura : herramientas get-file y list-files que funcionan para acceder a archivos de Figma
• ✅ Arquitectura del servidor : Se implementó un sistema de almacenamiento en caché, manejo de errores y monitoreo de estadísticas.
• ✅ Protocolos de transporte : Se admiten mecanismos de transporte stdio y SSE

Funcionalidad potencial completa

El servidor ha sido diseñado con código para admitir estas funciones (actualmente limitadas por restricciones de API):

• Gestión de variables : crear, leer, actualizar y eliminar tokens de diseño (variables)
• Manejo de referencias : crear y validar relaciones entre tokens
• Gestión de temas : crea temas con múltiples modos (por ejemplo, claro/oscuro)
• Análisis de dependencia : detectar y prevenir referencias circulares
• Operaciones por lotes : realice acciones masivas sobre variables y temas

Con el desarrollo del complemento Figma o un acceso API ampliado, estas funciones podrían habilitarse por completo.

Características

• 🔑 Autenticación segura con la API de Figma
• 📁 Operaciones con archivos (leer, listar)
• 🎨 Gestión de sistemas de diseño
  • Creación y gestión de variables
  • Creación y configuración de temas
  • Manejo y validación de referencias
• 🚀 Rendimiento optimizado
  • Almacenamiento en caché de LRU
  • Manejo del límite de velocidad
  • Agrupación de conexiones
• 📊 Monitoreo integral
  • controles de salud
  • Estadísticas de uso
  • Seguimiento de errores

Prerrequisitos

• Node.js 18.x o superior
• Token de acceso de Figma con los permisos adecuados
• Comprensión básica del MCP (Protocolo de Contexto Modelo)

Instalación

Configuración

1. Cree un archivo .env basado en .env.example :

2. Para la integración de Claude Desktop:

El servidor se puede configurar en el archivo de configuración de Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Ventanas: %APPDATA%\Claude\claude_desktop_config.json

Notas importantes:

• Utilice rutas ABSOLUTAS, no relativas
• En Windows, utilice barras invertidas dobles (\\) en las rutas
• Reinicie Claude Desktop después de realizar cambios de configuración

Uso

Uso básico

Herramientas disponibles

1. obtener archivo
   • Recuperar detalles del archivo Figma GXP5
2. archivos de lista
   • Lista de archivos en un proyecto de Figma GXP6
3. crear variables
   • Crear variables del sistema de diseño GXP7
4. crear tema
   • Crear y configurar temas GXP8

Documentación de la API

Métodos de servidor

• startServer(figmaToken: string, debug?: boolean, port?: number)
  • Inicializa e inicia el servidor MCP
  • Devoluciones: Promesa

Esquemas de herramientas

Todas las entradas de la herramienta se validan utilizando esquemas Zod:

Manejo de errores

El servidor proporciona mensajes de error detallados y códigos de error adecuados:

• Token no válido: 403 con mensaje de error específico
• Limitación de velocidad: 429 con tiempo de reinicio
• Errores de validación: 400 con detalles específicos del campo
• Errores del servidor: 500 con seguimiento de errores

Limitaciones y problemas conocidos

Restricciones de la API

1. Operaciones de solo lectura
   • Limitado a operaciones de solo lectura debido a las restricciones de la API de Figma
   • Los tokens de acceso personal solo admiten operaciones de lectura, no de escritura.
   • No se pueden modificar variables, componentes o estilos a través de la API REST con tokens personales
   • Las operaciones de escritura requerirían el desarrollo del complemento Figma.
2. Limitación de velocidad
   • Sigue los límites de velocidad de la API de Figma
   • Implementar un retroceso exponencial para un mejor manejo
3. Gestión de caché
   • TTL predeterminado de 5 minutos
   • Limitado a 500 entradas
   • Considere implementar ganchos de invalidación de caché
4. Autenticación
   • Solo admite tokens de acceso personal
   • No hay soporte para permisos a nivel de equipo ni edición colaborativa
   • Implementación de OAuth planificada para el futuro
5. Implementación técnica
   • Requiere rutas absolutas en la configuración
   • Debe compilar archivos TypeScript antes de la ejecución
   • Requiere el manejo de la resolución del módulo tanto local como global

Contribuyendo

1. Bifurcar el repositorio
2. Crear una rama de características
3. Realiza tus cambios con pruebas
4. Enviar una solicitud de extracción

Por favor, siga nuestros estándares de codificación:

• Modo estricto de TypeScript
• Configuración de ESLint
• Broma para probar
• Manejo integral de errores

Licencia

Licencia MIT: consulte el archivo LICENCIA para obtener más detalles

Solución de problemas

Consulte TROUBLESHOOTING.md para obtener una guía completa de solución de problemas.

Problemas comunes

1. Errores de conexión JSON
   • Usar rutas absolutas en la configuración de Claude Desktop
   • Asegúrese de que el servidor esté compilado ( npm run build )
   • Verifique que todas las variables de entorno estén configuradas
2. Problemas de autenticación
   • Verifique que su token de acceso de Figma sea válido
   • Compruebe que el token tenga los permisos necesarios
   • Asegúrese de que el token esté configurado correctamente
3. El servidor no se inicia
   • Verifique la versión de Node.js (se requiere 18.x+)
   • Verificar que la compilación exista ( dist/index.js )
   • Consulte los registros de Claude Desktop:
     • macOS: ~/Library/Logs/Claude/mcp*.log
     • Ventanas: %APPDATA%\Claude\logs\mcp*.log

Para obtener pasos de depuración y soluciones más detallados, consulte la guía de solución de problemas.

Apoyo

• Problemas de GitHub: Informar un error
• Documentación: Wiki
• Discord: Únete a nuestra comunidad