appiq-solution 1.4.8 → 1.5.0

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

@@ -1,151 +0,0 @@
-# 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

@@ -1,370 +0,0 @@
-# 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