1. Anleitungen
MCP Offizielle Dokumentation (Deutsche)
  • Erste Schritte
    • Einführung
    • Beispielserver
    • Beispielkunden
    • Quickstart
      • Für Serverentwickler
      • Für Client-Entwickler
      • Für Claude Desktop-Benutzer
  • Anleitungen
    • Erstellen von MCP mit LLMs
    • Debuggen
    • Inspektor
  • Konzepte
    • Kernarchitektur
    • Ressourcen
    • Eingabeaufforderungen
    • Werkzeuge
    • Probenahme
    • Wurzeln
    • Transportmöglichkeiten
  • Entwicklung
    • Was ist neu
    • Fahrplan
    • Beitragen
  1. Anleitungen

Debuggen

Hier ist die Übersetzung des Markdown-Inhalts ins Deutsche, wobei Fachbegriffe wie "Model Context Protocol (MCP)" beibehalten werden und Codeblöcke nicht übersetzt werden:
Ein umfassender Leitfaden zur Fehlersuche bei Model Context Protocol (MCP)-Integrationen
Effektive Fehlersuche ist unerlässlich bei der Entwicklung von MCP-Servern oder deren Integration in Anwendungen. Dieser Leitfaden behandelt die im MCP-Ökosystem verfügbaren Werkzeuge und Ansätze zur Fehlersuche.
Dieser Leitfaden ist für macOS. Anleitungen für andere Plattformen folgen in Kürze.

Überblick über Debugging-Tools#

MCP bietet verschiedene Tools zur Fehlersuche auf verschiedenen Ebenen:
1.
MCP Inspector
Interaktive Debugging-Schnittstelle
Direkter Servertest
Details finden Sie im Inspector Guide
2.
Claude Desktop Developer Tools
Integrationstests
Protokollsammlung
Chrome DevTools-Integration
3.
Serverprotokollierung
Benutzerdefinierte Protokollierungs-Implementierungen
Fehlerverfolgung
Leistungsüberwachung

Debugging in Claude Desktop#

Serverstatus prüfen#

Die Claude.app-Schnittstelle bietet grundlegende Serverstatusinformationen:
1.
Klicken Sie auf das img Symbol, um Folgendes anzuzeigen:
Verbundene Server
Verfügbare Prompts und Ressourcen
2.
Klicken Sie auf das img Symbol, um Folgendes anzuzeigen:
Tools, die dem Modell zur Verfügung gestellt werden

Protokolle anzeigen#

Überprüfen Sie detaillierte MCP-Protokolle von Claude Desktop:
Die Protokolle erfassen:
Serververbindungsereignisse
Konfigurationsprobleme
Laufzeitfehler
Nachrichtenaustausch

Verwenden von Chrome DevTools#

Greifen Sie in Claude Desktop auf die Entwicklertools von Chrome zu, um clientseitige Fehler zu untersuchen:
1.
Erstellen Sie eine developer_settings.json-Datei mit allowDevTools auf true gesetzt:
2.
Öffnen Sie DevTools: Command-Option-Shift-i
Hinweis: Sie sehen zwei DevTools-Fenster:
Hauptinhaltsfenster
App-Titelleistenfenster
Verwenden Sie das Konsolenfenster, um clientseitige Fehler zu untersuchen.
Verwenden Sie das Netzwerkfenster, um Folgendes zu untersuchen:
Nachrichten-Payloads
Verbindungs-Timing

Häufige Probleme#

Arbeitsverzeichnis#

Bei Verwendung von MCP-Servern mit Claude Desktop:
Das Arbeitsverzeichnis für Server, die über claude_desktop_config.json gestartet werden, kann undefiniert sein (wie / auf macOS), da Claude Desktop von überall aus gestartet werden kann.
Verwenden Sie immer absolute Pfade in Ihren Konfigurations- und .env-Dateien, um einen zuverlässigen Betrieb zu gewährleisten.
Zum Testen von Servern direkt über die Befehlszeile ist das Arbeitsverzeichnis der Ort, an dem Sie den Befehl ausführen.
Verwenden Sie beispielsweise in claude_desktop_config.json:
{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/data"]
}
Anstelle von relativen Pfaden wie ./data

Umgebungsvariablen#

MCP-Server erben automatisch nur eine Teilmenge der Umgebungsvariablen, wie USER, HOME und PATH.
Um die Standardvariablen zu überschreiben oder eigene anzugeben, können Sie einen env-Schlüssel in claude_desktop_config.json angeben:
{
  "myserver": {
    "command": "mcp-server-myapp",
    "env": {
      "MYAPP_API_KEY": "some_key",
    }
  }
}

Serverinitialisierung#

Häufige Initialisierungsprobleme:
1.
Pfadprobleme
Falscher Server-Ausführungspfad
Fehlende erforderliche Dateien
Berechtigungsprobleme
Versuchen Sie, einen absoluten Pfad für command zu verwenden
2.
Konfigurationsfehler
Ungültige JSON-Syntax
Fehlende erforderliche Felder
Typenkonflikte
3.
Umgebungsprobleme
Fehlende Umgebungsvariablen
Falsche Variablenwerte
Berechtigungsbeschränkungen

Verbindungsprobleme#

Wenn Server keine Verbindung herstellen können:
1.
Überprüfen Sie die Claude Desktop-Protokolle
2.
Stellen Sie sicher, dass der Serverprozess ausgeführt wird
3.
Testen Sie ihn eigenständig mit Inspector
4.
Überprüfen Sie die Protokollkompatibilität

Implementieren der Protokollierung#

Serverseitige Protokollierung#

Beim Erstellen eines Servers, der den lokalen stdio Transport verwendet, werden alle an stderr (Standardfehler) protokollierten Nachrichten automatisch von der Hostanwendung (z. B. Claude Desktop) erfasst.
Lokale MCP-Server sollten keine Nachrichten an stdout (Standardausgabe) protokollieren, da dies den Protokollbetrieb beeinträchtigt.
Für alle Transporte können Sie die Protokollierung auch für den Client bereitstellen, indem Sie eine Protokollnachricht senden:
Python
TypeScript
Wichtige zu protokollierende Ereignisse:
Initialisierungsschritte
Ressourcenzugriff
Werkzeugausführung
Fehlerzustände
Leistungskennzahlen

Clientseitige Protokollierung#

In Clientanwendungen:
1.
Debug-Protokollierung aktivieren
2.
Netzwerkverkehr überwachen
3.
Nachrichtenaustausch verfolgen
4.
Fehlerzustände aufzeichnen

Debugging-Workflow#

Entwicklungszyklus#

1.
Ersteinwicklung
Verwenden Sie Inspector für grundlegende Tests
Implementieren Sie die Kernfunktionalität
Fügen Sie Protokollierungspunkte hinzu
2.
Integrationstests
Testen Sie in Claude Desktop
Überwachen Sie die Protokolle
Überprü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: Verwenden Sie Inspector während der Entwicklung

Bewährte Methoden#

Protokollierungsstrategie#

1.
Strukturierte Protokollierung
Verwenden Sie konsistente Formate
Schließen Sie den Kontext ein
Fügen Sie Zeitstempel hinzu
Verfolgen Sie Anforderungs-IDs
2.
Fehlerbehandlung
Protokollieren Sie Stacktraces
Schließen Sie den Fehlerkontext ein
Verfolgen Sie Fehlermuster
Überwachen Sie die Wiederherstellung
3.
Leistungsverfolgung
Protokollieren Sie das Operationstiming
Überwachen Sie die Ressourcennutzung
Verfolgen Sie die Nachrichtengrößen
Messen Sie die Latenz

Sicherheitsüberlegungen#

Beim Debuggen:
1.
Sensible Daten
Bereinigen Sie Protokolle
Schützen Sie Anmeldeinformationen
Maskieren Sie persönliche Informationen
2.
Zugriffskontrolle
Überprüfen Sie Berechtigungen
Überprüfen Sie die Authentifizierung
Überwachen Sie Zugriffsmuster

Hilfe erhalten#

Bei Problemen:
1.
Erste Schritte
Überprüfen Sie die Serverprotokolle
Testen Sie mit Inspector
Überprüfen Sie die Konfiguration
Überprüfen Sie die Umgebung
2.
Supportkanäle
GitHub-Probleme
GitHub-Diskussionen
3.
Bereitstellung von Informationen
Protokollauszüge
Konfigurationsdateien
Schritte zur Reproduktion
Umgebungsdetails
Modified at 2025-03-13 03:55:16
Previous
Erstellen von MCP mit LLMs
Next
Inspektor
Built with