Serveur MCP FastIntercom

Serveur MCP (Model Context Protocol) haute performance pour l'analyse des conversations Intercom. Il fournit un accès local et rapide aux conversations d'interphonie grâce à une mise en cache intelligente et à une synchronisation en arrière-plan.

Caractéristiques

• accès local rapide: Temps de réponse inférieurs à 100 ms pour les recherches de conversations
• synchronisation intelligente: Les mises à jour en arrière-plan déclenchées par les demandes garantissent des données fraîches
• 💾Stockage efficace: Stockage local basé sur SQLite (~2KB par conversation)
• 🔍 Recherche puissante: Recherche de temps et de texte en langage naturel
• ⚡ Intégration MCP: Intégration directe avec Claude Desktop et les clients MCP

Démarrage rapide

Installation

# Cloner et installer git clone <repository-url> cd fast-intercom-mcp python -m venv venv source venv/bin/activate # Sous Windows : venv\Scripts\activate pip install -e

Setup

# Initialiser avec vos identifiants Intercom fast-intercom-mcp init # Vérifier le statut fast-intercom-mcp status # Synchroniser l'historique des conversations fast-intercom-mcp sync --force --days 7

Intégration de Claude Desktop

Ajoutez à votre configuration 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" } } } }

Utilisation

Commandes CLI

fast-intercom-mcp status # Affiche l'état du serveur et les statistiques fast-intercom-mcp sync # Synchronisation incrémentale des conversations récentes fast-intercom-mcp sync --force --days 7 # Force la synchronisation des 7 derniers jours fast-intercom-mcp start # Démarre le serveur MCP fast-intercom-mcp logs # Affiche les entrées récentes du journal fast-intercom-mcp reset # Réinitialise toutes les données

Outils MCP

Une fois connecté à Claude Desktop, vous pouvez poser des questions telles que :

• "Rechercher les conversations sur la facturation au cours des 7 derniers jours"
• "Montrez-moi les conversations des clients d'hier"
• "Quel est l'état du serveur FastIntercom ?"
• "Obtenir les détails de la conversation pour l'ID 123456789"

Configuration

Variables d'environnement

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

Fichier de configuration

Situé dans ~/.fast-intercom-mcp/config.json:

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

Architecture

Stratégie de synchronisation intelligente

FastIntercom utilise une stratégie de cache sophistiquée :

1. Réponse immédiate: Les requêtes MCP renvoient instantanément les données du cache local
2. Synchronisation en arrière-plan: Les délais périmés déclenchent des mises à jour en arrière-plan
3. Déclencheurs intelligents: Le système s'inspire des modèles de demande pour optimiser la synchronisation
4. Données fraîches: La demande suivante reçoit des données mises à jour par la synchronisation en arrière-plan

Composants

• Base de données: SQLite avec schéma optimisé pour des recherches rapides
• Service de synchronisation: Service d'arrière-plan avec une logique de rafraîchissement intelligente
• Serveur MCP: Mise en œuvre du protocole Model Context
• Interface CLI: Outils de ligne de commande pour la gestion et la surveillance

Développement

Tests

Tests rapides

# Tests unitaires pytest tests/ # Test d'intégration (nécessite une clé API) ./scripts/run_integration_test.sh # Test Docker ./scripts/test_docker_install.sh

Tests complets

# Suite complète de tests unitaires avec couverture pytest tests/ --cov=fast_intercom_mcp # Test d'intégration avec rapport de performance ./scripts/run_integration_test.sh --performance-report # Test d'installation propre de Docker ./scripts/test_docker_install.sh --with-api-test # Benchmarking de performance ./scripts/run_performance_test.sh

Intégration CI/CD

• Vérification rapide: Exécute sur chaque PR (tests unitaires, linting, importations)
• Test d'intégration: Déclenchement manuel/hebdomadaire avec des données API réelles
• Test Docker: Sur les versions et la validation du déploiement

Pour des procédures de test détaillées, voir :

• docs/TESTING.md - Guide de test complet
• docs/INTEGRATION_TESTING.md - Procédures de test d'intégration
• scripts/README.md - Documentation des scripts de test

Développement local

# Installer en mode développement pip install -e . # Exécuter avec la journalisation verbose fast-intercom-mcp --verbose status # Surveiller les logs en temps réel tail -f ~/.fast-intercom-mcp/logs/fast-intercom-mcp.log

Performances

Mesures de performances typiques

• Temps de réponse: <100ms pour les requêtes mises en cache
• Efficacité du stockage: ~2KB par conversation en moyenne
• Vitesse de synchronisation: 10-50 conversations/seconde
• Utilisation de la mémoire: <100MB pour le processus du serveur

Exigences en matière de stockage

• Petit espace de travail: 100-500 conversations, ~5-25 Mo
• Espace de travail moyen: 1,000-5,000 conversations, ~50-250 MB
• Grand espace de travail: 10 000+ conversations, ~500+ MB

Résolution des problèmes

Problèmes courants

Échec de la connexion

• Vérifiez votre jeton d'accès Intercom
• Vérifiez les autorisations du jeton (lecture des conversations requise)
• Test : curl -H "Authorization : Bearer YOUR_TOKEN" https://api.intercom.io/me

Base de données verrouillée

• Arrêter tous les processus FastIntercom en cours : ps aux | grep fast-intercom-mcp
• Vérifier le fichier journal : ~/.fast-intercom-mcp/logs/fast-intercom-mcp.log

Le serveur MCP ne répond pas

• Vérifier la syntaxe JSON de la configuration de Claude Desktop
• Redémarrer Claude Desktop après des changements de configuration
• Vérifier que la commande fast-intercom-mcp est disponible dans le PATH

Mode débogage

fast-intercom-mcp --verbose start # Activer la journalisation verbose export FASTINTERCOM_LOG_LEVEL=DEBUG # Définir le niveau de débogage

Référence API

Outils MCP

search_conversations

Recherche des conversations avec des filtres flexibles.

Paramètres :

• requête (chaîne) : Texte à rechercher dans les messages de la conversation
• délai (chaîne) : Période en langage naturel ("7 derniers jours", "ce mois-ci", etc.)
• customer_email (chaîne) : Filtre sur l'email d'un client spécifique
• limit (entier) : Nombre maximum de conversations à retourner (par défaut : 50)

get_conversation

Obtenir tous les détails d'une conversation spécifique.

Paramètres :

• conversation_id (chaîne, obligatoire) : ID de la conversation d'interphone

get_server_status

Obtenir l'état et les statistiques du serveur.

Paramètres : (obligatoire) : état du serveur et statistiques : Aucun

sync_conversations

Déclenche la synchronisation manuelle des conversations.

Paramètres : aucun

• force (booléen) : Force la synchronisation complète même si des données récentes existent

Contribuer

1. Ouvrir le dépôt
2. Créer une branche de fonctionnalités(git checkout -b feature/amazing-feature)
3. Livrez vos modifications(git commit -m 'Add amazing feature')
4. Pousser vers la branche(git push origin feature/amazing-feature)
5. Ouvrir une demande de retrait (Pull Request)

Licence

Licence MIT - voir le fichier LICENSE pour plus de détails.

Support

• Problèmes: Questions sur GitHub
• Documentation: Ce README et la documentation du code en ligne
• Journaux: Consultez ~/.fast-intercom-mcp/logs/fast-intercom-mcp.log pour des informations détaillées