wehub-resource-sync
13 KiB
Débogage avec MCP Inspector
Le MCP Inspector est un outil de débogage essentiel qui vous permet de tester et de dépanner vos serveurs MCP de manière interactive sans avoir besoin d'une application hôte IA complète. Considérez-le comme le "Postman pour MCP" - il offre une interface visuelle pour envoyer des requêtes, voir les réponses et comprendre comment votre serveur se comporte.
Pourquoi utiliser MCP Inspector ?
Lors de la création de serveurs MCP, vous rencontrerez souvent ces défis :
- « Mon serveur fonctionne-t-il vraiment ? » - Inspector affiche le statut de la connexion
- « Mes outils sont-ils correctement enregistrés ? » - Inspector liste tous les outils disponibles
- « Quel est le format de réponse ? » - Inspector affiche les réponses JSON complètes
- « Pourquoi cet outil ne fonctionne-t-il pas ? » - Inspector affiche des messages d'erreur détaillés
Pré-requis
- Node.js 18+ installé
- npm (fourni avec Node.js)
- Un serveur MCP à tester (voir Module 3.1 - Premier serveur)
Installation
Option 1 : Lancer avec npx (Recommandé pour un test rapide)
npx @modelcontextprotocol/inspector
Option 2 : Installer globalement
npm install -g @modelcontextprotocol/inspector
mcp-inspector
Option 3 : Ajouter à votre projet
cd your-mcp-server-project
npm install --save-dev @modelcontextprotocol/inspector
Ajouter dans package.json :
{
"scripts": {
"inspector": "mcp-inspector"
}
}
Connexion à votre serveur
Serveurs stdio (Processus local)
Pour les serveurs qui communiquent via entrée/sortie standard :
# Serveur Python
npx @modelcontextprotocol/inspector python -m your_server_module
# Serveur Node.js
npx @modelcontextprotocol/inspector node ./build/index.js
# Avec des variables d'environnement
OPENAI_API_KEY=xxx npx @modelcontextprotocol/inspector python server.py
Serveurs SSE/HTTP (Réseau)
Pour les serveurs fonctionnant en tant que services HTTP :
-
Démarrez d'abord votre serveur :
python server.py # Serveur en cours d'exécution sur http://localhost:8080 -
Lancez Inspector et connectez-vous :
npx @modelcontextprotocol/inspector --sse http://localhost:8080/sse
Vue d'ensemble de l'interface Inspector
Lorsque Inspector démarre, vous verrez une interface web (généralement à http://localhost:5173) :
┌─────────────────────────────────────────────────────────────┐
│ MCP Inspector [Connected ✅] │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 🔧 Tools │ │ 📄 Resources│ │ 💬 Prompts │ │
│ │ (3) │ │ (2) │ │ (1) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────┐ │
│ │ 📋 Message Log │ │
│ │ ─────────────────────────────────────────────────── │ │
│ │ → initialize │ │
│ │ ← initialized (server info) │ │
│ │ → tools/list │ │
│ │ ← tools (3 tools) │ │
│ └───────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
Test des outils
Lister les outils disponibles
- Cliquez sur l'onglet Tools
- Inspector appelle automatiquement
tools/list - Vous verrez tous les outils enregistrés avec :
- Nom de l'outil
- Description
- Schéma d'entrée (paramètres)
Appeler un outil
- Sélectionnez un outil dans la liste
- Remplissez les paramètres requis dans le formulaire
- Cliquez sur Run Tool
- Consultez la réponse dans le panneau des résultats
Exemple : Tester un outil calculatrice
Tool: add
Parameters:
a: 25
b: 17
Response:
{
"content": [
{
"type": "text",
"text": "42"
}
]
}
Déboguer les erreurs d'outil
Lorsqu'un outil échoue, Inspector affiche :
Error Response:
{
"error": {
"code": -32602,
"message": "Invalid params: 'b' is required"
}
}
Codes d'erreur courants :
| Code | Signification |
|---|---|
| -32700 | Erreur de parsing (JSON invalide) |
| -32600 | Requête invalide |
| -32601 | Méthode non trouvée |
| -32602 | Paramètres invalides |
| -32603 | Erreur interne |
Test des ressources
Lister les ressources
- Cliquez sur l'onglet Resources
- Inspector appelle
resources/list - Vous verrez :
- URI des ressources
- Noms et descriptions
- Types MIME
Lire une ressource
- Sélectionnez une ressource
- Cliquez sur Read Resource
- Visualisez le contenu retourné
Exemple de sortie :
Resource: file:///config/settings.json
Content-Type: application/json
{
"config": {
"debug": true,
"maxConnections": 10
}
}
Test des prompts
Lister les prompts
- Cliquez sur l'onglet Prompts
- Inspector appelle
prompts/list - Visualisez les modèles de prompt disponibles
Obtenir un prompt
- Sélectionnez un prompt
- Remplissez les arguments requis
- Cliquez sur Get Prompt
- Voyez les messages de prompt rendus
Analyse du journal des messages
Le journal des messages affiche tous les messages du protocole MCP :
14:32:01 → {"jsonrpc":"2.0","id":1,"method":"initialize",...}
14:32:01 ← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-11-25",...}}
14:32:02 → {"jsonrpc":"2.0","id":2,"method":"tools/list"}
14:32:02 ← {"jsonrpc":"2.0","id":2,"result":{"tools":[...]}}
14:32:05 → {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add",...}}
14:32:05 ← {"jsonrpc":"2.0","id":3,"result":{"content":[...]}}
Points à surveiller
- Paires requête/réponse : Chaque
→doit avoir un←correspondant - Messages d'erreur : Cherchez
"error"dans les réponses - Timing : De grandes pauses peuvent indiquer des problèmes de performance
- Version du protocole : Assurez-vous que serveur et client sont d'accord sur la version
Intégration VS Code
Vous pouvez lancer Inspector directement depuis VS Code :
Utilisation de launch.json
Ajoutez à .vscode/launch.json :
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug with MCP Inspector",
"type": "node",
"request": "launch",
"runtimeExecutable": "npx",
"runtimeArgs": [
"@modelcontextprotocol/inspector",
"python",
"${workspaceFolder}/server.py"
],
"console": "integratedTerminal"
},
{
"name": "Debug SSE Server with Inspector",
"type": "chrome",
"request": "launch",
"url": "http://localhost:5173",
"preLaunchTask": "Start MCP Inspector"
}
]
}
Utilisation des Tasks
Ajoutez à .vscode/tasks.json :
{
"version": "2.0.0",
"tasks": [
{
"label": "Start MCP Inspector",
"type": "shell",
"command": "npx @modelcontextprotocol/inspector node ${workspaceFolder}/build/index.js",
"isBackground": true,
"problemMatcher": {
"pattern": {
"regexp": "^$"
},
"background": {
"activeOnStart": true,
"beginsPattern": "Inspector",
"endsPattern": "listening"
}
}
}
]
}
Scénarios courants de débogage
Scénario 1 : Le serveur ne se connecte pas
Symptômes : Inspector affiche « Disconnected » ou reste bloqué sur « Connecting... »
Liste de vérification :
- ✅ La commande du serveur est-elle correcte ?
- ✅ Toutes les dépendances sont-elles installées ?
- ✅ Le chemin du serveur est-il absolu ou relatif au répertoire courant ?
- ✅ Les variables d'environnement requises sont-elles définies ?
Étapes de débogage :
# Tester le serveur manuellement d'abord
python -c "import your_server_module; print('OK')"
# Vérifier les erreurs d'importation
python -m your_server_module 2>&1 | head -20
# Vérifier que le SDK MCP est installé
pip show mcp
Scénario 2 : Outils non affichés
Symptômes : L'onglet Tools affiche une liste vide
Causes possibles :
- Outils non enregistrés lors de l'initialisation du serveur
- Serveur planté après le démarrage
- Le gestionnaire
tools/listrenvoie un tableau vide
Étapes de débogage :
- Vérifiez le journal des messages pour la réponse
tools/list - Ajoutez des logs dans votre code d'enregistrement d'outils
- Vérifiez la présence des décorateurs
@mcp.tool()(Python)
Scénario 3 : L'outil retourne une erreur
Symptômes : L'appel à l'outil retourne une réponse d'erreur
Approche de débogage :
- Lisez attentivement le message d'erreur
- Vérifiez que les types de paramètres correspondent au schéma
- Ajoutez des blocs try/catch avec des messages d'erreur détaillés
- Consultez les logs du serveur pour les traces de pile
Exemple d'amélioration de la gestion des erreurs :
@mcp.tool()
async def my_tool(param1: str, param2: int) -> str:
try:
# Logique de l'outil ici
result = process(param1, param2)
return str(result)
except ValueError as e:
raise McpError(f"Invalid parameter: {e}")
except Exception as e:
raise McpError(f"Tool failed: {type(e).__name__}: {e}")
Scénario 4 : Contenu de la ressource vide
Symptômes : La ressource retourne mais le contenu est vide ou nul
Liste de vérification :
- ✅ Le chemin du fichier ou l'URI est correct
- ✅ Le serveur a la permission de lire la ressource
- ✅ Le contenu de la ressource est correctement renvoyé
Fonctionnalités avancées d'Inspector
En-têtes personnalisés (SSE)
npx @modelcontextprotocol/inspector \
--sse http://localhost:8080/sse \
--header "Authorization: Bearer your-token"
Journalisation détaillée
DEBUG=mcp* npx @modelcontextprotocol/inspector python server.py
Enregistrement des sessions
Inspector peut exporter les journaux des messages pour une analyse ultérieure :
- Cliquez sur Export Log dans le panneau des messages
- Sauvegardez le fichier JSON
- Partagez avec les membres de l'équipe pour le débogage
Bonnes pratiques
- Testez tôt et souvent - Utilisez Inspector pendant le développement, pas seulement quand ça casse
- Commencez simple - Testez la connectivité basique avant d'appeler des outils complexes
- Vérifiez le schéma - Beaucoup d'erreurs viennent d'incompatibilités de types de paramètres
- Lisez les messages d'erreur - Les erreurs MCP sont généralement explicites
- Gardez Inspector ouvert - Il aide à détecter les problèmes en cours de développement
Et après ?
Vous avez terminé le Module 3 : Premiers pas ! Continuez votre apprentissage :
Ressources supplémentaires
Avertissement :
Ce document a été traduit à l’aide du service de traduction automatique Co-op Translator. Bien que nous nous efforçons d’assurer l’exactitude, veuillez noter que les traductions automatiques peuvent contenir des erreurs ou des inexactitudes. Le document original dans sa langue d’origine doit être considéré comme la source faisant foi. Pour les informations critiques, une traduction professionnelle réalisée par un humain est recommandée. Nous déclinons toute responsabilité en cas de malentendus ou d’interprétations erronées résultant de l’utilisation de cette traduction.