Debug MCP

🚀 Debug-MCP：基於模型上下文協議的Python調試工具

Debug-MCP是一款Python調試工具，它通過簡潔的API和命令行界面（CLI）提供基於斷點的調試功能，旨在與AI助手和開發工具集成，為開發者提供高效、安全的調試體驗。

English | 日本語

✨ 主要特性

• 基於DAP的高級調試：使用微軟的debugpy進行生產級調試。
  • 斷點調試：設置斷點並在運行時檢查局部變量。
  • 單步執行：支持真正的逐行進入、逐行跳過和逐行跳出操作。
  • 無數據損壞：隔離的進程執行避免了sys.modules問題。
  • 環境感知：自動使用目標項目的Python解釋器。
• 會話管理：具有超時保護的隔離調試會話。
• 雙接口設計：
  • 命令行界面（CLI）：交互式調試，輸出美觀的表格。
  • MCP服務器：基於官方MCP SDK，便於AI助手集成。
• 安全執行：具有可配置限制的沙盒子進程執行。
• 類型安全：使用Pydantic v2模式進行請求/響應驗證。
• 異步支持：基於MCP SDK構建，完全支持異步/等待。
• 全面測試：共254個測試（119個單元測試 + 122個集成測試 + 13個探索性測試），覆蓋DAP工作流、會話管理和邊緣情況。
• 舊版兼容性：可選的bdb模式，確保向後兼容。

🚀 快速開始

📦 安裝指南

# 克隆倉庫
git clone https://github.com/your-org/Debug-MCP.git
cd Debug-MCP

# 創建虛擬環境
uv venv

# 安裝並支持CLI
uv pip install -e ".[cli]"

VS Code Copilot集成

要在VS Code中使用此工具與GitHub Copilot集成，請設置MCP服務器配置。

詳細說明請參閱VS Code設置指南。

快速設置（從Debug-MCP倉庫使用）：

1. 創建MCP配置目錄（macOS/Linux）：

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

2. 編輯mcp.json文件：

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

3. 重啟VS Code

從其他倉庫使用： 使用此工具時，需指定Debug-MCP的安裝路徑：

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

請將/absolute/path/to/Debug-MCP替換為實際的Debug-MCP安裝路徑。

使用Copilot Chat：

@workspace 在src/main.py的第42行設置斷點，並顯示該點的局部變量。

完整的配置示例請參閱mcp-config-example.json。

💻 使用示例

命令行界面（CLI）使用示例（推薦用於交互式調試）

# 啟動調試會話
SESSION_ID=$(uv run mcp-debug start-session src/app.py | jq -r .sessionId)

# 運行到斷點並檢查局部變量
uv run mcp-debug run-to-breakpoint $SESSION_ID src/app.py 42 --format table

# 繼續執行到下一個斷點
uv run mcp-debug continue $SESSION_ID src/app.py 100 --format table

# 檢查會話狀態
uv run mcp-debug state $SESSION_ID --format table

# 結束會話
uv run mcp-debug end $SESSION_ID

更多CLI示例請參閱快速入門指南。

API使用示例（Python集成）

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

# 初始化
workspace = Path.cwd()
manager = SessionManager(workspace)

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

# 運行到斷點
bp_req = BreakpointRequest(file="src/main.py", line=15)
result = manager.run_to_breakpoint(session.sessionId, bp_req)

if result.hit:
    print(f"在 {result.frameInfo.file}:{result.frameInfo.line} 處暫停")
    print(f"局部變量: {result.locals}")

# 繼續執行
continue_result = manager.continue_execution(
    session.sessionId, 
    BreakpointRequest(file="src/main.py", line=42)
)

# 清理會話
manager.end_session(session.sessionId)

🔧 技術細節

安全與限制

執行限制

• 超時時間：每個斷點操作的超時時間為20秒（可配置）。
• 輸出捕獲：每個會話的最大輸出捕獲量為10MB。
• 變量深度：局部變量檢查的最大嵌套級別為2級。
• 集合大小：列表/字典中最多顯示50個項目。
• 字符串長度：字符串在截斷前的最大長度為256個字符。

安全措施

• 路徑驗證：只允許使用項目相對路徑（不允許..遍歷）。
• 子進程隔離：被調試程序在隔離的子進程中運行。
• 工作目錄：鎖定到工作區根目錄。
• 無網絡訪問：被調試程序沒有特殊的網絡訪問權限（應用程序代碼仍可使用網絡）。

⚠️ 重要提示

調試器在執行用戶代碼時限制較少，請僅調試受信任的代碼。

架構

當前實現（v2 - 基於DAP）

Debug-MCP現在使用DAP（調試適配器協議） 通過debugpy進行生產調試：

┌─────────────────────────────────────────────────┐
│ MCP服務器 (server.py)                           │
│ - 官方MCP SDK (異步)                            │
│ - 工具註冊與路由                                │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│ 會話管理器 (sessions.py)                        │
│ - 生命週期管理                                 │
│ - DAP/bdb模式選擇                               │
└────────────────┬────────────────────────────────┘
                 │
                 ▼ (DAP模式 - 默認)
┌─────────────────────────────────────────────────┐
│ DAP同步包裝器 (dap_wrapper.py)                  │
│ - 同步DAP接口                                   │
│ - 事件隊列管理                                 │
│ - 超時處理                                     │
└────────────────┬────────────────────────────────┘
                 │ DAP協議 (JSON-RPC)
                 ▼
┌─────────────────────────────────────────────────┐
│ debugpy服務器 (獨立進程)                        │
│ - 微軟官方DAP實現                               │
│ - 處理斷點、單步執行、變量檢查                  │
│ - 管理目標腳本執行                              │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│ 目標Python腳本                                  │
│ - 在隔離進程中運行                              │
│ - 完全訪問目標依賴項                            │
│ - 無sys.modules損壞                             │
└─────────────────────────────────────────────────┘

為什麼選擇DAP（debugpy）？

• ✅ 無sys.modules損壞 - 在單獨的進程中運行。
• ✅ 真正的單步執行 - 跨步驟保持執行狀態。
• ✅ 自動環境處理 - 使用目標Python解釋器。
• ✅ 行業標準 - 微軟經過實戰檢驗的實現。
• ✅ 功能豐富 - 支持逐行進入/跳過/跳出、條件斷點、監視表達式。
• ✅ 面向未來 - 易於擴展高級調試功能。

通信流程：

1. MCP客戶端（VS Code Copilot） → MCP服務器（工具調用）
2. 服務器 → 會話管理器（通過異步包裝器的同步方法）
3. 會話管理器 → DAP同步包裝器（管理DAP會話）
4. DAP同步包裝器 ↔ debugpy服務器（通過套接字使用DAP協議）
5. debugpy捕獲局部變量 → DAP同步包裝器 → 會話管理器 → 服務器 → 客戶端

舊版bdb模式

基於bdb的實現仍然可用，以確保兼容性（useDap=false）：

會話管理器 → runner_main.py (子進程) → 調試控制器 (bdb)

然而，DAP現在是默認模式，建議在所有用例中使用。bdb模式存在已知問題：

• 多次運行時會出現sys.modules損壞。
• 沒有真正的單步執行（基於重放）。
• 複雜的PYTHONPATH管理。

文件組織（2025-11-03）

活動文件（生產環境）：

• ✅ server.py - MCP SDK服務器
• ✅ sessions.py - 會話生命週期管理
• ✅ dap_wrapper.py - DAP同步包裝器（主要）
• ✅ dap_client.py - 底層DAP協議客戶端（主要）
• ✅ schemas.py - Pydantic模型
• ✅ utils.py - 變量表示輔助函數和路徑實用工具

舊版文件（兼容性）：

• ⚠️ debugger.py - 基於bdb的引擎（舊版，使用useDap=false）
• ⚠️ runner_main.py - bdb子進程運行器（舊版）

已移除文件：

• runner.py - 舊的多進程方法（2025-10-30移除）

開發

環境設置

詳細的設置說明請參閱docs/development.md。

快速命令：

# 運行所有測試（254個測試：119個單元測試 + 122個集成測試 + 13個探索性測試）
uv run pytest

# 僅運行單元測試
uv run pytest tests/unit/

# 僅運行集成測試
uv run pytest tests/integration/

# 運行測試並生成覆蓋率報告
uv run pytest --cov=src/mcp_debug_tool --cov-report=html

# 代碼檢查
uv run ruff check .

# 代碼格式化
uv run ruff format .

# 自動修復代碼檢查問題
uv run ruff check --fix .

項目結構

Debug-MCP/
├── src/
│   ├── mcp_debug_tool/      # 核心調試引擎
│   │   ├── server.py        # MCP SDK服務器 (v2.0+)
│   │   ├── sessions.py      # 會話管理 (DAP/bdb模式選擇)
│   │   ├── dap_wrapper.py   # DAP同步包裝器 (主要)
│   │   ├── dap_client.py    # DAP協議客戶端 (主要)
│   │   ├── debugger.py      # 基於bdb的調試器 (舊版, 使用useDap=false)
│   │   ├── runner_main.py   # bdb子進程運行器 (舊版)
│   │   ├── schemas.py       # Pydantic模型
│   │   └── utils.py         # 變量表示輔助函數
│   └── cli/
│       └── main.py          # Typer CLI
├── tests/
│   ├── unit/                # 單元測試 (調試器、模式、DAP、會話)
│   └── integration/         # 集成測試 (DAP工作流、bdb兼容性)
├── specs/
│   └── 001-python-debug-tool/  # 規範文檔
└── docs/                    # 附加文檔
    ├── dap-phase*-*.md      # DAP集成文檔
    └── roadmap.md           # 未來增強計劃

📚 詳細文檔

• VS Code設置指南 - 如何在VS Code中使用MCP工具與Copilot集成 ⭐
• 快速入門指南 - CLI和API使用示例
• 規範文檔 - 完整的功能規範
• 數據模型 - 實體模式和驗證規則
• 研究文檔 - 設計決策和原理
• 開發指南 - 設置和貢獻指南
• 性能調優 - 超時和資源配置
• 路線圖 - 計劃中的v2功能

當前狀態

v2.0已發佈！DAP集成完成 🎉

• ✅ 階段1：基礎功能（完成 - 6/6測試通過）
• ✅ 階段2：核心邏輯（完成 - 28/28測試通過）
• ✅ 階段3：會話生命週期（完成 - 29/29測試通過）
• ✅ 階段4：斷點操作（完成 - 41/41測試通過）
• ✅ 階段5：錯誤可見性（完成 - 71/71測試通過）
• ✅ 階段6：MCP SDK遷移（完成 - 基於SDK的服務器，支持異步）
• ✅ 階段7：DAP集成（完成 - 生產級debugpy集成）

v2.0的新特性：

• DAP（debugpy）現在是默認模式 - 不再有sys.modules損壞問題！
• 真正的單步執行 - 逐行進入、逐行跳過、逐行跳出功能均正常工作。
• 自動環境處理 - 使用目標項目的Python解釋器。
• 行業標準協議 - 微軟經過實戰檢驗的實現。
• 增強的可靠性 - 隔離的進程執行防止崩潰。
• 向後兼容 - 舊版bdb模式仍然可用，可通過useDap=false啟用。

從v1.x遷移：

• 現有代碼可以直接使用（默認啟用DAP）。
• 若要顯式使用bdb：StartSessionRequest(entry="...", useDap=False)。
• 建議：默認使用DAP以獲得最佳效果。

限制（v2）

• 僅支持腳本入口：不支持模塊（python -m）或pytest目標（計劃在v2.1中支持）。
• 單線程：不支持多線程調試（計劃在v2.1中支持）。
• 行斷點：條件斷點尚未通過MCP暴露（DAP支持）。

✅ v1已解決的問題：

• 無單步執行功能 → 現在可用：逐行進入、逐行跳過、逐行跳出。
• sys.modules損壞 → 已修復：DAP使用隔離進程。
• Python環境不匹配 → 已修復：使用目標解釋器。

計劃中的v2.1+增強功能請參閱docs/roadmap.md。

貢獻

1. 分叉倉庫。
2. 創建功能分支 (git checkout -b feature/amazing-feature)。
3. 進行更改並編寫測試。
4. 運行測試和代碼檢查 (uv run pytest && uv run ruff check .)。
5. 提交更改 (git commit -m '添加出色的功能')。
6. 推送到分支 (git push origin feature/amazing-feature)。
7. 打開拉取請求。

📄 許可證

本項目採用MIT許可證，請參閱LICENSE文件獲取詳細信息。

致謝

本項目基於以下開源項目構建：

• debugpy - 微軟的Python調試器（DAP實現）
• MCP SDK - 模型上下文協議Python SDK
• bdb/pdb - Python的標準調試器框架（舊版模式）
• Pydantic - 使用Python類型註解進行數據驗證
• Typer - 基於Click構建的CLI框架
• Rich - 美觀的終端格式化工具
• pytest - 測試框架