Fast Intercom

Un servidor MCP de alto rendimiento para analizar conversaciones de Intercom, con velocidades hasta 100 veces más rápidas que la API REST.

GitHub

Documentación

Servidor MCP FastIntercom

Servidor de Protocolo de Contexto de Modelo (MCP) de alto rendimiento para análisis de conversaciones de Intercom. Proporciona acceso local rápido a conversaciones de Intercom mediante caché inteligente y sincronización en segundo plano.

Características

🚀 Acceso Local Rápido: Tiempos de respuesta inferiores a 100 ms para búsquedas de conversaciones
🧠 Sincronización Inteligente: Actualizaciones en segundo plano activadas por solicitudes garantizan datos actualizados
💾 Almacenamiento Eficiente: Almacenamiento local basado en SQLite (~2 KB por conversación)
🔍 Búsqueda Potente: Rangos de tiempo en lenguaje natural y búsqueda de texto
⚡ Integración MCP: Integración directa con Claude Desktop y clientes MCP

Inicio Rápido

Instalación

# Clone and install
git clone <repository-url>
cd fast-intercom-mcp
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Configuración

# Initialize with your Intercom credentials
fast-intercom-mcp init

# Check status
fast-intercom-mcp status

# Sync conversation history
fast-intercom-mcp sync --force --days 7

Integración con Claude Desktop

Agregue a su configuración de Claude Desktop (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "fast-intercom-mcp": {
      "command": "fast-intercom-mcp",
      "args": ["start"],
      "env": {
        "INTERCOM_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Uso

Comandos CLI

fast-intercom-mcp status              # Show server status and statistics
fast-intercom-mcp sync                # Incremental sync of recent conversations  
fast-intercom-mcp sync --force --days 7  # Force sync last 7 days
fast-intercom-mcp start               # Start MCP server
fast-intercom-mcp logs                # View recent log entries
fast-intercom-mcp reset               # Reset all data

Herramientas MCP

Una vez conectado a Claude Desktop, puede hacer preguntas como:

"Buscar conversaciones sobre facturación en los últimos 7 días"
"Mostrarme conversaciones de clientes de ayer"
"¿Cuál es el estado del servidor FastIntercom?"
"Obtener detalles de la conversación con ID 123456789"

Configuración

Variables de Entorno

INTERCOM_ACCESS_TOKEN=your_token_here
FASTINTERCOM_LOG_LEVEL=INFO
FASTINTERCOM_MAX_SYNC_AGE_MINUTES=5
FASTINTERCOM_BACKGROUND_SYNC_INTERVAL=10

Archivo de Configuración

Ubicado en ~/.fast-intercom-mcp/config.json:

{
  "log_level": "INFO",
  "max_sync_age_minutes": 5,
  "background_sync_interval_minutes": 10,
  "initial_sync_days": 30
}

Arquitectura

Estrategia de Sincronización Inteligente

FastIntercom utiliza una estrategia de caché sofisticada:

Respuesta Inmediata: Las solicitudes MCP devuelven datos al instante desde la caché local
Sincronización en Segundo Plano: Los rangos de tiempo desactualizados activan actualizaciones en segundo plano
Activadores Inteligentes: El sistema aprende de los patrones de solicitudes para optimizar el tiempo de sincronización
Datos Actualizados: La siguiente solicitud obtiene datos actualizados de la sincronización en segundo plano

Componentes

Base de Datos: SQLite con esquema optimizado para búsquedas rápidas
Servicio de Sincronización: Servicio en segundo plano con lógica de actualización inteligente
Servidor MCP: Implementación del Protocolo de Contexto de Modelo
Interfaz CLI: Herramientas de línea de comandos para gestión y monitoreo

Desarrollo

Pruebas

Pruebas Rápidas

# Unit tests
pytest tests/

# Integration test (requires API key)
./scripts/run_integration_test.sh

# Docker test
./scripts/test_docker_install.sh

Pruebas Integrales

# Full unit test suite with coverage
pytest tests/ --cov=fast_intercom_mcp

# Integration test with performance report
./scripts/run_integration_test.sh --performance-report

# Docker clean install test
./scripts/test_docker_install.sh --with-api-test

# Performance benchmarking
./scripts/run_performance_test.sh

Integración CI/CD

Verificación Rápida: Se ejecuta en cada PR (pruebas unitarias, linting, importaciones)
Prueba de Integración: Activación manual/semanal con datos reales de API
Prueba Docker: En lanzamientos y validación de despliegue

Para procedimientos de prueba detallados, consulte:

docs/TESTING.md - Guía completa de pruebas
docs/INTEGRATION_TESTING.md - Procedimientos de prueba de integración
scripts/README.md - Documentación de scripts de prueba

Desarrollo Local

# Install in development mode
pip install -e .

# Run with verbose logging
fast-intercom-mcp --verbose status

# Monitor logs in real-time
tail -f ~/.fast-intercom-mcp/logs/fast-intercom-mcp.log

Rendimiento

Métricas de Rendimiento Típicas

Tiempo de Respuesta: <100 ms para consultas en caché
Eficiencia de Almacenamiento: ~2 KB por conversación en promedio
Velocidad de Sincronización: 10-50 conversaciones/segundo
Uso de Memoria: <100 MB para el proceso del servidor

Requisitos de Almacenamiento

Espacio de trabajo pequeño: 100-500 conversaciones, ~5-25 MB
Espacio de trabajo mediano: 1,000-5,000 conversaciones, ~50-250 MB
Espacio de trabajo grande: 10,000+ conversaciones, ~500+ MB

Solución de Problemas

Problemas Comunes

Conexión Fallida

Verifique su token de acceso de Intercom
Compruebe los permisos del token (se requiere lectura de conversaciones)
Prueba: curl -H "Authorization: Bearer YOUR_TOKEN" https://api.intercom.io/me

Base de Datos Bloqueada

Detenga cualquier proceso FastIntercom en ejecución: ps aux | grep fast-intercom-mcp
Verifique el archivo de registro: ~/.fast-intercom-mcp/logs/fast-intercom-mcp.log

Servidor MCP Sin Respuesta

Verifique la sintaxis JSON de la configuración de Claude Desktop
Reinicie Claude Desktop después de los cambios de configuración
Compruebe que el comando fast-intercom-mcp esté disponible en PATH

Modo Depuración

fast-intercom-mcp --verbose start    # Enable verbose logging
export FASTINTERCOM_LOG_LEVEL=DEBUG  # Set debug level

Referencia de API

Herramientas MCP

`search_conversations`

Buscar conversaciones con filtros flexibles.

Parámetros:

query (cadena): Texto para buscar en mensajes de conversación
timeframe (cadena): Rango de tiempo en lenguaje natural ("últimos 7 días", "este mes", etc.)
customer_email (cadena): Filtrar por correo electrónico específico del cliente
limit (entero): Máximo de conversaciones a devolver (predeterminado: 50)

`get_conversation`

Obtener detalles completos de una conversación específica.

Parámetros:

conversation_id (cadena, obligatorio): ID de conversación de Intercom

`get_server_status`

Obtener estado del servidor y estadísticas.

Parámetros: Ninguno

`sync_conversations`

Activar sincronización manual de conversaciones.

Parámetros:

force (booleano): Forzar sincronización completa incluso si existen datos recientes

Contribuciones

Haga un fork del repositorio
Cree una rama de características (git checkout -b feature/amazing-feature)
Confirme sus cambios (git commit -m 'Add amazing feature')
Envíe a la rama (git push origin feature/amazing-feature)
Abra una Solicitud de Extracción (Pull Request)

Licencia

Licencia MIT - consulte el archivo LICENSE para más detalles.

Soporte

Problemas: Problemas de GitHub
Documentación: Este README y documentación de código en línea
Registros: Consulte ~/.fast-intercom-mcp/logs/fast-intercom-mcp.log para información detallada