Улучшенный сервер Klaviyo MCP

Комплексный сервер Model Context Protocol (MCP) для взаимодействия с API Klaviyo. Эта улучшенная версия обеспечивает расширенные возможности аналитики, оптимизацию производительности и надежную обработку ошибок, сохраняя при этом полную совместимость с исходным сервером MCP.

🌟 Основные характеристики

• Расширенная аналитика и отчетность : доступ к показателям эффективности кампании, агрегированным данным и подробным сведениям.

• Комплексное покрытие API : поддержка всех конечных точек API Klaviyo с последней версией (15.06.2024)

• Оптимизация производительности : интеллектуальное кэширование, обработка ограничений скорости и эффективная обработка данных.

• Надежная обработка ошибок : механизмы отката, подробное ведение журнала и плавная деградация

• Простая интеграция : бесшовная интеграция с Клодом и другими LLM через протокол контекста модели

Related MCP server: BolideAI MCP

📊 Возможности аналитики и отчетности

В этой улучшенной версии добавлены мощные аналитические возможности, которых не было в оригинале:

• Показатели эффективности кампании : показатели открытий, кликов, отказов и т. д.

• Пользовательская агрегация метрик : агрегация метрик по периодам времени, измерениям и измерениям.

• Атрибуция доходов : отслеживайте доходы, полученные от кампаний и потоков.

• Аналитика подписчиков : анализ роста числа подписчиков, их вовлеченности и поведения.

🔧 Технические улучшения

1. Централизованная конфигурация ✅

• Создана центральная система конфигурации ( src/config.js ) для всех параметров API.

• Сделал дату пересмотра API, действительную статистику и другие параметры легко настраиваемыми

• Предотвращены несоответствия между различными файлами при изменении параметров API.

2. Улучшенная система ведения журнала ✅

• Реализована надежная система ведения журнала с различными уровнями (отладка, информация, предупреждение, ошибка)

• Добавлено специализированное ведение журнала для запросов и ответов API.

• Маскировка конфиденциальных данных в журналах в целях безопасности

• Настраиваемые места назначения и уровень детализации журнала

3. Интеллектуальное ограничение скорости ✅

• Добавлена логика повтора для ошибок ограничения скорости

• Реализована экспоненциальная задержка с джиттером для повторных попыток

• Добавлена четкая обратная связь при достижении ограничений по скорости

• Приоритетные критические запросы во время ограничения скорости

4. Кэширование производительности ✅

• Реализовано кэширование в памяти для часто используемых данных

• Добавлена возможность аннулирования кэша на основе TTL (времени жизни)

• Оптимизированный кэш для различных типов данных (показатели, кампании и т. д.)

• Статистика кэширования для мониторинга и оптимизации

5. Обработка ошибок и откаты ✅

• Комплексная обработка ошибок для всех взаимодействий API

• Резервные механизмы для ухудшения работы при сбое основных запросов

• Подробные сообщения об ошибках и информация по устранению неполадок

• Предотвращение и обработка ошибок анализа JSON

🔄 Версия API

Эта улучшенная версия использует Klaviyo API Revision 2024-06-15 , которая включает в себя последние функции и улучшения. Сервер разработан для обеспечения прямой совместимости с будущими версиями API через централизованную систему конфигурации.

📋 Атрибуция

Этот проект является улучшенной версией оригинального Klaviyo MCP Server, созданного Мэттом Коутсвортом . Оригинальная работа легла в основу этой улучшенной версии.

🚀 Начало работы

Предпосылки

• Node.js v18 или выше

• Аккаунт Klaviyo с доступом к API

• Закрытый ключ API с соответствующими областями действия (кампании: чтение, метрики: чтение и т. д.)

Установка

1. Клонируйте этот репозиторий:

   git clone https://github.com/ivan-rivera-projects/Klaviyo-MCP-Server-Enhanced.git
   cd Klaviyo-MCP-Server-Enhanced

2. Установить зависимости:

   npm install

3. Создайте файл .env на основе .env.example :

   cp .env.example .env

4. Отредактируйте файл .env , чтобы добавить свой ключ API Klaviyo:

   KLAVIYO_API_KEY=your_private_api_key_here
   LOG_LEVEL=info
   LOG_FILE=/tmp/klaviyo-mcp.log
   LOG_RESPONSES=false
   NODE_ENV=development

Запуск сервера

Запустить сервер в режиме разработки с автоматической перезагрузкой:

npm run dev

Для производственного использования:

npm start

Тестирование с помощью MCP Inspector

Вы можете протестировать сервер с помощью MCP Inspector:

npm run inspect

Откроется веб-интерфейс, где вы сможете протестировать все доступные инструменты и ресурсы.

📚 Документация

Подробную информацию о возможностях аналитики и параметрах API см. здесь:

• ANALYTICS.md — Полная документация по функциям и использованию аналитики

• docs/KLAVIYO_API_REFERENCE.md - Справочник по параметрам API Klaviyo

🔍 Примеры использования

Получение показателей эффективности кампании

// Retrieve open rates and click rates for a campaign
get_campaign_metrics({
    id: "01JSQRND0PMH88186NREAJEGGN",
    metrics: ["open_rate", "click_rate", "delivered", "bounce_rate"],
    conversion_metric_id: "VevE7N", // Placed Order metric ID
    start_date: "2025-04-01T00:00:00Z", // Optional: Custom date range
    end_date: "2025-05-01T00:00:00Z"    // Optional: Custom date range
})

Запрос агрегированных показателей

// Count placed orders grouped by month
query_metric_aggregates({
    metric_id: "VevE7N", // Placed Order metric ID
    measurement: "count",
    group_by: ["month"],
    timeframe: "last_30_days", // Predefined timeframe
    // Or use custom dates:
    start_date: "2025-01-01T00:00:00Z",
    end_date: "2025-05-01T00:00:00Z"
})

Получение сводки эффективности кампании

// Get a comprehensive summary of campaign performance
get_campaign_performance({
    id: "01JSQRND0PMH88186NREAJEGGN"
})

🛠️ Доступные инструменты

Аналитика и отчетность (новое в расширенной версии)

• get_campaign_metrics : получение показателей эффективности для определенной кампании (показатели открытий, показатели кликов и т. д.)

• query_metric_aggregates : Запрос агрегированных метрических данных для создания пользовательских аналитических отчетов

• get_campaign_performance : получите полную сводку эффективности кампании

Кампании (Расширенные)

• get_campaigns : Получить кампании от Klaviyo

• get_campaign : Получить конкретную кампанию от Klaviyo

• get_campaign_message : Получить конкретное сообщение кампании с данными шаблона

• get_campaign_messages : Получить все сообщения для определенной кампании

• get_campaign_recipient_estimation : Получить предполагаемое количество получателей для кампании

Профили

• get_profiles : Получить профили из Klaviyo

• get_profile : Получить определенный профиль из Klaviyo

• create_profile : Создать новый профиль в Klaviyo

• update_profile : Обновить существующий профиль в Klaviyo

• delete_profile : Удалить профиль из Klaviyo

Списки и сегменты

• get_lists : Получить списки из Klaviyo

• get_list : Получить определенный список из Klaviyo

• create_list : Создать новый список в Klaviyo

• add_profiles_to_list : Добавить профили в список в Klaviyo

• get_segments : Получить сегменты из Klaviyo

• get_segment : Получить определенный сегмент из Klaviyo

События и метрики

• get_events : Получить события от Klaviyo

• create_event : Создать новое событие в Klaviyo

• get_metrics : Получить метрики от Klaviyo

• get_metric : Получить определенную метрику из Klaviyo

Потоки

• get_flows : Получить потоки от Klaviyo

• get_flow : Получить определенный поток из Klaviyo

• update_flow_status : Обновить статус потока в Klaviyo

Управление контентом

• get_templates : Получить шаблоны из Klaviyo

• get_template : Получить определенный шаблон из Klaviyo

• create_template : Создать новый шаблон в Klaviyo

• get_images : Получить изображения из Klaviyo

• get_image : Получить определенное изображение из Klaviyo

Электронная коммерция

• get_catalogs : Получить каталоги от Klaviyo

• get_catalog_items : Получить элементы из каталога в Klaviyo

• get_catalog_item : Получить определенный элемент из каталога в Klaviyo

• get_coupons : Получить купоны от Klaviyo

• create_coupon_code : Создать новый код купона в Klaviyo

Дополнительные инструменты

• get_tags : Получить теги от Klaviyo

• create_tag : Создать новый тег в Klaviyo

• add_tag_to_resource : Добавить тег к ресурсу в Klaviyo

• get_webhooks : Получить вебхуки от Klaviyo

• create_webhook : создать новый вебхук в Klaviyo

• delete_webhook : удалить вебхук из Klaviyo.

• request_profile_deletion : Запрос на удаление профиля для соблюдения конфиденциальности данных

• get_forms : Получить формы из Klaviyo

• get_form : Получить определенную форму из Klaviyo

• get_product_reviews : Получите обзоры продуктов от Klaviyo

• get_product_review : Получите обзор конкретного продукта от Klaviyo

🔗 Доступные ресурсы

• klaviyo://profile/{id} : Получить информацию о конкретном профиле

• klaviyo://list/{id} : Получить информацию о конкретном списке

• klaviyo://segment/{id} : Получить информацию о конкретном сегменте

• klaviyo://campaign/{id} : Получить информацию о конкретной кампании

• klaviyo://flow/{id} : Получить информацию о конкретном потоке

• klaviyo://template/{id} : Получить информацию о конкретном шаблоне

• klaviyo://metric/{id} : Получить информацию о конкретной метрике

• klaviyo://catalog/{id} : Получить информацию о конкретном каталоге

⚠️ Известные проблемы и ограничения

• API Klaviyo может накладывать ограничения на скорость отправки отчетов на конечные точки

• Некоторые показатели могут быть доступны в API с задержкой.

• Доступность исторических данных может быть ограничена в зависимости от вашего плана Klaviyo.

• При использовании с Claude Desktop вы можете иногда видеть предупреждения анализа JSON, которые не влияют на функциональность.

📝 Лицензия

Этот проект является производным от оригинального Klaviyo MCP Server. Пожалуйста, свяжитесь с оригинальным автором для получения информации о лицензировании.

👥 Участники

• Оригинальная работа Мэтта Коутсворта

• Расширенная версия Ивана Риверы

🔗 Внешние ресурсы

• Документация API Klaviyo

• Модель контекстного протокола

• Документация Клода