debug_mcp_draft.md•8.9 kB
# 🧩 Copilot連携デバッグ支援ツール 仕様書（設計書）
## 1. 概要
本ツールは、**GitHub Copilot（MCP対応）とVS CodeのPythonデバッガ（DAP対応）を統合**し、
自然言語による指示でPythonコードのデバッグを自動化することを目的とする。
Copilotチャット画面から「この関数のバグを調べて」と指示すると、
LLMエージェントが自動的にデバッガを操作し、
実行・ステップ・変数観察・原因推定を行う。
---
## 2. システム構成
```plaintext
+----------------------------------------------------------+
| VS Code (IDE) |
| +----------------------------------------------------+ |
| | Copilot Chat (LLM) | |
| | ↓ MCP呼び出し | |
| | [あなたのデバッグ支援MCPツール] | |
| +----------------------------------------------------+ |
| ↓ DAP通信 (Debug Adapter Protocol) |
| +----------------------------------------------------+ |
| | Python Debug Adapter (debugpy) | |
| +----------------------------------------------------+ |
| ↓ 実コード実行環境 |
| +----------------------------------------------------+ |
| | 対象Pythonアプリケーション | |
| +----------------------------------------------------+ |
+----------------------------------------------------------+
```
---
## 3. 技術スタック
| 項目 | 技術 / モジュール |
| ---------- | ---------------------------------------------------------- |
| IDE | Visual Studio Code |
| LLM | GitHub Copilot（MCP対応） |
| プロトコル | MCP (Model Context Protocol), DAP (Debug Adapter Protocol) |
| MCPツール実装言語 | Node.js または Python |
| Pythonデバッガ | `debugpy` |
| 通信形式 | JSON-RPC over WebSocket |
| モデル提案処理 | OpenAI API (GPT-4/5) またはローカルLLM |
| 拡張ポイント | VS Code MCPツール登録・Copilot Agent呼び出し |
---
## 4. 機能一覧
### 4.1 基本機能
| 機能名 | 概要 | 対応プロトコル |
| ---------------------------------- | ---------------------- | --------- |
| 🔹 セッション開始 (`start_debug_session`) | 指定ファイル・行からPythonデバッグ開始 | MCP → DAP |
| 🔹 ステップ実行 (`step`) | 1行ずつコードを進める（ステップオーバー） | DAP |
| 🔹 関数内部に入る (`step_in`) | 関数呼び出しに入る | DAP |
| 🔹 関数外に出る (`step_out`) | 関数実行完了まで進める | DAP |
| 🔹 変数取得 (`get_variables`) | 現在スコープの変数値を取得 | DAP |
| 🔹 コールスタック取得 (`get_stacktrace`) | 実行中のスタック情報を取得 | DAP |
| 🔹 式評価 (`evaluate`) | 任意のPython式を現在スコープで評価 | DAP |
| 🔹 停止 (`stop_debug_session`) | デバッグセッション終了 | MCP |
---
### 4.2 LLM統合機能
| 機能 | 概要 |
| --------- | ----------------------------------- |
| バグ分析 | 取得した変数・コールスタック情報をLLMに渡し、異常箇所を自動分析 |
| 自動ステップ制御 | LLMが次にステップすべき箇所を判断し、自動的に`step()`を呼ぶ |
| 修正提案 | バグ原因の推定と修正パッチ（差分コード）を生成 |
| 根本原因報告 | 「どの関数で・どの条件で不具合が発生したか」を自然言語で報告 |
| ユーザ承認付き実行 | LLM提案を即実行せず、ユーザ承認後に反映 |
---
## 5. MCPツール仕様
### 5.1 MCP Manifest
`manifest.json`
```json
{
"name": "debug-assistant",
"description": "Python debugging tool integrated with Copilot",
"tools": [
{
"name": "start_debug_session",
"description": "Start debugging a Python file from a specific line",
"parameters": {
"file": "string",
"line": "integer"
}
},
{
"name": "step",
"description": "Step over to the next line"
},
{
"name": "get_variables",
"description": "Get current local and global variable values"
},
{
"name": "get_stacktrace",
"description": "Retrieve the current stacktrace"
},
{
"name": "evaluate",
"description": "Evaluate a Python expression in the current context",
"parameters": {
"expression": "string"
}
},
{
"name": "stop_debug_session",
"description": "Terminate the current debugging session"
}
]
}
```
---
### 5.2 MCPツール内部構造
```plaintext
MCP Adapter (Node.js/Python)
├─ config/
│ └─ manifest.json
├─ src/
│ ├─ main.ts (MCP entrypoint)
│ ├─ debugSession.ts (DAPクライアント管理)
│ ├─ variableFetcher.ts (変数取得処理)
│ ├─ llmAnalyzer.ts (LLM呼び出し・推論処理)
│ └─ utils/logger.ts
└─ tests/
└─ debugSession.test.ts
```
---
## 6. DAP連携仕様
### 6.1 利用するDAPメッセージ
| コマンド | 説明 |
| -------------------- | ------------ |
| `initialize` | デバッグセッション初期化 |
| `launch` / `attach` | 対象プロセスへの接続 |
| `setBreakpoints` | ブレークポイント設定 |
| `continue` | 実行再開 |
| `next` | ステップオーバー |
| `stepIn` / `stepOut` | 関数の入出制御 |
| `stackTrace` | 現在のコールスタック取得 |
| `scopes` | スコープ情報取得 |
| `variables` | 各スコープ変数一覧取得 |
| `evaluate` | 式評価 |
### 6.2 通信例
```json
{
"seq": 1,
"type": "request",
"command": "next",
"arguments": { "threadId": 1 }
}
```
```json
{
"seq": 2,
"type": "response",
"request_seq": 1,
"success": true,
"body": {
"line": 42,
"source": { "path": "main.py" }
}
}
```
---
## 7. LLMエージェント動作シーケンス
```plaintext
User: 「この関数のバグを調べて」
↓
Copilot (LLM)
├─> MCP: start_debug_session("app.py", 120)
├─> MCP: step() / get_variables() / get_stacktrace()
├─> LLM内部解析:
│ if variable "user_id" == None:
│ 推定: 初期化漏れ
├─> MCP: evaluate("user_id")
└─> Copilot出力:
「関数login_user内でuser_idがNoneです。初期化されていません。」
```
---
## 8. セキュリティ設計
| 項目 | 対策 |
| ----- | ------------------------------ |
| 実行環境 | `debugpy`サンドボックス内で制御（外部アクセス制限） |
| 変数値送信 | 機密データをフィルタリングしてLLMへ送信 |
| コード改変 | ユーザ承認必須（自動適用しない） |
| ログ管理 | MCPとDAP通信ログを暗号化保存 |
---
## 9. 拡張計画
| フェーズ | 内容 |
| ---- | ----------------------- |
| v1.0 | Python対応 / 基本デバッグ機能 |
| v1.1 | LLMによる自動原因推定・修正提案 |
| v2.0 | 他言語対応（JavaScript, Goなど） |
| v2.1 | マルチスレッド・非同期コード対応 |
| v3.0 | 静的解析・実行トレース融合型LLMデバッグ |
---
## 10. ライセンス / メンテナンス
| 項目 | 内容 |
| ------ | ---------------------------------------------- |
| ライセンス | MIT |
| メンテナ | Community |
| バックエンド | OpenAI GPT-5 (予定) |
| レポジトリ | `github.com/your-org/Debug-MCP` |
---
### ✅ 次のステップ提案
* [ ] MCPツール雛形（Node or Python）を生成
* [ ] DAP通信クライアント実装（`debugpy`制御）
* [ ] VS Codeへの登録テスト
* [ ] Chatプロンプト連携テスト
---