Debug MCP

🚀 Debug - MCP: Python Debugging via Model Context Protocol

Debug - MCPは、クリーンなAPIとCLIを通じてブレークポイントベースのデバッグ機能を提供するPythonデバッグツールです。AIアシスタントや開発ツールとの統合を目的として設計されています。

English | 日本語

✨ 主な機能

• DAPによる高度なデバッグ: Microsoftのdebugpyを使用した本番環境でも利用可能なデバッグ
  • ブレークポイントデバッグ: ブレークポイントを設定し、実行時にローカル変数を検査できます。
  • ステップ実行: 本格的なステップイン、ステップオーバー、ステップアウト操作が可能です。
  • 破損防止: 分離されたプロセスで実行するため、sys.modulesの問題を防ぎます。
  • 環境認識: 自動的に対象プロジェクトのPythonインタープリターを使用します。
• セッション管理: タイムアウト保護付きの分離されたデバッグセッションを提供します。
• デュアルインターフェース:
  • CLI: 美しいテーブル出力で対話的なデバッグができます。
  • MCPサーバー: AIアシスタント用の公式MCP SDKベースの統合機能があります。
• 安全な実行: 設定可能な制限付きのサンドボックス化されたサブプロセスで実行されます。
• 型安全: Pydantic v2スキーマを使用してリクエスト/レスポンスの検証を行います。
• 非同期サポート: MCP SDKをベースに構築され、完全なasync/awaitサポートがあります。
• 包括的なテスト: DAPワークフロー、セッション管理、エッジケースをカバーする254個のテスト（119個の単体テスト + 122個の統合テスト + 13個の探索的テスト）があります。
• レガシー互換性: 下位互換性のためのオプションの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 Set a breakpoint at line 42 in src/main.py and 
show me the local variables at that point.

完全な設定例については、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）

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"Paused at {result.frameInfo.file}:{result.frameInfo.line}")
    print(f"Locals: {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は現在、本番環境でのデバッグにdebugpyを介した**DAP（Debug Adapter Protocol）**を使用しています。

┌─────────────────────────────────────────────────┐
│ 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                     │
└─────────────────────────────────────────────────┘

なぜDAP（debugpy）を使用するのか？

• ✅ sys.modulesの破損がない: 別のプロセスで実行されるため、sys.modulesの破損を防ぎます。
• ✅ 本格的なステップ実行: ステップ間で実行状態を維持します。
• ✅ 自動的な環境処理: 対象のPythonインタープリターを使用します。
• ✅ 業界標準のプロトコル: Microsoftの実績のある実装です。
• ✅ 豊富な機能: ステップイン、ステップオーバー、ステップアウト、条件付きブレークポイント、ウォッチ式などの機能があります。
• ✅ 将来性がある: 高度なデバッグ機能を容易に拡張できます。

通信フロー:

1. MCPクライアント（VS Code Copilot） → MCPサーバー（ツール呼び出し）
2. サーバー → セッションマネージャー（非同期ラッパーを介した同期メソッド）
3. セッションマネージャー → DAPSyncWrapper（DAPセッションを管理）
4. DAPSyncWrapper ↔ debugpyサーバー（ソケットを介したDAPプロトコル）
5. debugpyがローカル変数をキャプチャ → DAPSyncWrapper → セッションマネージャー → サーバー → クライアント

レガシーbdbモード

bdbベースの実装は、互換性のために引き続き利用可能です（useDap=false）。

SessionManager → runner_main.py (subprocess) → DebugController (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に削除）

📚 ドキュメント

• VS Codeセットアップガイド - VS Code CopilotでMCPツールを使用する方法 ⭐
• クイックスタートガイド - 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インタープリターを使用します。
• 業界標準のプロトコル - Microsoftの実績のある実装です。
• 信頼性の向上 - 分離されたプロセスで実行することでクラッシュを防ぎます。
• 下位互換性 - useDap=falseでレガシーbdbモードも引き続き利用可能です。

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以降の機能強化については、ロードマップを参照してください。

コントリビュート方法

1. リポジトリをフォークします。
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）。
3. テストを含めて変更を加えます。
4. テストとリントを実行します（uv run pytest && uv run ruff check .）。
5. 変更をコミットします（git commit -m 'Add amazing feature'）。
6. ブランチにプッシュします（git push origin feature/amazing-feature）。
7. プルリクエストを作成します。

📄 ライセンス

MITライセンス - 詳細についてはLICENSEファイルを参照してください。

謝辞

以下のツールを使用して構築されています。

• debugpy - MicrosoftのPythonデバッガ（DAP実装）
• MCP SDK - Model Context Protocol Python SDK
• bdb/pdb - Pythonの標準デバッガフレームワーク（レガシーモード）
• Pydantic - Pythonの型アノテーションを使用したデータ検証
• Typer - ClickをベースにしたCLIフレームワーク
• Rich - 美しいターミナルフォーマット
• pytest - テストフレームワーク