Skip to main content
Glama
debug-thinking

debug-thinking

by tosssssy

🧠 Debug Thinking MCP

npm version License: MIT Node.js Version MCP SDK


Debug Thinking MCP について

デバッグ時の思考フレームワークと、そこで得た知見をローカルディレクトリに保存 → 活用までを提供する MCP サーバーです。

Debug Thinking MCP は、デバッグプロセスを永続的な知識グラフとして構造化し、を再利用可能な資産に変えます。

📚 クイックスタートガイド - 実際のデバッグシナリオで使い方を学ぶ

Related MCP server: world-model-mcp

🚀 主要機能

🌳 問題解決ツリー

複雑な問題を管理可能なサブ問題に分解し、各問題を独立して解決

🔬 H-E-Lサイクル

仮説を立て、実験で検証し、観察から学習を抽出する科学的手法

🧠 知識グラフ

すべてのデバッグセッションが検索可能な知識として蓄積

🔍 類似問題検索

過去の類似問題と解決策を高速検索し、デバッグパスを提供

📦 クイックスタート

1. インストール

npm install -g mcp-server-debug-thinking

2. MCP Server 設定

{
  "mcpServers": {
    "debug-thinking": {
      "command": "npx",
      "args": ["mcp-server-debug-thinking"]
    }
  }
}

🎯 使用方法

基本的なデバッグフロー

graph LR
    A[問題発生] --> B[問題を定義]
    B --> C[仮説を立てる]
    C --> D[実験を設計]
    D --> E[結果を観察]
    E --> F{問題解決?}
    F -->|Yes| G[学習を抽出]
    F -->|No| C
    G --> H[知識として保存]

実際の使用例

1️⃣ 問題の定義

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️⃣ 仮説の作成

await use_tool("debug_thinking", {
  action: "create",
  nodeType: "hypothesis",
  content: "SSRでのデータフェッチ時にundefinedチェックが不足している可能性",
  parentId: "problem-123",
  metadata: {
    confidence: 85,
  },
});

3️⃣ 実験と観察

// 実験を実行
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️⃣ 知識の活用

// 類似問題を検索
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

🔵 Hypothesis

問題の原因についての仮説

ユーザーデータがnullの可能性

🟡 Experiment

仮説を検証する実験

nullチェックを追加してテスト

🟢 Observation

実験結果の観察

エラーが解消した

⚪ Learning

得られた知見・教訓

外部APIのデータは必ず検証が必要

🟣 Solution

検証済みの解決策

オプショナルチェーンの実装

関係性(エッジ)の種類

問題の分解

graph TD
    P1[🔴 問題] -->|decomposes| P2[🔴 サブ問題]

大きな問題を小さく分割

仮説検証サイクル

graph TD
    P3[🔴 問題] -->|hypothesizes| H[🔵 仮説]
    H -->|tests| E[🟡 実験]
    E -->|produces| O[🟢 観察]

仮説→実験→観察の流れ

知識の蓄積

graph TD
    O2[🟢 観察] -->|learns| L[⚪ 学習]
    L -->|solves| P4[🔴 問題]

観察から学習し解決へ

実際のデバッグ例:「ボタンクリックが効かない」

graph TD
    P["🔴 問題<br/>ボタンが反応しない"]

    P -->|hypothesizes| H1["🔵 仮説1<br/>イベントリスナーが<br/>登録されていない"]
    P -->|hypothesizes| H2["🔵 仮説2<br/>別の要素が<br/>ボタンを覆っている"]

    H1 -->|tests| E1["🟡 実験1<br/>console.logで<br/>クリック確認"]
    E1 -->|produces| O1["🟢 観察1<br/>ログが出力<br/>されない"]

    H2 -->|tests| E2["🟡 実験2<br/>DevToolsで<br/>要素を調査"]
    E2 -->|produces| O2["🟢 観察2<br/>透明なdivが<br/>上に存在"]

    O1 -->|supports| H1
    O2 -->|supports| H2

    O2 -->|learns| L1["⚪ 学習<br/>z-indexの確認は<br/>デバッグの基本"]

    L1 -->|solves| S["🟣 解決策<br/>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. 解決策の適用: 具体的な修正方法

🔍 クエリ機能

類似問題の検索と解決策の取得

過去の類似問題とその解決策を検索し、デバッグパスも含めて取得します。

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": "..." }
      ]
    }]
  }]
}

最近の活動を確認

直近のデバッグノードを時系列で取得し、セッションの継続性を保ちます。

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
}

🏗️ アーキテクチャ

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   # メタデータ

🛠️ 開発者向け

ローカル開発

# リポジトリをクローン
git clone https://github.com/tosssssy/mcp-server-debug-thinking.git
cd mcp-server-debug-thinking

# 依存関係をインストール
npm install

# 開発モードで実行
npm run dev

# テストを実行
npm test

# プロダクションビルド
npm run build

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。詳細はLICENSEをご覧ください。

Available Tools

1 tool
debug_thinkingA

Graph-based debugging knowledge management system. Helps track debugging process systematically and retrieve past solutions.

Use this tool when:

  • User reports an error or bug that needs systematic investigation

  • You need to document your debugging approach for complex issues

  • You want to check if similar problems were solved before

  • Building a knowledge base of debugging patterns

Actions:

  1. CREATE - Add nodes to the debugging graph

    • nodeType: problem|hypothesis|experiment|observation|learning|solution

    • content: Description of the node

    • parentId: Optional parent node for automatic edge creation

    • metadata: Optional tags, confidence scores, etc.

  2. CONNECT - Link nodes with relationships

    • from/to: Node IDs to connect

    • type: decomposes|hypothesizes|tests|produces|learns|contradicts|supports|solves

    • strength: 0-1 relationship strength

  3. QUERY - Search and analyze the graph

    • queryType: similar-problems|recent-activity

    • parameters: pattern (search text), limit, minSimilarity

Example workflow:

  • CREATE problem "TypeError: Cannot read property 'x' of undefined"

  • CREATE hypothesis "Missing null check in async operation"

  • CREATE experiment "Add optional chaining operator"

  • CREATE observation "Error resolved"

  • QUERY similar-problems with pattern "TypeError undefined"

Data persists in ~/.debug-thinking-mcp/

Inputs: action (required), nodeType, content, parentId, +7 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.9/5.0

    Scored across 1 tool

    Disambiguation5/5

    Only one tool exists, so there is no ambiguity between tools. The tool's multiple actions are clearly separated within it.

    Naming Consistency5/5

    The single tool name 'debug_thinking' is consistent and descriptive. No naming inconsistencies exist.

    Tool Count5/5

    One tool is appropriate for this domain as it encapsulates all necessary operations (create, connect, query) in a cohesive interface for debugging knowledge management.

    Completeness4/5

    The tool covers core actions like creating nodes, connecting them, and querying. Missing explicit update/delete operations for nodes, but the graph-based approach may rely on recreation.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      Not graded
      maintenance
      An intelligent debugging assistant that automates the debugging process by analyzing bugs, injecting HTTP-based debug logs into code across multiple environments (browser, Node.js, mobile, etc.), and iteratively fixing issues based on real-time feedback.
      8
      MIT
    • A
      license
      C
      quality
      C
      maintenance
      Temporal knowledge graph for codebases that captures decision traces, links test failures to code changes, learns co-edit patterns, predicts regression risk, and enforces learned constraints at the edit boundary via a PreToolUse hook.
      31
      24
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to maintain a persistent knowledge graph of a project, providing dependency context, impact analysis, side-effect discovery, and session recording for more informed coding decisions.
      5
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables coding agents to maintain a shared, verified memory of debugging failures and fixes, with candidate verification, project-scoped search, and cross-project promotion.
      6 npm
      MIT