mcp-debugger

# mcp-debugger

<div align="center">
  <img src="assets/logo.png" alt="MCP Debugger Logo - A stylized circuit board with debug breakpoints" width="400" height="400">
</div>

**A headless, agentic debugger over MCP — let your AI agents debug running programs in nine languages.**

[![CI](https://github.com/debugmcp/mcp-debugger/actions/workflows/ci.yml/badge.svg)](https://github.com/debugmcp/mcp-debugger/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/debugmcp/mcp-debugger/branch/main/graph/badge.svg)](https://codecov.io/gh/debugmcp/mcp-debugger)
[![npm version](https://img.shields.io/npm/v/@debugmcp/mcp-debugger.svg)](https://www.npmjs.com/package/@debugmcp/mcp-debugger)
[![Docker Pulls](https://img.shields.io/docker/pulls/debugmcp/mcp-debugger.svg)](https://hub.docker.com/r/debugmcp/mcp-debugger)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/debugmcp/mcp-debugger/badge)](https://scorecard.dev/viewer/?uri=github.com/debugmcp/mcp-debugger)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/13543/badge)](https://www.bestpractices.dev/projects/13543)

## 🎯 Overview

mcp-debugger is a Model Context Protocol (MCP) server that exposes step-through debugging as structured tool calls. It lets AI agents set breakpoints, inspect variables, evaluate expressions, and step through running programs across nine languages — driving real language debuggers through the Debug Adapter Protocol (DAP).

**No IDE required.** mcp-debugger runs anywhere Node.js runs: CI runners, Docker containers, Kubernetes pods, SSH boxes, and the sandboxes that cloud coding agents live in. It's the debugger for where IDEs can't go.

### When to use mcp-debugger vs an IDE-bound debug server

Microsoft's [DebugMCP](https://github.com/microsoft/DebugMCP) exposes VS Code's debugger over MCP and is a good choice when your agent works *inside* a running VS Code. The two projects make different structural trade-offs:

| | mcp-debugger | microsoft/DebugMCP |
|---|---|---|
| Runs headless (CI, containers, k8s, cloud agents) | ✅ standalone Node process | ❌ requires a running VS Code |
| Transports | stdio + Streamable HTTP | Streamable HTTP (localhost) |
| Distribution | npx, npm, Docker image | VS Code Marketplace extension |
| Remote attach without an IDE | ✅ debugpy / rdbg / JDWP, incl. pods via port-forward | ❌ |
| Per-session process isolation | ✅ one proxy process per session | shares the VS Code instance |
| Java hot-swap (`redefine_classes`) | ✅ | ❌ |
| Debuggee output as subscribable MCP resource | ✅ | ❌ |
| In-IDE debugging UX alongside the agent | ✅ read-only IDE mirror ([`expose_session`](docs/tool-reference.md#expose_session)) — the IDE joins the *agent's* live session | ✅ native |
| Logpoints without pausing (prod-safe value watching) | ✅ [`logMessage` breakpoints](docs/tool-reference.md#set_breakpoint) | ✅ via VS Code |
| Content/function-addressed breakpoints (`statement:`, `function:`, `expectedContent`) | ✅ agent-native addressing that survives edits | — |
| Secret redaction on by default | ✅ variable/evaluate/output masking + least-privilege mode | — |
| Kubernetes ephemeral debug sidecar (native attach-by-PID) | ✅ [`kubectl debug` flow](docs/kubernetes.md) | ❌ |
| C/C++ | ✅ via CodeLLDB (launch + attach-by-PID) | ✅ via VS Code extensions |
| COBOL | ✅ via GnuCOBOL + CodeLLDB (launch + attach-by-PID, COBOL-shaped variables) | — |
| PHP | ❌ | ✅ via VS Code extensions |
| Languages | Python, JS/TS, Ruby, Rust, Go, Java, .NET, C/C++, COBOL | Python, JS/TS, Ruby, Rust, Go, Java, .NET, C/C++, PHP |

If your agent runs in a terminal, a pipeline, or a cloud sandbox — or needs to attach to a process on another machine — you want mcp-debugger.

> 🆕 **v0.25.0** — **COBOL debugging** lands (GnuCOBOL + CodeLLDB, with COBOL-shaped variables, PERFORM-aware stepping and paragraph breakpoints), and **Rust and C/C++ work out of the box on every platform npm installs** now that CodeLLDB ships as per-platform packages. Also new: `mcp-debugger doctor`, a Kubernetes debugging recipe, an HTTP transport locked to `127.0.0.1` with Host/Origin checks, launch responses that say how a run ended, exit codes for Go and Docker JavaScript, and a lighter startup. See the [CHANGELOG](./CHANGELOG.md) for the full release history.

## ✨ Key Features

- 🌐 **Multi-language support** – Clean adapter pattern for any language
- 🐍 **Python debugging via debugpy** – Full DAP protocol support
- 💎 **Ruby debugging via rdbg** – Launch and attach workflows, including remote attach to containers and Kubernetes pods
- 🟨 **JavaScript (Node.js) debugging via js-debug** – VSCode's proven debugger
- 🦀 **Rust debugging via CodeLLDB** – Debug Rust & Cargo projects (Linux/macOS; Windows needs the GNU toolchain — see [Rust on Windows](docs/rust-debugging-windows.md))
- 🐹 **Go debugging via Delve** – Full DAP support for Go programs
- ☕ **Java debugging via JDI bridge** – Launch and attach modes with JDK 21+
- 🔷 **.NET/C# debugging via netcoredbg** – Debug .NET applications with full DAP support
- ⚙️ **C/C++ debugging via CodeLLDB** – Launch prebuilt binaries or lone source files (auto-compiled), attach by PID; core dumps and gdbserver/rr targets via config pass-through
- 🧮 **COBOL debugging via GnuCOBOL + CodeLLDB** – Launch `.cob`/`.cbl` sources (auto-compiled with `cobc`) or prebuilt executables, attach by PID; WORKING-STORAGE / LOCAL-STORAGE / LINKAGE scopes with DISPLAY, COMP, COMP-3 and 88-level values decoded, breakpoints in copybooks, statement-granular stepping, and a pause on libcob runtime errors (the S0C7/SSRANGE analogues) — built for mainframe-to-GnuCOBOL migrations ([guide](docs/cobol/README.md))
- 🧪 **Mock adapter for testing** – Test without external dependencies
- 🛰️ **Out-of-IDE & remote attach** – Attach over host/port to a process on another machine or inside a container (Python via debugpy, Ruby via rdbg, JavaScript via the V8 inspector, Java via JDWP) with source-path mapping, or by PID for native code (C/C++, COBOL). Python and Ruby attach *direct-connect* — the debug engine already runs inside the target, so no local Python or Ruby is needed; JavaScript, Java, .NET, C/C++ and COBOL spawn a local adapter instead; of those, only Java (a JDK) and .NET (netcoredbg) need a toolchain you install, since the JavaScript, C/C++ and COBOL debug engines ship with the package. `list_supported_languages` reports per-mode availability with reasons
- 🎯 **Breakpoints that survive edits** – Address by content (`statement: "total = sum(prices)"`), by symbol (`function: "main"`), or assert line content with `expectedContent`; anchors re-resolve across `restart_debugging` and weak matches warn loudly
- 🪵 **Logpoints** – `set_breakpoint` with `logMessage: "x={x}"` streams interpolated values into `get_output` without pausing — prod-safe value watching on hot paths
- 🧰 **Full breakpoint lifecycle** – `list_breakpoints` / `remove_breakpoint` / `clear_breakpoints` work live mid-run; `restart_debugging` relaunches with the same config and re-applies everything in one call
- 📡 **Buffered program output** – `get_output` returns debuggee stdout/stderr with a cursor, and each session exposes its transcript as a subscribable MCP resource
- 💥 **Crash-state debugging by default** – Launch sessions pause on uncaught exceptions with stack and locals live (`breakOnExceptions`; exception class/message surfaced via `lastStop`)
- 🪞 **Read-only IDE mirror** – `expose_session` opens a loopback, token-gated DAP endpoint so a human's IDE can inspect the agent's live session without taking control
- ☸️ **Kubernetes debugging** – port-forward attach for interpreted runtimes, `kubectl debug --target` + attach-by-PID for native processes ([recipe](docs/kubernetes.md), [turnkey manifests](examples/kubernetes/))
- 🔌 **STDIO and Streamable HTTP transports** – Works with any MCP client (legacy SSE transport is deprecated)
- 📦 **Zero-runtime dependencies** – Self-contained bundles via esbuild + tsup
- ⚡ **npx ready** – Run directly with `npx @debugmcp/mcp-debugger` - no installation needed
- 🐳 **Docker and npm packages** – Deploy anywhere
- 🤖 **Built for AI agents** – Structured JSON responses for easy parsing
- 🔒 **Secret redaction on by default** – Credential-shaped values (API keys, tokens, private keys) are masked as labeled placeholders in variable, evaluate, and output results before they reach the agent ([details](./docs/tool-reference.md#secret-redaction); opt out with `DEBUG_MCP_NO_REDACT=1`)
- 🛡️ **Path validation** – Prevents crashes from non-existent files
- 📝 **AI-aware line context** – Intelligent breakpoint placement with code context
- ✅ **Comprehensive test suite** – unit, integration, and end-to-end coverage across every adapter ([CI status](https://github.com/debugmcp/mcp-debugger/actions/workflows/ci.yml))

## 🧠 Agent Skill

Tools tell an agent *what* it can do; a skill teaches it *how to debug well*. This repo ships an [agent skill](skills/debugging/) covering the session golden path, root-cause discipline (bisection over line-by-line stepping), attach/remote recipes, and per-language quirks:

```bash
# Claude Code (user-level)
cp -r skills/debugging ~/.claude/skills/mcp-debugger
# Cross-agent directories (Copilot CLI and friends)
cp -r skills/debugging ~/.agents/skills/mcp-debugger
```

The server also serves condensed guidance in-band: MCP `instructions` on connect, plus a `debugging-workflow` prompt any MCP client can request. See [skills/debugging/README.md](skills/debugging/README.md) for details.

## 🎬 See It In Action

- **[Auto-debug failing CI tests](.github/actions/debug-failing-test/)** – a composite GitHub Action that launches mcp-debugger + an agent on a test failure and posts the root-cause analysis
- **[Sick pod walkthrough](examples/sick-pod/)** – attach to a misbehaving Python service in Kubernetes via port-forward ([tutorial](do