Débogage de serveurs MCP dans le Kit de développement logiciel (SDK) Copilot

Diagnostiquer et résoudre les problèmes liés aux serveurs MCP intégrés, SDK Copilotnotamment les échecs de démarrage du serveur, les problèmes de découverte d’outils et les erreurs de protocole.

Qui peut utiliser cette fonctionnalité ?

Kit de développement logiciel (SDK) GitHub Copilot est disponible dans tous les forfaits Copilot.

Dans cet article

Remarque

SDK Copilot est actuellement en préversion publique. Les fonctionnalités et la disponibilité sont susceptibles de changer.

Diagnostics rapides

Liste de contrôle

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 ou antivirus ne bloque 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

          **Réponse attendue :**

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

Pour obtenir un exemple Windows PowerShell, consultez le Guide de débogage du serveur MCP dans le github/copilot-sdk référentiel.

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 :**

{"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.
La causeSolution
Chemin d’accès de commande incorrectUtilisez le chemin absolu : /usr/local/bin/server
Autorisation exécutable manquanteExécutez chmod +x /path/to/server
Dépendances manquantesVérifier avec ldd (Linux) ou exécuter manuellement
Problèmes de répertoire de travailDé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.

1. Outils non activés dans la configuration :

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

  1.        **Le serveur n’expose pas les outils :** Testez manuellement avec une `tools/list` requête. Vérifiez que le serveur implémente la `tools/list` méthode.

  2.        **Échec de l'échange d'initialisation :** Le serveur doit répondre correctement à `initialize` et 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.

  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érifiez qu’il s’agit `inputSchema` d’un schéma JSON valide. Les champs obligatoires doivent être répertoriés dans le `required` tableau.

Erreurs de délai d’expiration

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

  1. Augmentez le délai d’expiration :

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

  2. Optimisez les performances du serveur en ajoutant la journalisation de progression pour identifier le goulot d’étranglement, en tenant compte des opérations asynchrones et en vérifiant les E/S bloquantes.

  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 messages du serveur écrits sur stdout sont incorrects :** la sortie de débogage allant vers stdout au lieu de stderr, ou la présence de lignes supplémentaires ou d'espaces blancs superflus :
    TypeScript
    // Wrong—pollutes stdout
console.log("Debug info");

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

  2.        **Problèmes d’encodage :** Vérifiez l’encodage UTF-8 sans boM (marque d’ordre d’octet).

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

Problèmes spécifiques à la plateforme

Fenêtres

Sur Windows, un antivirus ou un logiciel de pare-feu peut bloquer de nouveaux exécutables ou processus communiquant via stdin/stdout. Ajoutez des exclusions pour votre exécutable de serveur MCP si nécessaire.

Pour obtenir des exemples de configuration spécifiques à Windows pour les applications console .NET et les commandes NPX, consultez le Guide de débogage du serveur MCP dans le github/copilot-sdk référentiel.

          **Problèmes de chemin d’accès :**
  • Utilisez des chaînes brutes (@"C:\path") ou des barres obliques ("C:/path").
  • Évitez les espaces dans les chemins lorsque cela est possible.
  • Si des espaces sont nécessaires, assurez-vous d'utiliser les guillemets appropriés.

macOS

  1.        **Blocage de Gatekeeper :** Si le serveur est bloqué :
    Bash
    xattr -d com.apple.quarantine /path/to/mcp-server

  2.        **Chemins Homebrew :** Les applications GUI peuvent ne pas avoir `/opt/homebrew` dans PATH. Utilisez le chemin d’accès complet :
    TypeScript
    mcpServers: {
  "my-server": {
    command: "/opt/homebrew/bin/node",  // Full path
    args: ["/path/to/server.js"],
  },
}

Linux

  1.        **Problèmes d’autorisation :**
    Bash
    chmod +x /path/to/mcp-server

  2.        **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="/tmp/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 des réponses et inspecter des 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) :

// 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’un problème ou de la demande d’aide sur les problèmes GitHub, 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, et ainsi de suite)
  • 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