💭 thought-graph-mcp

If it's hallucinating, make it think. Inspired by a research paper, this local MCP makes an LLM reason out loud as an explicit, editable graph of small thinking steps instead of one opaque answer.

<p align="center"> <img src="examples/web-crawler-design/web-crawler-design.png" alt="Thought graph for a web crawler system design session" width="800" /> <br /> <em>Example: <a href="examples/web-crawler-design/web-crawler-system-design-bote-estimation-b8cf4764.html">web crawler system design with back-of-the-envelope estimation</a></em> </p>

1. Injects guidance that instructs the LLM to break a complex problem into multiple smaller reasoning paths (returned by the begin_thinking tool).
2. Saves the thinking process to a Markdown file (.md) — every step, with dependencies, branches, confidence, and revisions.
3. Renders an interactive HTML graph (.html) so you can see each step as a node and how they connect.
4. Lets you understand how the LLM reached the answer by walking the graph node-by-node (click any node for its full reasoning).
5. Lets you pinpoint a specific step and regenerate it — the revise_step tool supersedes that node, drops in a fresh revision, and tells the model which downstream steps to reconsider.

https://github.com/user-attachments/assets/29162024-35ce-4b98-8be2-9745560fe16a

Demo

Explore a full web crawler system design session

https://github.com/user-attachments/assets/b3341f27-89af-460a-927f-b4f65a39090d

Get Started

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "thought-graph": {
      "command": "npx",
      "args": ["-y", "thought-graph-mcp"],
      "env": {
        "THOUGHT_GRAPH_DIR": "~/thought-graph-sessions"
      }
    }
  }
}

Session artifacts default to ~/thought-graph-sessions/. Override with THOUGHT_GRAPH_DIR in the server's env block if you want a different folder.

Restart Claude Desktop. Enable the server under the 🔌 (MCP) menu — the tools (begin_thinking, add_thought, etc.) become available to the model.

Claude Code

Project-scoped (create .mcp.json in your project root):

{
  "mcpServers": {
    "thought-graph": {
      "command": "npx",
      "args": ["-y", "thought-graph-mcp"]
    }
  }
}

Or add it from the CLI:

claude mcp add thought-graph -- npx -y thought-graph-mcp

Verify with claude mcp list.

Try it

In the client, ask:

Use the thought-graph tools to reason about: should our team migrate from REST to GraphQL?

The model will call begin_thinking, decompose into sub-problems, branch competing hypotheses, attach evidence, and finalize_thinking. Open the generated .html:

• Click a node → full reasoning + its dependencies in the side panel.
• Spot a weak step (e.g. n4) → tell the assistant "revise step n4 of session <id> — that assumption is wrong because …". It calls revise_step, the node is dimmed as superseded, a revision replaces it, and the graph rebuilds.

Examples

Here are a few examples of using the MCP tool to analyze mission-critical LLM inference.

Example	Problem	Nodes	Directory
Web crawler system design + BOTE	Design a crawler for ~1B pages/month — politeness, dedup, refresh — with back-of-the-envelope sizing for storage, bandwidth, QPS, and fleet size	18	examples/web-crawler-design/
Rate limit service design	Design a distributed rate limiter — high throughput, low latency, flexible per-user/key/endpoint rules, graceful degradation	21	examples/rate-limit-service-design/
Autocomplete feature design	Design typeahead suggestions — data source, matching/ranking, frontend UX, latency, accessibility	14	examples/autocomplete-feature-design/

---

How it works

Prompt

The guidance in src/prompt.ts is injected into the context window when the tool begin_thinking is called, instructing the model to build the thought graph.

Node types

Every node in the graph has a type. It drives node color in the HTML graph, grouping in the Markdown export, and the shape of the reasoning protocol the model follows.

Type	Label	What it represents	How it's created
root	🎯 Problem	The original question the session is about	Automatically by begin_thinking (node n1)
decompose	🔱 Decompose	A framing step that breaks the problem into axes or sub-questions	add_thought
subproblem	🧩 Sub-problem	One focused piece of the larger problem to solve	add_thought
hypothesis	💡 Hypothesis	A candidate idea or approach — sibling hypotheses are parallel branches	add_thought
evidence	📎 Evidence	A fact, observation, or computation that supports a path	add_thought
evaluation	⚖️ Evaluation	Weighing trade-offs or checking whether a hypothesis holds	add_thought
revision	♻️ Revision	A corrected replacement for an earlier step	Automatically by revise_step (original node is kept but dimmed as superseded)
conclusion	✅ Conclusion	A synthesized partial or final answer for a branch	add_thought; the session-level answer is recorded separately via finalize_thinking

Typical flow: root → decompose → one or more subproblem nodes → competing hypothesis branches on each → evidence / evaluation attached to the relevant branch → conclusion nodes that merge paths → finalize_thinking for the overall answer. If a step turns out wrong, revise_step inserts a revision node and flags downstream dependents for reconsideration.

---

MCP Size

npx -y thought-graph-mcp downloads the npm package and its dependencies into your npm/npx cache, then runs the MCP server as a Node.js process over stdio. You do not need to clone this repo or run a bundler.

What	Approx. size	Role
npm package (thought-graph-mcp)	~280 KB download · ~1.2 MB unpacked	Compiled MCP server (dist/), Handlebars template, plus pre-copied browser assets in dist/_vendor/ (~1 MB) and dist/_graph/ (~22 KB)
npm dependencies (installed once, cached by npx)	~45–55 MB on disk	Libraries the server uses at runtime (see table below)
Session folder (grows as you reason)	~0.7–1 MB per session .html	Self-contained graph file (embeds static CSS/JS from the package) plus ~10–20 KB .json / .md sidecars

Total first-time footprint: roughly 50–60 MB in npm cache. Each session .html is ~0.7–1 MB (mostly the graph runtime block below).

What npx installs (gzip treemap)

Treemap region	bundled	share	What it is
graph-runtime.js	209.4 KB	71%	Graph HTML stack: cytoscape, html2canvas, dagre, marked, dompurify, graph.client.js, … — embedded in each session .html
mcp-server.js	86.4 KB	29%	MCP server process: @modelcontextprotocol/sdk, zod, handlebars, transitive server deps
Total	295.8 KB	100%	Minified production dependency tree (gzip); on disk node_modules is larger (~45–55 MB) because packages ship source, types, and unminified files

<p align="center"> <a href="docs/bundle-analysis/treemap.html"> <img src="docs/bundle-analysis/treemap.png" alt="webpack-bundle-analyzer treemap of the full npx install footprint with gzip size table" width="900" /> </a> <br /> <em>gzip sizes · <a href="docs/bundle-analysis/treemap.html">interactive treemap</a> · regenerate with <code>npm run analyze:bundle:all</code> (writes <code>docs/bundle-analysis/summary.json</code>)</em> </p>

Session artifacts on disk

After your first begin_thinking call, expect this layout:

~/thought-graph-sessions/
  assets/                         # static graph runtime (copied once per package version)
    .asset-version
    vendor/                       # cytoscape, dagre, marked, html2canvas, … (~1 MB)
    graph/                        # graph.css, graph.client.js (~22 KB)
  sessions/
    my-problem-abc12345.html      ~0.7–1 MB — embeds assets (Claude in-app browser)
    my-problem-abc12345.json      ~10–20 KB
    my-problem-abc12345.md        ~10 KB