MCP-Serverdebugginghandbuch

In diesem Handbuch werden Debuggingtechniken behandelt, die für MCP-Server (Model Context Protocol) bei Verwendung des Copilot SDK spezifisch sind.

In diesem Artikel

Inhaltsverzeichnis

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:

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:

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

{"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:

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:

#!/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:

./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:

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

Debuggen durch manuelles Ausführen:

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

    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:

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

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

    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
    // 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

using GitHub.Copilot;

public static class McpDotnetConfigExample
{
    public static void Main()
    {
        var servers = new Dictionary<string, McpServerConfig>
        {
            ["my-dotnet-server"] = new McpStdioServerConfig
            {
                Command = @"C:\Tools\MyServer\MyServer.exe",
                Args = new List<string>(),
                WorkingDirectory = @"C:\Tools\MyServer",
                Tools = new List<string> { "*" },
            },
            ["my-dotnet-tool"] = new McpStdioServerConfig
            {
                Command = "dotnet",
                Args = new List<string> { @"C:\Tools\MyTool\MyTool.dll" },
                WorkingDirectory = @"C:\Tools\MyTool",
                Tools = new List<string> { "*" },
            }
        };
    }
}

// Correct configuration for .NET exe
["my-dotnet-server"] = new McpStdioServerConfig
{
    Command = @"C:\Tools\MyServer\MyServer.exe",  // Full path with .exe
    Args = new List<string>(),
    WorkingDirectory = @"C:\Tools\MyServer",  // Set working directory
    Tools = new List<string> { "*" },
}

// For dotnet tool (DLL)
["my-dotnet-tool"] = new McpStdioServerConfig
{
    Command = "dotnet",
    Args = new List<string> { @"C:\Tools\MyTool\MyTool.dll" },
    WorkingDirectory = @"C:\Tools\MyTool",
    Tools = new List<string> { "*" },
}

npx-Befehle

using GitHub.Copilot;

public static class McpNpxConfigExample
{
    public static void Main()
    {
        var servers = new Dictionary<string, McpServerConfig>
        {
            ["filesystem"] = new McpStdioServerConfig
            {
                Command = "cmd",
                Args = new List<string> { "/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\allowed\\path" },
                Tools = new List<string> { "*" },
            }
        };
    }
}

// Windows needs cmd /c for npx
["filesystem"] = new McpStdioServerConfig
{
    Command = "cmd",
    Args = new List<string> { "/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\allowed\\path" },
    Tools = new List<string> { "*" },
}

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

# If the server is blocked
xattr -d com.apple.quarantine /path/to/mcp-server

Homebrew-Pfade

import { MCPStdioServerConfig } from "@github/copilot-sdk";

const mcpServers: Record<string, MCPStdioServerConfig> = {
  "my-server": {
    command: "/opt/homebrew/bin/node",
    args: ["/path/to/server.js"],
    tools: ["*"],
  },
};

// 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

chmod +x /path/to/mcp-server

Fehlende gemeinsame Bibliotheken

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

#!/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:

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:

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:

// 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 usw.)
  • Vollständige MCP-Serverkonfiguration (redact secrets)
  • Ergebnis des manuellen initialize Tests
  • Ergebnis des manuellen tools/list Tests
  • Debugprotokolle aus DEM SDK
  • Fehlermeldungen

Siehe auch