# Guide de débogage du serveur MCP

Ce guide décrit les techniques de débogage spécifiques aux serveurs MCP (Model Context Protocol) lors de l’utilisation du KIT DE développement logiciel (SDK) Copilot.

<!-- markdownlint-disable GHD046 GHD005 -->

<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->

## Table des matières

* [Diagnostics rapides](#quick-diagnostics)
* [Test des serveurs MCP indépendamment](#testing-mcp-servers-independently)
* [Problèmes courants](#common-issues)
* [Problèmes spécifiques à la plateforme](#platform-specific-issues)
* [Débogage avancé](#advanced-debugging)

## Diagnostics rapides

### Liste de vérification

Avant de plonger en profondeur, vérifiez ces principes de base :

* [ ] Le fichier exécutable du serveur MCP existe et peut être exécuté
* [ ] Chemin de commande correct (utilisez des chemins absolus en cas de doute)
* [ ] Les outils sont activés (`tools: ["*"]` ou noms d’outils spécifiques)
* [ ] Le serveur implémente correctement le protocole MCP (répond à `initialize`)
* [ ] Aucun pare-feu/antivirus bloquant le processus (Windows)

### Activer la journalisation du débogage MCP

Ajoutez des variables d’environnement à votre configuration de serveur MCP :

```typescript
mcpServers: {
  "my-server": {
    type: "local",
    command: "/path/to/server",
    args: [],
    env: {
      MCP_DEBUG: "1",
      DEBUG: "*",
      NODE_DEBUG: "mcp",  // For Node.js MCP servers
    },
  },
}
```

## Test des serveurs MCP indépendamment

Testez toujours votre serveur MCP en dehors du Kit de développement logiciel (SDK) en premier.

### Test manuel du protocole

Envoyez une `initialize` demande via stdin :

```bash
# Unix/macOS
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | /path/to/your/mcp-server

# Windows (PowerShell)
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | C:\path\to\your\mcp-server.exe
```

**Réponse attendue :**

```json
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"your-server","version":"1.0"}}}
```

### Liste des outils de test

Après l’initialisation, demandez la liste des outils :

```bash
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | /path/to/your/mcp-server
```

**Réponse attendue :**

```json
{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"my_tool","description":"Does something","inputSchema":{...}}]}}
```

### Script de test interactif

Créez un script de test pour déboguer de manière interactive votre serveur MCP :

```bash
#!/bin/bash
# test-mcp.sh

SERVER="$1"

# Initialize
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

# Send initialized notification
echo '{"jsonrpc":"2.0","method":"notifications/initialized"}'

# List tools
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# Keep stdin open
cat
```

Utilisation :

```bash
./test-mcp.sh | /path/to/mcp-server
```

## Problèmes courants

### Le serveur ne démarre pas

**Symptômes:** Aucun outil n’apparaît, aucune erreur n'est consignée.

**Causes & Solutions :**

| Cause                                | Solution                                             |
| ------------------------------------ | ---------------------------------------------------- |
| Chemin d’accès de commande incorrect | Utilisez le chemin absolu : `/usr/local/bin/server`  |
| Autorisation exécutable manquante    | Exécutez `chmod +x /path/to/server`                  |
| Dépendances manquantes               | Vérifier avec `ldd` (Linux) ou exécuter manuellement |
| Problèmes de répertoire de travail   | Définir `cwd` dans la configuration                  |

**Déboguer en exécutant manuellement :**

```bash
# Run exactly what the SDK would run
cd /expected/working/dir
/path/to/command arg1 arg2
```

### Le serveur démarre, mais les outils n’apparaissent pas

**Symptômes:** Le processus serveur s’exécute, mais aucun outil n’est disponible.

**Causes & Solutions :**

1. **Outils non activés dans la configuration :**

   ```typescript
   mcpServers: {
     "server": {
       // ...
       tools: ["*"],  // Must be "*" or list of tool names
     },
   }
   ```

2. **Le serveur n’expose pas les outils :**
   * Tester la requête manuellement avec `tools/list`
   * Check Server implémente la `tools/list` méthode

3. **Échec de la négociation d’initialisation :**
   * Le serveur doit répondre à `initialize` correctement
   * Le serveur doit gérer `notifications/initialized`

### Outils répertoriés mais jamais appelés

**Symptômes:** Les outils apparaissent dans les journaux de débogage, mais le modèle ne les utilise pas.

**Causes & Solutions :**

1. **L’invite n’a pas besoin clairement de l’outil :**

   ```typescript
   // Too vague
   await session.sendAndWait({ prompt: "What's the weather?" });

   // Better - explicitly mentions capability
   await session.sendAndWait({ 
     prompt: "Use the weather tool to get the current temperature in Seattle" 
   });
   ```

2. **La description de l’outil n’est pas claire :**

   ```typescript
   // Bad - model doesn't know when to use it
   { name: "do_thing", description: "Does a thing" }

   // Good - clear purpose
   { name: "get_weather", description: "Get current weather conditions for a city. Returns temperature, humidity, and conditions." }
   ```

3. **Problèmes de schéma d’outil :**
   * Vérifier qu’il s’agit `inputSchema` d’un schéma JSON valide
   * Les champs obligatoires doivent être dans le `required` tableau

### Erreurs de délai d’expiration

**Symptômes:**`MCP tool call timed out` Erreurs.

**Solutions :**

1. **Augmentez le délai d’expiration :**

   ```typescript
   mcpServers: {
     "slow-server": {
       // ...
       timeout: 300000,  // 5 minutes
     },
   }
   ```

2. **Optimiser les performances du serveur :**
   * Ajouter une journalisation de l’avancement pour identifier un goulot d’étranglement
   * Envisager des opérations asynchrones
   * Recherchez tout blocage I/O

3. **Pour les outils de longue durée**, envisagez de diffuser des réponses en continu si elles sont prises en charge.

### erreurs de JSON-RPC

**Symptômes:** Erreurs d’analyse, erreurs de requête non valides.

**Causes courantes :**

1. **Les écritures du serveur dans stdout sont incorrectes :**
   * Sortie de débogage redirigée vers stdout au lieu de stderr
   * Nouvelles lignes ou espaces blancs supplémentaires
   ```typescript
   // Wrong - pollutes stdout
   console.log("Debug info");

   // Correct - use stderr for debug
   console.error("Debug info");
   ```

2. **Problèmes d’encodage :**
   * Vérifier l’encodage UTF-8
   * Sans BOM (indicateur d’ordre des octets)

3. **Trame de message :**
   * Chaque message doit être un objet JSON complet
   * Délimité par nouvelle ligne (un message par ligne)

## Problèmes spécifiques à la plateforme

### Windows

#### Applications console / outils .NET

```csharp
// Correct configuration for .NET exe
["my-dotnet-server"] = new McpStdioServerConfig
{
    Command = @"C:\Tools\MyServer\MyServer.exe",  // Full path with .exe
    Args = new List<string>(),
    WorkingDirectory = @"C:\Tools\MyServer",  // Set working directory
    Tools = new List<string> { "*" },
}

// For dotnet tool (DLL)
["my-dotnet-tool"] = new McpStdioServerConfig
{
    Command = "dotnet",
    Args = new List<string> { @"C:\Tools\MyTool\MyTool.dll" },
    WorkingDirectory = @"C:\Tools\MyTool",
    Tools = new List<string> { "*" },
}
```

#### commandes npx

```csharp
// Windows needs cmd /c for npx
["filesystem"] = new McpStdioServerConfig
{
    Command = "cmd",
    Args = new List<string> { "/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\allowed\\path" },
    Tools = new List<string> { "*" },
}
```

#### Problèmes de chemin d’accès

* Utiliser des chaînes brutes (`@"C:\path"`) ou des barres obliques (`"C:/path"`)
* Éviter les espaces dans les chemins lorsque cela est possible
* Si des espaces sont nécessaires, assurez-vous d’utiliser les guillemets appropriés

#### Antivirus/pare-feu

Windows Defender ou d’autres AV peuvent bloquer :

* Nouveaux exécutables
* Processus de communication via stdin/stdout

**Solution:** Ajoutez des exclusions pour votre exécutable de serveur MCP.

### macOS

#### Blocage par Gatekeeper

```bash
# If the server is blocked
xattr -d com.apple.quarantine /path/to/mcp-server
```

#### Chemins d’accès Homebrew

```typescript
// GUI apps may not have /opt/homebrew in PATH
mcpServers: {
  "my-server": {
    command: "/opt/homebrew/bin/node",  // Full path
    args: ["/path/to/server.js"],
  },
}
```

### Linux

#### Problèmes d’autorisation

```bash
chmod +x /path/to/mcp-server
```

#### Bibliothèques partagées manquantes

```bash
# Check dependencies
ldd /path/to/mcp-server

# Install missing libraries
apt install libfoo  # Debian/Ubuntu
yum install libfoo  # RHEL/CentOS
```

## Débogage avancé

### Capturer tout le trafic MCP

Créez un script wrapper pour journaliser toutes les communications :

```bash
#!/bin/bash
# mcp-debug-wrapper.sh

LOG="./mcp-debug-$(date +%s).log"
ACTUAL_SERVER="$1"
shift

echo "=== MCP Debug Session ===" >> "$LOG"
echo "Server: $ACTUAL_SERVER" >> "$LOG"
echo "Args: $@" >> "$LOG"
echo "=========================" >> "$LOG"

# Tee stdin/stdout to log file
tee -a "$LOG" | "$ACTUAL_SERVER" "$@" 2>> "$LOG" | tee -a "$LOG"
```

Utilisez-le :

```typescript
mcpServers: {
  "debug-server": {
    command: "/path/to/mcp-debug-wrapper.sh",
    args: ["/actual/server/path", "arg1", "arg2"],
  },
}
```

### Inspecter avec l’inspecteur MCP

Utilisez l’outil d’inspecteur MCP officiel :

```bash
npx @modelcontextprotocol/inspector /path/to/your/mcp-server
```

Cela fournit une interface utilisateur web pour :

* Envoyer des demandes de test
* Afficher les réponses
* Inspecter les schémas d’outil

### Incompatibilités de version du protocole

Vérifiez que votre serveur prend en charge la version du protocole utilisée par le Kit de développement logiciel (SDK) :

```json
// In initialize response, check protocolVersion
{"result":{"protocolVersion":"2024-11-05",...}}
```

Si les versions ne correspondent pas, mettez à jour votre bibliothèque de serveurs MCP.

## Liste de vérification du débogage

Lors de l’ouverture d’une issue ou d’une demande d’aide, collectez :

* [ ] Langue et version du Kit de développement logiciel (SDK)
* [ ] Version de CLI (`copilot --version`)
* [ ] Type de serveur MCP (Node.js, Python, .NET, Go, Rust, etc.)
* [ ] Configuration complète du serveur MCP (secrets rédigés)
* [ ] Résultat du test manuel `initialize`
* [ ] Résultat du test manuel `tools/list`
* [ ] Journaux de débogage du SDK
* [ ] Messages d’erreur

## Voir aussi

* [Utilisation de serveurs MCP avec le SDK GitHub Copilot](/fr/copilot/how-tos/copilot-sdk/features/mcp) - Configuration et installation
* [Guide de débogage](/fr/copilot/how-tos/copilot-sdk/troubleshooting/debugging) - Débogage à l’échelle du Kit de développement logiciel (SDK)
* [Spécification MCP](https://modelcontextprotocol.io/) - Documents de protocole officiels