Graph-based MCP server for systematic debugging using Problem-Solution Trees and Hypothesis-Experiment-Learning cycles
npm install mcp-server-debug-thinking



---
デバッグ時の思考フレームワークと、そこで得た知見をローカルディレクトリに保存 → 活用までを提供する MCP サーバーです。
Debug Thinking MCP は、デバッグプロセスを永続的な知識グラフとして構造化し、を再利用可能な資産に変えます。
📚 クイックスタートガイド - 実際のデバッグシナリオで使い方を学ぶ
$3複雑な問題を管理可能なサブ問題に分解し、各問題を独立して解決 | $3仮説を立て、実験で検証し、観察から学習を抽出する科学的手法 |
$3すべてのデバッグセッションが検索可能な知識として蓄積 | $3過去の類似問題と解決策を高速検索し、デバッグパスを提供 |
``bash`
npm install -g mcp-server-debug-thinking
`json`
{
"mcpServers": {
"debug-thinking": {
"command": "npx",
"args": ["mcp-server-debug-thinking"]
}
}
}
`mermaid`
graph LR
A[問題発生] --> B[問題を定義]
B --> C[仮説を立てる]
C --> D[実験を設計]
D --> E[結果を観察]
E --> F{問題解決?}
F -->|Yes| G[学習を抽出]
F -->|No| C
G --> H[知識として保存]
#### 1️⃣ 問題の定義
`typescript`
await use_tool("debug_thinking", {
action: "create",
nodeType: "problem",
content: "Next.jsアプリが'TypeError: Cannot read property of undefined'でクラッシュ",
metadata: {
tags: ["nextjs", "runtime-error", "production"],
},
});
#### 2️⃣ 仮説の作成
`typescript`
await use_tool("debug_thinking", {
action: "create",
nodeType: "hypothesis",
content: "SSRでのデータフェッチ時にundefinedチェックが不足している可能性",
parentId: "problem-123",
metadata: {
confidence: 85,
},
});
#### 3️⃣ 実験と観察
`typescript
// 実験を実行
await use_tool("debug_thinking", {
action: "create",
nodeType: "experiment",
content: "getServerSidePropsでオプショナルチェーンを追加",
parentId: "hypothesis-456",
});
// 結果を記録
await use_tool("debug_thinking", {
action: "create",
nodeType: "observation",
content: "エラーが解消し、ページが正常にレンダリングされる",
parentId: "experiment-789",
});
`
#### 4️⃣ 知識の活用
`typescript`
// 類似問題を検索
await use_tool("debug_thinking", {
action: "query",
type: "similar-problems",
parameters: {
pattern: "TypeError undefined Next.js SSR",
limit: 5,
},
});
Debug Thinkingは、すべてのデバッグプロセスを有向グラフとして記録します。各ノードは特定の意味を持ち、エッジ(矢印)がノード間の関係を表現します。
| ノードタイプ | 役割 | 例 |
| ------------------ | ------------------------ | ----------------------------------------------------- |
| 🔴 Problem | 解決すべき問題・エラー | TypeError: Cannot read property 'name' of undefined |ユーザーデータがnullの可能性
| 🔵 Hypothesis | 問題の原因についての仮説 | |nullチェックを追加してテスト
| 🟡 Experiment | 仮説を検証する実験 | |エラーが解消した
| 🟢 Observation | 実験結果の観察 | |外部APIのデータは必ず検証が必要
| ⚪ Learning | 得られた知見・教訓 | |オプショナルチェーンの実装
| 🟣 Solution | 検証済みの解決策 | |
問題の分解 ` 大きな問題を小さく分割 | 仮説検証サイクル ` 仮説→実験→観察の流れ | 知識の蓄積 ` 観察から学習し解決へ |
`mermaid
graph TD
P["🔴 問題
ボタンが反応しない"]
P -->|hypothesizes| H1["🔵 仮説1
イベントリスナーが
登録されていない"]
P -->|hypothesizes| H2["🔵 仮説2
別の要素が
ボタンを覆っている"]
H1 -->|tests| E1["🟡 実験1
console.logで
クリック確認"]
E1 -->|produces| O1["🟢 観察1
ログが出力
されない"]
H2 -->|tests| E2["🟡 実験2
DevToolsで
要素を調査"]
E2 -->|produces| O2["🟢 観察2
透明なdivが
上に存在"]
O1 -->|supports| H1
O2 -->|supports| H2
O2 -->|learns| L1["⚪ 学習
z-indexの確認は
デバッグの基本"]
L1 -->|solves| S["🟣 解決策
z-indexを修正"]
S -->|solves| P
style P fill:#ff6b6b,stroke:#333,stroke-width:3px
style H1 fill:#4ecdc4,stroke:#333,stroke-width:2px
style H2 fill:#4ecdc4,stroke:#333,stroke-width:2px
style E1 fill:#f39c12,stroke:#333,stroke-width:2px
style E2 fill:#f39c12,stroke:#333,stroke-width:2px
style O1 fill:#2ecc71,stroke:#333,stroke-width:2px
style O2 fill:#2ecc71,stroke:#333,stroke-width:2px
style L1 fill:#ecf0f1,stroke:#333,stroke-width:2px
style S fill:#9b59b6,stroke:#333,stroke-width:2px
`
この例では、よくある「ボタンがクリックできない」問題を通じて、Debug Thinkingがどのように動作するかを示しています:
1. 問題を定義: ボタンが反応しないという明確な問題
2. 複数の仮説: イベントリスナーの問題とレイアウトの問題
3. 実験で検証: console.logとDevToolsを使った検証
4. 観察から学習: z-indexの重要性を学習
5. 解決策の適用: 具体的な修正方法
過去の類似問題とその解決策を検索し、デバッグパスも含めて取得します。
`typescript
const result = await use_tool("debug_thinking", {
action: "query",
type: "similar-problems",
parameters: {
pattern: "TypeError undefined Next.js SSR",
limit: 5,
minSimilarity: 0.3,
},
});
// レスポンス例:
{
"problems": [{
"nodeId": "prob-123",
"content": "TypeError: Cannot read property 'name' of undefined in getServerSideProps",
"similarity": 0.85,
"status": "solved",
"solutions": [{
"nodeId": "sol-456",
"content": "Add optional chaining to handle undefined data",
"verified": true,
"debugPath": [
{ "nodeId": "prob-123", "type": "problem", "content": "..." },
{ "nodeId": "hyp-234", "type": "hypothesis", "content": "..." },
{ "nodeId": "exp-345", "type": "experiment", "content": "..." },
{ "nodeId": "obs-456", "type": "observation", "content": "..." },
{ "nodeId": "sol-456", "type": "solution", "content": "..." }
]
}]
}]
}
`
直近のデバッグノードを時系列で取得し、セッションの継続性を保ちます。
`typescript
const recentActivity = await use_tool("debug_thinking", {
action: "query",
type: "recent-activity",
parameters: {
limit: 10, // 取得件数(デフォルト: 10)
},
});
// レスポンス例:
{
"nodes": [{
"nodeId": "node-789",
"type": "solution",
"content": "Fixed by adding null check",
"createdAt": "2024-01-20T10:30:00Z",
"parent": {
"nodeId": "node-678",
"type": "observation",
"content": "Variable is undefined on first render"
},
"edges": [
{ "type": "solves", "targetNodeId": "prob-123", "direction": "from" }
]
}],
"totalNodes": 156
}
`
`text`
mcp-server-debug-thinking/
├── src/
│ ├── index.ts # MCPサーバーエントリーポイント
│ ├── services/
│ │ ├── GraphService.ts # グラフ操作のコアロジック
│ │ └── GraphStorage.ts # 永続化レイヤー
│ ├── types/
│ │ ├── graph.ts # グラフデータ型定義
│ │ └── graphActions.ts # アクション型定義
│ └── utils/
│ └── logger.ts # ロギングユーティリティ
└── .debug-thinking-mcp/ # データストレージ
├── nodes.jsonl # ノードデータ
├── edges.jsonl # エッジデータ
└── graph-metadata.json # メタデータ
`bashリポジトリをクローン
git clone https://github.com/tosssssy/mcp-server-debug-thinking.git
cd mcp-server-debug-thinking
このプロジェクトはMITライセンスの下で公開されています。詳細はLICENSEをご覧ください。