@referencime/mcp-server

🚀 Easy Links MCP Server

Serveur MCP centralisé pour l'analyse SEO avec Claude Desktop

Transformez vos données Easy Links en puissants outils d'analyse SEO directement accessibles dans Claude Desktop, sans aucune installation technique pour l'utilisateur final.

🎯 Vue d'ensemble

Ce serveur MCP centralisé permet aux utilisateurs d'Easy Links d'analyser leurs données SEO directement dans Claude Desktop via 5 outils d'analyse avancés :

• 🔍 Analyse complète de mots-clés - Performance, volume, GSC, tendances
• 📈 Évolution des positions - Historique et analyse des changements SERP
• ⚖️ Comparaison de mots-clés - Analyse comparative multi-mots-clés
• 📊 Résumé site web - Vue d'ensemble des performances SEO
• 🚨 Détection de changements - Alertes sur les variations de positions

🏗️ Architecture

Claude Desktop → WebSocket MCP → Serveur Centralisé → API WordPress → Base de données Easy Links

Avantages de cette architecture :

• ✅ Zéro installation utilisateur - Simple configuration JSON dans Claude Desktop
• ✅ Centralisé et scalable - Un seul serveur pour tous les utilisateurs
• ✅ Sécurisé - Authentification JWT avec rate limiting
• ✅ Performant - Cache intelligent et connexions optimisées
• ✅ Monitored - Logs détaillés et métriques de performance

🛠️ Installation et Déploiement

Prérequis

• Node.js 18+
• Plugin Easy Links installé sur WordPress
• Serveur o2switch ou compatible Node.js

1. Installation des dépendances

cd mcp.referencime.fr
npm install

2. Configuration

Copiez le fichier d'exemple et configurez :

cp .env.example .env

Éditez .env :

PORT=3000
NODE_ENV=production

# WordPress API Configuration
WORDPRESS_API_URL=https://referencime.fr/wp-json/easy-links/v1
JWT_SECRET=your-super-secret-jwt-key-here

# Rate Limiting (1000 requêtes/jour par utilisateur)
RATE_LIMIT_REQUESTS_PER_DAY=1000
RATE_LIMIT_WINDOW_MS=86400000

# Logging
LOG_LEVEL=info
LOG_FILE=logs/mcp-server.log

# CORS et Security
ALLOWED_ORIGINS=*
TRUST_PROXY=true

3. Démarrage

# Production
npm start

# Développement avec auto-reload
npm run dev

# Test de connexion
npm test

4. Vérification

Le serveur devrait être accessible sur :

• API REST : https://mcp.referencime.fr/api/test
• WebSocket MCP : wss://mcp.referencime.fr/mcp
• Client MCP : https://mcp.referencime.fr/client.js

🔧 Configuration Claude Desktop

Pour l'utilisateur final (super simple) :

• Générer la clé API dans Easy Links → Paramètres → API
• Ajouter cette configuration dans Claude Desktop :

{
  "mcpServers": {
    "easy-links": {
      "command": "node",
      "args": ["-e", "require('https://mcp.referencime.fr/client.js')"],
      "env": {
        "EASY_LINKS_API_KEY": "VOTRE_CLE_API_ICI"
      }
    }
  }
}

• Redémarrer Claude Desktop
• C'est tout ! Les outils SEO sont maintenant disponibles

Test rapide :

Dans Claude Desktop :

"Peux-tu analyser les performances du mot-clé 'référencement' pour mon site ?"

📚 Documentation API

Outils MCP Disponibles

1. analyze_keyword_performance

Analyse complète d'un mot-clé avec métriques détaillées.

Paramètres :

• keyword (string) - Le mot-clé à analyser
• website_id (number) - ID du site web dans Easy Links

Exemple d'utilisation :

// Via Claude Desktop (automatique)
"Analyse les performances du mot-clé 'seo' pour le site 1"

// Via API REST (test)
POST /api/tools/analyze-keyword
{
  "keyword": "seo",
  "website_id": 1
}

2. get_position_evolution

Évolution des positions d'un mot-clé sur une période donnée.

Paramètres :

• keyword (string) - Le mot-clé
• website_id (number) - ID du site web
• period (string, optionnel) - Période (7days, 30days, 90days)

3. compare_keywords_performance

Compare les performances de 2 à 10 mots-clés.

Paramètres :

• keywords (array) - Liste des mots-clés (2-10)
• website_id (number) - ID du site web

4. get_website_performance_summary

Résumé global des performances SEO d'un site.

Paramètres :

• website_id (number) - ID du site web
• period (string, optionnel) - Période d'analyse

5. detect_ranking_changes

Détecte les changements significatifs de positions.

Paramètres :

• website_id (number) - ID du site web
• days (number, optionnel) - Nombre de jours à analyser (défaut: 7)
• threshold (number, optionnel) - Seuil de changement (défaut: 3)

Endpoints REST (pour tests et administration)

• GET /api/test - Test de connectivité
• GET /api/tools - Liste des outils disponibles
• POST /api/auth/validate - Test d'authentification
• GET /api/admin/mcp-stats - Statistiques du serveur
• GET /api/test/wordpress-connection - Test connexion WordPress

🔒 Sécurité et Rate Limiting

Authentification

• JWT Bearer tokens fournis par l'API WordPress Easy Links
• Cache intelligent pour éviter la surcharge (5 min de TTL)
• Validation en temps réel des abonnements utilisateur

Rate Limiting

• 1000 requêtes/jour par utilisateur
• Compteurs par utilisateur avec reset automatique
• Headers informatifs sur l'utilisation restante
• Nettoyage automatique des anciens compteurs

Monitoring et Logs

• Logs détaillés avec rotation automatique (Winston)
• Métriques de performance pour chaque outil
• Alertes automatiques en cas d'erreur
• Statistiques d'utilisation par utilisateur

🚀 Architecture Technique

Structure du Projet

mcp.referencime.fr/
├── server.js                 # Serveur principal Express + WebSocket
├── package.json              # Dépendances et scripts
├── .env.example              # Configuration exemple
├── src/
│   ├── mcp-server.js         # Serveur MCP avec gestion WebSocket
│   ├── client.js             # Client MCP pour Claude Desktop
│   ├── auth/
│   │   └── middleware.js     # Authentification JWT
│   ├── utils/
│   │   ├── logger.js         # Système de logs
│   │   └── rate-limiter.js   # Rate limiting par utilisateur
│   ├── api/
│   │   ├── wordpress-client.js # Client API WordPress
│   │   └── routes.js         # Routes REST pour tests
│   └── tools/                # 5 outils d'analyse SEO
│       ├── analyze-keyword-performance.js
│       ├── get-position-evolution.js
│       ├── compare-keywords-performance.js
│       ├── get-website-performance-summary.js
│       └── detect-ranking-changes.js
└── logs/                     # Logs automatiques

Technologies Utilisées

• Node.js + Express - Serveur web et API REST
• WebSocket (ws) - Protocole MCP temps réel
• Axios - Client HTTP pour WordPress
• Winston - Logging avancé
• JWT - Authentification sécurisée
• Helmet + CORS - Sécurité web

📊 Monitoring et Maintenance

Logs Disponibles

• logs/mcp-server.log - Logs généraux
• logs/error.log - Erreurs uniquement
• logs/exceptions.log - Exceptions non gérées

Métriques Surveillées

• Connexions WebSocket actives
• Taux d'authentification
• Performance des outils (durée d'exécution)
• Utilisation du rate limiting
• Erreurs API WordPress

Commandes Utiles

# Voir les logs en temps réel
tail -f logs/mcp-server.log

# Stats de performance
curl https://mcp.referencime.fr/api/admin/mcp-stats

# Test de santé complet
curl https://mcp.referencime.fr/health

# Redémarrage graceful
pm2 restart mcp-easy-links

🛠️ Développement et Tests

Scripts Disponibles

npm run dev      # Développement avec nodemon
npm start        # Production
npm test         # Test de connexion

Tests des Outils

# Test direct d'un outil
node -e "
const tool = require('./src/tools/analyze-keyword-performance');
tool({ keyword: 'seo', website_id: 1, apiKey: 'test' }, { userId: 1 })
  .then(console.log)
  .catch(console.error);
"

# Test via API REST
curl -X POST https://mcp.referencime.fr/api/tools/analyze-keyword \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"seo","website_id":1}'

🐛 Dépannage

Problèmes Courants

1. Erreur de connexion WebSocket

# Vérifier que le serveur écoute sur le bon port
netstat -tulpn | grep :3000

2. Authentification échoue

# Tester la connectivité WordPress
curl https://mcp.referencime.fr/api/test/wordpress-connection

3. Rate limit dépassé

# Voir les stats de rate limiting
curl https://mcp.referencime.fr/api/admin/rate-limit-stats

Logs de Debug

Activez le debug en modifiant .env :

LOG_LEVEL=debug
NODE_ENV=development

📞 Support

• Documentation : Ce README
• Issues : GitHub Issues du projet Easy Links
• Contact : [e-mail]

🔄 Roadmap

Version 1.1 (Prochaine)

• Dashboard web d'administration
• Métriques Prometheus/Grafana
• Support de multiples serveurs WordPress
• API GraphQL complémentaire

Version 1.2

• Outils d'analyse concurrentielle
• Intégration Google Analytics 4
• Alertes email automatiques
• Export des données en CSV/Excel

🎉 Conclusion

Ce serveur MCP centralisé révolutionne l'utilisation d'Easy Links en permettant une analyse SEO naturelle et puissante directement dans Claude Desktop, sans aucune complexité technique pour l'utilisateur final.

Architecture : Serveur centralisé scalable
Sécurité : JWT + Rate limiting
Performance : Cache intelligent + logs détaillés
Simplicité : Configuration JSON unique dans Claude Desktop

Prêt pour la production ! 🚀