Skip to content
Back to search

mcp-atom-of-thoughts

MCP server for structured AI reasoning — decompose problems into atomic thoughts with dependency graphs, confidence tracking, and interactive D3.js visualization

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dioptx--mcp-atom-of-thoughts/badge.svg)](/listings/dioptx--mcp-atom-of-thoughts)

HTML

<a href="/listings/dioptx--mcp-atom-of-thoughts"><img src="/api/listings/dioptx--mcp-atom-of-thoughts/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**1.** Add to your MCP config:

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

**2.** Restart your client.

**3.** Ask the model to reason something through:

> *"Use AoT-fast to think through whether we should use JWT or session-based auth for the API."*

The model breaks the problem into five kinds of atoms (premise, reasoning, hypothesis, verification, conclusion), each tagged with a confidence score. You get a structured chain you can audit, not a black-box answer.

> [!TIP] > Works with Claude Code, Cursor, Windsurf, or any MCP-aware client.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 268 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # Atom of Thoughts
  3. Structured reasoning for LLMs. Decompose, track confidence, visualize, approve.
  4. [![npm version](https://img.shields.io/npm/v/@dioptx/mcp-atom-of-thoughts?color=0969da)](https://www.npmjs.com/package/@dioptx/mcp-atom-of-thoughts)
  5. [![license](https://img.shields.io/npm/l/@dioptx/mcp-atom-of-thoughts?color=22c55e)](LICENSE)
  6. [![node](https://img.shields.io/node/v/@dioptx/mcp-atom-of-thoughts)](package.json)
  7. [![tests](https://img.shields.io/badge/tests-183%20passed-brightgreen)](#development)
  8. [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white)](tsconfig.json)
  9. ![Atom of Thoughts: live TUI watching reasoning unfold](assets/demo-watch.gif)
  10. </div>
  11. ---
  12. ## Quickstart
  13. **1.** Add to your MCP config:
  14. ```json
  15. {
  16. "mcpServers": {
  17. "atom-of-thoughts": {
  18. "command": "npx",
  19. "args": ["-y", "@dioptx/mcp-atom-of-thoughts"]
  20. }
  21. }
  22. }
  23. ```
  24. **2.** Restart your client.
  25. **3.** Ask the model to reason something through:
  26. > *"Use AoT-fast to think through whether we should use JWT or session-based auth for the API."*
  27. The model breaks the problem into five kinds of atoms (premise, reasoning, hypothesis, verification, conclusion), each tagged with a confidence score. You get a structured chain you can audit, not a black-box answer.
  28. > [!TIP]
  29. > Works with Claude Code, Cursor, Windsurf, or any MCP-aware client.
  30. ## Install
  31. **npx** *(recommended; zero install, always latest)*
  32. ```json
  33. { "command": "npx", "args": ["-y", "@dioptx/mcp-atom-of-thoughts"] }
  34. ```
  35. **npm global**
  36. ```bash
  37. npm install -g @dioptx/mcp-atom-of-thoughts
  38. ```
  39. ```json
  40. { "command": "mcp-atom-of-thoughts" }
  41. ```
  42. **Smithery**
  43. ```bash
  44. npx -y @smithery/cli install @dioptx/mcp-atom-of-thoughts --client claude
  45. ```
  46. **Docker**
  47. ```bash
  48. docker build -t aot .
  49. ```
  50. ```json
  51. { "command": "docker", "args": ["run", "-i", "--rm", "aot"] }
  52. ```
  53. ## How it works
  54. ```mermaid
  55. graph LR
  56. P["P · Premise"]:::premise --> R["R · Reasoning"]:::reasoning
  57. R --> H["H · Hypothesis"]:::hypothesis
  58. H --> V["V · Verification"]:::verification
  59. V --> C["C · Conclusion"]:::conclusion
  60. classDef premise fill:#6b7280,stroke:#9ca3af,color:#fff,font-weight:bold
  61. classDef reasoning fill:#3b82f6,stroke:#60a5fa,color:#fff,font-weight:bold
  62. classDef hypothesis fill:#eab308,stroke:#facc15,color:#000,font-weight:bold
  63. classDef verification fill:#06b6d4,stroke:#22d3ee,color:#fff,font-weight:bold
  64. classDef conclusion fill:#22c55e,stroke:#4ade80,color:#fff,font-weight:bold
  65. ```
  66. Atoms chain through dependencies. Each carries a confidence score from 0 to 1. Reasoning terminates when a high-confidence conclusion lands or max depth is hit. Each problem runs in its own session, so two threads of thought never bleed into each other.
  67. ## Tools
  68. Three tools cover the full surface:
  69. | Tool | When to reach for it |
  70. |------|---------------------|
  71. | **`AoT-fast`** | Default. Tradeoffs, debugging, decisions, option evaluation. Depth 3. |
  72. | **`AoT-full`** | Plans, architecture, decomposition into sub-problems. Depth 5. |
  73. | **`atomcommands`** | Sessions, export, approval polling, decomposition lifecycle. |
  74. ### Quick example
  75. ```
  76. AoT-fast({atomId:"P1", content:"API returns 500 on POST /users", atomType:"premise"})
  77. AoT-fast({atomId:"R1", content:"Unhandled exception in route handler", atomType:"reasoning", dependencies:["P1"]})
  78. AoT-fast({atomId:"C1", content:"Add try-catch in POST handler", atomType:"conclusion", dependencies:["R1"], confidence:0.9})
  79. ```
  80. Only `atomId`, `content`, and `atomType` are required. Everything else has sensible defaults.
  81. ### Visualization
  82. Pass `viz: true` on any call to open an interactive D3 graph in the browser:
  83. ```
  84. AoT-fast({atomId:"C1", ..., viz: true})
  85. ```
  86. Approve and reject decisions POST back to the server over HTTP. No filesystem polling.
  87. ## Live TUI
  88. Watch the model reason in a second terminal pane while it works, and feed approve/reject decisions back into the next tool call. The event feed is on by default; nothing extra to configure.
  89. In a second pane next to your LLM client:
  90. ```bash
  91. npx -y @dioptx/mcp-atom-of-thoughts tui
  92. ```
  93. ### 1. Watch reasoning unfold
  94. ![Watch atoms streaming in](assets/demo-watch.gif)
  95. Atoms appear as the model emits them, walking the chain premise → reasoning → hypothesis → verification → conclusion. Confidence bars fill in real time, dependencies show as inline arrows, and a velocity sparkline tracks event rate. Auto-scroll keeps the newest atom selected.
  96. ### 2. Give granular feedback
  97. ![Accept, reject with note, submit](assets/demo-feedback.gif)
  98. `j` / `k` move the selection. `a` accepts an atom; `*` stars it as critical context; `r` rejects it and prompts for a one-line reason. `s` submits the verdict. The submit flash tells you exactly what to do next: ask the model to call `atomcommands check_approval`. The verdict is written as the same approval JSON the existing file-fallback path already polls for, so feedback flows back through a contract the server already understands. **Zero new wire protocol.**
  99. ### 3. Customize the view
  100. ![Settings overlay and help overlay](assets/demo-customize.gif)
  101. `t` opens settings: confidence threshold to hide low-confidence atoms, color theme (vibrant, soft, or mono), compact mode, dependency arrows toggle. `?` shows the full keymap.
  102. ### Keys reference
  103. | Key | Action |
  104. |-----|--------|
  105. | `j` / `k` | Move selection |
  106. | `a` | Accept the selected atom |
  107. | `r` | Reject (prompts for a one-line reason) |
  108. | `u` | Clear feedback on the selected atom |
  109. | `*` | Star as critical context |
  110. | `s` | Submit verdict (writes `aot-approval-*.json`) |
  111. | `t` | Settings (threshold, theme, compact mode, deps) |
  112. | `?` | Keys help |
  113. | `space` | Pause / resume event stream |
  114. | `q` | Quit |
  115. > [!TIP]
  116. > Skip setup and see it in action: `npx -y @dioptx/mcp-atom-of-thoughts tui --demo`
  117. ---
  118. <details>
  119. <summary><b>Configuration</b></summary>
  120. ```json
  121. {
  122. "args": ["-y", "@dioptx/mcp-atom-of-thoughts", "--mode", "fast", "--viz", "never"]
  123. }
  124. ```
  125. | Flag | Default | Effect |
  126. |------|---------|--------|
  127. | `--mode full\|fast\|both` | `both` | Which tools to register |
  128. | `--viz auto\|always\|never` | `auto` | `auto`: render on `viz:true`. `always`: render every call. `never`: skip (CI) |
  129. | `--max-depth <n>` | 5 / 3 | Override depth limit |
  130. | `--output-dir <path>` | OS temp | Where to write viz HTML |
  131. | `--downloads-dir <path>` | ~/Downloads | Approval JSON fallback |
  132. </details>
  133. <details>
  134. <summary><b>Sessions</b></summary>
  135. Each reasoning chain gets its own session. Default ID: `"default"`.
  136. - `atomcommands new_session` creates and activates a new one.
  137. - `atomcommands switch_session` / `list_sessions` / `reset_session` for management.
  138. - When reasoning terminates, the session auto-archives. The next zero-dependency atom auto-spawns `default-2`, `default-3`, and so on.
  139. - Or pass `sessionId` on any AoT call to target one explicitly.
  140. Two problems in one MCP process stay isolated without manual session management.
  141. </details>
  142. <details>
  143. <summary><b>Browser visualization (alternative to the TUI)</b></summary>
  144. Prefer a browser tab to a terminal pane? Pass `viz: true` on any AoT call. The server writes a self-contained HTML file (D3 inlined, works offline) and opens it:
  145. - Force-directed graph colored by atom type with confidence rings
  146. - Sidebar to approve or reject phases or individual atoms
  147. - Approve / reject POSTs to a local `127.0.0.1` listener on an ephemeral port; falls back to a `~/Downloads` file scan if the listener can't bind
  148. The TUI and the browser viz both feed `atomcommands check_approval`. Pick whichever fits your workflow.
  149. </details>
  150. <details>
  151. <summary><b>Install methods</b></summary>
  152. **npx** (zero install):
  153. ```json
  154. { "command": "npx", "args": ["-y", "@dioptx/mcp-atom-of-thoughts"] }
  155. ```
  156. **npm global**:
  157. ```bash
  158. npm install -g @dioptx/mcp-atom-of-thoughts
  159. ```
  160. **Smithery**:
  161. ```bash
  162. npx -y @smithery/cli install @dioptx/mcp-atom-of-thoughts --client claude
  163. ```
  164. **Docker**:
  165. ```bash
  166. docker build -t aot . && docker run -i --rm aot
  167. ```
  168. </details>
  169. <details>
  170. <summary><b>Development</b></summary>
  171. ```bash
  172. git clone https://github.com/dioptx/mcp-atom-of-thoughts.git
  173. cd mcp-atom-of-thoughts
  174. npm install
  175. npm test # 183 tests (unit + e2e)
  176. npm run build
  177. ```
  178. </details>
  179. <details>
  180. <summary><b>Migrating from v2</b></summary>
  181. See [`MIGRATION_v2_to_v3.md`](MIGRATION_v2_to_v3.md) for the full lookup table. The short version:
  182. - `AoT-light` is now `AoT-fast`
  183. - `AoT` is now `AoT-full`
  184. - `generate_visualization` is now `viz: true` on any AoT call
  185. - `export_graph` and `check_approval` are now `atomcommands` subcommands
  186. - `--no-viz` and `--no-approval` are replaced by `--viz auto|always|never`
  187. </details>
  188. ---
  189. MIT. Based on [Atom of Thoughts](https://arxiv.org/abs/2502.12018).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.