FastIntercom

Un servidor MCP de alto rendimiento para analizar conversaciones de Intercom con acceso local rápido mediante almacenamiento en caché y sincronización en segundo plano.

GitHubPrueba este MCPPatrocinado

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

Añade a tu 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, puedes hacer preguntas como:

"Busca conversaciones sobre facturación en los últimos 7 días"
"Muéstrame conversaciones de clientes de ayer"
"¿Cuál es el estado del servidor FastIntercom?"
"Obtén los 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
Disparadores Inteligentes: El sistema aprende de los patrones de solicitud 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 Exhaustivas

# 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: Disparador manual/semanal con datos reales de la API
Prueba Docker: En lanzamientos y validación de despliegues

Para procedimientos de prueba detallados, consulta:

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

Verifica tu token de acceso de Intercom
Comprueba 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

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

El Servidor MCP No Responde

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

Modo de Depuración

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

Referencia de la API

Herramientas MCP

`search_conversations`

Busca conversaciones con filtros flexibles.

Parámetros:

query (cadena): Texto para buscar en los mensajes de la 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`

Obtiene los detalles completos de una conversación específica.

Parámetros:

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

`get_server_status`

Obtiene el estado del servidor y estadísticas.

Parámetros: Ninguno

`sync_conversations`

Activa la sincronización manual de conversaciones.

Parámetros:

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

Contribuciones

Haz un fork del repositorio
Crea una rama de funcionalidad (git checkout -b feature/amazing-feature)
Realiza tus cambios (git commit -m 'Add amazing feature')
Sube la rama (git push origin feature/amazing-feature)
Abre una Solicitud de Extracción (Pull Request)

Licencia

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

Soporte

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