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