{"meta":{"title":"Guide de débogage du serveur MCP","intro":"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.","product":"GitHub Copilot","breadcrumbs":[{"href":"/fr/copilot","title":"GitHub Copilot"},{"href":"/fr/copilot/how-tos","title":"Procédures"},{"href":"/fr/copilot/how-tos/copilot-sdk","title":"Kit de développement logiciel (SDK) Copilot"},{"href":"/fr/copilot/how-tos/copilot-sdk/troubleshooting","title":"Résolution des problèmes"},{"href":"/fr/copilot/how-tos/copilot-sdk/troubleshooting/mcp-debugging","title":"Débogage MCP"}],"documentType":"article"},"body":"# Guide de débogage du serveur MCP\n\nCe 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.\n\n<!-- markdownlint-disable GHD046 GHD005 -->\n\n<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->\n\n## Table des matières\n\n* [Diagnostics rapides](#quick-diagnostics)\n* [Test des serveurs MCP indépendamment](#testing-mcp-servers-independently)\n* [Problèmes courants](#common-issues)\n* [Problèmes spécifiques à la plateforme](#platform-specific-issues)\n* [Débogage avancé](#advanced-debugging)\n\n## Diagnostics rapides\n\n### Liste de vérification\n\nAvant de plonger en profondeur, vérifiez ces principes de base :\n\n* [ ] Le fichier exécutable du serveur MCP existe et peut être exécuté\n* [ ] Chemin de commande correct (utilisez des chemins absolus en cas de doute)\n* [ ] Les outils sont activés (`tools: [\"*\"]` ou noms d’outils spécifiques)\n* [ ] Le serveur implémente correctement le protocole MCP (répond à `initialize`)\n* [ ] Aucun pare-feu/antivirus bloquant le processus (Windows)\n\n### Activer la journalisation du débogage MCP\n\nAjoutez des variables d’environnement à votre configuration de serveur MCP :\n\n```typescript\nmcpServers: {\n  \"my-server\": {\n    type: \"local\",\n    command: \"/path/to/server\",\n    args: [],\n    env: {\n      MCP_DEBUG: \"1\",\n      DEBUG: \"*\",\n      NODE_DEBUG: \"mcp\",  // For Node.js MCP servers\n    },\n  },\n}\n```\n\n## Test des serveurs MCP indépendamment\n\nTestez toujours votre serveur MCP en dehors du Kit de développement logiciel (SDK) en premier.\n\n### Test manuel du protocole\n\nEnvoyez une `initialize` demande via stdin :\n\n```bash\n# Unix/macOS\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}' | /path/to/your/mcp-server\n\n# Windows (PowerShell)\n'{\"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\n```\n\n**Réponse attendue :**\n\n```json\n{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{\"tools\":{}},\"serverInfo\":{\"name\":\"your-server\",\"version\":\"1.0\"}}}\n```\n\n### Liste des outils de test\n\nAprès l’initialisation, demandez la liste des outils :\n\n```bash\necho '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}' | /path/to/your/mcp-server\n```\n\n**Réponse attendue :**\n\n```json\n{\"jsonrpc\":\"2.0\",\"id\":2,\"result\":{\"tools\":[{\"name\":\"my_tool\",\"description\":\"Does something\",\"inputSchema\":{...}}]}}\n```\n\n### Script de test interactif\n\nCréez un script de test pour déboguer de manière interactive votre serveur MCP :\n\n```bash\n#!/bin/bash\n# test-mcp.sh\n\nSERVER=\"$1\"\n\n# Initialize\necho '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}'\n\n# Send initialized notification\necho '{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\"}'\n\n# List tools\necho '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}'\n\n# Keep stdin open\ncat\n```\n\nUtilisation :\n\n```bash\n./test-mcp.sh | /path/to/mcp-server\n```\n\n## Problèmes courants\n\n### Le serveur ne démarre pas\n\n**Symptômes:** Aucun outil n’apparaît, aucune erreur n'est consignée.\n\n**Causes & Solutions :**\n\n| Cause                                | Solution                                             |\n| ------------------------------------ | ---------------------------------------------------- |\n| Chemin d’accès de commande incorrect | Utilisez le chemin absolu : `/usr/local/bin/server`  |\n| Autorisation exécutable manquante    | Exécutez `chmod +x /path/to/server`                  |\n| Dépendances manquantes               | Vérifier avec `ldd` (Linux) ou exécuter manuellement |\n| Problèmes de répertoire de travail   | Définir `cwd` dans la configuration                  |\n\n**Déboguer en exécutant manuellement :**\n\n```bash\n# Run exactly what the SDK would run\ncd /expected/working/dir\n/path/to/command arg1 arg2\n```\n\n### Le serveur démarre, mais les outils n’apparaissent pas\n\n**Symptômes:** Le processus serveur s’exécute, mais aucun outil n’est disponible.\n\n**Causes & Solutions :**\n\n1. **Outils non activés dans la configuration :**\n\n   ```typescript\n   mcpServers: {\n     \"server\": {\n       // ...\n       tools: [\"*\"],  // Must be \"*\" or list of tool names\n     },\n   }\n   ```\n\n2. **Le serveur n’expose pas les outils :**\n   * Tester la requête manuellement avec `tools/list`\n   * Check Server implémente la `tools/list` méthode\n\n3. **Échec de la négociation d’initialisation :**\n   * Le serveur doit répondre à `initialize` correctement\n   * Le serveur doit gérer `notifications/initialized`\n\n### Outils répertoriés mais jamais appelés\n\n**Symptômes:** Les outils apparaissent dans les journaux de débogage, mais le modèle ne les utilise pas.\n\n**Causes & Solutions :**\n\n1. **L’invite n’a pas besoin clairement de l’outil :**\n\n   ```typescript\n   // Too vague\n   await session.sendAndWait({ prompt: \"What's the weather?\" });\n\n   // Better - explicitly mentions capability\n   await session.sendAndWait({ \n     prompt: \"Use the weather tool to get the current temperature in Seattle\" \n   });\n   ```\n\n2. **La description de l’outil n’est pas claire :**\n\n   ```typescript\n   // Bad - model doesn't know when to use it\n   { name: \"do_thing\", description: \"Does a thing\" }\n\n   // Good - clear purpose\n   { name: \"get_weather\", description: \"Get current weather conditions for a city. Returns temperature, humidity, and conditions.\" }\n   ```\n\n3. **Problèmes de schéma d’outil :**\n   * Vérifier qu’il s’agit `inputSchema` d’un schéma JSON valide\n   * Les champs obligatoires doivent être dans le `required` tableau\n\n### Erreurs de délai d’expiration\n\n**Symptômes:**`MCP tool call timed out` Erreurs.\n\n**Solutions :**\n\n1. **Augmentez le délai d’expiration :**\n\n   ```typescript\n   mcpServers: {\n     \"slow-server\": {\n       // ...\n       timeout: 300000,  // 5 minutes\n     },\n   }\n   ```\n\n2. **Optimiser les performances du serveur :**\n   * Ajouter une journalisation de l’avancement pour identifier un goulot d’étranglement\n   * Envisager des opérations asynchrones\n   * Recherchez tout blocage I/O\n\n3. **Pour les outils de longue durée**, envisagez de diffuser des réponses en continu si elles sont prises en charge.\n\n### erreurs de JSON-RPC\n\n**Symptômes:** Erreurs d’analyse, erreurs de requête non valides.\n\n**Causes courantes :**\n\n1. **Les écritures du serveur dans stdout sont incorrectes :**\n   * Sortie de débogage redirigée vers stdout au lieu de stderr\n   * Nouvelles lignes ou espaces blancs supplémentaires\n   ```typescript\n   // Wrong - pollutes stdout\n   console.log(\"Debug info\");\n\n   // Correct - use stderr for debug\n   console.error(\"Debug info\");\n   ```\n\n2. **Problèmes d’encodage :**\n   * Vérifier l’encodage UTF-8\n   * Sans BOM (indicateur d’ordre des octets)\n\n3. **Trame de message :**\n   * Chaque message doit être un objet JSON complet\n   * Délimité par nouvelle ligne (un message par ligne)\n\n## Problèmes spécifiques à la plateforme\n\n### Windows\n\n#### Applications console / outils .NET\n\n```csharp\n// Correct configuration for .NET exe\n[\"my-dotnet-server\"] = new McpStdioServerConfig\n{\n    Command = @\"C:\\Tools\\MyServer\\MyServer.exe\",  // Full path with .exe\n    Args = new List<string>(),\n    WorkingDirectory = @\"C:\\Tools\\MyServer\",  // Set working directory\n    Tools = new List<string> { \"*\" },\n}\n\n// For dotnet tool (DLL)\n[\"my-dotnet-tool\"] = new McpStdioServerConfig\n{\n    Command = \"dotnet\",\n    Args = new List<string> { @\"C:\\Tools\\MyTool\\MyTool.dll\" },\n    WorkingDirectory = @\"C:\\Tools\\MyTool\",\n    Tools = new List<string> { \"*\" },\n}\n```\n\n#### commandes npx\n\n```csharp\n// Windows needs cmd /c for npx\n[\"filesystem\"] = new McpStdioServerConfig\n{\n    Command = \"cmd\",\n    Args = new List<string> { \"/c\", \"npx\", \"-y\", \"@modelcontextprotocol/server-filesystem\", \"C:\\\\allowed\\\\path\" },\n    Tools = new List<string> { \"*\" },\n}\n```\n\n#### Problèmes de chemin d’accès\n\n* Utiliser des chaînes brutes (`@\"C:\\path\"`) ou des barres obliques (`\"C:/path\"`)\n* Éviter les espaces dans les chemins lorsque cela est possible\n* Si des espaces sont nécessaires, assurez-vous d’utiliser les guillemets appropriés\n\n#### Antivirus/pare-feu\n\nWindows Defender ou d’autres AV peuvent bloquer :\n\n* Nouveaux exécutables\n* Processus de communication via stdin/stdout\n\n**Solution:** Ajoutez des exclusions pour votre exécutable de serveur MCP.\n\n### macOS\n\n#### Blocage par Gatekeeper\n\n```bash\n# If the server is blocked\nxattr -d com.apple.quarantine /path/to/mcp-server\n```\n\n#### Chemins d’accès Homebrew\n\n```typescript\n// GUI apps may not have /opt/homebrew in PATH\nmcpServers: {\n  \"my-server\": {\n    command: \"/opt/homebrew/bin/node\",  // Full path\n    args: [\"/path/to/server.js\"],\n  },\n}\n```\n\n### Linux\n\n#### Problèmes d’autorisation\n\n```bash\nchmod +x /path/to/mcp-server\n```\n\n#### Bibliothèques partagées manquantes\n\n```bash\n# Check dependencies\nldd /path/to/mcp-server\n\n# Install missing libraries\napt install libfoo  # Debian/Ubuntu\nyum install libfoo  # RHEL/CentOS\n```\n\n## Débogage avancé\n\n### Capturer tout le trafic MCP\n\nCréez un script wrapper pour journaliser toutes les communications :\n\n```bash\n#!/bin/bash\n# mcp-debug-wrapper.sh\n\nLOG=\"./mcp-debug-$(date +%s).log\"\nACTUAL_SERVER=\"$1\"\nshift\n\necho \"=== MCP Debug Session ===\" >> \"$LOG\"\necho \"Server: $ACTUAL_SERVER\" >> \"$LOG\"\necho \"Args: $@\" >> \"$LOG\"\necho \"=========================\" >> \"$LOG\"\n\n# Tee stdin/stdout to log file\ntee -a \"$LOG\" | \"$ACTUAL_SERVER\" \"$@\" 2>> \"$LOG\" | tee -a \"$LOG\"\n```\n\nUtilisez-le :\n\n```typescript\nmcpServers: {\n  \"debug-server\": {\n    command: \"/path/to/mcp-debug-wrapper.sh\",\n    args: [\"/actual/server/path\", \"arg1\", \"arg2\"],\n  },\n}\n```\n\n### Inspecter avec l’inspecteur MCP\n\nUtilisez l’outil d’inspecteur MCP officiel :\n\n```bash\nnpx @modelcontextprotocol/inspector /path/to/your/mcp-server\n```\n\nCela fournit une interface utilisateur web pour :\n\n* Envoyer des demandes de test\n* Afficher les réponses\n* Inspecter les schémas d’outil\n\n### Incompatibilités de version du protocole\n\nVérifiez que votre serveur prend en charge la version du protocole utilisée par le Kit de développement logiciel (SDK) :\n\n```json\n// In initialize response, check protocolVersion\n{\"result\":{\"protocolVersion\":\"2024-11-05\",...}}\n```\n\nSi les versions ne correspondent pas, mettez à jour votre bibliothèque de serveurs MCP.\n\n## Liste de vérification du débogage\n\nLors de l’ouverture d’une issue ou d’une demande d’aide, collectez :\n\n* [ ] Langue et version du Kit de développement logiciel (SDK)\n* [ ] Version de CLI (`copilot --version`)\n* [ ] Type de serveur MCP (Node.js, Python, .NET, Go, Rust, etc.)\n* [ ] Configuration complète du serveur MCP (secrets rédigés)\n* [ ] Résultat du test manuel `initialize`\n* [ ] Résultat du test manuel `tools/list`\n* [ ] Journaux de débogage du SDK\n* [ ] Messages d’erreur\n\n## Voir aussi\n\n* [Utilisation de serveurs MCP avec le SDK GitHub Copilot](/fr/copilot/how-tos/copilot-sdk/features/mcp) - Configuration et installation\n* [Guide de débogage](/fr/copilot/how-tos/copilot-sdk/troubleshooting/debugging) - Débogage à l’échelle du Kit de développement logiciel (SDK)\n* [Spécification MCP](https://modelcontextprotocol.io/) - Documents de protocole officiels"}