Debug-MCP

# Debug-MCP: Model Context Protocol を通じた Python デバッグ AI アシスタントや開発ツールとの統合を目的とした、クリーンな API と CLI を通じてブレークポイントベースのデバッグ機能を提供する Python デバッグツールです。 [English](README.md) | 日本語 ## 機能 - **DAP による高度なデバッグ**: Microsoft の debugpy を使用した本番環境対応のデバッグ - **ブレークポイントデバッグ**: 実行時にブレークポイントを設定してローカル変数を検査 - **ステップ実行**: 真のステップイン、ステップオーバー、ステップアウト操作 - **破損なし**: 分離されたプロセス実行により sys.modules の問題を防止 - **環境認識**: ターゲットプロジェクトの Python インタプリタを自動使用 - **セッション管理**: タイムアウト保護機能付きの分離されたデバッグセッション - **デュアルインターフェース**: - **CLI**: 美しいテーブル出力を備えたインタラクティブデバッグ - **MCP サーバー**: AI アシスタント用の公式 MCP SDK ベースの統合 - **安全な実行**: 設定可能な制限付きサンドボックス化サブプロセス実行 - **型安全性**: リクエスト/レスポンス検証のための Pydantic v2 スキーマ - **非同期サポート**: 完全な async/await サポートを備えた MCP SDK 上に構築 - **包括的なテスト**: 254 テスト（119 ユニット + 122 統合 + 13 探索）で DAP ワークフロー、セッション管理、エッジケースをカバー - **レガシー互換性**: 後方互換性のためのオプションの bdb モード ## クイックスタート ### インストール ```bash # リポジトリをクローン 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 セットアップガイド](docs/vscode-setup.md) を参照してください。** **クイック設定（Debug-MCPリポジトリから使用する場合）:** 1. MCP 設定ディレクトリを作成（macOS/Linux）: ```bash mkdir -p ~/Library/Application\ Support/Code/User/globalStorage/github.copilot-chat ``` 2. `mcp.json` ファイルを編集: ```json { "mcpServers": { "python-debug": { "command": "uv", "args": ["run", "mcp-debug-server", "--workspace", "${workspaceFolder}"], "env": {"PYTHONUNBUFFERED": "1"} } } } ``` 3. VS Code を再起動 **別のリポジトリから使用する場合:** 別のリポジトリからこのツールを使用する場合は、Debug-MCPのインストールパスを指定します: ```json { "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 の使用方法（インタラクティブデバッグに推奨） ```bash # デバッグセッションを開始 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 の例については、[クイックスタートガイド](specs/001-python-debug-tool/quickstart.md)を参照してください。 ### API の使用方法（Python 統合） ```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) ``` ## アーキテクチャ ### 現在の実装（v2 - DAP ベース） Debug-MCP は本番環境でのデバッグに **DAP (Debug Adapter Protocol)** を debugpy 経由で使用しています： ``` ┌─────────────────────────────────────────────────┐ │ MCP サーバー (server.py) │ │ - 公式 MCP SDK（非同期） │ │ - ツール登録とルーティング │ └────────────────┬────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────┐ │ セッションマネージャー (sessions.py) │ │ - ライフサイクル管理 │ │ - DAP/bdb モード選択 │ └────────────────┬────────────────────────────────┘ │ ▼ (DAP モード - デフォルト) ┌─────────────────────────────────────────────────┐ │ DAPSyncWrapper (dap_wrapper.py) │ │ - 同期 DAP インターフェース │ │ - イベントキュー管理 │ │ - タイムアウト処理 │ └────────────────┬────────────────────────────────┘ │ DAP プロトコル (JSON-RPC) ▼ ┌─────────────────────────────────────────────────┐ │ debugpy サーバー（別プロセス） │ │ - Microsoft 公式 DAP 実装 │ │ - ブレークポイント、ステップ、変数処理 │ │ - ターゲットスクリプト実行管理 │ └────────────────┬────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────┐ │ ターゲット Python スクリプト │ │ - 分離されたプロセスで実行 │ │ - ターゲット依存関係への完全アクセス │ │ - sys.modules の破損なし │ └─────────────────────────────────────────────────┘ ``` **なぜ DAP (debugpy)？** - ✅ **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`）： ``` セッションマネージャー → runner_main.py（サブプロセス）→ 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 削除） ## 安全性と制約 ### 実行制限 - **タイムアウト**: ブレークポイント操作ごとに 20 秒（設定可能） - **出力キャプチャ**: セッションあたり最大 10MB - **変数の深さ**: ローカル変数検査で最大 2 レベルのネスト - **コレクションサイズ**: リスト/辞書で表示される最大 50 項目 - **文字列長**: 切り捨て前の最大 256 文字 ### セキュリティ - **パス検証**: プロジェクト相対パスのみ許可（`..` による移動不可） - **サブプロセス分離**: デバッグ対象は分離されたサブプロセスで実行 - **作業ディレクトリ**: ワークスペースルートに固定 - **ネットワークなし**: デバッグ対象には特別なネットワークアクセスなし（ただしアプリケーションコードはネットワークを使用可能） ⚠️ **重要**: デバッガーは最小限の制限でユーザーコードを実行します。信頼できるコードのみをデバッグしてください。 ## 開発 ### セットアップ 詳細なセットアップ手順については、[docs/development.md](docs/development.md) を参照してください。 クイックコマンド: ```bash # すべてのテストを実行（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 セットアップガイド](docs/vscode-setup.md) - VS Code Copilot での MCP ツール使用方法 ⭐ - [クイックスタートガイド](specs/001-python-debug-tool/quickstart.md) - CLI と API の使用例 - [仕様書](specs/001-python-debug-tool/spec.md) - 完全な機能仕様 - [データモデル](specs/001-python-debug-tool/data-model.md) - エンティティスキーマと検証ルール - [リサーチ](specs/001-python-debug-tool/research.md) - 設計決定と根拠 - [開発ガイド](docs/development.md) - セットアップと貢献ガイド - [パフォーマンスチューニング](docs/performance-tuning.md) - タイムアウトとリソース設定 - [ロードマップ](docs/roadmap.md) - v2 の計画機能 ## 現在の状況 **v2.0 リリース！DAP 統合完了** 🎉 - ✅ Phase 1: 基盤（完了 - 6/6 テスト合格） - ✅ Phase 2: コアロジック（完了 - 28/28 テスト合格） - ✅ Phase 3: セッションライフサイクル（完了 - 29/29 テスト合格） - ✅ Phase 4: ブレークポイント操作（完了 - 41/41 テスト合格） - ✅ Phase 5: エラー可視性（完了 - 71/71 テスト合格） - ✅ Phase 6: MCP SDK への移行（完了 - 非同期サポート付き SDK ベースサーバー） - ✅ **Phase 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+ で計画されている機能強化については、[docs/roadmap.md](docs/roadmap.md) を参照してください。 ## 貢献 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](LICENSE) ファイルを参照してください ## 謝辞 以下を使用して構築: - [debugpy](https://github.com/microsoft/debugpy) - Microsoft の Python デバッガー（DAP 実装） - [MCP SDK](https://github.com/modelcontextprotocol/python-sdk) - Model Context Protocol Python SDK - [bdb/pdb](https://docs.python.org/3/library/bdb.html) - Python の標準デバッガーフレームワーク（レガシーモード） - [Pydantic](https://docs.pydantic.dev/) - Python 型アノテーションを使用したデータ検証 - [Typer](https://typer.tiangolo.com/) - Click をベースにした CLI フレームワーク - [Rich](https://rich.readthedocs.io/) - 美しいターミナルフォーマット - [pytest](https://pytest.org/) - テストフレームワーク