Debugging

Effektives Debugging ist essentiell bei der Entwicklung von MCP-Servern oder deren Integration in Anwendungen. Dieser Leitfaden behandelt die Debugging-Tools und Ansätze, die im MCP-Ökosystem verfügbar sind.

Übersicht der Debugging-Tools

MCP bietet mehrere Tools zum Debugging auf verschiedenen Ebenen:

1. MCP-Inspektor

   • Interaktive Debugging-Oberfläche
   • Direktes Server-Testing
   • Siehe den Inspektor-Leitfaden für Details

2. Claude Desktop Entwicklertools

   • Integrationstests
   • Log-Sammlung
   • Chrome DevTools Integration

3. Server-Logging

   • Benutzerdefinierte Logging-Implementierungen
   • Fehler-Tracking
   • Performance-Monitoring

Debugging in Claude Desktop

Server-Status überprüfen

Die Claude.app Oberfläche bietet grundlegende Server-Statusinformationen:

1. Klicken Sie auf das <img src="/images/claude-desktop-mcp-plug-icon.svg" style={{display: ‘inline’, margin: 0, height: ‘1.3em’}} /> Symbol, um Folgendes anzuzeigen:

   • Verbundene Server
   • Verfügbare Prompts und Ressourcen

2. Klicken Sie auf das <img src="/images/claude-desktop-mcp-hammer-icon.svg" style={{display: ‘inline’, margin: 0, height: ‘1.3em’}} /> Symbol, um Folgendes anzuzeigen:

   • Dem Modell bereitgestellte Werkzeuge

Protokolle anzeigen

Sehen Sie sich detaillierte MCP‑Protokolle aus Claude Desktop an:

# Follow logs in real-time
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Die Protokolle erfassen:

• Serververbindungsereignisse
• Konfigurationsprobleme
• Laufzeitfehler
• Nachrichtenaustausch

Chrome DevTools verwenden

Öffnen Sie die Entwicklerwerkzeuge von Chrome in Claude Desktop, um Client-seitige Fehler zu untersuchen:

1. DevTools aktivieren:

jq '.allowDevTools = true' ~/Library/Application\ Support/Claude/developer_settings.json > tmp.json \
  && mv tmp.json ~/Library/Application\ Support/Claude/developer_settings.json

2. DevTools öffnen: Command-Option-Shift-i

Hinweis: Sie sehen zwei DevTools-Fenster:

• Hauptfenster des Inhalts
• Fenster der Titelleiste der App

Nutzen Sie das Console-Panel, um Client-seitige Fehler zu analysieren.

Verwenden Sie das Netzwerk-Panel, um Folgendes zu überprüfen:

• Nachrichteninhalte
• Verbindungszeiten

Häufige Probleme

Umgebungsvariablen

MCP‑Server erben automatisch nur einen Teil der Umgebungsvariablen, z. B. USER, HOME und PATH.

Um Standardvariablen zu überschreiben oder eigene zu setzen, können Sie in der claude_desktop_config.json einen Schlüssel env angeben:

{
  "myserver": {
    "command": "mcp-server-myapp",
    "env": {
      "MYAPP_API_KEY": "some_key",
    }
  }
}

Server‑Initialisierung

Häufige Probleme bei der Initialisierung:

1. Pfadprobleme

   • Falscher Pfad zur Serverausführungsdatei
   • Fehlende erforderliche Dateien
   • Berechtigungsprobleme

2. Konfigurationsfehler

   • Ungültige JSON-Syntax
   • Fehlende Pflichtfelder
   • Falsche Datentypen

3. Umgebungsprobleme

   • Fehlende Umgebungsvariablen
   • Falsche Variablenwerte
   • Berechtigungseinschränkungen

Verbindungsprobleme

Wenn Server keine Verbindung herstellen:

1. Prüfen Sie die Claude-Desktop-Protokolle
2. Stellen Sie sicher, dass der Serverprozess läuft
3. Testen Sie den Server separat mit dem Inspector
4. Überprüfen Sie die Protokollkompatibilität

Logging implementieren

Serverseitiges Logging

Wenn Sie einen Server mit lokalem stdio‑Transport bauen, werden alle Meldungen auf stderr (Standardfehler) automatisch von der Host‑Anwendung (z. B. Claude Desktop) erfasst.

Für alle Transporte können Sie außerdem Log‑Meldungen an den Client senden (Log‑Benachrichtigung):

Wichtige Ereignisse für das Logging:

• Initialisierungsschritte
• Ressourcenzugriffe
• Werkzeugausführungen
• Fehlersituationen
• Leistungskennzahlen

Clientseitiges Logging

In Client-Anwendungen:

1. Aktivieren Sie Debug-Logging
2. Überwachen Sie den Netzwerkverkehr
3. Verfolgen Sie den Nachrichtenaustausch
4. Protokollieren Sie Fehlerzustände

Debugging‑Workflow

Entwicklungszyklus

1. Erste Entwicklungsphase

   • Verwenden Sie den Inspector für grundlegende Tests
   • Implementieren Sie die Kernfunktionen
   • Fügen Sie Logpunkte hinzu

2. Integrationstests

   • Testen Sie in Claude Desktop
   • Überwachen Sie die Protokolle
   • Prüfen Sie die Fehlerbehandlung

Änderungen testen

So testen Sie Änderungen effizient:

• Konfigurationsänderungen: Starten Sie Claude Desktop neu
• Servercode-Änderungen: Verwenden Sie Command-R zum Neuladen
• Schnelle Iteration: Nutzen Sie den Inspector während der Entwicklung

Best practices

Logging strategy

1. Strukturiertes Logging

   • Verwenden Sie konsistente Formate
   • Ergänzen Sie Kontextinformationen
   • Fügen Sie Zeitstempel hinzu
   • Verfolgen Sie Anfrage-IDs

2. Fehlerbehandlung

   • Protokollieren Sie Stacktraces
   • Ergänzen Sie Fehlerkontext
   • Verfolgen Sie Fehlermuster
   • Überwachen Sie die Wiederherstellung

3. Performance-Überwachung

   • Protokollieren Sie Ausführungszeiten
   • Überwachen Sie Ressourcennutzung
   • Verfolgen Sie Nachrichtengrößen
   • Messen Sie Latenzen

Security considerations

When debugging:

1. Sensible Daten

   • Bereinigen Sie Protokolle
   • Schützen Sie Zugangsdaten
   • Maskieren Sie personenbezogene Informationen

2. Zugriffskontrolle

   • Überprüfen Sie Berechtigungen
   • Kontrollieren Sie die Authentifizierung
   • Überwachen Sie Zugriffsmuster

Getting help

Wenn Probleme auftreten:

1. Erste Schritte

   • Prüfen Sie die Serverlogs
   • Testen Sie mit dem Inspector
   • Überprüfen Sie die Konfiguration
   • Validieren Sie die Umgebung

2. Support-Kanäle

   • GitHub-Issues
   • GitHub-Diskussionen

3. Bereitzustellende Informationen

   • Logauszüge
   • Konfigurationsdateien
   • Reproduktionsschritte
   • Umgebungsdetails

Next steps