Debuggen von MCP-Servern im Copilot SDK

Diagnostizieren und Beheben von Problemen mit MCP-Servern, die mit Copilot SDK integriert sind, einschließlich Serverstartfehlern, Toolermittlungsproblemen und Protokollfehlern.

Wer kann dieses Feature verwenden?

GitHub Copilot SDK ist mit allen Copilot Tarifen verfügbar.

In diesem Artikel

Hinweis

          Copilot SDK ist zurzeit in öffentliche Vorschau. Funktionalität und Verfügbarkeit können geändert werden.

Schnelle Diagnose

Prüfliste

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)
  • Keine Firewall oder Antivirensoftware 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

          **Erwartete Antwort:**

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

Ein Windows PowerShell-Beispiel finden Sie im McP-Serverdebugginghandbuch im github/copilot-sdk Repository.

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

{"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.
UrsacheLösung
Falscher BefehlspfadAbsoluter Pfad verwenden: /usr/local/bin/server
Fehlende AusführungsberechtigungFühren Sie chmod +x /path/to/server aus.
Fehlende AbhängigkeitenMit ldd überprüfen (Linux) oder manuell ausführen
Arbeitsverzeichnisprobleme
          `cwd` in der Konfiguration festlegen |

Debugging manuell 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.

1. In der Konfiguration nicht aktivierte Tools:

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

  1.        **Der Server macht keine Tools verfügbar:** Testen Sie manuell mit einer `tools/list` Anforderung. Überprüfen Sie, ob der Server die `tools/list` Methode implementiert.

  2.        **Initialisierungs-Handshake schlägt fehl:** Der Server muss korrekt auf `initialize` reagieren und `notifications/initialized` handhaben.

Aufgeführte, aber nie aufgerufene Tools

          **Symptome:** Tools werden in Debugprotokollen angezeigt, aber das Modell verwendet sie nicht.

  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:** Stellen Sie sicher, dass es sich um `inputSchema` ein gültiges JSON-Schema handelt. Erforderliche Felder müssen im `required` Array aufgelistet werden.

Timeoutfehler

          **Symptome:**`MCP tool call timed out` Fehler.

  1. Erhöhen Sie das Timeout:

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

  2. Optimieren Sie die Serverleistung, indem Sie die Fortschrittprotokollierung hinzufügen, um den Engpass zu identifizieren, asynchrone Vorgänge zu berücksichtigen und auf blockierende E/A zu überprüfen.

  3. Bei langandauernden Werkzeugen sollten Sie Streaming-Antworten erwägen, 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 zu „stdout” anstelle von „stderr”, oder es gibt zusätzliche neue Zeilen oder Leerzeichen:
    TypeScript
    // Wrong—pollutes stdout
console.log("Debug info");

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

  2.        **Codierungsprobleme:** Stellen Sie die UTF-8-Codierung ohne BOM (Byte Order Mark) sicher.

  3.           **Nachrichtenrahmen:** Jede Nachricht muss ein vollständiges JSON-Objekt sein, mit Zeilentrennzeichen (eine Nachricht pro Zeile).

Plattformspezifische Probleme

Windows

Unter Windows können Antivirensoftware oder Firewallsoftware neue ausführbare Dateien oder Prozesse blockieren, die über stdin/stdout kommunizieren. Fügen Sie Ausschlüsse für die ausführbare Datei des MCP-Servers hinzu, falls erforderlich.

Windows-spezifische Konfigurationsbeispiele für .NET-Konsolen-Apps und NPX-Befehle finden Sie im McP Server Debugging Guide im github/copilot-sdk Repository.

          **Pfadprobleme:**
  • Verwenden Sie unformatierte Zeichenfolgen (@"C:\path") oder Schrägstriche ("C:/path").
  • Vermeiden Sie nach Möglichkeit Leerzeichen in Pfaden.
  • Wenn Leerzeichen erforderlich sind, stellen Sie eine ordnungsgemäße Quotierung sicher.

macOS

  1.        **Gatekeeper-Blockierung:** Wenn der Server blockiert ist:
    Bash
    xattr -d com.apple.quarantine /path/to/mcp-server

  2.        **Homebrew-Pfade:** GUI-Apps sind möglicherweise nicht in PATH enthalten `/opt/homebrew` . Verwenden Sie den vollständigen Pfad:
    TypeScript
    mcpServers: {
  "my-server": {
    command: "/opt/homebrew/bin/node",  // Full path
    args: ["/path/to/server.js"],
  },
}

Linux

  1.        **Berechtigungsprobleme:**
    Bash
    chmod +x /path/to/mcp-server

  2.        **Fehlende freigegebene 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="/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"

Verwenden Sie sie:

TypeScript
mcpServers: {
  "debug-server": {
    command: "/path/to/mcp-debug-wrapper.sh",
    args: ["/actual/server/path", "arg1", "arg2"],
  },
}

Prüfen mit MCP Inspector

Verwenden Sie das offizielle MCP Inspector-Tool:

Bash
npx @modelcontextprotocol/inspector /path/to/your/mcp-server

Dies bietet eine Web-UI zum Senden von Testanforderungen, Anzeigen von Antworten und Überprüfen von Toolschemas.

Protokollversionskonflikten

Überprüfen Sie, ob ihr Server die Protokollversion unterstützt, die das SDK verwendet:

// In initialize response, check protocolVersion
{"result":{"protocolVersion":"2024-11-05",...}}

Wenn versionen nicht übereinstimmen, aktualisieren Sie Ihre MCP-Serverbibliothek.

Checkliste zum Debuggen

Sammeln Sie beim Öffnen eines Problems oder beim Anfordern von Hilfe zu GitHub-Problemen Folgendes:

  • SDK-Sprache und -Version
  • CLI-Version (copilot --version)
  • MCP-Servertyp (Node.js, Python, .NET, Go usw.)
  • Vollständige MCP-Serverkonfiguration (redact secrets)
  • Ergebnis des manuellen initialize Tests
  • Ergebnis des manuellen tools/list Tests
  • Debugprotokolle aus DEM SDK
  • Fehlermeldungen