appiq-solution 1.2.0 → 1.3.0

package/#Tools/claude-talk-to-figma-mcp/context/01/00-analisis.md

@@ -0,0 +1,151 @@
+# Análisis del Proyecto claude-talk-to-figma-mcp
+
+## 📋 Resumen del Proyecto
+
+Este proyecto implementa un plugin de Figma que permite la integración de Claude AI con Figma mediante el Model Context Protocol (MCP). Facilita la comunicación bidireccional entre Claude y Figma, permitiendo al asistente de IA interpretar, manipular y crear diseños directamente en Figma.
+
+## 🏗️ Arquitectura del Sistema
+
+La arquitectura del sistema consta de tres componentes principales:
+
+1. **Plugin de Figma (claude_mcp_plugin)**: 
+   - Ejecutado dentro del entorno de Figma
+   - Establece una conexión WebSocket con el servidor MCP
+   - Expone las APIs de Figma al servidor
+
+2. **Servidor MCP (talk_to_figma_mcp)**:
+   - Actúa como un intermediario entre Claude y Figma
+   - Implementa la especificación del Model Context Protocol
+   - Proporciona herramientas (tools) que Claude puede invocar para interactuar con Figma
+
+3. **Cliente WebSocket (socket.ts)**:
+   - Maneja la comunicación WebSocket entre el plugin de Figma y el servidor MCP
+   - Gestiona la reconexión automática y el seguimiento de solicitudes pendientes
+
+## 🔄 Flujo de Comunicación
+
+```
+Claude AI <---> Servidor MCP <---> WebSocket <---> Plugin de Figma <---> API de Figma
+```
+
+El flujo de datos sigue estos pasos:
+1. Claude invoca una herramienta del servidor MCP
+2. El servidor MCP envía un comando al plugin de Figma a través de WebSocket
+3. El plugin ejecuta el comando utilizando la API de Figma
+4. El resultado se devuelve al servidor MCP
+5. El servidor MCP formatea la respuesta y la devuelve a Claude
+
+## 🧰 Herramientas Disponibles
+
+El servidor MCP expone numerosas herramientas que Claude puede utilizar para interactuar con Figma:
+
+### Obtención de Información
+- `get_document_info`: Información sobre el documento actual
+- `get_selection`: Información sobre la selección actual
+- `get_node_info`: Información detallada sobre un nodo específico
+- `get_nodes_info`: Información sobre múltiples nodos
+- `scan_text_nodes`: Escanear todos los nodos de texto
+- `get_styles`: Obtener estilos del documento
+- `get_local_components`: Obtener componentes locales
+- `get_remote_components`: Obtener componentes de bibliotecas de equipos
+- `get_styled_text_segments`: Analizar segmentos de texto con estilos específicos
+
+### Creación de Elementos
+- `create_rectangle`: Crear un rectángulo
+- `create_frame`: Crear un marco
+- `create_text`: Crear un elemento de texto
+- `create_ellipse`: Crear una elipse
+- `create_polygon`: Crear un polígono
+- `create_star`: Crear una estrella
+- `create_component_instance`: Crear una instancia de componente
+
+### Manipulación de Elementos
+- `set_fill_color`: Establecer color de relleno
+- `set_stroke_color`: Establecer color de trazo
+- `move_node`: Mover un nodo
+- `resize_node`: Cambiar tamaño de un nodo
+- `delete_node`: Eliminar un nodo
+- `clone_node`: Clonar un nodo existente
+- `group_nodes`: Agrupar nodos
+- `ungroup_nodes`: Desagrupar nodos
+- `flatten_node`: Aplanar un nodo
+- `insert_child`: Insertar un nodo hijo
+
+### Modificación de Texto
+- `set_text_content`: Modificar contenido de texto
+- `set_multiple_text_contents`: Modificar múltiples contenidos de texto
+- `set_font_name`: Establecer nombre y estilo de fuente
+- `set_font_size`: Establecer tamaño de fuente
+- `set_font_weight`: Establecer peso de fuente
+- `set_letter_spacing`: Establecer espaciado entre letras
+- `set_line_height`: Establecer altura de línea
+- `set_paragraph_spacing`: Establecer espaciado de párrafo
+- `set_text_case`: Establecer caso de texto (mayúsculas, minúsculas, etc.)
+- `set_text_decoration`: Establecer decoración de texto (subrayado, tachado)
+
+### Otros
+- `set_corner_radius`: Establecer radio de esquina
+- `export_node_as_image`: Exportar nodo como imagen
+- `load_font_async`: Cargar fuente de forma asíncrona
+- `set_auto_layout`: Configurar auto layout
+- `set_effects`: Establecer efectos visuales
+- `set_effect_style_id`: Aplicar estilo de efecto
+
+## 📚 Prompts y Estrategias
+
+El servidor incluye varios prompts predefinidos que ofrecen estrategias y mejores prácticas para trabajar con Figma:
+
+- `design_strategy`: Mejores prácticas para trabajar con diseños de Figma
+- `read_design_strategy`: Mejores prácticas para leer diseños de Figma
+- `text_replacement_strategy`: Enfoque sistemático para reemplazar texto en diseños de Figma
+
+## 🔒 Manejo de Errores y Seguridad
+
+- El sistema implementa control de errores en todas las herramientas
+- Utiliza filtrado para reducir la complejidad de las respuestas de Figma
+- Implementa un sistema de registro personalizado que escribe en stderr para evitar la captura
+
+## 🔌 Configuración y Conexión
+
+- El servidor admite argumentos de línea de comandos para personalizar:
+  - URL del servidor (`--server`)
+  - Puerto (`--port`, predeterminado: 3055)
+  - Intervalo de reconexión (`--reconnect-interval`)
+- Permite la conexión a WebSocket seguro (WSS) o inseguro (WS)
+- Implementa reconexión automática para mayor robustez
+
+## 💬 Gestión de Canales
+
+- Admite la conexión a canales específicos para la comunicación con Figma
+- Permite a Claude "unirse" a canales específicos para interactuar con diferentes instancias de Figma
+
+## 📊 Características Avanzadas
+
+- **Procesamiento por Lotes**: Las operaciones que involucran múltiples nodos (como el reemplazo de texto) se procesan en lotes para mejorar el rendimiento
+- **Informes de Progreso**: Para operaciones largas, proporciona actualizaciones de progreso
+- **Reconexión Inteligente**: El sistema maneja automáticamente la reconexión cuando se interrumpe la comunicación WebSocket
+
+## 🖥️ Uso Práctico
+
+Este sistema permite escenarios como:
+1. Analizar diseños existentes de Figma
+2. Crear nuevos diseños basados en instrucciones en lenguaje natural
+3. Modificar textos y estilos en todo un documento
+4. Extraer información estructurada de diseños de Figma
+5. Hacer cambios específicos en elementos de diseño seleccionados
+
+## 🚀 Mejores Usos para Claude
+
+1. **Creación de Prototipos**: Crear rápidamente prototipos de UI basados en descripciones
+2. **Modificación por Lotes**: Actualizar múltiples elementos de texto o estilos manteniendo la coherencia
+3. **Análisis de Diseño**: Extraer información estructurada sobre componentes de UI y sus relaciones
+4. **Transformación de Texto**: Localizar interfaces o adaptar contenido para diferentes audiencias
+5. **Optimización de Diseño**: Sugerir mejoras basadas en principios de diseño y accesibilidad
+
+## 🛠️ Limitaciones Técnicas
+
+1. **Complejidad de Respuesta**: Las respuestas complejas de Figma necesitan filtrado para ser manejables
+2. **Rendimiento**: Las operaciones masivas pueden ser lentas y requieren procesamiento por lotes
+3. **Sincronización**: Posibles desafíos con cambios concurrentes en el documento de Figma
+4. **Tiempo de Respuesta**: Las operaciones que involucran muchos nodos pueden tener latencia alta
+5. **Tipos de Nodos**: No todos los tipos de nodos de Figma (como vectores) son completamente compatibles

package/#Tools/claude-talk-to-figma-mcp/context/01/01-tools-refactor.md

@@ -0,0 +1,370 @@
+# Propuesta de Refactorización para server.ts
+
+## 📋 Resumen de la Propuesta
+
+El archivo `server.ts` del proyecto "claude-talk-to-figma-mcp" actualmente supera las 2500 líneas, lo que dificulta su mantenimiento y comprensión. Esta propuesta plantea una refactorización estructural que divide el código en módulos más pequeños y manejables, manteniendo la funcionalidad actual sin añadir nuevas características.
+
+## 🔍 Análisis del Código Actual
+
+El archivo `server.ts` contiene:
+
+1. Configuración del servidor MCP
+2. Múltiples definiciones de herramientas (tools)
+3. Funciones auxiliares para el manejo de WebSockets
+4. Lógica de conexión y comunicación con Figma
+5. Definición de prompts
+6. Manejo de errores y tipos
+
+Esta estructura monolítica dificulta la navegación, el mantenimiento y las futuras ampliaciones.
+
+## 🧩 Estructura Propuesta
+
+Propongo dividir el código en los siguientes módulos:
+
+```
+src/talk_to_figma_mcp/
+├── server.ts                  # Punto de entrada principal (reducido)
+├── config/
+│   └── config.ts              # Configuración y argumentos de línea de comandos
+├── types/
+│   └── index.ts               # Definiciones de tipos e interfaces
+├── utils/
+│   ├── logger.ts              # Funciones de logging
+│   ├── figma-helpers.ts       # Funciones auxiliares para Figma (filterFigmaNode, etc.)
+│   └── websocket.ts           # Manejo de WebSocket (conectar, enviar comandos)
+├── tools/
+│   ├── index.ts               # Exporta todas las herramientas
+│   ├── document-tools.ts      # Herramientas de información del documento
+│   ├── selection-tools.ts     # Herramientas relacionadas con la selección
+│   ├── creation-tools.ts      # Herramientas para crear elementos (rectángulos, marcos, etc.)
+│   ├── modification-tools.ts  # Herramientas para modificar elementos
+│   ├── text-tools.ts          # Herramientas para texto
+│   ├── component-tools.ts     # Herramientas para componentes
+│   ├── style-tools.ts         # Herramientas para estilos
+│   ├── effects-tools.ts       # Herramientas para efectos
+│   └── export-tools.ts        # Herramientas de exportación
+└── prompts/
+    └── index.ts               # Definiciones de prompts
+```
+
+## ⚙️ Plan de Implementación 
+
+### 1. Crear la estructura de directorios ✅
+
+```bash
+mkdir -p src/talk_to_figma_mcp/{config,types,utils,tools,prompts}
+```
+
+### 2. Extraer Tipos y Configuración ✅
+
+**types/index.ts:**
+```typescript
+// Definir interfaces para respuestas de Figma
+export interface FigmaResponse {
+  id: string;
+  result?: any;
+  error?: string;
+}
+
+// Definir interfaz para actualizaciones de progreso
+export interface CommandProgressUpdate {
+  type: 'command_progress';
+  commandId: string;
+  commandType: string;
+  status: 'started' | 'in_progress' | 'completed' | 'error';
+  progress: number;
+  totalItems: number;
+  processedItems: number;
+  currentChunk?: number;
+  totalChunks?: number;
+  chunkSize?: number;
+  message: string;
+  payload?: any;
+  timestamp: number;
+}
+
+// Definir tipos de comandos Figma
+export type FigmaCommand =
+  | "get_document_info"
+  | "get_selection"
+  | "get_node_info"
+  // ... otros comandos
+```
+
+**config/config.ts:**
+```typescript
+// Configuración y análisis de argumentos
+import { z } from "zod";
+
+// Argumentos de línea de comandos
+const args = process.argv.slice(2);
+const serverArg = args.find(arg => arg.startsWith('--server='));
+const portArg = args.find(arg => arg.startsWith('--port='));
+const reconnectArg = args.find(arg => arg.startsWith('--reconnect-interval='));
+
+export const serverUrl = serverArg ? serverArg.split('=')[1] : 'localhost';
+export const defaultPort = portArg ? parseInt(portArg.split('=')[1], 10) : 3055;
+export const reconnectInterval = reconnectArg ? parseInt(reconnectArg.split('=')[1], 10) : 2000;
+
+export const WS_URL = serverUrl === 'localhost' ? `ws://${serverUrl}` : `wss://${serverUrl}`;
+
+// Configuración del servidor MCP
+export const SERVER_CONFIG = {
+  name: "ClaudeTalkToFigmaMCP",
+  description: "Claude MCP Plugin for Figma",
+  version: "0.4.0",
+};
+```
+
+### 3. Extraer Utilidades ✅
+
+**utils/logger.ts:**
+```typescript
+// Funciones personalizadas de logging
+export const logger = {
+  info: (message: string) => process.stderr.write(`[INFO] ${message}\n`),
+  debug: (message: string) => process.stderr.write(`[DEBUG] ${message}\n`),
+  warn: (message: string) => process.stderr.write(`[WARN] ${message}\n`),
+  error: (message: string) => process.stderr.write(`[ERROR] ${message}\n`),
+  log: (message: string) => process.stderr.write(`[LOG] ${message}\n`)
+};
+```
+
+**utils/figma-helpers.ts:**
+```typescript
+// Funciones auxiliares para procesar datos de Figma
+export function rgbaToHex(color: any): string {
+  // Implementación existente
+}
+
+export function filterFigmaNode(node: any) {
+  // Implementación existente
+}
+
+export function processFigmaNodeResponse(result: unknown): any {
+  // Implementación existente
+}
+```
+
+**utils/websocket.ts:**
+```typescript
+import WebSocket from "ws";
+import { v4 as uuidv4 } from "uuid";
+import { logger } from "./logger";
+import { serverUrl, defaultPort, WS_URL, reconnectInterval } from "../config/config";
+import { FigmaCommand, FigmaResponse, CommandProgressUpdate } from "../types";
+
+// WebSocket connection and request tracking
+let ws: WebSocket | null = null;
+let currentChannel: string | null = null;
+
+const pendingRequests = new Map<string, {
+  resolve: (value: unknown) => void;
+  reject: (reason: unknown) => void;
+  timeout: ReturnType<typeof setTimeout>;
+  lastActivity: number;
+}>();
+
+// Función para conectar con Figma
+export function connectToFigma(port: number = defaultPort) {
+  // Implementación existente
+}
+
+// Función para unirse a un canal
+export async function joinChannel(channelName: string): Promise<void> {
+  // Implementación existente
+}
+
+// Función para enviar comandos a Figma
+export function sendCommandToFigma(
+  command: FigmaCommand,
+  params: unknown = {},
+  timeoutMs: number = 30000
+): Promise<unknown> {
+  // Implementación existente
+}
+```
+
+### 4. Organizar Herramientas por Categorías ✅
+
+**tools/document-tools.ts:**
+```typescript
+import { z } from "zod";
+import { sendCommandToFigma } from "../utils/websocket";
+import { filterFigmaNode } from "../utils/figma-helpers";
+
+// Exportar función para registrar herramientas en el servidor
+export function registerDocumentTools(server: any) {
+  // Document Info Tool
+  server.tool(
+    "get_document_info",
+    "Get detailed information about the current Figma document",
+    {},
+    async () => {
+      // Implementación existente
+    }
+  );
+
+  // Selection Tool
+  server.tool(
+    "get_selection",
+    "Get information about the current selection in Figma",
+    {},
+    async () => {
+      // Implementación existente
+    }
+  );
+
+  // Node Info Tool
+  server.tool(
+    "get_node_info",
+    "Get detailed information about a specific node in Figma",
+    {
+      nodeId: z.string().describe("The ID of the node to get information about"),
+    },
+    async ({ nodeId }) => {
+      // Implementación existente
+    }
+  );
+
+  // Nodes Info Tool
+  server.tool(
+    "get_nodes_info",
+    "Get detailed information about multiple nodes in Figma",
+    {
+      nodeIds: z.array(z.string()).describe("Array of node IDs to get information about")
+    },
+    async ({ nodeIds }) => {
+      // Implementación existente
+    }
+  );
+}
+```
+
+Las demás herramientas se organizarían de manera similar en sus respectivos archivos.
+
+### 5. Organizar Prompts ✅
+
+**prompts/index.ts:**
+```typescript
+export function registerPrompts(server: any) {
+  // Design Strategy Prompt
+  server.prompt(
+    "design_strategy",
+    "Best practices for working with Figma designs",
+    (extra) => {
+      // Implementación existente
+    }
+  );
+
+  // Read Design Strategy Prompt
+  server.prompt(
+    "read_design_strategy",
+    "Best practices for reading Figma designs",
+    (extra) => {
+      // Implementación existente
+    }
+  );
+
+  // Text Replacement Strategy Prompt
+  server.prompt(
+    "text_replacement_strategy",
+    "Systematic approach for replacing text in Figma designs",
+    (extra) => {
+      // Implementación existente
+    }
+  );
+}
+```
+
+### 6. Refactorizar el Archivo Principal ✅
+
+**server.ts** (refactorizado):
+```typescript
+#!/usr/bin/env node
+
+/**
+ * Main entry point for the Figma MCP Server
+ * This file initializes the server, connects to Figma,
+ * and registers all tools and prompts.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// Import configuration
+import { SERVER_CONFIG } from "./config/config";
+
+// Import utilities
+import { logger } from "./utils/logger";
+import { connectToFigma } from "./utils/websocket";
+
+// Import tools registration function from tools/index.ts
+import { registerTools } from "./tools";
+
+// Import prompts registration function from prompts/index.ts
+import { registerPrompts } from "./prompts";
+
+/**
+ * Initialize and start the MCP server
+ */
+async function main() {
+  try {
+    // Create MCP server instance with configuration
+    const server = new McpServer(SERVER_CONFIG);
+    
+    // Register all tools with the server
+    registerTools(server);
+    
+    // Register all prompts with the server
+    registerPrompts(server);
+    
+    // Try to connect to Figma socket server
+    try {
+      connectToFigma();
+    } catch (error) {
+      logger.warn(`Could not connect to Figma initially: ${error instanceof Error ? error.message : String(error)}`);
+      logger.warn('Will try to connect when the first command is sent');
+    }
+
+    // Start the MCP server with stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info('FigmaMCP server running on stdio');
+  } catch (error) {
+    logger.error(`Error starting FigmaMCP server: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+  }
+}
+
+// Run the server
+main().catch(error => {
+  logger.error(`Error starting FigmaMCP server: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+});
+```
+
+## 🔄 Proceso de Migración
+
+Para garantizar una migración segura y sin interrupciones, recomiendo el siguiente enfoque:
+
+1. Crear la nueva estructura de directorios
+2. Mover el código a los nuevos archivos manteniendo su funcionalidad
+3. Integrar todos los módulos en el nuevo archivo principal
+4. Ejecutar pruebas exhaustivas para verificar que todo funcione como antes
+5. Resolver cualquier problema de importación o dependencia circular
+
+## 🏁 Beneficios de la Refactorización
+
+1. **Mejor Mantenibilidad**: Archivos más pequeños y enfocados
+2. **Mayor Claridad**: Organización lógica por tipos de herramientas
+3. **Facilidad de Extensión**: Añadir nuevas herramientas será más sencillo
+4. **Mejor Colaboración**: Varios desarrolladores pueden trabajar en diferentes módulos
+5. **Pruebas Simplificadas**: Unidades más pequeñas que son más fáciles de probar
+
+## 🚀 Recomendaciones Adicionales
+
+- Mantener la compatibilidad con la configuración actual de compilación (tsup.config.ts)
+- Actualizar scripts de construcción para manejar la nueva estructura de archivos
+- Considerar la adición de pruebas unitarias para cada módulo
+- Documentar la nueva estructura para facilitar el trabajo futuro