Go Delve Debugger MCP Server

An MCP server that allows LLMs to interact with the Delve Go debugger.

Description

This project implements a Model Context Protocol (MCP) server that integrates with the Delve Go debugger to enable AI assistants to debug Go applications. The server exposes a set of tools that allow LLMs to start, control, and interact with debug sessions.

You can find a working example at EXAMPLE.md.

Features

• Start debug sessions for Go programs
• Set breakpoints in code
• Step through code (next, step in, step out)
• Evaluate expressions in the context of a debug session
• Inspect variables and stack traces
• Manage multiple debug sessions

Installation

Prerequisites

• Go 1.21 or higher
• Delve debugger installed (`go install github.com/go-delve/delve/cmd/dlv@latest`)

Install

go install github.com/xhd2015/dlv-mcp/cmd/dlv-mcp@latest

Usage

Start the MCP server:

dlv-mcp --listen :9097

Then configure MCP Server at `http://localhost:9097/sse`, in Cursor or any MCP client.

Inspect the MCP Server

bunx @modelcontextprotocol/inspector dlv-mcp

Available Tools

Debug Session Management

• `start_debug`: Start a new debug session
  • `program`: Path to Go program to debug
  • `args`: Command line arguments for the program (optional)
  • `mode`: Debug mode (`debug`, `test`, or `exec`, default: `debug`)

• `terminate_debug`: Terminate a debug session
  • `session_id`: ID of the debug session to terminate

• `list_debug_sessions`: List active debug sessions

Breakpoint Management

• `set_breakpoint`: Set a breakpoint in a debug session
  • `session_id`: ID of the debug session
  • `file`: Source file to set breakpoint in (absolute path)
  • `line`: Line number to set breakpoint at

Execution Control

• `continue`: Continue execution in a debug session
  • `session_id`: ID of the debug session

• `next`: Step over current line in a debug session
  • `session_id`: ID of the debug session

• `step_in`: Step into function in a debug session
  • `session_id`: ID of the debug session

• `step_out`: Step out of function in a debug session
  • `session_id`: ID of the debug session

Inspection

• `evaluate`: Evaluate an expression in a debug session
  • `session_id`: ID of the debug session
  • `expression`: Expression to evaluate
  • `frame_id`: Stack frame ID (optional, default: 0)

Example Workflow

1. Start a debug session:

start_debug program=/path/to/program.go

2. Set a breakpoint:

set_breakpoint session_id=session-123456 file=/path/to/program.go line=15

3. Continue to breakpoint:

continue session_id=session-123456

4. Evaluate an expression:

evaluate session_id=session-123456 expression="myVariable"

5. Step over a line:

next session_id=session-123456

6. Terminate the session:

terminate_debug session_id=session-123456

Architecture

The server is built using the following components:

• MCP Server Layer: Implements the Model Context Protocol using mark3labs/mcp-go
• DAP Client Layer: Communicates with Delve's DAP server
• Session Management: Maintains and manages debug sessions

Inspect The MCP Server

bunx @modelcontextprotocol/inspector go run ./cmd/dlv-mcp

Using the Demo Client

We've created a demo client that shows how to use the debugger-mcp server programmatically. The demo:

1. Starts the MCP server

2. Launches a debug session for `./testdata/hello.go`

3. Tries to set a breakpoint and execute debugging commands

4. Properly terminates the session and server

To run the demo:

go run ./demo/main.go

The demo client showcases how to:

• Start and communicate with the MCP server using JSON-RPC
• Send tool calls using the correct format
• Parse and handle responses
• Deal with errors gracefully

Check out `demo/main.go` and `demo/README.md` for more details on the implementation.

License

MIT License