debugpy-mcp

MCP server for debugpy integration via Debug Adapter Protocol (DAP). Uses attach-based debugging (not launch-based) to connect to running Python applications. Enables Claude Code to set breakpoints, step through code, evaluate expressions, and inspect variables.

Note: This project is distinct from Microsoft's DebugMCP which focuses on launch-based debugging. debugpy-mcp specializes in attach-based debugging for already-running processes.

Architecture

Claude Code
    ↓ (MCP protocol - JSON-RPC over stdio)
debugpy-mcp Server (this)
    ↓ (DAP protocol - JSON-RPC over TCP)
debugpy (port 5678)
    ↓ (attach to running process)
Python Application (Evennia)

Features

• Breakpoint Management: Set, remove, and list breakpoints
• Code Stepping: Step over, into, and out of functions
• Expression Evaluation: Evaluate arbitrary Python expressions in current context
• Variable Inspection: View local, global, or all variables
• Stack Traces: Get current call stack information
• Session Management: Start, stop, and restart debug sessions

Prerequisites

1. Node.js (v18 or later)
2. debugpy installed in target Python environment:

   pip install debugpy
   

3. Evennia with debugpy enabled (see evennia/contrib/utils/debugpy)

Installation

1. Install dependencies

cd .mcp-servers/debugpy-mcp
npm install

2. Build the server

npm run build

3. Configure Claude Code

Add to your Claude Code MCP configuration (typically ~/.config/claude-code/mcp.json or similar):

{
  "mcpServers": {
    "debugpy-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/.mcp-servers/debugpy-mcp/dist/index.js"
      ],
      "env": {
        "DEBUGPY_HOST": "localhost",
        "DEBUGPY_PORT": "5678"
      }
    }
  }
}

Important: Use the absolute path to your dist/index.js file.

4. Start debugpy in Evennia

In your Evennia game, run:

debugpy

You should see:

Debugpy listening. Waiting for client connection...

Usage

Basic Workflow

1. Set breakpoints in the code you want to debug
2. Start a debug session (connects to debugpy)
3. Trigger the code path (run a command in Evennia)
4. Inspect state when execution pauses at breakpoint
5. Step through code or continue execution

Example: Debugging an Evennia Command

# 1. Set a breakpoint in the command file
mcp__debugpy_mcp__add_breakpoint(
    fileFullPath="evennia/commands/default/general.py",
    lineContent="        if not self.args:"
)

# 2. Start debug session
mcp__debugpy_mcp__start_debugging(
    fileFullPath="evennia/commands/default/general.py"
)

# 3. Trigger the command in Evennia (run 'look' command via telnet/webclient)

# 4. When breakpoint hits, inspect variables
mcp__debugpy_mcp__get_variables_values(scope="local")

# 5. Evaluate expressions
mcp__debugpy_mcp__evaluate_expression(expression="self.caller.key")

# 6. Step through code
mcp__debugpy_mcp__step_over()

# 7. Continue execution
mcp__debugpy_mcp__continue_execution()

Available MCP Tools

Session Management

start_debugging

Start a debug session for a source code file.

Parameters:

• fileFullPath (string, required): Full path to the source file
• workingDirectory (string, optional): Working directory

Example:

mcp__debugpy_mcp__start_debugging(
    fileFullPath="/path/to/evennia/commands/default/general.py"
)

stop_debugging

Stop the current debug session.

Example:

mcp__debugpy_mcp__stop_debugging()

restart_debugging

Restart the current debug session.

Example:

mcp__debugpy_mcp__restart_debugging()

Breakpoint Management

add_breakpoint

Add a breakpoint at a specific line.

Parameters:

• fileFullPath (string, required): Full path to the file
• lineContent (string, required): Exact line content (whitespace matters!)

Example:

mcp__debugpy_mcp__add_breakpoint(
    fileFullPath="evennia/commands/command.py",
    lineContent="        if not self.args:"
)

Critical: lineContent must match the exact code text including all whitespace. This is used to find the correct line number.

remove_breakpoint

Remove a breakpoint from a specific line.

Parameters:

• fileFullPath (string, required): Full path to the file
• line (number, required): Line number (1-based)

Example:

mcp__debugpy_mcp__remove_breakpoint(
    fileFullPath="evennia/commands/command.py",
    line=42
)

list_breakpoints

List all active breakpoints.

Returns: JSON array of breakpoint objects.

Example:

mcp__debugpy_mcp__list_breakpoints()

Code Stepping

step_over

Execute the next line of code (step over function calls).

Example:

mcp__debugpy_mcp__step_over()

step_into

Step into the current function call.

Example:

mcp__debugpy_mcp__step_into()

step_out

Step out of the current function.

Example:

mcp__debugpy_mcp__step_out()

continue_execution

Continue execution until next breakpoint.

Example:

mcp__debugpy_mcp__continue_execution()

Variable Inspection

get_variables_values

Get variables and their values at the current execution point.

Parameters:

• scope (string, optional): Variable scope - 'local', 'global', or 'all' (default)

Returns: JSON array of variable objects.

Example:

# Get all variables
mcp__debugpy_mcp__get_variables_values(scope="all")

# Get only local variables
mcp__debugpy_mcp__get_variables_values(scope="local")

evaluate_expression

Evaluate an arbitrary Python expression in the current debug context.

Parameters:

• expression (string, required): Python expression to evaluate

Returns: String representation of the result.

Example:

# Simple expression
mcp__debugpy_mcp__evaluate_expression(expression="self.caller.key")

# Complex expression
mcp__debugpy_mcp__evaluate_expression(expression="""
from evennia.contrib.utils.claudecode import debug_helpers as dh
context = dh.get_breakpoint_context()
context['character']['location']
""")

get_stack_trace

Get the current call stack.

Returns: JSON array of stack frame objects.

Example:

mcp__debugpy_mcp__get_stack_trace()

Integration with Evennia Debugger Loop

This MCP server works seamlessly with Evennia's debugger loop script (evennia/contrib/utils/claudecode/debugger_loop.py).

Automated Testing Pattern

1. Start the debugger loop (in Evennia):

   from evennia.contrib.utils.claudecode.debugger_loop import start_debugger_loop
   start_debugger_loop()
   

2. Set strategic breakpoints (in Claude Code):

   # Breakpoint #1: Command injection
   mcp__debugpy_mcp__add_breakpoint(
       fileFullPath="evennia/contrib/utils/claudecode/debugger_loop.py",
       lineContent="        if self.db.pending_command is None:"
   )
   
   # Breakpoint #2: Output capture
   mcp__debugpy_mcp__add_breakpoint(
       fileFullPath="evennia/contrib/utils/claudecode/debugger_loop.py",
       lineContent="        pass  # This line exists solely as a breakpoint target"
   )
   

3. Automated testing loop:

   # Wait for breakpoint #1 (happens every 2 seconds)
   # Inject command
   mcp__debugpy_mcp__evaluate_expression(
       expression="self.db.pending_command = 'look'"
   )
   
   # Continue to breakpoint #2
   mcp__debugpy_mcp__continue_execution()
   
   # Read output
   mcp__debugpy_mcp__evaluate_expression(
       expression="self.db.last_output"
   )
   
   # Repeat for next command...
   

See the Debugger Loop documentation for more details.

Troubleshooting

"Not connected to debugger"

Cause: debugpy is not running or the MCP server hasn't connected yet.

Solution:

1. Ensure debugpy is running in Evennia: debugpy command
2. Start a debug session: mcp__debugpy_mcp__start_debugging(...)

"Failed to add breakpoint"

Cause: The lineContent doesn't match any line in the file.

Solution:

• Verify the file path is correct
• Copy the exact line content including all whitespace
• Make sure you're using the first executable line in a function (not the def line)

"Connection refused"

Cause: debugpy is not listening on the configured port.

Solution:

1. Check debugpy is running: debugpy command in Evennia
2. Verify port configuration matches (default: 5678)
3. Check DEBUGPY_PORT environment variable in MCP config

"Expression evaluation failed"

Cause: Code is not paused at a breakpoint.

Solution:

• DAP requires an active stack frame to evaluate expressions
• Ensure execution is paused at a breakpoint before evaluating

Development

Building

npm run build

Watch mode (auto-rebuild on changes)

npm run watch

Testing manually

You can test the server directly:

# Start the server
node dist/index.js

# It will wait for MCP protocol messages on stdin
# Send JSON-RPC requests manually for testing

Protocol Details

MCP Protocol

This server uses the Model Context Protocol (MCP) to communicate with Claude Code:

• Transport: stdio (JSON-RPC over standard input/output)
• Message format: JSON-RPC 2.0

DAP Protocol

The server connects to debugpy using the Debug Adapter Protocol (DAP):

• Transport: TCP socket (default: localhost:5678)
• Message format: JSON with Content-Length headers
• Protocol: DAP v1.68

References

• Model Context Protocol
• Debug Adapter Protocol
• debugpy
• vscode-debugadapter-node

License

MIT