Servidor MCP de Keap

Un servidor de Protocolo de Contexto de Modelo (MCP) de alto rendimiento para interactuar con los datos de Keap CRM, con funciones avanzadas que incluyen soporte para HTTP/2, diagnósticos integrales y operaciones por lotes.

Características

Gestión integral de contactos y etiquetas

• Gestión integral de contactos - Listar, buscar, filtrar y obtener información detallada de contactos

• Operaciones avanzadas con etiquetas - Gestión completa del ciclo de vida de las etiquetas, incluyendo creación, consulta y operaciones por lotes

• Operaciones por lotes con etiquetas - Aplicar o eliminar múltiples etiquetas de múltiples contactos de manera eficiente

• Operaciones con campos personalizados - Buscar contactos por valores de campos personalizados y actualizar campos personalizados de forma masiva

• Filtrado lógico complejo - Soporte para operadores AND, OR, NOT con condiciones anidadas

Rendimiento y optimización

• Soporte para HTTP/2 - Rendimiento de conexión mejorado con agrupación de conexiones

• Limitación de tasa inteligente - Límites de solicitudes diarias con estrategias de retroceso adaptativo

• Optimización de consultas - Filtrado inteligente del lado del servidor frente al lado del cliente con análisis de rendimiento

• Monitoreo de rendimiento - Análisis de consultas en tiempo real y sugerencias de optimización

• Caché persistente - Caché basada en SQLite para reducir las llamadas a la API y mejorar el rendimiento

Características avanzadas

• Diagnósticos integrales - Métricas de rendimiento de la API, monitoreo del sistema y comprobaciones de estado

• Manejo de errores mejorado - Lógica de reintento robusta con retroceso exponencial para diferentes tipos de errores

• Actualizaciones masivas de campos personalizados - Establecer valores de campos personalizados de manera eficiente en múltiples contactos

• Operadores de filtro avanzados - Más de 15 operadores, incluyendo BETWEEN, IN, SINCE, STARTS_WITH, etc.

• Operaciones con listas de ID - Funciones de utilidad para trabajar con conjuntos de ID de contactos y etiquetas

Related MCP server: claude-cli-mcp

Arquitectura

El servidor MCP de Keap utiliza una arquitectura optimizada de alto rendimiento:

• Cliente API (src/api/client.py) - Comunicación mejorada con la API de Keap con HTTP/2, limitación de tasa y diagnósticos

• Herramientas MCP (src/mcp/) - Implementación integral del protocolo MCP con optimización

• Gestor de caché (src/cache/) - Caché persistente basada en SQLite con invalidación inteligente

• Motor de optimización (src/mcp/optimization/) - Optimización de consultas y análisis de rendimiento

• Esquemas (src/schemas/) - Validación de datos y modelos

• Utilidades (src/utils/) - Utilidades compartidas para el procesamiento y filtrado de contactos

Herramientas MCP

El servidor expone 17 herramientas MCP integrales:

Operaciones de contacto

1. list_contacts - Listar contactos con filtrado y paginación (ahora optimizado)

2. search_contacts_by_email - Encontrar contactos por dirección de correo electrónico

3. search_contacts_by_name - Encontrar contactos por nombre

4. get_contact_details - Obtener información detallada sobre un contacto específico

5. query_contacts_by_custom_field - Consultar contactos por valor de campo personalizado

Operaciones con etiquetas

6. get_tags - Recuperar etiquetas con filtrado opcional

7. get_tag_details - Obtener información detallada sobre una etiqueta específica

8. get_contacts_with_tag - Obtener contactos que tienen una etiqueta específica

9. create_tag - Crear una nueva etiqueta

Gestión de etiquetas (operaciones por lotes)

10. modify_tags - Añadir o eliminar etiquetas de contactos

11. apply_tags_to_contacts - Aplicar múltiples etiquetas a múltiples contactos mediante operaciones por lotes

12. remove_tags_from_contacts - Eliminar múltiples etiquetas de múltiples contactos

Gestión de campos personalizados

13. set_custom_field_values - Actualizar masivamente valores de campos personalizados en múltiples contactos

Operaciones avanzadas de consulta y rendimiento

14. query_contacts_optimized - Consulta de contactos avanzada con optimización y análisis de rendimiento

15. analyze_query_performance - Analizar el rendimiento de la consulta y el potencial de optimización

Operaciones del sistema

16. get_api_diagnostics - Diagnósticos integrales de la API y métricas de rendimiento

Operaciones de utilidad

17. intersect_id_lists - Encontrar la intersección de múltiples listas de ID

Primeros pasos

Requisitos previos

• Python 3.9 o superior

• Credenciales de la API de Keap

Instalación

1. Clonar el repositorio:

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

2. Instalar dependencias:

   pip install -r requirements.txt

3. Configurar sus credenciales de la API de Keap:

   • La aplicación utiliza un archivo .env para la configuración

   • La clave de API se ha copiado de keapsync, pero puede modificarla si es necesario

   • La configuración incluye:

     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

Ejecución del servidor

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

Opciones de línea de comandos:

• --host - Host al que vincularse (predeterminado: 127.0.0.1)

• --port - Puerto en el que escuchar (predeterminado: 5000)

• --log-level - Nivel de registro (predeterminado: INFO)

• --log-file - Ruta del archivo de registro (predeterminado: keap_mcp_server.log)

• --no-console-log - Deshabilitar el registro en consola

Pruebas y cobertura

El servidor MCP de Keap incluye un conjunto de pruebas integral para garantizar la fiabilidad y el funcionamiento correcto con una integración completa en la canalización CI/CD.

Pruebas rápidas

Utilice el Makefile para una ejecución de pruebas sencilla:

# 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

Integración CI/CD

El proyecto incluye pruebas automatizadas e informes de cobertura:

• Integración continua: Las pruebas se ejecutan en Python 3.9, 3.10 y 3.11

• Seguimiento de cobertura: Se aplica una cobertura mínima del 60%

• Comprobaciones previas al commit: Formato de código, linting y comprobaciones de seguridad

• Insignias de cobertura: Se actualizan automáticamente en la rama principal

Categorías de prueba

• Pruebas unitarias (tests/unit/) - Pruebas de componentes individuales con simulación integral

• Pruebas de integración (tests/integration/) - Verificación de funcionalidad de extremo a extremo

• Pruebas de rendimiento (tests/performance/) - Validación de carga y optimización

• Validación de API - Verificación del formato de respuesta de la API de Keap

Requisitos de cobertura

• Cobertura actual: 55% de cobertura de integración, varía según el componente

• Cliente API: Funcionalidad principal probada con simulación integral

• Herramientas MCP: Pruebas de integración con dependencias simuladas

• Sistema de caché: Pruebas integrales de persistencia y rendimiento

• Utilidades: Funcionalidad de procesamiento y filtrado de contactos probada

• Optimización: Análisis de rendimiento y optimización de consultas cubiertos

Ejecución de pruebas específicas

# 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

Uso del servidor MCP

Ejemplo: Listar contactos (ahora optimizado)

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

Nota: list_contacts ahora utiliza el motor de optimización internamente para un mejor rendimiento. Para obtener métricas de rendimiento detalladas, utilice query_contacts_optimized directamente.

Ejemplo: Buscar por correo electrónico

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

Ejemplo: Obtener etiquetas

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

Ejemplo: Operaciones por lotes con etiquetas

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

Ejemplo: Consulta de campo personalizado

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

Ejemplo: Crear nueva etiqueta

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

Ejemplo: Actualizaciones masivas de campos personalizados

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

O con valores individuales por contacto:

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

Ejemplo: Diagnósticos de API

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

Ejemplo: Intersección de listas de 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"
  }
}

Características de rendimiento

Soporte para HTTP/2

El servidor utiliza HTTP/2 para un rendimiento mejorado con agrupación de conexiones y conexiones persistentes (keepalive).

Limitación de tasa

• Límites de solicitudes diarias (25.000 solicitudes/día por defecto)

• Estrategias de retroceso inteligente

• Monitoreo y diagnóstico de límites de tasa

Estrategia de caché

• Caché persistente basada en SQLite

• Invalidación de caché inteligente

• Expiración basada en TTL

• Seguimiento de aciertos/fallos de caché

Manejo de errores

• Retroceso exponencial para reintentos

• Diferentes estrategias para errores de tiempo de espera, red y HTTP

• Seguimiento y diagnóstico integral de errores

Licencia

Este proyecto está bajo la Licencia MIT - consulte el archivo LICENSE para obtener más detalles.