plan.md•3.98 kB
# Implementation Plan: Python Debugging MCP Tool
**Branch**: `001-python-debug-tool` | **Date**: 2025-10-23 | **Spec**: `specs/001-python-debug-tool/spec.md`
**Input**: Feature specification from `/specs/001-python-debug-tool/spec.md`
## Summary
Enable Copilot/LLM to perform real debugging on Python code via an MCP tool: set a breakpoint at a given file/line, run until hit, and return local variables. Technical approach: implement an MCP server that manages per-request debug sessions using a sandboxed Python subprocess with a lightweight bdb/pdb-based controller to set breakpoints, run, capture locals, and continue. Provide session lifecycle controls, timeouts, and bounded outputs.
## Technical Context
**Language/Version**: Python 3.11 (tool + debug runner)
**Primary Dependencies**: Standard library (bdb/pdb, subprocess, multiprocessing), typer/click for local CLI (optional), pydantic for schemas, pytest for tests
**Storage**: N/A (in-memory session state only)
**Testing**: pytest + coverage; integration tests run sample scripts to break and capture locals
**Target Platform**: macOS and Linux (developer machines/CI)
**Project Type**: Single project (MCP tool implemented in Python)
**Performance Goals**: Return snapshot within 15s for 90% of valid requests; steady-state memory < 100MB per session
**Constraints**: CPU time limit per run (configurable, default 20s); output truncation (e.g., 32KB); safe path execution restricted to workspace
**Scale/Scope**: Local development, 1–3 concurrent sessions typical
Unknowns (to resolve in research.md):
- NEEDS CLARIFICATION: Entrypoint strategy (script path vs module vs test target) and how args/env are provided.
- NEEDS CLARIFICATION: Virtualenv/conda detection and interpreter selection when multiple Pythons exist.
- NEEDS CLARIFICATION: Support for conditional breakpoints and expression evaluation in v1 vs v2 scope.
## Constitution Check
The following checks derive from the Constitution and will be enforced:
- [x] Code Quality: Define formatter (ruff/black) and lint rules; keep complexity small and document any exceptions. Measurement: run `ruff check .` in CI.
- [x] Testing: Test plan with pytest; target coverage ≥ 80% enforced in CI. Measurement: coverage gate in CI.
- [x] UX Consistency: CLI/tool responses use consistent, accessible JSON structures and actionable messages. Measurement: response schema tests.
- [x] Performance: Goals and constraints declared above; measurement approach: timed integration tests with timeouts.
## Project Structure
### Documentation (this feature)
```text
specs/001-python-debug-tool/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
└── contracts/
└── openapi.yaml
```
### Source Code (repository root)
```text
src/
├── mcp_debug_tool/
│ ├── __init__.py
│ ├── server.py # MCP tool server (stdio)
│ ├── sessions.py # Session manager
│ ├── debugger.py # bdb-based controller
│ ├── runner.py # Subprocess entry for debug sessions
│ ├── schemas.py # Pydantic models for requests/responses
│ └── utils.py
└── cli/
└── main.py # Optional local CLI wrapper
tests/
├── unit/
│ ├── test_sessions.py
│ ├── test_debugger.py
│ └── test_schemas.py
└── integration/
├── samples/
│ └── buggy_script.py
└── test_run_to_breakpoint.py
```
**Structure Decision**: Single Python project with clear separation of server, session, and debug runner to keep surfaces small and testable.
## Complexity Tracking
| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| Subprocess per session | Isolation and safe termination | In-process debugging risks corrupting MCP server state and leaking globals |