Klaviyo MCP Server

Servidor Klaviyo MCP mejorado

Un servidor completo de Protocolo de Contexto de Modelo (MCP) para interactuar con la API de Klaviyo. Esta versión mejorada ofrece funciones de análisis avanzadas, optimizaciones de rendimiento y una gestión robusta de errores, a la vez que mantiene total compatibilidad con el servidor MCP original.

🌟 Características principales

• Análisis e informes avanzados : acceda a métricas de rendimiento de campañas, datos agregados e información detallada.
• Cobertura completa de API : Compatibilidad con todos los puntos finales de API de Klaviyo con la última revisión (15/06/2024)
• Optimizaciones de rendimiento : almacenamiento en caché inteligente, gestión de límites de velocidad y procesamiento de datos eficiente
• Manejo robusto de errores : mecanismos de respaldo, registro detallado y degradación elegante
• Fácil integración : Integración perfecta con Claude y otros LLM a través del Protocolo de contexto de modelo

📊 Capacidades de análisis e informes

Esta versión mejorada agrega potentes capacidades de análisis que no estaban disponibles en la versión original:

• Métricas de rendimiento de la campaña : tasas de apertura, tasas de clics, tasas de rebote y más
• Agregación de métricas personalizadas : agregue métricas por períodos de tiempo, dimensiones y mediciones
• Atribución de ingresos : realice un seguimiento de los ingresos generados por campañas y flujos
• Información sobre suscriptores : analice el crecimiento, la participación y el comportamiento de los suscriptores.

🔧 Mejoras técnicas

1. Configuración centralizada ✅

• Se creó un sistema de configuración central ( src/config.js ) para todos los parámetros de API
• Se hizo que la fecha de revisión de la API, las estadísticas válidas y otros parámetros sean fácilmente configurables
• Se evitaron inconsistencias entre diferentes archivos cuando cambian los parámetros de la API

2. Sistema de registro mejorado ✅

• Se implementó un sistema de registro robusto con diferentes niveles de registro (depuración, información, advertencia, error)
• Se agregó un registro especializado para solicitudes y respuestas de API
• Datos confidenciales enmascarados en registros por seguridad
• Destinos de registro configurables y nivel de detalle

3. Limitación de velocidad inteligente ✅

• Se agregó lógica de reintento para errores de límite de velocidad
• Se implementó un retroceso exponencial con fluctuación para los reintentos.
• Se agregó una respuesta clara cuando se alcanzan los límites de velocidad.
• Solicitudes críticas priorizadas durante la limitación de velocidad

4. Almacenamiento en caché de rendimiento ✅

• Se implementó el almacenamiento en caché en memoria para datos a los que se accede con frecuencia
• Se agregó invalidación de caché basada en TTL (tiempo de vida)
• Caché optimizada para diferentes tipos de datos (métricas, campañas, etc.)
• Estadísticas de caché para monitorización y optimización

5. Manejo de errores y alternativas ✅

• Manejo integral de errores para todas las interacciones de API
• Mecanismos de respaldo para operaciones degradadas cuando fallan las solicitudes principales
• Mensajes de error detallados e información de solución de problemas
• Prevención y manejo de errores de análisis de JSON

🔄 Versión de API

Esta versión mejorada utiliza la revisión de la API de Klaviyo 2024-06-15 , que incluye las últimas funciones y mejoras. El servidor está diseñado para ser compatible con futuras revisiones de la API mediante el sistema de configuración centralizado.

📋 Atribución

Este proyecto es una versión mejorada del servidor MCP Klaviyo original, creado por Matt Coatsworth . El trabajo original sentó las bases para esta versión mejorada.

🚀 Primeros pasos

Prerrequisitos

• Node.js v18 o superior
• Una cuenta de Klaviyo con acceso API
• Una clave API privada con alcances apropiados (campañas, métricas, etc.)

Instalación

1. Clonar este repositorio:
   git clone https://github.com/ivan-rivera-projects/Klaviyo-MCP-Server-Enhanced.git cd Klaviyo-MCP-Server-Enhanced
2. Instalar dependencias:
   npm install
3. Cree un archivo .env basado en .env.example :
   cp .env.example .env
4. Edite el archivo .env para agregar su clave API de Klaviyo:
   KLAVIYO_API_KEY=your_private_api_key_here LOG_LEVEL=info LOG_FILE=/tmp/klaviyo-mcp.log LOG_RESPONSES=false NODE_ENV=development

Iniciando el servidor

Inicie el servidor en modo de desarrollo con recarga automática:

Para uso en producción:

Pruebas con MCP Inspector

Puede probar el servidor utilizando el Inspector MCP:

Esto abrirá una interfaz web donde podrás probar todas las herramientas y recursos disponibles.

📚 Documentación

Para obtener información detallada sobre las capacidades de análisis y los parámetros de la API, consulte:

• ANALYTICS.md : documentación completa sobre las funciones y el uso de análisis
• docs/KLAVIYO_API_REFERENCE.md - Referencia para los parámetros de la API de Klaviyo

🔍 Ejemplos de uso

Obtener métricas de rendimiento de la campaña

Consulta de métricas agregadas

Obtener un resumen del rendimiento de la campaña

🛠️ Herramientas disponibles

Análisis e informes (Novedades en la versión mejorada)

• get_campaign_metrics : obtiene métricas de rendimiento para una campaña específica (tasas de apertura, tasas de clics, etc.)
• query_metric_aggregates : consulta datos de métricas agregadas para informes analíticos personalizados
• get_campaign_performance : Obtenga un resumen completo del rendimiento de una campaña

Campañas (mejoradas)

• get_campaigns : Obtener campañas de Klaviyo
• get_campaign : Obtener una campaña específica de Klaviyo
• get_campaign_message : Obtener un mensaje de campaña específico con detalles de la plantilla
• get_campaign_messages : Obtener todos los mensajes de una campaña específica
• get_campaign_recipient_estimation : Obtener el recuento estimado de destinatarios para una campaña

Perfiles

• get_profiles : Obtener perfiles de Klaviyo
• get_profile : Obtenga un perfil específico de Klaviyo
• create_profile : Crea un nuevo perfil en Klaviyo
• update_profile : Actualizar un perfil existente en Klaviyo
• delete_profile : Eliminar un perfil de Klaviyo

Listas y segmentos

• get_lists : Obtener listas de Klaviyo
• get_list : Obtener una lista específica de Klaviyo
• create_list : Crea una nueva lista en Klaviyo
• add_profiles_to_list : Agregar perfiles a una lista en Klaviyo
• get_segments : Obtener segmentos de Klaviyo
• get_segment : Obtener un segmento específico de Klaviyo

Eventos y métricas

• get_events : Obtener eventos de Klaviyo
• create_event : Crea un nuevo evento en Klaviyo
• get_metrics : Obtener métricas de Klaviyo
• get_metric : obtiene una métrica específica de Klaviyo

Flujos

• get_flows : Obtener flujos de Klaviyo
• get_flow : obtiene un flujo específico de Klaviyo
• update_flow_status : Actualiza el estado de un flujo en Klaviyo

Gestión de contenidos

• get_templates : Obtener plantillas de Klaviyo
• get_template : Obtener una plantilla específica de Klaviyo
• create_template : Crea una nueva plantilla en Klaviyo
• get_images : Obtener imágenes de Klaviyo
• get_image : Obtener una imagen específica de Klaviyo

Comercio electrónico

• get_catalogs : Obtenga catálogos de Klaviyo
• get_catalog_items : Obtener artículos de un catálogo en Klaviyo
• get_catalog_item : Obtener un artículo específico de un catálogo en Klaviyo
• get_coupons : Obtén cupones de Klaviyo
• create_coupon_code : Crea un nuevo código de cupón en Klaviyo

Herramientas adicionales

• get_tags : Obtener etiquetas de Klaviyo
• create_tag : Crea una nueva etiqueta en Klaviyo
• add_tag_to_resource : Agregar una etiqueta a un recurso en Klaviyo
• get_webhooks : Obtener webhooks de Klaviyo
• create_webhook : Crea un nuevo webhook en Klaviyo
• delete_webhook : Eliminar un webhook de Klaviyo
• request_profile_deletion : Solicitar la eliminación de un perfil para el cumplimiento de la privacidad de los datos
• get_forms : Obtener formularios de Klaviyo
• get_form : Obtener un formulario específico de Klaviyo
• get_product_reviews : Obtén reseñas de productos de Klaviyo
• get_product_review : Obtenga una reseña de producto específica de Klaviyo

🔗 Recursos disponibles

• klaviyo://profile/{id} : Obtener información sobre un perfil específico
• klaviyo://list/{id} : Obtener información sobre una lista específica
• klaviyo://segment/{id} : Obtener información sobre un segmento específico
• klaviyo://campaign/{id} : Obtener información sobre una campaña específica
• klaviyo://flow/{id} : Obtener información sobre un flujo específico
• klaviyo://template/{id} : Obtener información sobre una plantilla específica
• klaviyo://metric/{id} : Obtener información sobre una métrica específica
• klaviyo://catalog/{id} : Obtener información sobre un catálogo específico

⚠️ Problemas y limitaciones conocidos

• La API de Klaviyo puede imponer límites de velocidad en los puntos finales de informes
• Algunas métricas pueden tener un retraso antes de estar disponibles en la API
• La disponibilidad de datos históricos puede ser limitada según su plan de Klaviyo
• Al utilizar Claude Desktop, es posible que ocasionalmente vea advertencias de análisis de JSON que no afectan la funcionalidad.

📝 Licencia

Este proyecto se deriva del servidor MCP original de Klaviyo. Para obtener información sobre la licencia, contacte con el autor original.

👥 Colaboradores

• Obra original de Matt Coatsworth
• Versión mejorada de Iván Rivera

🔗 Recursos externos

• Documentación de la API de Klaviyo
• Protocolo de contexto modelo
• Documentación de Claude