Debug-MCP

# Tasks: Debug Insight (Python Debugging MCP Tool) Below is a phased, small, and testable checklist ordered Setup → Foundational → User Stories (US1–US3) → Polish. Each task follows the "- [ ] T### [P?] [USx?] Description with file path" format. [P] marks tasks that can run in parallel; [USx] indicates the related user story. ## Phase 1: Setup - [X] T001 Create src directory for package: src/mcp_debug_tool/ - [X] T002 Create tests directory layout (unit/integration): tests/{unit,integration}/ - [X] T003 Add package initializer: src/mcp_debug_tool/__init__.py - [X] T004 Add utility module scaffold (safe path resolution / limit constants): src/mcp_debug_tool/utils.py - [X] T005 Add schema scaffold (Pydantic base models): src/mcp_debug_tool/schemas.py - [X] T006 Add sample script scaffold (for integration tests): tests/integration/samples/buggy_script.py - [X] T007 Add pytest config file (markers/paths): pytest.ini - [X] T008 Add ruff config file (minimal rules): ruff.toml ## Phase 2: Foundational - [X] T009 Session manager skeleton (ID/state/create/destroy): src/mcp_debug_tool/sessions.py - [X] T010 Debugger controller skeleton (bdb-based): src/mcp_debug_tool/debugger.py - [X] T011 Runner subprocess entry scaffold (initialize IPC): src/mcp_debug_tool/runner.py - [X] T012 MCP server skeleton (stdio endpoint / method registry): src/mcp_debug_tool/server.py - [X] T013 Logging foundation (record request/response/timings): src/mcp_debug_tool/utils.py - [X] T014 Execution guard settings (timeouts/output cap/depth limits): src/mcp_debug_tool/utils.py - [X] T015 Baseline session state API (state): src/mcp_debug_tool/sessions.py - [X] T016 Baseline session end API (end): src/mcp_debug_tool/sessions.py - [X] T017 Wire state/end handlers into server: src/mcp_debug_tool/server.py - [X] T018 Align OpenAPI contract basics (endpoints/property names): specs/001-python-debug-tool/contracts/openapi.yaml ## Phase 3: User Story 1 (P1) — Run to breakpoint and capture locals - [X] T019 [US1] Implement start session (validate entry/args/env/pythonPath → create): src/mcp_debug_tool/sessions.py - [X] T020 [P] [US1] Implement start session handler (/sessions POST): src/mcp_debug_tool/server.py - [X] T021 [US1] Implement run_to_breakpoint (set breakpoint / run / pause): src/mcp_debug_tool/debugger.py - [X] T022 [US1] Execute entry in runner (apply args/env; lock workspace cwd): src/mcp_debug_tool/runner.py - [X] T023 [US1] Capture variable snapshot (safe repr / depth & item limits): src/mcp_debug_tool/debugger.py - [X] T024 [P] [US1] Finalize snapshot Pydantic models (types / truncation flags): src/mcp_debug_tool/schemas.py - [X] T025 [US1] Validate path/line (existence and range): src/mcp_debug_tool/utils.py - [X] T026 [P] [US1] Implement breakpoint handler (/sessions/{id}/breakpoint POST): src/mcp_debug_tool/server.py - [X] T027 [P] [US1] Unit: schema validation (request/response/limits): tests/unit/test_schemas.py - [X] T028 [P] [US1] Unit: debugger stops at single breakpoint and captures locals: tests/unit/test_debugger.py - [X] T029 [P] [US1] Integration: run_to_breakpoint returns expected locals: tests/integration/test_run_to_breakpoint.py - [X] T030 [P] [US1] Improve integration sample (two breakpoint locations): tests/integration/samples/buggy_script.py ## Phase 4: User Story 2 (P2) — Continue within the same session - [X] T031 [US2] Implement continue (run to next breakpoint): src/mcp_debug_tool/debugger.py - [X] T032 [P] [US2] Continue handler (/sessions/{id}/continue POST): src/mcp_debug_tool/server.py - [X] T033 [US2] Update session state (lastBreakpoint/timings): src/mcp_debug_tool/sessions.py - [X] T034 [P] [US2] Unit: continue reaches next breakpoint: tests/unit/test_debugger_continue.py - [X] T035 [P] [US2] Integration: reaches second breakpoint: tests/integration/test_continue_to_next_breakpoint.py - [X] T036 [P] [US2] Unit: session state transitions: tests/unit/test_sessions.py ## Phase 5: User Story 3 (P3) — Error visibility and termination reasons - [X] T037 [US3] Structured error schema (type/message/truncated traceback): src/mcp_debug_tool/schemas.py - [X] T038 [US3] Exception capture and safe traceback truncation: src/mcp_debug_tool/runner.py - [X] T039 [P] [US3] Map invalid input errors (bad file/line) to responses: src/mcp_debug_tool/server.py - [X] T040 [US3] Apply execution guards (timeout/output cap forced termination): src/mcp_debug_tool/runner.py - [X] T041 [P] [US3] Unit: structured error for invalid input: tests/unit/test_validation_errors.py - [X] T042 [P] [US3] Unit: forced-termination reports for timeout/output cap: tests/unit/test_guards.py - [X] T043 [P] [US3] Integration: structured error when an exception occurs before breakpoint: tests/integration/test_error_before_breakpoint.py - [X] T044 [P] [US3] Integration: error report for invalid line/file: tests/integration/test_invalid_location.py - [X] T045 [P] [US3] Integration: error report when timeout triggers: tests/integration/test_timeout.py - [X] T046 [P] [US3] Unit: response shape consistency: tests/unit/test_response_shapes.py ## Final Phase: Polish & Cross-Cutting - [X] T047 [P] Flesh out OpenAPI example responses (locals/error examples): specs/001-python-debug-tool/contracts/openapi.yaml - [X] T048 [P] Create Typer CLI skeleton: src/cli/main.py - [X] T049 [P] CLI: add start-session command: src/cli/main.py - [X] T050 [P] CLI: add run-to-breakpoint command: src/cli/main.py - [X] T051 [P] CLI: add continue command: src/cli/main.py - [X] T052 [P] CLI: add state/end commands: src/cli/main.py - [X] T053 [P] CLI: output format toggle (JSON/table): src/cli/main.py - [X] T054 [P] Add CLI usage examples to Quickstart: specs/001-python-debug-tool/quickstart.md - [X] T055 [P] Update research decisions (entry strategy / interpreter selection / conditional BP in v2): specs/001-python-debug-tool/research.md - [X] T056 [P] Update data model (limits / validation rules): specs/001-python-debug-tool/data-model.md - [X] T057 [P] Create README (how to run, safety, limits): README.md - [X] T058 [P] Developer guide (Python 3.11, venv, ruff, pytest): docs/development.md - [X] T059 [P] Performance/limits tuning guide: docs/performance-tuning.md - [X] T060 [P] Roadmap (v2: conditional BP, module execution, pytest target): docs/roadmap.md ## Updating task ## Phase 6: MCP SDK Migration (Breaking Change → v0.2.0) ### Preparation (Phase 6.1) - [X] T061 [SDK] Add mcp dependency to pyproject.toml and requirements.txt - [X] T062 [P] [SDK] Research SDK patterns (decorators, async, stdio_server): specs/001-python-debug-tool/updates/mcp-sdk-migration.md - [X] T063 [P] [SDK] Create SDK exploration script to verify basic usage: tests/exploration/test_mcp_sdk.py - [X] T064 [SDK] Set up parallel server implementation structure: src/mcp_debug_tool/server_v2.py ### Implementation (Phase 6.2) - [X] T065 [SDK] Implement SDK-based server skeleton (Server instance, stdio_server): src/mcp_debug_tool/server_v2.py - [X] T066 [SDK] Implement list_tools handler with SDK decorators: src/mcp_debug_tool/server_v2.py - [X] T067 [SDK] Implement call_tool handler (sessions_create): src/mcp_debug_tool/server_v2.py - [X] T068 [SDK] Implement call_tool handler (sessions_breakpoint): src/mcp_debug_tool/server_v2.py - [X] T069 [SDK] Implement call_tool handler (sessions_continue): src/mcp_debug_tool/server_v2.py - [X] T070 [SDK] Implement call_tool handlers (sessions_state, sessions_end): src/mcp_debug_tool/server_v2.py - [X] T071 [P] [SDK] Add async wrapper for SessionManager methods: src/mcp_debug_tool/sessions.py - [X] T072 [P] [SDK] Update schemas to remove MCP protocol structures: src/mcp_debug_tool/schemas.py ### Testing (Phase 6.3) - [X] T073 [P] [SDK] Create integration test for SDK server (all 5 tools): tests/integration/test_sdk_server.py - [X] T074 [P] [SDK] Verify existing integration tests work with SDK server: tests/integration/ - [X] T075 [P] [SDK] Add async-specific tests (concurrent requests): tests/integration/test_concurrent_sessions.py - [X] T076 [SDK] Manual test with MCP Inspector: Manual testing checklist - [X] T077 [P] [SDK] Benchmark comparison (old vs new server): tests/benchmark/compare_servers.py ### Migration & Cleanup (Phase 6.4) - [X] T078 [SDK] Replace server.py with server_v2.py (rename): src/mcp_debug_tool/server.py - [X] T079 [SDK] Update CLI to use new async server: src/cli/main.py - [X] T080 [P] [SDK] Update mcp-config-example.json with new command: mcp-config-example.json - [X] T081 [P] [SDK] Update README with SDK-based examples: README.md - [X] T082 [P] [SDK] Update development guide with async patterns: docs/development.md - [X] T083 [P] [SDK] Update quickstart with SDK changes: specs/001-python-debug-tool/quickstart.md - [X] T084 [SDK] Remove old custom JSON-RPC code: Git commit cleanup - [X] T085 [SDK] Bump version to 0.2.0 in pyproject.toml: pyproject.toml --- ## Dependencies and execution order - Phase order: Setup → Foundational → US1 → US2 → US3 → Polish → MCP SDK Migration - Representative dependencies: - T020 depends on T019 (session creation must exist first) - T026 depends on T021–T025 (run-to-breakpoint, validation, and schema in place) - T032 depends on T031 (continue logic implemented first) - T039/T040 depend on T037–T038 (error shapes and capture in place) ## Parallel execution examples per story - US1: Run T020, T024, T026, T027, T028, T029, T030 in parallel (separate files/independent tests) - US2: Run T032, T034, T035, T036 in parallel - US3: Run T039 and T041–T046 in parallel - SDK Migration Preparation: Run T062, T063 in parallel - SDK Migration Implementation: Run T071, T072 in parallel - SDK Migration Testing: Run T073, T074, T075, T077 in parallel - SDK Migration Cleanup: Run T080, T081, T082, T083 in parallel ## Implementation strategy (MVP → incremental) - MVP: Complete US1 (T019–T030) to support "run to a line and return locals" - Next: Add US2 for continue; add US3 for error visibility and hardening - Polish: Add CLI and documentation/contract refinements ## Report - Total task count: 85 - Task count per user story: - US1: 12 - US2: 6 - US3: 10 - MCP SDK Migration: 25 - Parallelizable tasks ([P]): 44 - Independent test criteria (each story) - US1: A single run_to_breakpoint request returns expected locals on first attempt - US2: continue within the same session returns locals at the next breakpoint - US3: not-reached/exception/timeout/invalid-input are returned as typed structured responses - SDK Migration: All 5 tools work identically via MCP SDK with <30% code reduction - Suggested MVP scope: US1 (all Phase 3 tasks) - Suggested v0.2.0 scope: All phases including SDK Migration (T001-T085) - Format validation: All tasks follow "- [ ] T### [P?] [USx?] Description with file path"