Delphi MCP Debugger: Complete Workflow & Demonstration

[WladiD]

This guide demonstrates how to effectively use the Delphi MCP Debugger to establish a debugging session, inspect state, and trace execution. It includes a ready-to-use prompt for your AI assistant and a step-by-step breakdown of the typical workflow.

🎯 Example Prompt for the AI Assistant

You can use the following prompt to instruct your AI assistant to start a debugging session and investigate an issue:

Please investigate the crash happening in `MyUnit.pas` around line 42 when processing user input. 
Here is your workflow:
1. Set a breakpoint in `MyUnit.pas` at line 40 (before the suspect code).
2. Start a debug session for `MyApp.exe`.
3. Wait until the process is paused at the breakpoint.
4. Retrieve the stack trace and the stack slots to inspect the local variables.
5. Step over the next few lines, checking the stack slots after each step to see how the variables mutate.
6. If an exception occurs, inspect the registers and assembly around the crash site.
7. Terminate the session and summarize your findings.

---

🛠️ Complete Debugging Workflow

Here is how the AI assistant interacts with the MCP Debugger under the hood to execute a debugging session.

1. Preparation: Setting Breakpoints & Exceptions

Before launching the executable, we set up our breakpoints and configure exception handling.

Tools used:

• mcp_DptDelphiDebugger_set_breakpoint(unit="MyUnit.pas", line=40)
• (Optional) mcp_DptDelphiDebugger_ignore_exception(class_name="EConvertError") to ignore known, non-critical exceptions.
• mcp_DptDelphiDebugger_list_breakpoints() to verify the breakpoints are set (they will be in "pending" state).

2. Starting the Session

Launch the executable. The debugger will automatically attach and apply the pending breakpoints once the modules are loaded.

Tool used:

• mcp_DptDelphiDebugger_start_debug_session(executable_path="C:\Path\To\MyApp.exe")

3. Waiting for Execution to Pause

After starting the session or issuing a continue/step command, the execution happens asynchronously. We must wait for the debugger to hit our breakpoint.

Tool used:

• mcp_DptDelphiDebugger_wait_until_paused(timeout_ms=5000)
  (Returns state "paused" with the current unit and line. If the timeout expires before pausing, it returns the current state, e.g., "running". In that case, you may need to wait again or pause the process manually.)

4. Inspecting the Application State

Once paused, we can inspect the call stack, local variables (via stack slots), and CPU registers.

Tools used:

• mcp_DptDelphiDebugger_get_stack_trace(): See how we reached the current line.
• mcp_DptDelphiDebugger_get_stack_slots(): View heuristics-based interpretation of local variables and parameters on the stack (Strings, Integers, Pointers).
• mcp_DptDelphiDebugger_get_registers(): View CPU registers (EAX, EBX, EIP, etc.) for low-level analysis.

5. Stepping Through Code

To observe how the state changes, we step through the code line by line.

Tools used:

• mcp_DptDelphiDebugger_step_over(): Execute the current line and pause at the next line in the same routine.
• mcp_DptDelphiDebugger_wait_until_paused(): Wait for the step to complete.
• mcp_DptDelphiDebugger_get_stack_slots(): Re-evaluate local variables to see what changed.

6. Deep Dive Inspections (If needed)

If the source-level information isn't enough (e.g., memory corruption, pointer issues), we can drop down to memory and assembly.

Tools used:

• mcp_DptDelphiDebugger_read_memory(address="00401000", size=32): Dump raw bytes.
• mcp_DptDelphiDebugger_get_proc_asm(): Review the machine code of the current procedure.

7. Resuming or Terminating

Once the bug is identified, we can either let the program run its course or terminate it immediately.

Tools used:

• mcp_DptDelphiDebugger_terminate_debug_session(): Kills the debugged process.
• (Alternative) mcp_DptDelphiDebugger_continue() followed by mcp_DptDelphiDebugger_stop_debug_session() to detach and let the process run normally.