mcp-debugger

MCP-Server für sprachübergreifendes Debugging – verleihen Sie Ihren KI-Agenten Debugging-Superkräfte 🚀

🎯 Übersicht

mcp-debugger ist ein Model Context Protocol (MCP)-Server, der Debugging-Tools als strukturierte API-Aufrufe bereitstellt. Er ermöglicht es KI-Agenten, mittels des Debug Adapter Protocol (DAP) schrittweises Debugging in mehreren Programmiersprachen durchzuführen.

🆕 Version 0.19.0: Java-Debugging via JDI-Bridge mit Start- und Attach-Modi! Sowie Go-Debugging mit Delve.

🆕 Version 0.17.0: Rust-Debugging-Unterstützung! Debuggen Sie Rust-Programme mit CodeLLDB auf Linux/macOS, inklusive Cargo-Projekten, asynchronem Code und vollständiger Variableninspektion – zudem geben Schritt-Befehle jetzt den aktiven Quellkontext zurück, sodass Agenten automatisch ihre Position beibehalten.

🔥 Version 0.16.0: JavaScript/Node.js-Debugging-Unterstützung! Volle Debugging-Funktionen mit gebündeltem js-debug, TypeScript-Unterstützung und null Laufzeitabhängigkeiten durch verbesserte npx-Distribution.

🎬 Demo-Video: Sehen Sie den Debugger in Aktion!

Aufnahme läuft - Dies zeigt einen KI-Agenten, der den Variablen-Tausch-Fehler in Echtzeit entdeckt und behebt

✨ Hauptmerkmale

• 🌐 Mehrsprachige Unterstützung – Sauberes Adapter-Muster für jede Sprache

• 🐍 Python-Debugging via debugpy – Volle DAP-Protokoll-Unterstützung

• 🟨 JavaScript (Node.js)-Debugging via js-debug – Der bewährte Debugger von VSCode

• 🦀 Rust-Debugging via CodeLLDB – Debuggen von Rust- & Cargo-Projekten (Linux/macOS/Windows mit GNU-Toolchain)

• 🐹 Go-Debugging via Delve – Volle DAP-Unterstützung für Go-Programme

• ☕ Java-Debugging via JDI-Bridge – Start- und Attach-Modi mit JDK 21+

• 🔷 .NET/C#-Debugging via netcoredbg – Debuggen von .NET-Anwendungen mit voller DAP-Unterstützung

WARNUNG: Verwenden Sie unter Windows die GNU-Toolchain für eine vollständige Variableninspektion. Führen Sie mcp-debugger check-rust-binary <path-to-exe> aus, um Ihren Build zu überprüfen, und lesen Sie Rust Debugging on Windows für detaillierte Anleitungen. HINWEIS: Das veröffentlichte npm-Paket enthält die Linux x64 CodeLLDB-Laufzeitumgebung, um die Größenbeschränkungen der Registry einzuhalten. Unter macOS oder Windows verweisen Sie die Umgebungsvariable CODELLDB_PATH auf eine bestehende CodeLLDB-Installation (z. B. aus der VSCode-Erweiterung) oder klonen Sie das Repo und führen Sie pnpm --filter @debugmcp/adapter-rust run build:adapter aus, um Ihre Plattform-Binärdateien lokal zu vendoren.

Windows Rust-Setup-Skript

Wenn Sie unter Windows den schnellsten Weg zu einer funktionierenden GNU-Toolchain + dlltool-Konfiguration suchen, führen Sie aus:

pwsh scripts/setup/windows-rust-debug.ps1

Das Skript installiert die stable-gnu-Toolchain (via rustup), richtet dlltool.exe ein (bevorzugt MSYS2/MinGW, falls verfügbar, andernfalls wird die in rustup enthaltene Kopie verwendet), baut die gebündelten Rust-Beispiele und führt standardmäßig die Rust-Smoke-Tests aus. Fügen Sie -SkipTests hinzu, um das Ausführen von Tests zu überspringen. Fügen Sie -UpdateUserPath hinzu, wenn der dlltool-Pfad dauerhaft in Ihre Benutzer-PATH/DLLTOOL-Variablen übernommen werden soll.

Das Skript versucht außerdem, eine MSYS2-basierte MinGW-w64-Toolchain bereitzustellen (via winget + pacman), damit cargo +stable-gnu über einen voll funktionsfähigen dlltool/ld/as-Stack verfügt. Wenn MSYS2 bereits installiert ist, wird es einfach wiederverwendet; andernfalls werden Sie durch die Installation geführt (oder gewarnt, damit Sie sie manuell installieren können).

• 🧪 Mock-Adapter für Tests – Testen ohne externe Abhängigkeiten

• 🔌 STDIO- und SSE-Transportmodi – Funktioniert mit jedem MCP-Client

• 📦 Null Laufzeitabhängigkeiten – Eigenständige Bundles via esbuild + tsup

• ⚡ npx-bereit – Direkt ausführen mit npx @debugmcp/mcp-debugger – keine Installation erforderlich

• 📊 1266+ Tests bestehen – kampferprobt durch End-to-End-Tests

• 🐳 Docker- und npm-Pakete – Überall bereitstellbar

• 🤖 Für KI-Agenten gebaut – Strukturierte JSON-Antworten für einfaches Parsen

• 🛡️ Pfadvalidierung – Verhindert Abstürze durch nicht existierende Dateien

• 📝 KI-bewusster Zeilenkontext – Intelligente Breakpoint-Platzierung mit Code-Kontext

🚀 Schnellstart

Für MCP-Clients (Claude Desktop, etc.)

Fügen Sie dies zu Ihrer MCP-Konfiguration hinzu:

{
  "mcpServers": {
    "mcp-debugger": {
      "command": "node",
      "args": ["C:/path/to/mcp-debugger/dist/index.js", "stdio", "--log-level", "debug", "--log-file", "C:/path/to/logs/debug-mcp-server.log"],
      "disabled": false,
      "autoApprove": ["create_debug_session", "set_breakpoint", "get_variables"]
    }
  }
}

Für Claude Code CLI

Für Benutzer von Claude Code stellen wir ein automatisiertes Installationsskript bereit:

Voraussetzung: Die Claude CLI muss installiert und in Ihrem PATH verfügbar sein, bevor das Installationsskript ausgeführt wird. Siehe Claude Code-Dokumentation für Installationsanweisungen.

# Clone the repository
git clone https://github.com/debugmcp/mcp-debugger.git
cd mcp-debugger

# Run the installation script
./scripts/install-claude-mcp.sh

# Verify the connection (use 'claude mcp list' if claude is on your PATH)
claude mcp list

Wichtig: Das stdio-Argument ist erforderlich, um zu verhindern, dass Konsolenausgaben das JSON-RPC-Protokoll beschädigen. Siehe CLAUDE.md für detaillierte Einrichtung und Fehlerbehebung.

Verwendung von Docker

docker run -v $(pwd):/workspace debugmcp/mcp-debugger:latest

⚠️ Das Docker-Image enthält Python-, JavaScript-, Go-, Java- und .NET-Adapter. Rust-Debugging erfordert lokale, SSE- oder gepackte Deployments, bei denen der Adapter neben Ihrer Toolchain läuft. Hinweis: Adapter werden zur Laufzeit dynamisch geladen — nur diejenigen, deren Toolchain installiert und erkannt wurde, werden von list_supported_languages als verfügbar gemeldet.

Verwendung von npm

npm install -g @debugmcp/mcp-debugger
mcp-debugger --help

Oder verwenden Sie es ohne Installation via npx:

npx @debugmcp/mcp-debugger --help

📸 Screenshot: MCP-Integration in Aktion

Dieser Screenshot zeigt die Echtzeit-MCP-Protokollkommunikation mit Tool-Aufrufen und JSON-Antworten, die zwischen dem KI-Agenten und dem Debugger fließen.

📚 Funktionsweise

mcp-debugger stellt Debugging-Operationen als MCP-Tools bereit, die mit strukturierten JSON-Parametern aufgerufen werden können:

// Tool: create_debug_session
// Request:
{
  "language": "python",  // or "javascript", "rust", "go", "java", "dotnet", or "mock" for testing
  "name": "My Debug Session"
}
// Response:
{
  "success": true,
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "message": "Created python debug session: My Debug Session"
}

📸 Screenshot: Aktive Debugging-Sitzung

Dieser Screenshot zeigt den Debugger, der an einem Breakpoint pausiert ist, mit dem Stack-Trace im linken Bereich, lokalen Variablen im rechten Bereich und dem Quellcode mit Zeilenhervorhebung in der Mitte.

🛠️ Verfügbare Tools

📸 Screenshot: Multi-Sitzungs-Debugging

Dieser Screenshot zeigt den Debugger bei der Verwaltung mehrerer gleichzeitiger Debug-Sitzungen und demonstriert, wie KI-Agenten verschiedene Skripte gleichzeitig mit isolierter Sitzungsverwaltung debuggen können.

🏗️ Architektur: Dynamisches Laden von Adaptern

Version 0.10.0 führt ein sauberes Adapter-Muster ein, das sprachunabhängige Kernfunktionen von sprachspezifischen Implementierungen trennt:

┌─────────────┐     ┌────────────────┐     ┌──────────────┐     ┌─────────────────┐
│ MCP Client  │────▶│ DebugMcpServer │────▶│SessionManager│────▶│ AdapterRegistry │
└─────────────┘     └────────────────┘     └──────────────┘     └─────────────────┘
                            │                      │
                            ▼                      ▼
                    ┌──────────────┐      ┌─────────────────┐
                    │ ProxyManager │◀─────│ Language Adapter│
                    └──────────────┘      └─────────────────┘
                                                   │
                          ┌──────────────┴──────────────────────────────────────────┐
                          │                                                          │
              ┌───────────┼───────────┬───────────┬───────────┬───────────┐          │
              │           │           │           │           │           │          │
        ┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐┌─────▼────┐
        │Python    ││JavaScript││Rust      ││Go        ││Java      ││Dotnet    ││Mock      │
        │Adapter   ││Adapter   ││Adapter   ││Adapter   ││Adapter   ││Adapter   ││Adapter   │
        └──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────────┘└──────���───┘

Hinzufügen von Sprachunterstützung

Möchten Sie Debugging-Unterstützung für Ihre Lieblingssprache hinzufügen? Lesen Sie den Adapter-Entwicklungsleitfaden!

💡 Beispiel: Debuggen von Python-Code

Hier ist ein vollständiges Beispiel für eine Debugging-Sitzung:

# buggy_swap.py
def swap_variables(a, b):
    a = b  # Bug: loses original value of 'a'
    b = a  # Bug: 'b' gets the new value of 'a'
    return a, b

Schritt 1: Debug-Sitzung erstellen

// Tool: create_debug_session
// Request:
{
  "language": "python",
  "name": "Swap Bug Investigation"
}
// Response:
{
  "success": true,
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "message": "Created python debug session: Swap Bug Investigation"
}

Schritt 2: Breakpoints setzen

// Tool: set_breakpoint
// Request:
{
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "file": "buggy_swap.py",
  "line": 2
}
// Response:
{
  "success": true,
  "breakpointId": "28e06119-619e-43c0-b029-339cec2615df",
  "file": "C:\\path\\to\\buggy_swap.py",
  "line": 2,
  "verified": false,
  "message": "Breakpoint set at C:\\path\\to\\buggy_swap.py:2"
}

Schritt 3: Debugging starten

// Tool: start_debugging
// Request:
{
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "scriptPath": "buggy_swap.py"
}
// Response:
{
  "success": true,
  "state": "paused",
  "message": "Debugging started for buggy_swap.py. Current state: paused",
  "data": {
    "message": "Debugging started for buggy_swap.py. Current state: paused",
    "reason": "breakpoint"
  }
}

Schritt 4: Variablen untersuchen

Zuerst die Scopes abrufen:

// Tool: get_scopes
// Request:
{
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "frameId": 3
}
// Response:
{
  "success": true,
  "scopes": [
    {
      "name": "Locals",
      "variablesReference": 5,
      "expensive": false,
      "presentationHint": "locals",
      "source": {}
    },
    {
      "name": "Globals", 
      "variablesReference": 6,
      "expensive": false,
      "source": {}
    }
  ]
}

Dann die lokalen Variablen abrufen:

// Tool: get_variables
// Request:
{
  "sessionId": "a4d1acc8-84a8-44fe-a13e-28628c5b33c7",
  "scope": 5
}
// Response:
{
  "success": true,
  "variables": [
    {"name": "a", "value": "10", "type": "int", "variablesReference": 0, "expandable": false},
    {"name": "b", "value": "20", "type": "int", "variablesReference": 0, "expandable": false}
  ],
  "count": 2,
  "variablesReference": 5
}

📸 Screenshot: Variableninspektion enthüllt den Fehler

Dieser Screenshot zeigt den TUI-Visualizer nach dem Überspringen von Zeile 4, wo beide Variablen fälschlicherweise den Wert 20 anzeigen, was den Variablen-Tausch-Fehler deutlich macht. Der linke Bereich zeigt den Ausführungsstatus, die Mitte den hervorgehobenen Code und der rechte Bereich die falschen Variablenwerte.

📖 Dokumentation

• 📘 Tool-Referenz – Vollständige API-Dokumentation

• 🚦 Erste Schritte – Einrichtung für Erstbenutzer

• 🏗️ Architektur-Übersicht – Mehrsprachiges Design

• 🔧 Adapter-Entwicklung – Neue Sprachen hinzufügen

• 🔌 Architektur des dynamischen Ladens – Laufzeit-Erkennung, Lazy Loading, Caching

• 🧩 Adapter-API-Referenz – Verträge für Adapter, Factory, Loader und Registry

• 🔄 Migrationsleitfaden – Upgrade auf v0.15.0 (dynamisches Laden)

• 🐍 Python-Debugging-Leitfaden – Python-spezifische Funktionen

• 🟨 JavaScript-Debugging-Leitfaden – JavaScript/TypeScript-Funktionen

• 🐹 Go-Debugging-Leitfaden – Go-Debugging mit Delve

• ☕ Java-Debugging-Leitfaden – Java-Debugging mit JDI-Bridge

• [Rust-Debugging unter Windows](docs/rust