# Funcionalidades Completas

Este servidor MCP proporciona **lectura y escritura completa** de comentarios en Figma.

## Operaciones de Lectura

### 1. Obtener Comentarios (`get_figma_comments`)

Lee todos los comentarios de un archivo de Figma con información completa:

- ✅ Texto del comentario
- ✅ Información del autor (nombre, avatar)
- ✅ Fecha y hora de creación
- ✅ Ubicación en el diseño (coordenadas y nodo)
- ✅ Estado de resolución
- ✅ Hilos completos de respuestas

**Ejemplo de uso:**
```
"Muéstrame todos los comentarios del archivo ABC123"
"¿Cuántos comentarios sin resolver hay en el archivo XYZ?"
```

### 2. Resumir Comentarios (`summarize_figma_comments`)

Genera estadísticas y análisis automático:

- ✅ Total de comentarios y respuestas
- ✅ Comentarios resueltos vs sin resolver
- ✅ Agrupación por autor
- ✅ Agrupación por ubicación (elementos del diseño)
- ✅ Vista previa de cada comentario

**Ejemplo de uso:**
```
"Dame un resumen de la actividad de comentarios en ABC123"
"¿Quién ha comentado más en este archivo?"
```

### 3. Listar Usuarios (`get_comment_users`)

Obtiene la lista de usuarios que han comentado en un archivo. Muy útil para saber a quién puedes mencionar:

- ✅ Lista todos los usuarios únicos
- ✅ Incluye handle (username) y avatar
- ✅ Perfecto para usar antes de mencionar a alguien

**Ejemplo de uso:**
```
"¿Quién ha comentado en el archivo ABC123?"
"Muéstrame los usuarios que puedo mencionar en XYZ"
```

**Ejemplo de salida:**
```json
[
  {"id": "...", "handle": "john_designer", "img_url": "..."},
  {"id": "...", "handle": "maria_ux", "img_url": "..."}
]
```

## Operaciones de Escritura

### 4. Crear Comentarios (`post_figma_comment`)

Crea nuevos comentarios en archivos de Figma con opciones avanzadas:

- ✅ Comentarios generales en el archivo
- ✅ Comentarios en elementos específicos (usando node_id)
- ✅ Comentarios en coordenadas exactas (x, y)
- ✅ Comentarios con ubicación combinada (nodo + coordenadas)
- ✅ **Soporte completo de @menciones** para notificar usuarios

**Ejemplos de uso:**

**Comentario general:**
```
"Añade un comentario en ABC123 diciendo 'Diseño aprobado para producción'"
```

**Comentario en un elemento específico:**
```
"Comenta en el nodo 123:456 del archivo ABC: 'Este botón necesita más contraste'"
```

**Comentario en coordenadas:**
```
"Añade un comentario en la posición x:100, y:200 del archivo ABC: 'Revisar espaciado aquí'"
```

**Comentario con menciones:**
```
"Post a comment: '@john_designer @maria_ux Por favor revisen el esquema de colores actualizado'"
```

### 5. Responder a Comentarios (`reply_to_figma_comment`)

Responde a comentarios existentes manteniendo los hilos organizados:

- ✅ Responder a cualquier comentario por su ID
- ✅ Mantener conversaciones en hilos
- ✅ Respuestas múltiples coordinadas por IA
- ✅ **Soporte completo de @menciones** para notificar usuarios específicos

**Ejemplos de uso:**

**Respuesta simple:**
```
"Responde al comentario 789 en ABC123: 'Buen punto, lo cambiaré'"
```

**Respuesta con mención:**
```
"Responde al comentario 789: '@sarah Gracias por el feedback, lo actualizaré hoy'"
```

**Respuestas en lote:**
```
"Responde a todos los comentarios sin resolver en ABC123 diciendo que estás trabajando en ello"
```

**Respuestas inteligentes:**
```
"Revisa los comentarios de 'usuario123' y responde apropiadamente a cada uno"
```

## Usar @Menciones en Comentarios

Las menciones permiten notificar a usuarios específicos cuando comentas o respondes. Cuando mencionas a alguien con `@username`, esa persona recibe una notificación en Figma como un **objeto de usuario clicable** (no texto plano).

### ¿Cómo funcionan las menciones?

#### Para el Usuario
1. **Obtén la lista de usuarios** disponibles usando `get_comment_users`
2. **Incluye @username** en tu mensaje al crear o responder comentarios
3. **El usuario mencionado** recibe una notificación automática en Figma

#### Funcionamiento Técnico
El servidor MCP convierte automáticamente `@username` en el formato correcto:
- Detecta menciones con patrón `@\w+` en el texto
- Busca el `user_id` correspondiente al username
- Transforma el mensaje a formato `message_meta` de Figma
- Cada mención se convierte en: `{t: "@username", mention: "user_id"}`
- El resultado es un objeto de usuario clicable en Figma (no texto plano)

**Nota Técnica:** Se usa el formato `message_meta` no documentado oficialmente, descubierto mediante ingeniería inversa del cliente web de Figma. Es el mismo formato que usa la interfaz oficial de Figma.

### Ejemplos con Menciones

**Mencionar en comentario nuevo:**
```
"Añade un comentario: '@john_designer El botón de envío necesita mejor contraste para accesibilidad'"
```

**Mencionar múltiples usuarios:**
```
"Post a comment: '@john_designer @maria_ux @sarah_pm Por favor revisen antes del viernes'"
```

**Mencionar al responder:**
```
"Responde al comentario 456: '@maria_ux Estoy de acuerdo, lo cambiaré hoy mismo'"
```

**Workflow completo con menciones:**
```
1. "¿Quién ha comentado en ABC123?"
   → Claude obtiene: john_designer, maria_ux, sarah_pm

2. "Responde a todos los comentarios sin resolver mencionando a sus autores"
   → Claude responde personalizadamente a cada comentario mencionando al autor

3. "Añade un comentario general agradeciendo a todos"
   → Claude crea: "@john_designer @maria_ux @sarah_pm Gracias por el feedback..."
```

### Mejores Prácticas

- ✅ Usa `get_comment_users` primero para conocer los usernames disponibles
- ✅ Menciona usuarios cuando necesites su atención inmediata
- ✅ Menciona a equipos completos para coordinar reviews
- ✅ Combina menciones con ubicaciones específicas (node_id) para mayor claridad
- ✅ Sé específico en tu mensaje al mencionar para dar contexto

## Casos de Uso Combinados

### Análisis y Respuesta Automática

```
"Obtén todos los comentarios de ABC123, identifica los que requieren acción inmediata, y responde confirmando que los revisarás"
```

### Revisión Asistida por IA

```
"Analiza el diseño y los comentarios existentes en ABC123, luego añade comentarios constructivos adicionales"
```

### Gestión de Comentarios

```
"Encuentra todos los comentarios de hace más de una semana en ABC123 y añade un comentario general resumiendo el progreso"
```

### Coordinación de Equipo

```
"Responde a los comentarios de 'juan' en ABC123 confirmando los cambios, y añade un comentario general notificando que está listo para review"
```

## Permisos Requeridos

### Para Lectura
- Acceso de **lectura** al archivo de Figma
- Token con permisos básicos

### Para Escritura
- Acceso de **edición** al archivo de Figma
- Token con permisos de escritura (incluido por defecto en tokens personales)
- Ser miembro del equipo o tener acceso explícito al archivo

## Limitaciones

- No se pueden eliminar comentarios (limitación de la API de Figma)
- No se pueden marcar comentarios como resueltos directamente (limitación de la API)
- Los comentarios deben tener al menos 1 carácter
- Los node_id deben existir en el archivo

## Seguridad

- Cada usuario usa su propio token de Figma
- Los comentarios se crean con tu identidad de usuario
- Todos los comentarios quedan registrados en el historial de Figma
- No se comparten tokens entre usuarios

## Ejemplos Avanzados

### Workflow de Revisión Completa

1. **Análisis inicial:**
   ```
   "Dame un resumen completo de los comentarios en ABC123"
   ```

2. **Identificar problemas:**
   ```
   "¿Qué comentarios mencionan problemas de accesibilidad?"
   ```

3. **Responder coordinadamente:**
   ```
   "Responde a esos comentarios diciendo que se implementarán en el siguiente sprint"
   ```

4. **Documentar decisiones:**
   ```
   "Añade un comentario general resumiendo las decisiones tomadas hoy"
   ```

### Colaboración con IA

```
"Revisa los comentarios en ABC123, extrae action items, créame un resumen, y añade un comentario en Figma con ese resumen"
```

### Automatización de Feedback

```
"Cada vez que encuentres comentarios sobre accesibilidad en ABC123, responde con las guías de WCAG relevantes"
```

---

**Nota:** Este MCP es especialmente potente cuando se combina con las capacidades de análisis de Claude, permitiendo workflows de diseño más eficientes y colaborativos.