# MCP Debug Server

**⚠️ EXPERIMENTAL PROJECT** - This is an experimental implementation. Use at your own risk.

An MCP (Model Context Protocol) server that provides Claude with direct debugging capabilities by leveraging existing Debug Adapter Protocol (DAP) implementations in major debuggers.

## Installation

### Global Installation
```bash
npm install -g mcp-debug-server
```

### Run with npx (no installation required)
```bash
npx mcp-debug-server
```

## Configuration

Add to your Claude Desktop configuration (`claude_desktop_config.json`):

**For global installation:**
```json
{
  "mcpServers": {
    "debug": {
      "command": "mcp-debug-server",
      "args": []
    }
  }
}
```

**For npx usage:**
```json
{
  "mcpServers": {
    "debug": {
      "command": "npx",
      "args": ["mcp-debug-server"]
    }
  }
}
```

## Features

This MCP server provides Claude with 11 debugging tools that work with native debuggers:

- **✅ Go debugging**: Complete implementation via `dlv dap`
- **🚧 Python/Node.js support**: Requires plugin architecture (planned)
- **Session management**: Start/stop debug sessions with automatic cleanup
- **Breakpoint control**: Set conditional breakpoints in source files
- **Execution control**: Continue, step over, step into, step out
- **Variable inspection**: Examine local and global variables
- **Expression evaluation**: Evaluate expressions in debugger context
- **Stack trace analysis**: Get complete call stacks

## Architecture

```
Claude → MCP Server → Direct TCP Connection → DAP Server (dlv/debugpy/node) → Debugger
```

The server acts as a bridge between Claude and existing Debug Adapter Protocol implementations, eliminating the need for custom debugger integration.

## Supported Debuggers

### ✅ Currently Implemented
- **Go**: Uses `dlv dap --listen=:0` - Complete debugging workflow

### 🚧 Planned (Plugin Architecture Required)
- **Python**: Uses `python -m debugpy --listen localhost:0 --wait-for-client` 
- **Node.js**: Uses `node --inspect=0.0.0.0:0`

*Note: Python and Node.js support require implementing a plugin architecture to handle language-specific DAP behaviors. See [docs/PLAN.md](docs/PLAN.md) for details.*

## Available Tools

1. **start_debug_session** - Spawn DAP server and return session ID
2. **set_breakpoint** - Set breakpoint with optional condition  
3. **start_execution** - Begin program execution after breakpoints are set
4. **continue_execution** - Continue program execution
5. **step_over** - Step over current line
6. **step_into** - Step into function call
7. **step_out** - Step out of current function
8. **get_stack_trace** - Get complete call stack
9. **get_variables** - Get variable values in current scope
10. **evaluate_expression** - Evaluate expressions in debugger context
11. **stop_debug_session** - Clean session shutdown

## Usage Example

Once configured, Claude can autonomously debug programs:

```
User: "Debug my Go HTTP server - it's returning 500 errors"

Claude workflow:
1. Starts debug session with the Go program
2. Sets breakpoint in error handler
3. Continues execution while user triggers HTTP request
4. Examines variables when breakpoint hits
5. Evaluates expressions to understand the issue
6. Provides fix and stops debug session
```

## Development Status

**✅ Go Debugging Implementation Complete**
- Complete MCP server with 11 debugging tools
- Full DAP protocol implementation with TCP communication
- Go debugger integration with `dlv dap` - all features working
- Comprehensive session management and error handling
- Integration tests demonstrating full debugging workflow
- Dynamic port assignment and process cleanup

**🚧 Multi-Language Support** 
- Plugin architecture needed for Python/Node.js support
- Each language has unique DAP implementation quirks
- See [docs/PLAN.md](docs/PLAN.md) for architecture details

## Prerequisites

### For Go Debugging (Currently Supported)
- **Go**: `go install github.com/go-delve/delve/cmd/dlv@latest`

### For Future Language Support
- **Python**: `pip install debugpy` *(requires plugin architecture)*
- **Node.js**: Built-in (Node.js 8+) *(requires plugin architecture)*

## License

MIT

## Contributing

This project follows the Debug Adapter Protocol specification. All DAP messages must conform to the official JSON schema at: https://microsoft.github.io/debug-adapter-protocol/debugAdapterProtocol.json