Debug-MCP

# Feature Specification: Python Debugging MCP Tool **Feature Branch**: `[001-python-debug-tool]` **Created**: 2025-10-23 **Status**: Draft **Input**: User description: "I am planning to create an MCP tool for debugging Python. Currently, when using Copilot for development, if I ask it to fix a bug or an error in the project, it often resorts to methods like using print() for debugging or generating new debugging files. Instead of these methods, I want the Large Language Model (LLM) to be able to perform direct debugging operations—specifically, to use breakpoints (like a Python debugger), execute the code up to that line, and inspect the values of variables at that point. I want to develop an MCP tool that can achieve this functionality. Please ask me any questions, if any." ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Breakpoint Inspection Request (Priority: P1) When a developer uses Copilot to understand a failing Python routine, the LLM can launch a debug session, add a breakpoint at the requested file and line, run the program, and return the variable values at the pause so the developer can decide what to do next. **Why this priority**: Direct visibility into runtime state is the core value that reduces time spent on trial-and-error debugging. **Independent Test**: Trigger a single breakpoint request on a Python script with a known defect and verify the tool returns the expected variable snapshot without needing other stories. **Acceptance Scenarios**: 1. **Given** a Python script with an accessible breakpoint line, **When** the LLM requests a breakpoint inspection, **Then** the tool executes the script, pauses at the line, and returns local variables with their values. 2. **Given** a request that includes file path, line number, and optional input parameters, **When** the tool runs the script, **Then** it uses the supplied context and confirms the breakpoint was hit before returning results. --- ### User Story 2 - Iterative Debug Session (Priority: P2) After reviewing the first breakpoint, the developer can ask Copilot to continue execution to subsequent breakpoints within the same session and receive the next set of variable values without starting over. **Why this priority**: Maintaining session continuity lets developers explore multiple execution points efficiently, reducing repeated setup effort. **Independent Test**: Establish a debug session with two breakpoints, resume execution from the first, and confirm the tool reports values from the second breakpoint in the same session. **Acceptance Scenarios**: 1. **Given** an active debug session with multiple breakpoints, **When** the LLM requests execution to continue, **Then** the tool resumes execution and reports the state at the next breakpoint reached. --- ### User Story 3 - Error Visibility (Priority: P3) If the program cannot reach the requested breakpoint because of an exception, missing file, or invalid line, the LLM receives a structured explanation of what happened so the developer can adjust their request. **Why this priority**: Helpful error feedback prevents dead ends and keeps developers informed about why the session failed. **Independent Test**: Request a breakpoint on a line that triggers an exception and verify the tool returns the exception details and execution status without crashing. **Acceptance Scenarios**: 1. **Given** a script that raises an error before the breakpoint, **When** the tool attempts to run it, **Then** it captures the error, reports the failure reason, and notes that the breakpoint was not reached. --- ### Edge Cases - Execution raises an exception before any breakpoint is hit. - The requested file path or line number does not exist in the project workspace. - The script runs longer than the allotted execution window or produces excessive output. ## Requirements *(mandatory)* ### Functional Requirements - **FR-001**: The tool MUST allow the LLM to define a breakpoint target using project-relative file path and line number. - **FR-002**: The tool MUST execute the Python entry command from a clean session context and pause when the specified breakpoint is first hit. - **FR-003**: The tool MUST return a structured snapshot of local variables (names and values) present when execution pauses at a breakpoint. - **FR-004**: The tool MUST support continuing execution within the same session to reach subsequent breakpoints without reinitializing state unless explicitly requested. - **FR-005**: The tool MUST report when a breakpoint is not hit, including whether execution completed normally, timed out, or failed with an error. - **FR-006**: The tool MUST enforce execution safeguards such as maximum runtime and output length and report when safeguards end a session. - **FR-007**: The tool MUST provide session lifecycle controls that allow the LLM to end, reset, or query the current debug session state. - **FR-008**: The tool MUST log each request and response context (timestamp, file, line, outcome) for auditing within the MCP host without exposing sensitive code beyond the session. ### Key Entities *(include if feature involves data)* - **Debug Session**: Represents a single bounded execution context, including session identifier, active breakpoints, runtime configuration, current status, and execution history. - **Breakpoint Target**: Captures the source identifier (file path), line number, optional conditional expression, and hit count within a session. - **Variable Snapshot**: Includes the variable name, evaluated value representation, variable scope, and capture timestamp at the moment the breakpoint is reached. - **Execution Outcome**: Summarizes the result of a run command, including success state, errors, duration, and whether the breakpoint was reached. ## Assumptions - Python projects expose a runnable entry command and environment settings that the MCP host can access without additional configuration. - The LLM provides accurate project-relative file paths and line numbers when requesting breakpoints. - Developers are comfortable supplying input arguments or fixtures needed to reach the code path under inspection. - Initial release focuses on run-to-breakpoint and continue operations; step-over or step-into navigation is deferred unless clarified later. ## Success Criteria *(mandatory)* ### Measurable Outcomes - **SC-001**: In 90% of valid breakpoint requests, the tool returns a variable snapshot from the target line within 15 seconds of the LLM request. - **SC-002**: 100% of attempts where the breakpoint is not reached provide a structured explanation covering the failure type and next steps for the developer. - **SC-003**: During pilot testing, at least 80% of developers report that the MCP debugging workflow reduces their reliance on ad-hoc print statements. - **SC-004**: Across a two-week evaluation, Copilot guidance relying on manual print debugging decreases by at least 60% compared with the baseline week preceding tool availability.