Debug-MCP

# Known Issues and Limitations Last updated: 2025-10-29 ## Current Implementation Issues ### 1. ⚠️ Replay Execution vs True Step Execution **Status**: Known Limitation **Severity**: Medium **Impact**: Performance and side effects #### Description The current `continue_execution()` implementation uses a **replay approach** instead of true step execution: - Each `continue` creates a new `DebugController` instance - The script is re-executed from the beginning each time - Global variables (`globals_dict`) are preserved between executions #### Consequences - ✅ **Works correctly** for most debugging scenarios - ✅ **Safe**: No `sys.modules` corruption - ❌ **Not efficient**: Re-executes entire script each time - ❌ **Side effects repeat**: File I/O, network calls, etc. happen again - ❌ **Performance**: Slow for large scripts #### Example ```python counter = 0 def increment(): global counter counter += 1 print(f"Counter: {counter}") # BP1 increment() print(f"Result: {counter}") # BP2 ``` **Current behavior (Replay)**: 1. Run to BP1: counter = 1 ✓ 2. Continue to BP2: Script restarts, counter = 1 again (but globals preserved, so actually shows 1) ✓ **Expected behavior (True Step)**: 1. Run to BP1: counter = 1, pause 2. Continue to BP2: Resume from pause, counter already = 1 #### Why This Happens Python's `bdb` module doesn't support calling `run()` multiple times on the same instance: - Causes `sys.modules` corruption - Results in `KeyError: 'argparse'` and similar errors - No safe way to reuse bdb state #### Potential Solutions 1. **Accept current limitation** (recommended for now) 2. **Async/Event-driven architecture**: Run debugger in background thread, block at breakpoints 3. **Alternative debug protocol**: Use DAP (Debug Adapter Protocol) instead of bdb --- ### 2. 🚨 Python Environment Mismatch (Cross-Repository Usage) **Status**: Critical Issue **Severity**: High **Impact**: Cannot debug code that uses external libraries #### Description When using the MCP debug server from **another repository** (not the Debug-MCP repo itself), the debugger cannot import libraries installed in that repository's virtual environment. #### Symptoms ```json { "error": { "type": "ModuleNotFoundError", "message": "No module named 'some_library'" } } ``` Or in some cases: ```json { "error": { "type": "KeyError", "message": "'argparse'", "traceback": "File \"<frozen importlib._bootstrap>\", line 188" } } ``` #### Root Cause The MCP debug server runs in its **own Python environment** (Debug-MCP's `.venv`), while the target code expects libraries from the **target repository's environment** (e.g., other repo's `venv`). ``` ┌─────────────────────────────────────────┐ │ MCP Server Process │ │ Python: Debug-MCP/.venv/bin/python │ │ Libraries: mcp, pydantic, etc. │ │ │ │ ┌─────────────────────────────────┐ │ │ │ Debug Subprocess (runner.py) │ │ │ │ Python: SAME as parent │ │ │ │ Tries to import: numpy, pandas │ │ │ │ ❌ Not found in Debug-MCP venv │ │ │ └─────────────────────────────────┘ │ └─────────────────────────────────────────┘ Target Repository: venv/lib/python3.11/site-packages/ ├── numpy/ ├── pandas/ └── other_libs/ ``` #### Current Workaround Attempt `runner.py` tries to add target repo's `site-packages` to `sys.path`: ```python def _setup_python_path(self, workspace_root: Path) -> None: venv_paths = [ workspace_root / ".venv", workspace_root / "venv", workspace_root / ".env", ] # ... attempts to add site-packages to sys.path ``` **This is insufficient because**: - Only adds `site-packages`, not the venv's Python interpreter - Missing native extensions compiled for different Python versions - PYTHONPATH is not reliably inherited by subprocesses #### Impact 🔴 **Blocker**: Cannot debug real-world projects that use dependencies #### Tested Scenarios - ✅ **Works**: Debug-MCP's own code (same environment) - ✅ **Works**: Simple scripts with no imports - ❌ **Fails**: Other repos with `venv` and dependencies - ❌ **Fails**: Projects using numpy, pandas, django, etc. #### Potential Solutions ##### Option 1: Use Target Repository's Python (Recommended) Execute debugger subprocess using the target repo's Python interpreter: ```python # In sessions.py def _spawn_subprocess(self, session): # Detect target venv venv_python = self._find_venv_python(self.workspace_root) if venv_python: # Use target's Python python_exe = venv_python else: # Fallback to current Python python_exe = sys.executable process = subprocess.Popen( [python_exe, "-m", "mcp_debug_tool.runner_main"], # ... ) ``` **Pros**: - ✅ All libraries available - ✅ Correct Python version - ✅ Native extensions work **Cons**: - ⚠️ Target venv must have `mcp_debug_tool` installed - ⚠️ Or need to add Debug-MCP/src to PYTHONPATH ##### Option 2: Dynamic Import in Subprocess Don't import target code in parent, only in subprocess with modified path. ##### Option 3: Use Python Path from Session Config Allow users to specify Python path explicitly: ```python # Start session with explicit Python session = sessions.create({ "entry": "main.py", "pythonPath": "/path/to/project/venv/bin/python" }) ``` --- ### 3. ⚠️ Module Import Lock Contention **Status**: Suspected Issue **Severity**: Medium **Impact**: Intermittent `KeyError: 'argparse'` #### Description The `KeyError: 'argparse'` error from `<frozen importlib._bootstrap>` suggests: - Multiple processes trying to import modules simultaneously - Import lock being held during fork/spawn - `sys.modules` corruption during subprocess creation #### When It Occurs - More likely with multiprocessing `spawn` method - May occur during first breakpoint hit - Intermittent - doesn't always reproduce #### Potential Causes 1. Parent process has partially initialized modules 2. Fork happens while import lock is held 3. Child inherits corrupted import state #### Mitigation Attempts - ✅ Using `DebugController` instances as throwaway - ✅ Creating new instances for each `continue` - ❌ Still occurs in some environments --- ### 4. 📝 Breakpoint Line Validation Strictness **Status**: By Design **Severity**: Low **Impact**: User experience #### Description The debugger rejects breakpoints on non-executable lines: ``` ValueError: Line 67 does not contain executable code. Nearest executable line: 66 ``` #### Behavior - Comments: ❌ Rejected - Empty lines: ❌ Rejected - Docstrings: ❌ Rejected - Function definitions: ✅ Accepted - Variable assignments: ✅ Accepted #### User Impact Users expect to set breakpoint on any line, even if debugger moves it to nearest executable line. #### Solution Options 1. **Auto-adjust**: Silently move to nearest executable line 2. **Warning**: Set on nearest line with warning message 3. **Current**: Reject with error (strictest) --- ## Summary Table | Issue | Severity | Workaround | Permanent Fix Required | |-------|----------|------------|----------------------| | Replay vs True Step | Medium | None - current behavior | Async architecture | | Python Env Mismatch | **Critical** | Manual venv config | Use target Python | | Import Lock Contention | Medium | Restart MCP server | Unknown | | Line Validation | Low | Use suggested line | Auto-adjust logic | --- ## Recommendations ### For Users (Workarounds) 1. **Python Environment Issues**: ```bash # Install mcp_debug_tool in target repo's venv cd /path/to/target-repo source venv/bin/activate pip install -e /path/to/Debug-MCP ``` 2. **KeyError: 'argparse'**: - Restart MCP server completely - Restart VS Code - Use `spawn` instead of `fork` (already default) 3. **Line Validation**: - Use the suggested line from error message - Avoid setting breakpoints on comments ### For Developers (Next Steps) **Priority 1 (Critical)**: Fix Python Environment Mismatch - [ ] Implement target Python detection - [ ] Test with real projects (numpy, pandas) - [ ] Add session config for `pythonPath` **Priority 2 (Important)**: Improve Step Execution - [ ] Research async debugger architecture - [ ] Prototype background thread approach - [ ] Measure performance impact **Priority 3 (Nice to have)**: Better UX - [ ] Auto-adjust breakpoint lines - [ ] Better error messages - [ ] Add `--python` CLI flag --- ## Testing Notes ### What Works ✅ - Debugging Debug-MCP's own code - Simple scripts with stdlib only - Multiple breakpoints in same file - Variable inspection - Error capturing ### What Fails ❌ - Cross-repository debugging with dependencies - Large scripts (performance) - Code with side effects (repeated) - Some edge cases with imports ### Test Repositories - **Pass**: Debug-MCP itself - **Pass**: Hello world scripts - **Fail**: Projects with numpy/pandas - **Fail**: Django projects - **Intermittent**: Complex imports --- ## Related Documentation - [Python Path Support](python-path-support.md) - [Performance Tuning](performance-tuning.md) - [Development Guide](development.md)