Debug-MCP: Python Debugging via Model Context Protocol

A Python debugging tool that exposes breakpoint-based debugging capabilities through a clean API and CLI, designed for integration with AI assistants and development tools.

English | 日本語

Features

• Advanced Debugging via DAP: Production-ready debugging using Microsoft's debugpy
  • Breakpoint Debugging: Set breakpoints and inspect local variables at runtime
  • Step Execution: True step-in, step-over, step-out operations
  • No Corruption: Isolated process execution prevents sys.modules issues
  • Environment-aware: Automatically uses target project's Python interpreter
• Session Management: Isolated debug sessions with timeout protection
• Dual Interface:
  • CLI: Interactive debugging with beautiful table output
  • MCP Server: Official MCP SDK-based integration for AI assistants
• Safe Execution: Sandboxed subprocess execution with configurable limits
• Type Safety: Pydantic v2 schemas for request/response validation
• Async Support: Built on MCP SDK with full async/await support
• Comprehensive Testing: 254 tests (119 unit + 122 integration + 13 exploration) covering DAP workflows, session management, and edge cases
• Legacy Compatibility: Optional bdb mode for backward compatibility

Quick Start

Installation

# Clone repository
git clone https://github.com/your-org/Debug-MCP.git
cd Debug-MCP

# Create virtual environment
uv venv

# Install with CLI support
uv pip install -e ".[cli]"

VS Code Copilot Integration

To use this tool with GitHub Copilot in VS Code, set up the MCP server configuration.

See VS Code Setup Guide for detailed instructions.

Quick Setup (Using from Debug-MCP repository):

1. Create MCP config directory (macOS/Linux):

   mkdir -p ~/Library/Application\ Support/Code/User/globalStorage/github.copilot-chat
   

2. Edit mcp.json file:

   {
     "mcpServers": {
       "python-debug": {
         "command": "uv",
         "args": ["run", "mcp-debug-server", "--workspace", "${workspaceFolder}"],
         "env": {"PYTHONUNBUFFERED": "1"}
       }
     }
   }
   

3. Restart VS Code

Using from Another Repository:

When using this tool from a different repository, specify the Debug-MCP installation path:

{
  "mcpServers": {
    "python-debug": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/Debug-MCP",
        "run",
        "mcp-debug-server",
        "--workspace",
        "${workspaceFolder}"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Replace /absolute/path/to/Debug-MCP with the actual path to your Debug-MCP installation.

Using Copilot Chat:

@workspace Set a breakpoint at line 42 in src/main.py and 
show me the local variables at that point.

See mcp-config-example.json for a complete configuration example.

CLI Usage (Recommended for Interactive Debugging)

# Start a debug session
SESSION_ID=$(uv run mcp-debug start-session src/app.py | jq -r .sessionId)

# Run to breakpoint and inspect locals  
uv run mcp-debug run-to-breakpoint $SESSION_ID src/app.py 42 --format table

# Continue to next breakpoint
uv run mcp-debug continue $SESSION_ID src/app.py 100 --format table

# Check session state
uv run mcp-debug state $SESSION_ID --format table

# End session
uv run mcp-debug end $SESSION_ID

See Quickstart Guide for more CLI examples.

API Usage (Python Integration)

from pathlib import Path
from mcp_debug_tool.sessions import SessionManager
from mcp_debug_tool.schemas import StartSessionRequest, BreakpointRequest

# Initialize
workspace = Path.cwd()
manager = SessionManager(workspace)

# Create session
req = StartSessionRequest(entry="src/main.py", args=["--verbose"])
session = manager.create_session(req)

# Run to breakpoint
bp_req = BreakpointRequest(file="src/main.py", line=15)
result = manager.run_to_breakpoint(session.sessionId, bp_req)

if result.hit:
    print(f"Paused at {result.frameInfo.file}:{result.frameInfo.line}")
    print(f"Locals: {result.locals}")

# Continue execution
continue_result = manager.continue_execution(
    session.sessionId, 
    BreakpointRequest(file="src/main.py", line=42)
)

# Cleanup
manager.end_session(session.sessionId)

Safety & Constraints

Execution Limits

• Timeout: 20 seconds per breakpoint operation (configurable)
• Output Capture: 10MB maximum per session
• Variable Depth: Max 2 levels of nesting in local variable inspection
• Collection Size: Max 50 items shown in lists/dicts
• String Length: Max 256 characters before truncation

Security

• Path Validation: Only project-relative paths allowed (no .. traversal)
• Subprocess Isolation: Debuggee runs in isolated subprocess
• Working Directory: Locked to workspace root
• No Network: Debuggee has no special network access (app code may still use network)

⚠️ Important: The debugger executes user code with minimal restrictions. Only debug trusted code.

Architecture

Current Implementation (v2 - DAP-based)

Debug-MCP now uses DAP (Debug Adapter Protocol) via debugpy for production debugging:

┌─────────────────────────────────────────────────┐
│ MCP Server (server.py)                          │
│ - Official MCP SDK (async)                      │
│ - Tool registration & routing                   │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│ Session Manager (sessions.py)                   │
│ - Lifecycle management                          │
│ - DAP/bdb mode selection                        │
└────────────────┬────────────────────────────────┘
                 │
                 ▼ (DAP mode - default)
┌─────────────────────────────────────────────────┐
│ DAPSyncWrapper (dap_wrapper.py)                 │
│ - Synchronous DAP interface                     │
│ - Event queue management                        │
│ - Timeout handling                              │
└────────────────┬────────────────────────────────┘
                 │ DAP Protocol (JSON-RPC)
                 ▼
┌─────────────────────────────────────────────────┐
│ debugpy Server (separate process)               │
│ - Microsoft's official DAP implementation       │
│ - Handles breakpoints, stepping, variables      │
│ - Manages target script execution               │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│ Target Python Script                            │
│ - Runs in isolated process                      │
│ - Full access to target dependencies            │
│ - No sys.modules corruption                     │
└─────────────────────────────────────────────────┘

Why DAP (debugpy)?

• ✅ No sys.modules corruption - Runs in separate process
• ✅ True step execution - Maintains execution state across steps
• ✅ Automatic environment handling - Uses target Python interpreter
• ✅ Industry standard - Microsoft's battle-tested implementation
• ✅ Rich features - Step in/over/out, conditional breakpoints, watch expressions
• ✅ Future-proof - Easy to extend with advanced debugging features

Communication Flow:

1. MCP Client (VS Code Copilot) → MCP Server (tool call)
2. Server → SessionManager (sync method via async wrapper)
3. SessionManager → DAPSyncWrapper (manages DAP session)
4. DAPSyncWrapper ↔ debugpy Server (DAP protocol over socket)
5. debugpy captures locals → DAPSyncWrapper → SessionManager → Server → Client

Legacy bdb Mode

The bdb-based implementation is still available for compatibility (useDap=false):

SessionManager → runner_main.py (subprocess) → DebugController (bdb)

However, DAP is now the default and recommended for all use cases. The bdb mode has known issues:

• sys.modules corruption with multiple runs
• No true step execution (replay-based)
• Complex PYTHONPATH management

File Organization (2025-11-03)

Active Files (Production):

• ✅ server.py - MCP SDK server
• ✅ sessions.py - Session lifecycle management
• ✅ dap_wrapper.py - DAP synchronous wrapper (PRIMARY)
• ✅ dap_client.py - Low-level DAP protocol client (PRIMARY)
• ✅ schemas.py - Pydantic models
• ✅ utils.py - Variable repr helpers and path utilities

Legacy Files (Compatibility):

• ⚠️ debugger.py - bdb-based engine (legacy, use useDap=false)
• ⚠️ runner_main.py - bdb subprocess runner (legacy)

Removed Files:

• runner.py - Old multiprocessing approach (removed 2025-10-30)

Development

Setup

See docs/development.md for detailed setup instructions.

Quick commands:

# Run all tests (254 tests: 119 unit + 122 integration + 13 exploration)
uv run pytest

# Run only unit tests
uv run pytest tests/unit/

# Run only integration tests
uv run pytest tests/integration/

# Run tests with coverage
uv run pytest --cov=src/mcp_debug_tool --cov-report=html

# Lint
uv run ruff check .

# Format  
uv run ruff format .

# Auto-fix lint issues
uv run ruff check --fix .

Project Structure

Debug-MCP/
├── src/
│   ├── mcp_debug_tool/      # Core debugging engine
│   │   ├── server.py        # MCP SDK-based server (v2.0+)
│   │   ├── sessions.py      # Session management (DAP/bdb mode selection)
│   │   ├── dap_wrapper.py   # DAP synchronous wrapper (PRIMARY)
│   │   ├── dap_client.py    # DAP protocol client (PRIMARY)
│   │   ├── debugger.py      # bdb-based debugger (LEGACY, use useDap=false)
│   │   ├── runner_main.py   # bdb subprocess runner (LEGACY)
│   │   ├── schemas.py       # Pydantic models
│   │   └── utils.py         # Variable repr helpers
│   └── cli/
│       └── main.py          # Typer CLI
├── tests/
│   ├── unit/                # Unit tests (debugger, schemas, DAP, sessions)
│   └── integration/         # Integration tests (DAP workflows, bdb compat)
├── specs/
│   └── 001-python-debug-tool/  # Specification documents
└── docs/                    # Additional documentation
    ├── dap-phase*-*.md      # DAP integration documentation
    └── roadmap.md           # Future enhancements

Documentation

• VS Code Setup Guide - How to use MCP tool with VS Code Copilot ⭐
• Quickstart Guide - CLI and API usage examples
• Specification - Complete feature specification
• Data Model - Entity schemas and validation rules
• Research - Design decisions and rationale
• Development Guide - Setup and contribution guide
• Performance Tuning - Timeout and resource configuration
• Roadmap - Planned v2 features

Current Status

v2.0 Released! DAP Integration Complete 🎉

• ✅ Phase 1: Foundation (Complete - 6/6 tests passing)
• ✅ Phase 2: Core Logic (Complete - 28/28 tests passing)
• ✅ Phase 3: Session Lifecycle (Complete - 29/29 tests passing)
• ✅ Phase 4: Breakpoint Operations (Complete - 41/41 tests passing)
• ✅ Phase 5: Error Visibility (Complete - 71/71 tests passing)
• ✅ Phase 6: MCP SDK Migration (Complete - SDK-based server with async support)
• ✅ Phase 7: DAP Integration (Complete - Production-ready debugpy integration)

What's New in v2.0:

• DAP (debugpy) is now the default - No more sys.modules corruption!
• True step execution - Step in, step over, step out all working
• Automatic environment handling - Uses target project's Python interpreter
• Industry-standard protocol - Microsoft's battle-tested implementation
• Enhanced reliability - Isolated process execution prevents crashes
• Backward compatible - Legacy bdb mode still available with useDap=false

Migration from v1.x:

• Existing code works as-is (DAP is opt-in by default)
• To explicitly use bdb: StartSessionRequest(entry="...", useDap=False)
• Recommended: Let it default to DAP for best results

Limitations (v2)

• Script entry only: No module (python -m) or pytest target support (planned for v2.1)
• Single-threaded: No support for multi-threaded debugging (planned for v2.1)
• Line breakpoints: Conditional breakpoints not yet exposed via MCP (DAP supports it)

✅ Resolved from v1:

• No stepping → Now available: Step in, step over, step out
• sys.modules corruption → Fixed: DAP uses isolated processes
• Python environment mismatch → Fixed: Uses target interpreter

See docs/roadmap.md for planned v2.1+ enhancements.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Run tests and linting (uv run pytest && uv run ruff check .)
5. Commit changes (git commit -m 'Add amazing feature')
6. Push to branch (git push origin feature/amazing-feature)
7. Open a Pull Request

License

MIT License - see LICENSE file for details

Acknowledgments

Built with:

• debugpy - Microsoft's Python debugger (DAP implementation)
• MCP SDK - Model Context Protocol Python SDK
• bdb/pdb - Python's standard debugger framework (legacy mode)
• Pydantic - Data validation using Python type annotations
• Typer - CLI framework built on Click
• Rich - Beautiful terminal formatting
• pytest - Testing framework