SEVYA MCP Server 🚀

Serveur MCP (Model Context Protocol) pour la plateforme SEVYA - Lead tracking et attribution pour consultants marketing.

📋 Description

Ce serveur MCP permet d'interagir avec l'API SEVYA directement depuis Claude ou d'autres clients MCP. Il expose 5 outils puissants pour gérer et analyser vos clients et leads :

• sevya_list_clients - Liste tous vos clients
• sevya_get_client_stats - Statistiques détaillées d'un client
• sevya_list_leads - Liste tous les leads (multi-clients)
• sevya_list_client_leads - Liste les leads d'un client spécifique
• sevya_analyze_lead_performance - Analyse de performance sur période

🔐 Authentification

Important : Chaque utilisateur fournit sa propre clé API SEVYA via les headers HTTP lors de la connexion. Le serveur ne stocke aucune clé API - l'authentification est faite par connexion.

🎯 Fonctionnalités

✅ Transport HTTP/SSE - Déployable sur Railway, Heroku, ou tout service cloud
✅ Filtrage avancé - Par statut, dates, client
✅ Pagination robuste - Gestion de grands volumes de données
✅ Formats multiples - Markdown (humain) ou JSON (machine)
✅ Gestion d'erreurs - Messages clairs et actionnables
✅ Type-safe - TypeScript strict pour fiabilité maximale
✅ Prêt pour production - Validations, limites, troncature

📦 Packages

Ce repository contient plusieurs packages :

• / (root) - Serveur MCP SEVYA principal (déployé sur Railway)
• packages/mcp-client/ - Package npm @sevya/mcp-client pour intégration facile

Utilisation Simple (Recommandée)

Pour les utilisateurs finaux, utilisez le package npm plug & play :

{
  "mcpServers": {
    "sevya": {
      "command": "npx",
      "args": ["-y", "sevya-mcp-client"],
      "env": {
        "SEVYA_API_KEY": "votre_clé_api_sevya"
      }
    }
  }
}

🔧 Installation et Déploiement

Prérequis

• Node.js >= 18
• npm ou yarn
• Un service d'hébergement (Railway, Heroku, etc.)
• Chaque utilisateur doit avoir sa propre clé API SEVYA

Déploiement du Serveur

# 1. Cloner ou télécharger le projet
cd sevya-mcp-server

# 2. Installer les dépendances
npm install

# 3. Configurer les variables d'environnement (optionnel)
export PORT=3000  # Défaut: 3000
export SEVYA_API_BASE_URL="https://api.sevya.fr/api"  # URL API custom

# 4. Compiler TypeScript
npm run build

# 5. Lancer le serveur
npm start

Note : Aucune clé API n'est requise pour démarrer le serveur. Les utilisateurs fourniront leur clé lors de la connexion.

Développement

# Mode développement avec hot-reload
npm run dev

👤 Configuration Utilisateur

Option 1 : Installation Simple (Recommandée)

Les utilisateurs ajoutent simplement ceci à leur claude_desktop_config.json :

{
  "mcpServers": {
    "sevya": {
      "command": "npx",
      "args": ["-y", "sevya-mcp-client"],
      "env": {
        "SEVYA_API_KEY": "votre_clé_api_sevya"
      }
    }
  }
}

Avantages :

• ✅ Plug & Play - Pas d'installation locale requise
• ✅ Auto-update - Utilise toujours la dernière version
• ✅ Simple - Juste copier-coller avec la clé API

Option 2 : Installation Manuelle (Avancée)

Pour les utilisateurs qui préfèrent gérer l'installation localement :

1. Cloner le repository :

git clone https://github.com/cvescan/sevya-mcp.git
cd sevya-mcp
npm install
npm run build

2. Configuration dans claude_desktop_config.json :

macOS/Linux

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Contenu du fichier

{
  "mcpServers": {
    "sevya": {
      "command": "node",
      "args": ["/path/to/sevya-mcp/packages/mcp-client/dist/index.js"],
      "env": {
        "SEVYA_API_KEY": "votre_clé_api_sevya"
      }
    }
  }
}

Note : Remplacez /path/to/sevya-mcp par le chemin complet vers votre installation.

📦 Package NPM

Le package sevya-mcp-client est publié sur npm : https://www.npmjs.com/package/sevya-mcp-client

🌐 Endpoints du Serveur

Le serveur SEVYA MCP (déployé sur https://mcp.sevya.fr) expose :

• GET / - Informations sur le serveur et liste des outils
• GET /health - Health check
• POST /mcp - Endpoint MCP Streamable HTTP - Requiert header X-API-Key
• GET /sse - Endpoint MCP Server-Sent Events - Requiert header X-API-Key

Exemple d'utilisation :

# Health check
curl https://mcp.sevya.fr/health

# Info serveur
curl https://mcp.sevya.fr/

# Test avec clé API
curl -H "X-API-Key: votre_clé_api" https://mcp.sevya.fr/sse

📚 Documentation des Outils

1. sevya_list_clients

Liste tous les clients rattachés à votre compte master.

Paramètres :

• response_format (optionnel) : "markdown" ou "json"

Exemple d'usage :

"Liste tous mes clients SEVYA"

2. sevya_get_client_stats

Obtient des statistiques détaillées pour un client spécifique.

Paramètres :

• client_id (requis) : ID du client
• response_format (optionnel) : "markdown" ou "json"

Retourne :

• Total de leads
• Répartition par statut
• Valeur totale et moyenne
• Taux de conversion
• Leads récents (30 jours)

Exemple d'usage :

"Donne-moi les stats du client ABC123"

3. sevya_list_leads

Liste tous les leads de tous les clients avec filtrage avancé.

Paramètres :

• page (optionnel, défaut: 1) : Numéro de page
• limit (optionnel, défaut: 20, max: 100) : Résultats par page
• status (optionnel) : "nouveau", "gagne", "perdu", "en_cours", "qualifie"
• created_after (optionnel) : Date YYYY-MM-DD
• created_before (optionnel) : Date YYYY-MM-DD
• response_format (optionnel) : "markdown" ou "json"

Exemple d'usage :

"Montre-moi les leads gagnés en novembre 2024"
→ status="gagne", created_after="2024-11-01", created_before="2024-11-30"

4. sevya_list_client_leads

Liste les leads d'un client spécifique avec filtrage.

Paramètres :

• client_id (requis) : ID du client
• Tous les paramètres de sevya_list_leads

Exemple d'usage :

"Liste les nouveaux leads du client XYZ"
→ client_id="XYZ", status="nouveau"

5. sevya_analyze_lead_performance

Analyse agrégée de performance des leads sur une période.

Paramètres :

• client_id (optionnel) : Filtrer par client
• date_from (optionnel) : Date de début YYYY-MM-DD
• date_to (optionnel) : Date de fin YYYY-MM-DD
• response_format (optionnel) : "markdown" ou "json"

Retourne :

• Métriques globales
• Répartition par statut
• Taux de conversion
• Insights automatiques

Exemple d'usage :

"Analyse de performance du Q3 2024"
→ date_from="2024-07-01", date_to="2024-09-30"

🚀 Déploiement sur Railway

1. Configuration Railway

# Créer un nouveau projet Railway
railway init

# Optionnel : Définir l'URL de l'API SEVYA si différente
railway variables set SEVYA_API_BASE_URL="https://api.sevya.fr/api"

# Déployer
railway up

2. Configuration automatique

Railway détectera automatiquement :

• Node.js (package.json)
• Build command : npm run build
• Start command : npm start
• Port depuis $PORT

3. Variables d'environnement

Dans Railway Dashboard → Variables :

• PORT : Fourni automatiquement par Railway
• SEVYA_API_BASE_URL : (Optionnel) URL custom de l'API SEVYA

Note : Plus besoin de SEVYA_API_KEY sur le serveur ! Chaque utilisateur fournit sa clé.

4. URL de déploiement

Railway fournira une URL comme :

https://sevya-mcp-server-production.up.railway.app

Avec domaine personnalisé configuré :

https://mcp.sevya.fr

❓ FAQ

Quelle méthode d'installation recommander aux utilisateurs ?

Recommandez l'Option 1 (npx) car :

• ✅ Aucune installation locale requise
• ✅ Toujours la dernière version
• ✅ Configuration ultra-simple (copy-paste)

Comment obtenir une clé API SEVYA ?

Chaque utilisateur doit avoir sa propre clé API depuis son tableau de bord SEVYA.

Puis-je utiliser le serveur distant directement ?

Non, Claude Desktop ne supporte que les connexions locales (stdio). Le package sevya-mcp-client fait le pont entre Claude Desktop et le serveur distant.

Le serveur stocke-t-il les clés API ?

Non, le serveur ne stocke aucune clé API. Chaque connexion fournit sa propre clé via les headers HTTP.

Endpoints disponibles :

• https://mcp.sevya.fr/health
• https://mcp.sevya.fr/mcp (requiert X-API-Key header)

🔒 Sécurité

Architecture Sécurisée

✅ Authentification par connexion - Chaque utilisateur utilise sa propre clé API
✅ Pas de clé stockée - Le serveur ne stocke aucune clé API
✅ Isolation des données - Chaque connexion accède uniquement à ses propres données
✅ Validation à la connexion - La clé API est validée avant d'établir la connexion SSE
✅ HTTPS recommandé - Utilisez HTTPS en production pour protéger les clés API en transit

Bonnes pratiques pour les utilisateurs

1. Ne jamais partager votre clé API SEVYA
2. Utiliser HTTPS - Toujours se connecter via HTTPS (https://)
3. Régénérer votre clé API si compromise
4. Vérifier que la clé est dans le fichier de config local, pas dans le code

Variables d'environnement (Serveur)

Le serveur n'a besoin que de variables optionnelles :

PORT=3000  # Optionnel, défaut: 3000
SEVYA_API_BASE_URL=https://api.sevya.fr/api  # Optionnel

Note : Aucune clé API n'est nécessaire côté serveur !

📊 Monitoring

Logs

Le serveur log automatiquement :

• Démarrage et validation API
• Connexions SSE
• Messages MCP reçus
• Erreurs

Health Check

curl https://mcp.sevya.fr/health

Retourne :

{
  "status": "healthy",
  "server": "sevya-mcp-server",
  "version": "1.0.0",
  "timestamp": "2024-11-06T13:30:00.000Z"
}

🐛 Troubleshooting

Erreur : "Missing X-API-Key header"

Solution : Vérifier la configuration dans claude_desktop_config.json

{
  "mcpServers": {
    "sevya": {
      "url": "https://mcp.sevya.fr/mcp",
      "apiKey": "votre_cle_api_ici"
    }
  }
}

Erreur : "Authentication failed" ou "Invalid API key"

Solutions :

1. Vérifier que votre clé API SEVYA est correcte
2. Vérifier qu'il n'y a pas d'espaces avant/après la clé
3. Tester la clé avec un curl :

curl -H "Authorization: Bearer VOTRE_CLE" https://api.sevya.fr/api/clients

Erreur : "Cannot connect to SEVYA API"

Solutions :

1. Vérifier la connexion internet
2. Vérifier que l'URL de l'API est accessible
3. Vérifier les logs du serveur Railway

Le serveur ne démarre pas localement

Solution : Vérifier que le port n'est pas déjà utilisé

export PORT=3001
npm start

🛠️ Développement

Structure du projet

sevya-mcp-server/
├── src/
│   ├── index.ts           # Point d'entrée HTTP/SSE
│   ├── constants.ts       # Constantes globales
│   ├── types.ts           # Interfaces TypeScript
│   ├── schemas/
│   │   └── input.ts       # Schémas Zod de validation
│   ├── services/
│   │   ├── api.ts         # Client API SEVYA
│   │   └── formatter.ts   # Formatage réponses
│   └── tools/
│       ├── clients.ts     # Outils clients
│       └── leads.ts       # Outils leads
├── dist/                  # Code compilé
├── package.json
├── tsconfig.json
└── README.md

Ajouter un nouvel outil

1. Créer le schéma Zod dans src/schemas/input.ts
2. Ajouter la fonction tool dans src/tools/
3. Enregistrer le tool dans src/index.ts
4. Rebuild : npm run build

Tests

# Compiler
npm run build

# Vérifier que le serveur démarre
npm start

# Dans un autre terminal, tester health
curl http://localhost:3000/health

📝 License

MIT

👤 Auteur

Cyril - Consultant Marketing Digital & SEO

• Plateforme : Visible Ici
• SEVYA : Lead tracking & attribution platform

🤝 Support

Pour toute question ou problème :

1. Vérifier la documentation ci-dessus
2. Consulter les logs du serveur
3. Contacter le support SEVYA

🎉 Merci d'utiliser SEVYA MCP Server !