Servidor MCP de FastIntercom

Servidor MCP (Model Context Protocol) de alto rendimiento para el análisis de conversaciones de interfonía. Proporciona un acceso rápido y local a las conversaciones de interfonía mediante el almacenamiento inteligente en caché y la 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: Las actualizaciones en segundo plano activadas por petición garantizan datos frescos
• almacenamiento eficiente: Almacenamiento local basado en SQLite (~2 KB por conversación)
• 🔍 Potente búsqueda: Plazos 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

# Clonar e instalar git clone <repository-url> cd fast-intercom-mcp python -m venv venv source venv/bin/activate # En Windows: venv\Scripts\activate pip install -e

Configurar

# Inicializa con tus credenciales de Intercom fast-intercom-mcp init # Comprueba el estado fast-intercom-mcp status # Sincroniza el historial de conversaciones fast-intercom-mcp sync --force --days 7

Integración con Claude Desktop

Añada 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 # Mostrar estado y estadísticas del servidor fast-intercom-mcp sync # Sincronización incremental de conversaciones recientes fast-intercom-mcp sync --force --days 7 # Forzar sincronización últimos 7 días fast-intercom-mcp start # Iniciar servidor MCP fast-intercom-mcp logs # Ver entradas de registro recientes fast-intercom-mcp reset # Restablecer todos los datos

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 para el ID 123456789"

Configuración

Variables de entorno

INTERCOM_ACCESS_TOKEN=su_token_aquí 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 sofisticada estrategia de almacenamiento en caché:

1. Respuesta inmediata: Las peticiones MCP devuelven datos instantáneamente desde la caché local
2. Sincronización en segundo plano: Los datos antiguos se actualizan en segundo plano
3. Disparadores inteligentes: El sistema aprende de los patrones de solicitud para optimizar el tiempo de sincronización
4. Datos frescos: La siguiente solicitud recibe 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 supervisión

Desarrollo

Pruebas

Pruebas rápidas

# Pruebas unitarias pytest tests/ Pruebas de integración (requiere clave API) ./scripts/run_integration_test.sh Pruebas Docker ./scripts/test_docker_install.sh

Pruebas completas

# Conjunto completo de pruebas unitarias con cobertura pytest tests/ --cov=fast_intercom_mcp # Prueba de integración con informe de rendimiento ./scripts/run_integration_test.sh --performance-report # Prueba de instalación limpia de Docker ./scripts/test_docker_install.sh --with-api-test # Evaluación comparativa del rendimiento ./scripts/run_performance_test.sh

Integración CI/CD

• Comprobación rápida: Se ejecuta en cada PR (pruebas unitarias, linting, importaciones)
• Pruebade integración: Disparo manual/semanal con datos reales de la API
• Prueba Docker: En lanzamientos y validación de despliegue

Para conocer los procedimientos de prueba detallados, consulte

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

Desarrollo local

# Instalar en modo desarrollo pip install -e . # Ejecutar con registro detallado fast-intercom-mcp --verbose status # Monitorizar registros en tiempo real 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 de media
• 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

Fallo de conexión

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

Base de datos bloqueada

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

El servidor MCP no responde

• 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 Debug

fast-intercom-mcp --verbose start # Activar el registro detallado export FASTINTERCOM_LOG_LEVEL=DEBUG # Establecer el nivel de depuración

Referencia API

Herramientas MCP

buscar_conversaciones

Buscar conversaciones con filtros flexibles.

Parámetros:

• query (cadena): Texto a buscar en los mensajes de la conversación
• timeframe (cadena): Marco temporal en lenguaje natural ("últimos 7 días", "este mes", etc.)
• customer_email (cadena): Filtro por correo electrónico específico del cliente
• limit (entero): Máximo de conversaciones a devolver (por defecto: 50)

get_conversation

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

Parámetros:

• conversation_id (cadena, obligatorio): ID de la conversación de interfonía

get_server_status

Obtiene el estado y las estadísticas del servidor.

Parámetros: Ninguno

sync_conversations

Activa la sincronización manual de conversaciones.

Parámetros:

• force (booleano): Forzar la sincronización completa aunque existan datos recientes

Contribuir

1. Abrir el repositorio
2. Crea una rama(git checkout -b feature/amazing-feature)
3. Confirma tus cambios(git commit -m 'Añadir característica sorprendente')
4. Empuja a la rama(git push origin feature/amazing-feature)
5. Abrir una Pull Request

Licencia

Licencia MIT - ver archivo LICENSE para más detalles.

Soporte

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