Keap MCP Server

Высокопроизводительный сервер протокола контекста модели (MCP) для взаимодействия с данными Keap CRM с расширенными функциями, включая поддержку HTTP/2, комплексную диагностику и пакетные операции.

Функции

Основное управление контактами и тегами

• Комплексное управление контактами - список, поиск, фильтрация и получение подробной информации о контактах

• Расширенные операции с тегами - полное управление жизненным циклом тегов, включая создание, запросы и пакетные операции

• Пакетные операции с тегами - эффективное применение или удаление нескольких тегов для нескольких контактов

• Операции с пользовательскими полями - поиск контактов по значениям пользовательских полей и массовое обновление пользовательских полей

• Сложная логическая фильтрация - поддержка операторов AND, OR, NOT с вложенными условиями

Производительность и оптимизация

• Поддержка HTTP/2 - повышенная производительность соединения с использованием пула соединений

• Интеллектуальное ограничение частоты запросов - суточные лимиты запросов с адаптивными стратегиями экспоненциальной задержки

• Оптимизация запросов - интеллектуальная фильтрация на стороне сервера или клиента с аналитикой производительности

• Мониторинг производительности - анализ запросов в реальном времени и рекомендации по оптимизации

• Постоянное кэширование - кэширование на основе SQLite для сокращения количества вызовов API и повышения производительности

Расширенные функции

• Комплексная диагностика - метрики производительности API, мониторинг системы и проверки работоспособности

• Улучшенная обработка ошибок - надежная логика повторных попыток с экспоненциальной задержкой для различных типов ошибок

• Массовое обновление пользовательских полей - эффективная установка значений пользовательских полей для нескольких контактов

• Расширенные операторы фильтрации - более 15 операторов, включая BETWEEN, IN, SINCE, STARTS_WITH и т. д.

• Операции со списками ID - вспомогательные функции для работы с наборами ID контактов и тегов

Related MCP server: claude-cli-mcp

Архитектура

Keap MCP Server использует оптимизированную высокопроизводительную архитектуру:

• API Client (src/api/client.py) - улучшенное взаимодействие с API Keap с использованием HTTP/2, ограничением частоты запросов и диагностикой

• MCP Tools (src/mcp/) - комплексная реализация протокола MCP с оптимизацией

• Cache Manager (src/cache/) - постоянное кэширование на основе SQLite с интеллектуальной инвалидацией

• Optimization Engine (src/mcp/optimization/) - оптимизация запросов и аналитика производительности

• Schemas (src/schemas/) - проверка данных и модели

• Utils (src/utils/) - общие утилиты для обработки и фильтрации контактов

Инструменты MCP

Сервер предоставляет 17 комплексных инструментов MCP:

Операции с контактами

1. list_contacts - список контактов с фильтрацией и пагинацией (теперь оптимизировано)

2. search_contacts_by_email - поиск контактов по адресу электронной почты

3. search_contacts_by_name - поиск контактов по имени

4. get_contact_details - получение подробной информации о конкретном контакте

5. query_contacts_by_custom_field - запрос контактов по значению пользовательского поля

Операции с тегами

6. get_tags - получение тегов с дополнительной фильтрацией

7. get_tag_details - получение подробной информации о конкретном теге

8. get_contacts_with_tag - получение контактов, имеющих определенный тег

9. create_tag - создание нового тега

Управление тегами (пакетные операции)

10. modify_tags - добавление или удаление тегов у контактов

11. apply_tags_to_contacts - применение нескольких тегов к нескольким контактам с использованием пакетных операций

12. remove_tags_from_contacts - удаление нескольких тегов у нескольких контактов

Управление пользовательскими полями

13. set_custom_field_values - массовое обновление значений пользовательских полей для нескольких контактов

Расширенные запросы и операции производительности

14. query_contacts_optimized - расширенный запрос контактов с оптимизацией и аналитикой производительности

15. analyze_query_performance - анализ производительности запроса и потенциала оптимизации

Системные операции

16. get_api_diagnostics - комплексная диагностика API и метрики производительности

Вспомогательные операции

17. intersect_id_lists - поиск пересечения нескольких списков ID

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

Предварительные требования

• Python 3.9 или выше

• Учетные данные API Keap

Установка

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

   git clone https://github.com/yourusername/keapmcp.git
   cd keapmcp

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

   pip install -r requirements.txt

3. Настройте учетные данные API Keap:

   • Приложение использует файл .env для конфигурации

   • Ключ API был скопирован из keapsync, но вы можете изменить его при необходимости

   • Конфигурация включает:

     KEAP_API_KEY=your_api_key_here
     KEAP_API_BASE_URL=https://api.infusionsoft.com/crm/rest/v1
     KEAP_MCP_HOST=127.0.0.1
     KEAP_MCP_PORT=5000
     KEAP_MCP_LOG_LEVEL=INFO
     KEAP_MCP_LOG_FILE=keap_mcp_server.log
     KEAP_MCP_CACHE_ENABLED=true
     KEAP_MCP_CACHE_TTL=3600

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

python run.py --host 127.0.0.1 --port 5000

Параметры командной строки:

• --host - хост для привязки (по умолчанию: 127.0.0.1)

• --port - порт для прослушивания (по умолчанию: 5000)

• --log-level - уровень логирования (по умолчанию: INFO)

• --log-file - путь к файлу логов (по умолчанию: keap_mcp_server.log)

• --no-console-log - отключить логирование в консоль

Тестирование и покрытие

Keap MCP Server включает комплексный набор тестов для обеспечения надежности и правильной работы с полной интеграцией в конвейер CI/CD.

Быстрое тестирование

Используйте Makefile для простого выполнения тестов:

# Run all unit tests
make test

# Run tests with coverage reporting  
make coverage

# Generate HTML coverage report
make coverage-html

# Run service-specific tests
make test-services
make test-models

# Full development workflow
make dev-test

Интеграция CI/CD

Проект включает автоматизированное тестирование и отчетность о покрытии:

• Непрерывная интеграция: тесты выполняются на Python 3.9, 3.10 и 3.11

• Отслеживание покрытия: обеспечивается минимальное покрытие 60%

• Предварительные проверки (Pre-commit): форматирование кода, линтинг и проверки безопасности

• Значки покрытия: автоматически обновляются в основной ветке

Категории тестов

• Модульные тесты (tests/unit/) - тестирование отдельных компонентов с комплексным мокированием

• Интеграционные тесты (tests/integration/) - проверка функциональности от начала до конца

• Тесты производительности (tests/performance/) - проверка нагрузки и оптимизации

• Проверка API - проверка формата ответа API Keap

Требования к покрытию

• Текущее покрытие: 55% интеграционного покрытия, варьируется в зависимости от компонента

• API Client: основная функциональность протестирована с комплексным мокированием

• MCP Tools: интеграционные тесты с фиктивными зависимостями

• Cache System: комплексное тестирование постоянства и производительности

• Utilities: протестирована функциональность обработки и фильтрации контактов

• Optimization: охвачена аналитика производительности и оптимизация запросов

Запуск конкретных тестов

# Run all tests
python -m pytest tests/ -v

# With coverage reporting
python -m pytest tests/ --cov=src --cov-fail-under=90

# Integration tests (requires running server)
python -m pytest tests/integration/ -v

Использование сервера MCP

Пример: Список контактов (теперь оптимизировано)

{
  "function": "list_contacts",
  "params": {
    "filters": [
      { "field": "email", "operator": "contains", "value": "@company.com" }
    ],
    "limit": 50,
    "include": ["id", "given_name", "family_name", "email"]
  }
}

Примечание: list_contacts теперь использует механизм оптимизации внутри для повышения производительности. Для получения подробных метрик производительности используйте query_contacts_optimized напрямую.

Пример: Поиск по электронной почте

{
  "function": "search_contacts_by_email",
  "params": {
    "email": "john.doe@company.com",
    "include": ["id", "given_name", "family_name", "email", "tags"]
  }
}

Пример: Получение тегов

{
  "function": "get_tags",
  "params": {
    "include_categories": true,
    "limit": 100
  }
}

Пример: Пакетные операции с тегами

{
  "function": "apply_tags_to_contacts",
  "params": {
    "tag_ids": ["123", "456"],
    "contact_ids": ["1001", "1002", "1003"]
  }
}

Пример: Запрос пользовательского поля

{
  "function": "query_contacts_by_custom_field",
  "params": {
    "field_id": "7",
    "field_value": "Engineering",
    "operator": "contains",
    "include": ["id", "given_name", "family_name", "email"]
  }
}

Пример: Создание нового тега

{
  "function": "create_tag",
  "params": {
    "name": "VIP Customer",
    "description": "High-value customer segment",
    "category_id": "2"
  }
}

Пример: Массовое обновление пользовательских полей

{
  "function": "set_custom_field_values",
  "params": {
    "field_id": "7",
    "contact_ids": ["1001", "1002", "1003"],
    "common_value": "VIP Customer"
  }
}

Или с индивидуальными значениями для каждого контакта:

{
  "function": "set_custom_field_values",
  "params": {
    "field_id": "7",
    "contact_values": {
      "1001": "Gold Tier",
      "1002": "Silver Tier", 
      "1003": "Bronze Tier"
    }
  }
}

Пример: Диагностика API

{
  "function": "get_api_diagnostics",
  "params": {}
}

Пример: Пересечение списков ID

{
  "function": "intersect_id_lists",
  "params": {
    "lists": [
      {"list_id": "active_contacts", "item_ids": ["1", "2", "3", "4"]},
      {"list_id": "newsletter_subscribers", "item_ids": ["2", "3", "5", "6"]}
    ],
    "id_field": "item_ids"
  }
}

Функции производительности

Поддержка HTTP/2

Сервер использует HTTP/2 для повышения производительности с пулом соединений и постоянными соединениями (keepalive).

Ограничение частоты запросов

• Суточные лимиты запросов (по умолчанию 25 000 запросов в день)

• Интеллектуальные стратегии экспоненциальной задержки

• Мониторинг и диагностика ограничений частоты запросов

Стратегия кэширования

• Постоянное кэширование на основе SQLite

• Интеллектуальная инвалидация кэша

• Истечение срока действия на основе TTL

• Отслеживание попаданий/промахов кэша

Обработка ошибок

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

• Различные стратегии для тайм-аутов, сетевых ошибок и ошибок HTTP

• Комплексное отслеживание ошибок и диагностика

Лицензия

Этот проект лицензирован по лицензии MIT - подробности см. в файле LICENSE.