mat-drupal-mcp/docs/troubleshooting.md

MatDrupal MCP - AI Assistant for Drupal Projects with bilingual FR/EN support

# 🛠️ Guide de Dépannage - MatDrupal MCP

> **Solutions aux problèmes courants et diagnostic**
> 
> Créé par [Mathieu Boisvert](https://github.com/boisvertmath)

## 🚨 Problèmes d'Installation

### Node.js non détecté

**Symptôme :**
```
node: command not found
```

**Solutions :**

1. **Installer Node.js via le site officiel**
   ```bash
   # Télécharger depuis https://nodejs.org/
   # Choisir la version LTS (18.x ou plus récente)
   ```

2. **Installer via Homebrew (macOS)**
   ```bash
   brew install node
   ```

3. **Installer via gestionnaire de versions**
   ```bash
   # Installer nvm
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
   
   # Redémarrer le terminal puis
   nvm install 18
   nvm use 18
   ```

4. **Vérifier le PATH**
   ```bash
   echo $PATH
   # Ajouter Node.js au PATH si nécessaire
   export PATH="/usr/local/bin:$PATH"
   ```

### Version Node.js incompatible

**Symptôme :**
```
Node.js version 16.x detected, version 18+ required
```

**Solutions :**

1. **Mettre à jour Node.js**
   ```bash
   # Via Homebrew
   brew upgrade node
   
   # Via nvm
   nvm install 20
   nvm use 20
   ```

2. **Vérifier la version active**
   ```bash
   node --version
   which node
   ```

### Erreurs de permissions npm

**Symptôme :**
```
EACCES: permission denied
```

**Solutions :**

1. **Configurer npm pour l'utilisateur**
   ```bash
   mkdir ~/.npm-global
   npm config set prefix '~/.npm-global'
   echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
   source ~/.profile
   ```

2. **Utiliser sudo (non recommandé)**
   ```bash
   sudo npm install -g
   ```

## 🔧 Problèmes de Compilation

### Erreurs TypeScript

**Symptôme :**
```
error TS2307: Cannot find module '@modelcontextprotocol/sdk'
```

**Solutions :**

1. **Réinstaller les dépendances**
   ```bash
   rm -rf node_modules package-lock.json
   npm install
   ```

2. **Vérifier la version TypeScript**
   ```bash
   npx tsc --version
   npm list typescript
   ```

3. **Nettoyer et recompiler**
   ```bash
   npm run clean || rm -rf dist/
   npm run build
   ```

### Compilation vide (dist/index.js vide)

**Symptôme :**
```
dist/index.js contient seulement "export {};"
```

**Solutions :**

1. **Vérifier tsconfig.json**
   ```json
   {
     "compilerOptions": {
       "target": "ES2022",
       "module": "CommonJS",
       "moduleResolution": "node",
       "esModuleInterop": true,
       "allowSyntheticDefaultImports": true
     }
   }
   ```

2. **Reconstruire complètement**
   ```bash
   rm -rf dist/ node_modules/
   npm install
   npm run build
   ```

## 🔌 Problèmes GitHub Copilot

### Serveur MCP non détecté

**Symptôme :**
GitHub Copilot ne reconnaît pas `@matdrupal`

**Solutions :**

1. **Vérifier la configuration MCP**
   ```bash
   cat ~/.config/github-copilot/mcp-config.json
   ```

2. **Reconfigurer automatiquement**
   ```bash
   ./setup.sh
   ```

3. **Configuration manuelle**
   ```json
   {
     "mcpServers": {
       "matdrupal": {
         "command": "node",
         "args": ["/chemin/absolu/vers/mat-drupal-mcp/dist/index.js"],
         "env": {
           "NODE_ENV": "production",
           "LANDO_SUPPORT": "true",
           "ACQUIA_CLI_SUPPORT": "true",
           "MATDRUPAL_MODE": "true",
           "BILINGUAL_MODE": "true"
         },
         "timeout": 90000
       }
     }
   }
   ```

4. **Redémarrer VS Code**
   ```bash
   # Fermer VS Code complètement
   # Rouvrir VS Code
   # Tester @matdrupal dans Copilot Chat
   ```

### Timeout du serveur MCP

**Symptôme :**
```
MCP server timeout after 30 seconds
```

**Solutions :**

1. **Augmenter le timeout**
   ```json
   {
     "mcpServers": {
       "matdrupal": {
         "timeout": 90000
       }
     }
   }
   ```

2. **Optimiser les performances**
   ```bash
   # Variables d'environnement pour améliorer les performances
   export NODE_ENV=production
   export DEBUG_MODE=false
   ```

### Configuration corrompue

**Symptôme :**
Erreurs JSON dans la configuration GitHub Copilot

**Solutions :**

1. **Sauvegarder et nettoyer**
   ```bash
   cp ~/.config/github-copilot/mcp-config.json ~/.config/github-copilot/mcp-config.json.backup
   ```

2. **Valider le JSON**
   ```bash
   cat ~/.config/github-copilot/mcp-config.json | jq .
   ```

3. **Recréer la configuration**
   ```bash
   ./setup.sh --force
   ```

## 🐳 Problèmes Lando

### Lando non détecté

**Symptôme :**
```
Lando command not found
```

**Solutions :**

1. **Installer Lando**
   ```bash
   # Via Homebrew (macOS)
   brew install lando
   
   # Ou télécharger depuis https://lando.dev/
   ```

2. **Vérifier l'installation**
   ```bash
   lando version
   which lando
   ```

3. **Désactiver le support Lando**
   ```bash
   export LANDO_SUPPORT=false
   ```

### Erreurs de permissions Docker

**Symptôme :**
```
Docker daemon connection failed
```

**Solutions :**

1. **Démarrer Docker Desktop**
   ```bash
   open -a Docker
   ```

2. **Vérifier Docker**
   ```bash
   docker --version
   docker ps
   ```

## ☁️ Problèmes Acquia CLI

### Acquia CLI non installé

**Symptôme :**
```
acli: command not found
```

**Solutions :**

1. **Installer Acquia CLI**
   ```bash
   curl -OL https://github.com/acquia/cli/releases/latest/download/acli.phar
   chmod +x acli.phar
   sudo mv acli.phar /usr/local/bin/acli
   ```

2. **Vérifier l'installation**
   ```bash
   acli --version
   ```

3. **Désactiver le support Acquia**
   ```bash
   export ACQUIA_CLI_SUPPORT=false
   ```

### Problèmes d'authentification

**Symptôme :**
```
Acquia CLI authentication failed
```

**Solutions :**

1. **Se connecter à Acquia CLI**
   ```bash
   acli auth:login
   ```

2. **Vérifier les credentials**
   ```bash
   acli auth:info
   ```

## 🔍 Diagnostic Général

### Test de santé complet

```bash
#!/bin/bash
echo "🏥 Diagnostic MatDrupal MCP"
echo "=========================="

# Vérifier Node.js
echo "Node.js: $(node --version 2>/dev/null || echo 'NON INSTALLÉ')"
echo "npm: $(npm --version 2>/dev/null || echo 'NON INSTALLÉ')"

# Vérifier l'installation MatDrupal
if [ -f "dist/index.js" ]; then
    echo "MatDrupal MCP: INSTALLÉ"
    echo "Version: $(node dist/index.js --version 2>/dev/null || echo 'ERREUR')"
else
    echo "MatDrupal MCP: NON INSTALLÉ"
fi

# Vérifier GitHub Copilot config
if [ -f "$HOME/.config/github-copilot/mcp-config.json" ]; then
    echo "Config Copilot: PRÉSENTE"
    echo "Validité JSON: $(cat ~/.config/github-copilot/mcp-config.json | jq . >/dev/null 2>&1 && echo 'VALIDE' || echo 'INVALIDE')"
else
    echo "Config Copilot: ABSENTE"
fi

# Vérifier les outils optionnels
echo "Lando: $(lando version 2>/dev/null || echo 'NON INSTALLÉ')"
echo "Acquia CLI: $(acli --version 2>/dev/null || echo 'NON INSTALLÉ')"

echo ""
echo "🔧 Pour corriger les problèmes:"
echo "   ./setup.sh --fix"
```

### Nettoyage complet

```bash
#!/bin/bash
echo "🧹 Nettoyage complet MatDrupal MCP"

# Sauvegarder la configuration
if [ -f "$HOME/.config/github-copilot/mcp-config.json" ]; then
    cp "$HOME/.config/github-copilot/mcp-config.json" "$HOME/.config/github-copilot/mcp-config.json.backup"
fi

# Nettoyer les fichiers de build
rm -rf dist/ node_modules/ package-lock.json

# Réinstaller
npm install
npm run build

# Reconfigurer
./setup.sh

echo "✅ Nettoyage terminé"
```

### Désinstallation complète

Si rien d'autre ne fonctionne, désinstallez complètement MatDrupal MCP :

```bash
# Désinstallation complète avec sauvegarde automatique
curl -sL https://raw.githubusercontent.com/boisvertmath/mat-drupal-mcp/main/scripts/uninstall.sh | bash

# Puis réinstaller
curl -sL https://raw.githubusercontent.com/boisvertmath/mat-drupal-mcp/main/scripts/install.sh | bash
```

**🔒 Sécurité :** Le script de désinstallation crée une sauvegarde complète avant suppression.

### Logs de debug

```bash
# Activer les logs détaillés
export DEBUG_MODE=true
export NODE_ENV=development

# Tester avec logs
node dist/index.js --test

# Logs GitHub Copilot (VS Code)
# Ouvrir: Help > Toggle Developer Tools > Console
# Chercher: "mcp" ou "matdrupal"
```

## 📞 Obtenir de l'Aide

### Collecter les informations de debug

```bash
#!/bin/bash
echo "📊 Informations de debug MatDrupal MCP"
echo "======================================"
echo "OS: $(uname -a)"
echo "Node.js: $(node --version)"
echo "npm: $(npm --version)"
echo "Répertoire: $(pwd)"
echo "Fichiers dist/: $(ls -la dist/ 2>/dev/null || echo 'Aucun')"
echo ""
echo "Configuration GitHub Copilot:"
cat ~/.config/github-copilot/mcp-config.json 2>/dev/null || echo "Fichier non trouvé"
echo ""
echo "Test du serveur:"
timeout 5s node dist/index.js --test 2>&1 || echo "Erreur ou timeout"
```

### Où demander de l'aide

1. **GitHub Issues** - [Créer une issue](https://github.com/boisvertmath/mat-drupal-mcp/issues)
2. **GitHub Discussions** - [Discussions communautaires](https://github.com/boisvertmath/mat-drupal-mcp/discussions)
3. **Documentation** - [Guides complets](https://github.com/boisvertmath/mat-drupal-mcp/wiki)

### Informations à inclure

- Version de Node.js et npm
- Système d'exploitation
- Messages d'erreur complets
- Configuration GitHub Copilot
- Étapes pour reproduire le problème

---

*Guide de dépannage créé par [Mathieu Boisvert](https://github.com/boisvertmath) pour assurer le bon fonctionnement de MatDrupal MCP.*