@gotza02/ultimatethinking

The Ultimate MCP Server for Sequential Thinking

An advanced Model Context Protocol server for dynamic, reflective, multi-step problem solving. It gives any MCP-compatible client (Claude Code, Codex, Gemini CLI, Kimi-CLI, Claude Desktop, ...) a structured scratchpad for deliberate, high-quality reasoning: break problems into steps, surface assumptions, enumerate alternatives, steelman opposing views, seek disconfirming evidence, revise earlier reasoning, branch into alternatives, set goals with success criteria and milestones, and persist sessions to disk.

Features: session management, goal tracking with automatic progress, branching and revision, thought categorization, calibrated confidence levels, an enriched thought model (assumptions, alternatives, evidence, reasoning, counter-arguments, and more), seven dedicated cognitive tools (reflect, adversarial review, synthesize, decompose, verify, completeness, decision matrix), tags and references, full Zod input validation, prototype-pollution protection, configurable memory limits, and session persistence.

Table of Contents

• What it is
• Installation
• Environment variables
• Usage with MCP clients
  • Claude Code
  • Codex
  • Gemini CLI
• Available tools
  • Core thinking tools
  • Enriched thought fields
  • Session and goal tools
  • Persistence and retrieval tools
  • Cognitive tools
• Reasoning protocol and quality bar
• Configuration
• Security
• System instruction

What it is

@gotza02/ultimatethinking is a stdio-based MCP server. Once registered with an MCP client, it exposes a set of tools the model can call during a task. The primary tool, sequential_thinking, records discrete reasoning steps; the supporting tools create sessions, set and track goals, search and summarize recorded thoughts, export sessions, and visualize reasoning graphs.

State lives in-process in a SessionManager and, when persistence is enabled, is mirrored to JSON files on disk so sessions survive restarts.

Installation

Global install (recommended for command-style MCP config)

npm install -g @gotza02/ultimatethinking

This puts the ultimatethinking (and ultimate-thinking) binary on your PATH. You can then point MCP clients at the binary directly.

Run without installing (npx)

npx -y @gotza02/ultimatethinking

From source

git clone https://github.com/gotza02/ultimatethinking.git
cd ultimatethinking
npm install
npm run build      # outputs to dist/
node dist/index.js

Environment variables

| Variable | Default | Description | |----------|---------|-------------| | DISABLE_THOUGHT_LOGGING | unset | Set to true to suppress the formatted, ANSI-colored thought banner that the server prints to stderr after every recorded thought. Useful when stderr is captured as structured logs. | | ULTIMATE_THINKING_DIR | unset | Directory where sessions are persisted as JSON. When unset, persistence is disabled: no persistence directory is created or read, and sessions live only in memory for the lifetime of the process. Set this to an absolute path (e.g. /home/me/.ultimatethinking) to enable saving/loading across restarts. |

Example:

DISABLE_THOUGHT_LOGGING=true \
ULTIMATE_THINKING_DIR=/home/me/.ultimatethinking \
npx -y @gotza02/ultimatethinking

Usage with MCP clients

The server speaks MCP over stdio, so any MCP-capable client can register it. Below are ready-to-use snippets for three popular clients.

Claude Code

Add the server with the CLI:

claude mcp add ultimatethinking -- npx -y @gotza02/ultimatethinking

Or edit ~/.claude.json (or the project .mcp.json) directly:

{
  "mcpServers": {
    "ultimatethinking": {
      "command": "npx",
      "args": ["-y", "@gotza02/ultimatethinking"],
      "env": {
        "ULTIMATE_THINKING_DIR": "/home/me/.ultimatethinking"
      }
    }
  }
}

Using the global binary instead of npx:

{
  "mcpServers": {
    "ultimatethinking": {
      "command": "ultimatethinking",
      "env": {
        "DISABLE_THOUGHT_LOGGING": "true"
      }
    }
  }
}

Codex

Codex reads MCP servers from ~/.codex/config.toml. Add a stdio entry:

[mcp_servers.ultimatethinking]
command = "npx"
args = ["-y", "@gotza02/ultimatethinking"]
env = { ULTIMATE_THINKING_DIR = "/home/me/.ultimatethinking" }

Or, with the global binary and a local build:

[mcp_servers.ultimatethinking]
command = "node"
args = ["/absolute/path/to/ultimatethinking/dist/index.js"]

Gemini CLI

Gemini CLI reads MCP servers from ~/.gemini/settings.json:

{
  "mcpServers": {
    "ultimatethinking": {
      "command": "npx",
      "args": ["-y", "@gotza02/ultimatethinking"],
      "env": {
        "ULTIMATE_THINKING_DIR": "/home/me/.ultimatethinking"
      }
    }
  }
}

Other clients (Claude Desktop, Kimi-CLI)

{
  "mcpServers": {
    "ultimatethinking": {
      "command": "npx",
      "args": ["-y", "@gotza02/ultimatethinking"]
    }
  }
}

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
• Kimi-CLI: ~/.kimi/mcp.json

Available tools

The server advertises 23 tools, grouped into four families: 1 core thinking tool, 6 session/goal tools, 9 analysis/persistence/retrieval tools, and 7 cognitive tools.

Core thinking tools

1. sequential_thinking (primary)

Records one discrete reasoning step and returns the updated session state. This is the main tool models call during a task.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | thought | string | Yes | The current thinking step | | nextThoughtNeeded | boolean | Yes | Whether another thought step is needed | | thoughtNumber | integer | Yes | Current thought number (1-based) | | totalThoughts | integer | Yes | Estimated total thoughts for the session | | category | enum | No | analysis | hypothesis | conclusion | revision | verification | insight | question | action | | confidence | integer | No | Confidence level (0-100); keep it calibrated | | isRevision | boolean | No | Whether this revises previous thinking | | revisesThought | integer | No | Which thought is being reconsidered (required if isRevision is true) | | branchFromThought | integer | No | Thought number to branch from | | branchId | string | No | Branch identifier (required if branchFromThought is provided) | | needsMoreThoughts | boolean | No | Signal that more thoughts are needed | | references | string[] | No | IDs of referenced thoughts in the current session | | tags | string[] | No | Tags for categorization |

Cross-field rules enforced by the schema: isRevision requires revisesThought (and vice versa); branchFromThought requires branchId (and vice versa).

Enriched thought fields

All of the fields below are optional and additive on top of the original sequential_thinking parameters above. They are accepted on every thought and make reasoning explicit, auditable, and searchable. Existing callers that omit them keep working unchanged.

| Field | Type | When to use it | |-------|------|----------------| | reasoningType | enum | Inference mode: deductive, inductive, abductive, analogical, or intuitive. | | assumptions | string[] | Premises this thought depends on. Name them so a reviewer (or reflect_and_critique) can test them. | | alternatives | string[] | Rival explanations or options you considered before this thought. | | counterArguments | string[] | The strongest objections to this thought, stated fairly (steelman). | | disconfirmingEvidence | string[] | Observations that would (or do) prove this thought wrong — actively sought, not avoided. | | evidence | string[] | Supporting observations, data, or citations backing the thought. | | reasoning | string | The explicit logical chain leading to this thought. Pair with evidence on conclusions. | | uncertainty | integer | Overall uncertainty from 0-100, where higher means less certain. | | openQuestions | string[] | Unknowns this thought leaves unresolved; carry them into the next thought. | | uncertaintyFactors | string[] | Specific drivers of low confidence — why this might be wrong even if it looks right. | | nextSteps | string[] | Concrete follow-up actions implied by this thought. | | biases | string[] | Cognitive biases being guarded against or suspected. | | decisionCriteria | string[] | Standards used to evaluate a decision or option. |

A few usage norms: a conclusion without reasoning and evidence is unfinished; a high confidence (>=85) without disconfirmingEvidence or counterArguments is suspicious; and assumptions should be filled whenever the thought would collapse if a premise were false.

Session and goal tools

2. create_thinking_session

Create a new thinking session with an optional goal, criteria, and milestones. Becomes the current session.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | goalTitle | string | No | Title of the goal | | goalDescription | string | No | Description of the goal | | estimatedThoughts | integer | No | Estimated thoughts (default 10) | | criteria | string[] | No | Success criteria | | milestones | {title, thoughtNumber}[] | No | Milestones to track |

3. set_session_goal

Set or update the goal on the current session (creates a session automatically if none exists).

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | title | string | Yes | Goal title | | description | string | No | Goal description | | criteria | string[] | No | Success criteria | | milestones | {title, thoughtNumber}[] | No | Milestones to track |

4. update_goal_progress

Toggle a criterion or milestone and recompute goal progress, or mark everything complete at once.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | criteriaId | string | No | Criterion ID to toggle | | milestoneId | string | No | Milestone ID to toggle | | markAllComplete | boolean | No | Mark all criteria and milestones complete (goal -> 100%) |

Provide one of criteriaId, milestoneId, or markAllComplete=true.

5. get_session_info

Return statistics, progress, and metadata for the current session.

6. get_thought_history

Return all thoughts from the current session with their details.

7. clear_session

Clear all thoughts and reset goal progress/completion state while keeping the session active.

Analysis, persistence, and retrieval tools

These tools are most useful when persistence is enabled (set ULTIMATE_THINKING_DIR).

8. summarize_session

Produce a compact summary of the current session: thought count and progress against the estimate, per-category counts, average confidence, top tags, branch count, goal status, and up to maxHighlights conclusion/insight excerpts. Operates on the current session only.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | maxHighlights | integer | No | Max conclusion/insight excerpts to include (1-50; default 5) |

9. search_thoughts

Filter the current session's thoughts by category, tag, and/or free-text keyword (matched case-insensitively against thought content). Provide at least one filter; when several are given, a thought matches on ANY of them (OR) unless matchAll is true (AND). Operates on the current session only.

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | category | enum | No | One of the 8 thought categories | | tag | string | No | Match thoughts that include this tag | | keyword | string | No | Free-text keyword, matched case-insensitively | | matchAll | boolean | No | Require ALL provided filters to match (default false = OR) |

10. export_session

Return a full JSON snapshot of the current session — all thoughts (with references, revision, and branch metadata), branches, and goal — as an inline JSON payload in the tool result. Takes no arguments and writes no file.

11. get_thought_graph

Return the session's reasoning as a graph: nodes are thoughts (with category and confidence) and edges encode references, revision, and branch relationships. Useful for visualization and dependency analysis.

12. analyze_session

Score the current session's reasoning coverage, confidence calibration, evidence, assumptions, counterarguments, and unresolved questions. Optionally includes deduplicated ranked insights.

13. reasoning_guidance

Recommend the single most useful next reasoning move based on the current session, goal progress, category coverage, and stagnation signals.

14. recommend_strategy

Recommend a reasoning strategy for a supplied problem and optional context, such as first-principles, deductive, abductive, adversarial, or pre-mortem.

15. reasoning_quality

Return reasoning-quality and stagnation metrics for the current session, including coverage, depth, evidence strength, bias risk, and coherence.

16. get_reasoning_template

List the available structured reasoning templates or retrieve one template by ID for use as a step-by-step session procedure.

Cognitive tools

These seven tools each force a specific high-leverage mode of thinking. They read from and write back to the same session, so their output stays connected to the reasoning chain. Use them deliberately at the points in a workflow where that mode belongs — they are not box-ticking steps.

17. plan_decomposition

Use at the start of a hard or ambiguous problem, before you have thought through anything. Breaks the problem into sub-problems and a sensible order of attack. The output becomes the skeleton your subsequent thoughts fill in.

18. reflect_and_critique

Use after a tentative conclusion, or whenever confidence climbs above ~80. Forces a step back: what is weakest about the reasoning so far, which assumptions are unverified, what would a careful reviewer flag? Run it before promoting a hypothesis to a final conclusion.

19. adversarial_review

Use when the stakes are high or you suspect you have anchored on a preferred answer. Argues the opposite case as strongly as possible and tries to break the conclusion. If it succeeds, record a revision; if it fails, the confidence is earned.

20. synthesize

Use when multiple thoughts, branches, or competing hypotheses need to be merged into one coherent position. Resolves tensions, drops what the evidence does not support, and produces the integrated view. Ideal after adversarial_review.

21. decision_matrix

Use when the task is a choice among discrete options (tools, architectures, approaches, vendors). Builds a weighted criteria-by-option matrix and scores each option, making the tradeoff explicit instead of vibes-based.

22. verify_conclusion

Use immediately before delivering a conclusion. Checks the conclusion against its stated evidence, reasoning, and the session's goal criteria; flags gaps where the conclusion outruns its support.

23. completeness_check

Use near the end of a session, before declaring done. Audits the session against the goal's success criteria and asks what is still missing, untested, or assumed. Catches the "solved the interesting part and forgot the rest" failure.

Reasoning protocol and quality bar

The goal of this server is reasoning quality, not feature count. The SYSTEM_INSTRUCTION.md document defines a full protocol; the essentials are summarized here.

Core principles (apply to every thought): think step-by-step; surface assumptions; enumerate alternatives; steelman opposing views; quantify uncertainty; seek disconfirming evidence; avoid named cognitive biases (anchoring, confirmation, availability, base-rate neglect, survivorship, overconfidence); sanity-check magnitude and units; iterate and revise.

Recommended workflow for hard problems:

1. decompose        plan_decomposition   -> sub-problems + order of attack
2. hypothesize      sequential_thinking  -> candidates with alternatives + assumptions
3. gather evidence  sequential_thinking  -> verification; fill evidence/disconfirmingEvidence
4. adversarial test adversarial_review   -> try to break the leading hypothesis
5. synthesize       synthesize           -> merge surviving branches into one position
6. verify           verify_conclusion    -> conclusion supported by evidence + reasoning
7. completeness     completeness_check   -> audit against goal criteria; close gaps
8. respond          (to the user)        -> only after 1-7 pass

Quality bar (a conclusion is acceptable when): it has explicit reasoning and evidence; load-bearing assumptions are listed and tested or flagged; counterArguments were stated and answered; adversarial_review failed to break it (or a surviving revision is recorded); confidence is calibrated; completeness_check finds no blocking gaps; and magnitudes/units are sanity-checked.

For decisions, insert decision_matrix before the adversarial test. For a self-critique loop and worked examples, see SYSTEM_INSTRUCTION.md.

Configuration

Runtime limits (apply per server instance):

| Setting | Default | Description | |---------|---------|-------------| | maxHistorySize | 1000 | Max thoughts retained per session (rolling window) | | maxBranches | 100 | Max branches retained per session | | maxSessions | 10 | Max concurrent sessions in memory | | autoSaveInterval | (reserved) | Accepted for compatibility but currently unused. Persistence is not on a fixed interval: when ULTIMATE_THINKING_DIR is set, every session mutation is saved with a short debounce (~150 ms) and flushed on clean shutdown. |

Environment variables (DISABLE_THOUGHT_LOGGING, ULTIMATE_THINKING_DIR) are documented above.

Memory model. Within a session, maxHistorySize keeps a rolling window of the most recent thoughts; when the window is full the oldest thought is evicted. totalThoughts always equals the number of thoughts currently stored (so it is non-monotonic by design), a reference that points at an evicted thought becomes unresolvable, and thoughtNumber is trusted client input (not resequenced). A future major version may add a monotonic cumulative counter; until then, treat totalThoughts as "currently in memory".

Security

• Prototype pollution protection - branch IDs are validated against a blocklist (__proto__, constructor, prototype, and other built-in property names) before they are used as Map keys.
• Memory limits - thoughts, branches, and sessions each have configurable ceilings; the oldest entries are evicted when a limit is reached.
• Input validation - every tool that accepts arguments is validated before its handler runs: the core tools via Zod schemas (length caps and cross-field rules) in schemas.ts, and the analysis/cognitive tools plus update_goal_progress via per-tool input schemas in tool-schemas.ts. (Eight tools take no arguments.)
• Disk persistence - when ULTIMATE_THINKING_DIR is set, sessions are written as JSON files under that directory. Treat the directory as trusted local storage; the server does not execute or evaluate persisted content.

System instruction

See SYSTEM_INSTRUCTION.md for a ready-to-paste system prompt that teaches an agent when and how to use these tools.

License

MIT (c) gotza