Debug-MCP

# Debug-MCP Roadmap This document outlines the planned evolution of the Debug-MCP tool beyond v1. ## Version 1.0 (Current) **Status**: ✅ Complete (134/134 tests passing) ### Core Features - ✅ Line-based breakpoints - ✅ Local variable inspection with safe repr - ✅ Session lifecycle management - ✅ Subprocess isolation with timeout protection - ✅ Pydantic v2 schema validation - ✅ CLI with JSON and table output formats - ✅ Comprehensive test suite (unit + integration) ### Limitations - Script entry only (no module or pytest support) - No conditional breakpoints - No stepping (step-in, step-over, step-out) - No expression evaluation - Single-threaded debugging only - No watch variables ## Version 2.0 (Planned) **Target**: Q2 2025 ### Enhanced Breakpoints #### Conditional Breakpoints ```python # Set breakpoint with condition manager.run_to_breakpoint( session_id, BreakpointRequest( file="src/app.py", line=42, condition="x > 10 and len(items) > 0" # NEW ) ) ``` **Safety constraints**: - Expression timeout: 1s max - Expression size limit: 256 chars - Safe eval with restricted builtins - No side effects allowed #### Hit Count Conditions ```python BreakpointRequest( file="src/app.py", line=100, hitCondition="== 5" # Pause on 5th hit only ) ``` #### Log Points (Non-Breaking Breakpoints) ```python BreakpointRequest( file="src/app.py", line=25, logMessage="Value of x: {x}, result: {result}" # Print without pausing ) ``` ### Module Execution Support Run Python modules instead of scripts: ```python StartSessionRequest( entry="my_package.main", entryType="module", # NEW: "script" | "module" args=["-m", "my_package.main"] ) ``` **Use cases**: - Debugging installed packages - Testing module entry points - Package development ### Pytest Integration Debug specific test cases: ```python StartSessionRequest( entry="tests/test_app.py::TestClass::test_method", entryType="pytest", # NEW pytestArgs=["-v", "-s"] ) ``` **Features**: - Pause at test failures - Inspect fixture values - Debug parameterized tests ### Stepping Operations Fine-grained execution control: ```python # Step into function call manager.step_into(session_id) # Step over function call manager.step_over(session_id) # Step out of current function manager.step_out(session_id) # Run until function returns manager.run_to_return(session_id) ``` ### Watch Expressions Monitor expressions across breakpoints: ```python # Add watch expression manager.add_watch(session_id, "len(items)") manager.add_watch(session_id, "self.state") # Watches evaluated at each breakpoint result = manager.run_to_breakpoint(...) print(result.watches) # {"len(items)": 42, "self.state": "active"} ``` ### Expression Evaluation Evaluate expressions in paused context: ```python # Evaluate expression at current breakpoint result = manager.evaluate( session_id, expression="sum(items) / len(items)", frameId=0 # Stack frame index ) # Returns: {"type": "float", "repr": "42.5"} ``` **Safety**: - Read-only evaluation (no assignments) - Timeout protection - Exception handling ## Version 2.1 (Future) **Target**: Q3 2025 ### Multi-Threaded Debugging Support debugging multi-threaded Python applications: ```python # List threads threads = manager.list_threads(session_id) # Set breakpoint in specific thread manager.run_to_breakpoint( session_id, BreakpointRequest(file="app.py", line=50), threadId=threads[1].id ) # Pause all threads manager.pause_all(session_id) ``` ### Stack Frame Navigation Inspect entire call stack: ```python # Get stack frames frames = manager.get_stack(session_id) # Inspect locals at specific frame locals = manager.get_frame_locals(session_id, frameIndex=2) # Evaluate in parent frame result = manager.evaluate(session_id, "x + y", frameIndex=1) ``` ### Enhanced Variable Inspection #### Custom Repr Functions ```python # User-defined variable formatter def custom_repr(obj, depth, limit): if isinstance(obj, MyClass): return f"<MyClass: {obj.key_field}>" return default_repr(obj, depth, limit) manager.set_repr_handler(custom_repr) ``` #### Lazy Loading for Large Objects ```python # Initial load shows summary result.locals["big_list"] # {"type": "list", "length": 10000, "preview": "[...]"} # Expand on demand items = manager.expand_variable(session_id, "big_list", start=0, count=100) ``` ### Remote Debugging Debug code running on remote machines: ```python # Start remote debug server mcp-debug serve --host 0.0.0.0 --port 8765 # Connect from client manager = RemoteSessionManager("http://remote-host:8765") ``` **Security**: - TLS encryption - Token-based authentication - IP allowlist ## Version 3.0 (Future) **Target**: Q4 2025 ### Visual Debugger Integration #### VS Code Extension - Breakpoint gutter icons - Variable tree view - Debug console - Call stack panel #### DAP (Debug Adapter Protocol) Support ```python # Expose DAP-compatible interface mcp-debug dap --port 4711 ``` **Benefits**: - Works with any DAP client - Standard protocol - Broader ecosystem ### Performance Profiling Integrated profiling during debugging: ```python # Enable profiling session = manager.create_session( request, enableProfiling=True ) # Get profile data profile = manager.get_profile(session_id) # Returns: line-by-line timing, call counts, memory usage ``` ### Time-Travel Debugging Record and replay execution: ```python # Enable recording session = manager.create_session(request, record=True) # Execute with breakpoints manager.run_to_breakpoint(...) manager.continue_execution(...) # Go back to previous state manager.step_back(session_id) # Replay from start manager.replay(session_id, until_line=50) ``` **Use cases**: - Understanding state changes - Finding when variable was modified - Comparing executions ### Async/Await Debugging Enhanced support for asyncio: ```python # Pause at next await manager.run_to_next_await(session_id) # List pending tasks tasks = manager.list_tasks(session_id) # Inspect event loop state loop_state = manager.get_event_loop_state(session_id) ``` ## Infrastructure & Quality ### Ongoing Improvements #### Performance - [ ] Reduce session startup time (< 50ms) - [ ] Streaming output capture - [ ] Parallel session execution - [ ] Session pooling/reuse #### Reliability - [ ] Automatic crash recovery - [ ] Session persistence across restarts - [ ] Graceful degradation on timeouts - [ ] Better error messages #### Security - [ ] Sandboxing with restricted builtins - [ ] Filesystem access controls - [ ] Network access controls - [ ] Resource quotas (CPU, memory) #### Testing - [ ] 90%+ code coverage - [ ] Property-based testing - [ ] Chaos testing (timeouts, crashes) - [ ] Performance benchmarks #### Documentation - [ ] Video tutorials - [ ] Interactive examples - [ ] API reference site - [ ] Architecture diagrams ## Community Features ### Extensibility #### Plugin System ```python # Custom breakpoint handlers class CustomBreakpointHandler: def on_hit(self, session, locals): # Custom logic pass manager.register_handler(CustomBreakpointHandler()) ``` #### Event Hooks ```python # React to debug events @manager.on_breakpoint_hit def handle_hit(session_id, frame_info): log.info(f"Hit breakpoint at {frame_info.file}:{frame_info.line}") ``` ### Integration Examples - [ ] Jupyter Notebook integration - [ ] pytest plugin - [ ] Django debug toolbar - [ ] FastAPI middleware - [ ] GitHub Actions workflow ## Research Areas ### Advanced Features (TBD) - **Symbolic execution**: Explore multiple code paths - **Automated debugging**: Suggest fixes based on state - **AI-assisted debugging**: LLM analyzes variable state - **Contract checking**: Assert invariants automatically - **Differential debugging**: Compare two executions ## Versioning & Compatibility ### API Stability - **v1.x**: Stable, backward compatible - **v2.x**: Additive changes, deprecations with warnings - **v3.x**: Breaking changes with migration guide ### Python Support - **v1.x**: Python 3.11+ - **v2.x**: Python 3.11+ (may add 3.10 support) - **v3.x**: Python 3.12+ (drop 3.11 if needed for new features) ## Contributing to the Roadmap We welcome community input! To suggest features: 1. **Open an issue**: Describe the use case 2. **Provide examples**: Show how it would work 3. **Discuss trade-offs**: Performance, security, complexity 4. **Propose implementation**: High-level approach ### Prioritization Criteria Features are prioritized by: 1. **User impact**: How many users benefit? 2. **Complexity**: Implementation effort vs value 3. **Safety**: Security and reliability implications 4. **Compatibility**: Breaking changes vs additive ## Get Involved - 💬 Discuss roadmap on GitHub Discussions - 🐛 Report bugs and request features via Issues - 🔧 Contribute code via Pull Requests - 📖 Improve documentation - 🧪 Add test cases ## Release Schedule - **v1.x patches**: Monthly (bug fixes) - **v1.x minor**: Quarterly (small features) - **v2.0**: Q2 2025 (major features) - **v3.0**: Q4 2025 (transformative changes) --- Last updated: 2025-01-23 Roadmap subject to change based on community feedback and priorities.