Atom of Thoughts

Structured reasoning for LLMs. Decompose, track confidence, visualize, approve.

---

Setup

Add to your MCP config:

{
  "mcpServers": {
    "atom-of-thoughts": {
      "command": "npx",
      "args": ["-y", "@dioptx/mcp-atom-of-thoughts"]
    }
  }
}

Tip

Works with Claude Code, Cursor, Windsurf, or any MCP client.

How it works

graph LR
    P["P · Premise"]:::premise --> R["R · Reasoning"]:::reasoning
    R --> H["H · Hypothesis"]:::hypothesis
    H --> V["V · Verification"]:::verification
    V --> C["C · Conclusion"]:::conclusion

    classDef premise fill:#6b7280,stroke:#9ca3af,color:#fff,font-weight:bold
    classDef reasoning fill:#3b82f6,stroke:#60a5fa,color:#fff,font-weight:bold
    classDef hypothesis fill:#eab308,stroke:#facc15,color:#000,font-weight:bold
    classDef verification fill:#06b6d4,stroke:#22d3ee,color:#fff,font-weight:bold
    classDef conclusion fill:#22c55e,stroke:#4ade80,color:#fff,font-weight:bold

Loading

Chain atoms together. Each carries a confidence score (0-1). Reasoning terminates when a high-confidence conclusion is reached or max depth is hit. Sessions isolate separate problems so they don't interfere.

Tools

Three tools:

Tool	When to reach for it
AoT-fast	Default. Tradeoffs, debugging, decisions, option evaluation. Depth 3.
AoT-full	Plans, architecture, decomposition into sub-problems. Depth 5.
atomcommands	Sessions, export, approval polling, decomposition lifecycle.

Quick example

AoT-fast({atomId:"P1", content:"API returns 500 on POST /users",     atomType:"premise"})
AoT-fast({atomId:"R1", content:"Unhandled exception in route handler", atomType:"reasoning", dependencies:["P1"]})
AoT-fast({atomId:"C1", content:"Add try-catch in POST handler",       atomType:"conclusion", dependencies:["R1"], confidence:0.9})

Only atomId, content, and atomType are required. Everything else has defaults.

Visualization

Set viz: true on any call to open an interactive D3 graph in the browser:

AoT-fast({atomId:"C1", ..., viz: true})

The approve/reject UI posts decisions back to the server over HTTP. No filesystem polling.

---

Configuration

{
  "args": ["-y", "@dioptx/mcp-atom-of-thoughts", "--mode", "fast", "--viz", "never"]
}

Flag	Default	Effect
--mode full|fast|both	both	Which tools to register
--viz auto|always|never	auto	auto = render on viz:true; always = every call; never = skip (CI)
--max-depth <n>	5 / 3	Override depth limit
--output-dir <path>	OS temp	Where to write viz HTML
--downloads-dir <path>	~/Downloads	Approval JSON fallback

Sessions

Each reasoning chain gets its own session. Default: "default".

• atomcommands new_session creates and activates a new one.
• atomcommands switch_session / list_sessions / reset_session for management.
• When reasoning terminates, the session auto-archives. The next zero-dep atom auto-spawns default-2, default-3, etc.
• Or pass sessionId on any AoT call to target explicitly.

Two problems in one MCP process stay isolated without manual session management.

Visualization & Approval

viz: true generates a self-contained HTML file (D3 bundled inline, works offline) and opens your browser. The UI shows:

• Force-directed graph colored by atom type with confidence rings
• Sidebar to approve/reject phases or individual atoms
• Approve/reject POSTs to a local 127.0.0.1 listener (ephemeral port)

Poll results via atomcommands check_approval. Falls back to ~/Downloads file scan if the HTTP listener can't bind.

Install Methods

npx (zero install):

{ "command": "npx", "args": ["-y", "@dioptx/mcp-atom-of-thoughts"] }

npm global:

npm install -g @dioptx/mcp-atom-of-thoughts

Smithery:

npx -y @smithery/cli install @dioptx/mcp-atom-of-thoughts --client claude

Docker:

docker build -t aot . && docker run -i --rm aot

Development

git clone https://github.com/dioptx/mcp-atom-of-thoughts.git
cd mcp-atom-of-thoughts
npm install
npm test        # 183 tests (unit + e2e)
npm run build

Migrating from v2

See MIGRATION_v2_to_v3.md for the full lookup table. The short version:

• AoT-light is now AoT-fast
• AoT is now AoT-full
• generate_visualization is now viz: true on any AoT call
• export_graph and check_approval are now atomcommands subcommands
• --no-viz / --no-approval replaced by --viz auto|always|never

---

MIT · Based on Atom of Thoughts