# Python Debugging with Debug MCP Server

The Debug MCP Server provides support for Python debugging through the [debugpy](https://github.com/microsoft/debugpy) library. This document explains how to use the Python debugging capabilities.

## Prerequisites

Before using the Python debugging features, ensure you have:

1. Python 3.7 or higher installed
2. The debugpy package installed:
   ```bash
   pip install debugpy
   ```

## Debugging Workflow

### 1. Create a Debug Session

First, create a Python debug session:

```
use_mcp_tool(
  tool_name="create_debug_session",
  arguments={
    "language": "python",
    "name": "My Python Debug Session"
  }
)
```

This returns a session ID that you'll use for all subsequent debugging commands.

### 2. Set Breakpoints

Set breakpoints in your code before starting execution:

```
use_mcp_tool(
  tool_name="set_breakpoint",
  arguments={
    "sessionId": "your-session-id",
    "file": "/path/to/your/script.py",
    "line": 10
  }
)
```

You can also set conditional breakpoints:

```
use_mcp_tool(
  tool_name="set_breakpoint",
  arguments={
    "sessionId": "your-session-id",
    "file": "/path/to/your/script.py",
    "line": 15,
    "condition": "x > 5"
  }
)
```

### 3. Start Debugging

Start debugging your Python script:

```
use_mcp_tool(
  tool_name="start_debugging",
  arguments={
    "sessionId": "your-session-id",
    "scriptPath": "/path/to/your/script.py",
    "args": ["--optional", "arguments"]
  }
)
```

### 4. Control Execution

When execution pauses at a breakpoint, you can:

#### Step Over (execute current line and pause at next line)
```
use_mcp_tool(
  tool_name="step_over",
  arguments={
    "sessionId": "your-session-id"
  }
)
```

#### Step Into (go into functions called on current line)
```
use_mcp_tool(
  tool_name="step_into",
  arguments={
    "sessionId": "your-session-id"
  }
)
```

#### Step Out (run until exiting current function)
```
use_mcp_tool(
  tool_name="step_out",
  arguments={
    "sessionId": "your-session-id"
  }
)
```

#### Continue (run until next breakpoint)
```
use_mcp_tool(
  tool_name="continue_execution",
  arguments={
    "sessionId": "your-session-id"
  }
)
```

#### Pause (pause a running program)
```
use_mcp_tool(
  tool_name="pause_execution",
  arguments={
    "sessionId": "your-session-id"
  }
)
```

### 5. Examine Program State

When paused, you can examine the program's state using the `get_stack_trace` -> `get_scopes` -> `get_variables` sequence. Each step returns numeric handles that feed into the next:

#### Step 1: Get the Stack Trace
```
use_mcp_tool(
  tool_name="get_stack_trace",
  arguments={
    "sessionId": "your-session-id"
  }
)
```
This returns stack frames, each with a numeric `id` (the frame ID).

#### Step 2: Get Scopes for a Frame
Use the `id` from the top stack frame:
```
use_mcp_tool(
  tool_name="get_scopes",
  arguments={
    "sessionId": "your-session-id",
    "frameId": 3
  }
)
```
This returns scopes (e.g., "Locals", "Globals"), each with a numeric `variablesReference`.

#### Step 3: Get Variables for a Scope
Use the `variablesReference` from a scope (not the frame ID):
```
use_mcp_tool(
  tool_name="get_variables",
  arguments={
    "sessionId": "your-session-id",
    "scope": 5
  }
)
```
The `scope` parameter is the numeric `variablesReference` from `get_scopes`.

#### Shortcut: Get Local Variables
For convenience, `get_local_variables` performs the full stack->scopes->variables traversal in a single call:
```
use_mcp_tool(
  tool_name="get_local_variables",
  arguments={
    "sessionId": "your-session-id"
  }
)
```

#### Evaluate Expressions
```
use_mcp_tool(
  tool_name="evaluate_expression",
  arguments={
    "sessionId": "your-session-id",
    "expression": "x + y * 2"
  }
)
```

#### View Stack Trace
```
use_mcp_tool(
  tool_name="get_stack_trace",
  arguments={
    "sessionId": "your-session-id"
  }
)
```

#### Get Source Context
```
use_mcp_tool(
  tool_name="get_source_context",
  arguments={
    "sessionId": "your-session-id",
    "file": "/path/to/your/script.py",
    "line": 15,
    "linesContext": 5
  }
)
```

### 6. Close the Session

When finished debugging, close the session:

```
use_mcp_tool(
  tool_name="close_debug_session",
  arguments={
    "sessionId": "your-session-id"
  }
)
```

## Debugging Tips

1. Always check if breakpoints are verified (some lines cannot have breakpoints, like blank lines)
2. If the debugger doesn't stop at a breakpoint, ensure the file path is correct and absolute
3. Use source context to see code around your current position
4. The stack trace shows the call hierarchy that led to the current position
5. Expressions are evaluated against the current paused debug context (current frame when available), with the evaluation context defaulting to `'variables'`
