# MCP-Serverdebugginghandbuch In diesem Handbuch werden Debuggingtechniken behandelt, die für MCP-Server (Model Context Protocol) bei Verwendung des Copilot SDK spezifisch sind. ## Inhaltsverzeichnis * [Schnelldiagnose](#quick-diagnostics) * [Unabhängiges Testen von MCP-Servern](#testing-mcp-servers-independently) * [Häufige Probleme](#common-issues) * [Plattformspezifische Probleme](#platform-specific-issues) * [Erweitertes Debuggen](#advanced-debugging) ## Schnelle Diagnose ### Checklist Bevor Sie tief tauchen, überprüfen Sie diese Grundlagen: * [ ] Die ausführbare Datei des MCP-Servers ist vorhanden und kann ausgeführt werden. * [ ] Befehlspfad ist richtig (verwenden Sie absolute Pfade, wenn sie zweifelsfrei sind) * [ ] Tools sind aktiviert (`tools: ["*"]` oder bestimmte Toolnamen) * [ ] Server implementiert das MCP-Protokoll korrekt (antwortet auf `initialize`) * [ ] Kein Firewall/Antivirus blockiert den Prozess (Windows) ### Aktivieren der MCP-Debugprotokollierung Hinzufügen von Umgebungsvariablen zur MCP-Serverkonfiguration: ```typescript mcpServers: { "my-server": { type: "local", command: "/path/to/server", args: [], env: { MCP_DEBUG: "1", DEBUG: "*", NODE_DEBUG: "mcp", // For Node.js MCP servers }, }, } ``` ## Unabhängiges Testen von MCP-Servern Testen Sie ihren MCP-Server immer außerhalb des SDK zuerst. ### Manueller Protokolltest Senden Sie eine `initialize` Anfrage über „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 # Windows (PowerShell) '{"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 ``` **Erwartete Antwort:** ```json {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"your-server","version":"1.0"}}} ``` ### Liste der Test-Tools Fordern Sie nach der Initialisierung die Toolsliste an: ```bash echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | /path/to/your/mcp-server ``` **Erwartete Antwort:** ```json {"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"my_tool","description":"Does something","inputSchema":{...}}]}} ``` ### Interaktives Testskript Erstellen Sie ein Testskript, um Ihren MCP-Server interaktiv zu debuggen: ```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 ``` Verwendung: ```bash ./test-mcp.sh | /path/to/mcp-server ``` ## Häufig auftretende Probleme ### Server wird nicht gestartet **Symptome:** Es werden keine Tools angezeigt, keine Fehler in Protokollen. **Ursachen & Lösungen:** | Ursache | Lösung | | ------------------------------------ | --------------------------------------------------- | | Falscher Befehlspfad | Absoluter Pfad verwenden: `/usr/local/bin/server` | | Fehlende Ausführungsberechtigung | Führen Sie `chmod +x /path/to/server` aus | | Fehlende Abhängigkeiten | Mit `ldd` überprüfen (Linux) oder manuell ausführen | | Arbeitsverzeichnisprobleme | | | `cwd` in der Konfiguration festlegen | | **Debuggen durch manuelles Ausführen:** ```bash # Run exactly what the SDK would run cd /expected/working/dir /path/to/command arg1 arg2 ``` ### Der Server startet, aber die Werkzeuge werden nicht angezeigt. **Symptome:** Der Serverprozess wird ausgeführt, aber es sind keine Tools verfügbar. **Ursachen & Lösungen:** 1. **In der Konfiguration nicht aktivierte Tools:** ```typescript mcpServers: { "server": { // ... tools: ["*"], // Must be "*" or list of tool names }, } ``` 2. **Der Server macht keine Tools verfügbar:** * Mit `tools/list` Anfrage manuell testen * Prüfen, ob der Server die Methode `tools/list` implementiert 3. **Initialisierungs-Handshake schlägt fehl:** * Der Server muss auf `initialize` korrekt reagieren. * Der Server muss `notifications/initialized` verarbeiten. ### Aufgeführte, aber nie aufgerufene Tools **Symptome:** Tools werden in Debugprotokollen angezeigt, aber das Modell verwendet sie nicht. **Ursachen & Lösungen:** 1. **Prompt benötigt das Tool nicht eindeutig:** ```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. **Beschreibung des Tools unklar:** ```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. **Toolschemaprobleme:** * Sicherstellen, dass es sich um `inputSchema` ein gültiges JSON-Schema handelt * Erforderliche Felder müssen sich im `required` Array befinden. ### Timeoutfehler **Symptome:**`MCP tool call timed out` Fehler. **Lösungen :** 1. **Timeout erhöhen:** ```typescript mcpServers: { "slow-server": { // ... timeout: 300000, // 5 minutes }, } ``` 2. **Optimieren der Serverleistung:** * Protokollierung des Fortschritts hinzufügen, um Engpässe zu identifizieren * Berücksichtigen Sie asynchrone Vorgänge * Überprüfen auf Blockieren von E/A 3. **Bei lang andauernden Tools** sollten Sie Streamingantworten in Betracht ziehen, wenn diese unterstützt werden. ### JSON-RPC Fehler **Symptome:** Analysefehler, ungültige Anforderungsfehler. **Häufige Ursachen:** 1. **Server schreibt fälschlicherweise in stdout:** * Debug-Ausgabe geht an stdout statt an stderr * Zusätzliche Neulinien oder Leerzeichen ```typescript // Wrong - pollutes stdout console.log("Debug info"); // Correct - use stderr for debug console.error("Debug info"); ``` 2. **Codierungsprobleme:** * Sicherstellen der UTF-8-Codierung * Kein BOM (Byte Order Mark) 3. **Nachrichtenrahmen:** * Jede Nachricht muss ein vollständiges JSON-Objekt sein. * Zeilentrennzeichen (eine Nachricht pro Zeile) ## Plattformspezifische Probleme ### Windows #### .NET Konsolen-Apps/-Tools ```csharp // Correct configuration for .NET exe ["my-dotnet-server"] = new McpStdioServerConfig { Command = @"C:\Tools\MyServer\MyServer.exe", // Full path with .exe Args = new List(), WorkingDirectory = @"C:\Tools\MyServer", // Set working directory Tools = new List { "*" }, } // For dotnet tool (DLL) ["my-dotnet-tool"] = new McpStdioServerConfig { Command = "dotnet", Args = new List { @"C:\Tools\MyTool\MyTool.dll" }, WorkingDirectory = @"C:\Tools\MyTool", Tools = new List { "*" }, } ``` #### npx-Befehle ```csharp // Windows needs cmd /c for npx ["filesystem"] = new McpStdioServerConfig { Command = "cmd", Args = new List { "/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\allowed\\path" }, Tools = new List { "*" }, } ``` #### Pfadprobleme * Verwenden Sie Rohzeichenfolgen (`@"C:\path"`) oder Schrägstriche (`"C:/path"`) * Vermeiden Sie Leerzeichen in Pfaden, wenn möglich. * Wenn Leerzeichen erforderlich sind, stellen Sie sicher, dass sie richtig zitiert werden #### Antivirus/Firewall Windows Defender oder ein anderer AV kann Folgendes blockieren: * Neue ausführbare Dateien * Kommunikationsprozesse über stdin/stdout **Lösung:** Fügen Sie Ausschlüsse für die ausführbare Datei des MCP-Servers hinzu. ### macOS #### Gatekeeper-Blockierung ```bash # If the server is blocked xattr -d com.apple.quarantine /path/to/mcp-server ``` #### Homebrew-Pfade ```typescript // GUI apps may not have /opt/homebrew in PATH mcpServers: { "my-server": { command: "/opt/homebrew/bin/node", // Full path args: ["/path/to/server.js"], }, } ``` ### Linux #### Berechtigungsprobleme ```bash chmod +x /path/to/mcp-server ``` #### Fehlende gemeinsame Bibliotheken ```bash # Check dependencies ldd /path/to/mcp-server # Install missing libraries apt install libfoo # Debian/Ubuntu yum install libfoo # RHEL/CentOS ``` ## Erweitertes Debuggen ### Gesamten MCP-Datenverkehr erfassen Erstellen Sie ein Wrapperskript, um die gesamte Kommunikation zu protokollieren: ```bash #!/bin/bash # mcp-debug-wrapper.sh LOG="./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" ``` Verwenden Sie sie: ```typescript mcpServers: { "debug-server": { command: "/path/to/mcp-debug-wrapper.sh", args: ["/actual/server/path", "arg1", "arg2"], }, } ``` ### Mit MCP-Inspektor prüfen Verwenden Sie das offizielle MCP Inspector-Tool: ```bash npx @modelcontextprotocol/inspector /path/to/your/mcp-server ``` Dadurch wird eine Web-UI für Folgendes bereitgestellt: * Senden von Testanforderungen * Antworten anzeigen * Tool-Schemata prüfen ### Protokollversionskonflikten Überprüfen Sie, ob ihr Server die Protokollversion unterstützt, die das SDK verwendet: ```json // In initialize response, check protocolVersion {"result":{"protocolVersion":"2024-11-05",...}} ``` Wenn versionen nicht übereinstimmen, aktualisieren Sie Ihre MCP-Serverbibliothek. ## Checkliste zum Debuggen Wenn Sie ein Issue öffnen oder um Hilfe bitten, halten Sie Folgendes bereit: * [ ] SDK-Sprache und -Version * [ ] CLI-Version (`copilot --version`) * [ ] MCP-Servertyp (Node.js, Python, .NET, Go, Rust und mehr) * [ ] Vollständige MCP-Serverkonfiguration (redact secrets) * [ ] Ergebnis des manuellen `initialize` Tests * [ ] Ergebnis des manuellen `tools/list` Tests * [ ] Debugprotokolle aus DEM SDK * [ ] Fehlermeldungen ## Siehe auch * [AUTOTITLE –](/de/copilot/how-tos/copilot-sdk/features/mcp) Konfiguration und Einrichtung * [Debughandbuch](/de/copilot/how-tos/copilot-sdk/troubleshooting/debugging) – SDK-weites Debuggen * [MCP-Spezifikation](https://modelcontextprotocol.io/) - Offizielle Protokolldokumente