DeepThinking MCP

An MCP server that gives an LLM structured reasoning methods as callable tools.

Instead of asking a model to "think carefully", you invoke a named method — Bayesian updating, causal chain analysis, Toulmin argumentation, first-principles decomposition — and the server enforces that method's structure: it validates the required fields, computes what can be computed (posteriors, Nash equilibria, source-reliability scores), tracks the reasoning across a session, and exports the result as a diagram or document.

34 reasoning modes are reachable through 13 tools, with session management, proof decomposition, and visual export.

What ships

This repository is one Claude Code plugin with four surfaces:

Surface	What you get
MCP server	13 tools across 34 reasoning modes, session management, proof decomposition
Slash commands	/think and /think-render (canonically /deepthinking-mcp:think)
Skills	14 reasoning skills covering 46 modes — including frameworks the server does not implement (SWOT, decision matrix, 5 Whys, fishbone, PESTLE, force-field, Pareto, stakeholder, gap/risk, cost-benefit)
Subagent	visual-exporter — renders a thought to 13 diagram/document formats (plus SVG/PNG via a render script) and a standalone interactive HTML dashboard. This path reaches formats the MCP tool API does not — see Capabilities.

Installation

As an npm package

npm install -g deepthinking-mcp

From source

git clone https://github.com/danielsimonjr/deepthinking-mcp.git
cd deepthinking-mcp
npm install && npm run build

Configuration

Add the server to your MCP client config:

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

Sessions are in-memory by default. To share them across instances, set SESSION_DIR to a directory both processes can reach — the server handles cross-process file locking.

{
  "mcpServers": {
    "deepthinking": {
      "command": "npx",
      "args": ["-y", "deepthinking-mcp"],
      "env": { "SESSION_DIR": "/shared/deepthinking-sessions" }
    }
  }
}

Full environment-variable reference, including which settings are parsed but not yet enforced, is in CLAUDE.md.

Quick start

Ask for a causal analysis:

{
  "tool": "deepthinking_causal",
  "arguments": {
    "mode": "causal",
    "thought": "Deploy latency rose 40% after the cache change",
    "thoughtNumber": 1,
    "totalThoughts": 3,
    "nextThoughtNeeded": true,
    "causalLinks": [
      { "cause": "cache TTL lowered to 30s", "effect": "origin request rate tripled", "strength": 0.9 },
      { "cause": "origin request rate tripled", "effect": "p99 latency +40%", "strength": 0.85 }
    ]
  }
}

Update a belief with evidence:

{
  "tool": "deepthinking_probabilistic",
  "arguments": {
    "mode": "bayesian",
    "thought": "Is the regression caused by the cache change?",
    "thoughtNumber": 1,
    "totalThoughts": 2,
    "nextThoughtNeeded": true,
    "hypothesis": "The cache TTL change caused the regression",
    "priorProbability": 0.6,
    "evidence": [{ "description": "Latency rose within 5 min of deploy", "likelihood": 0.9 }]
  }
}

The server computes the posterior for you. Then export the session:

{ "tool": "deepthinking_session", "arguments": { "action": "export", "format": "mermaid" } }

Tools

Tool	Modes / actions
deepthinking_core	inductive, deductive, abductive
deepthinking_standard	sequential, shannon, hybrid
deepthinking_mathematics	mathematics, physics, computability
deepthinking_temporal	temporal, historical
deepthinking_probabilistic	bayesian, evidential
deepthinking_causal	causal, counterfactual
deepthinking_strategic	gametheory, optimization
deepthinking_analytical	analogical, firstprinciples, metareasoning, cryptanalytic
deepthinking_scientific	scientificmethod, systemsthinking, formallogic
deepthinking_engineering	engineering, algorithmic
deepthinking_academic	synthesis, argumentation, critique, analysis
deepthinking_session	summarize, export, export_all, get_session, switch_mode, recommend_mode, delete_session
deepthinking_analyze	comprehensive_analysis, hypothesis_testing, decision_making, root_cause, future_planning

A legacy deepthinking catch-all tool remains callable for clients that hardcode the name, but it is hidden from tools/list and returns a deprecation warning. Use the focused tools.

Reasoning modes

Grouped by what you would reach for them to do. Each links to its own guide in docs/modes/, which covers the required fields, worked examples, and what the mode validates.

To do this	Use
Work a problem step by step, or split it across parallel tracks	sequential, shannon, hybrid
Reason from rules, from cases, or to the best explanation	deductive, inductive, abductive
Trace cause and effect, or ask what would have happened otherwise	causal, counterfactual
Update a belief as evidence arrives; weigh source reliability	bayesian, evidential
Analyse events over time, or evaluate historical sources	temporal, historical
Model strategic interaction, or optimise under constraints	gametheory, optimization
Decompose to fundamentals, or map one domain onto another	firstprinciples, analogical
Run a scientific method, model a system, or check a proof's logic	scientificmethod, systemsthinking, formallogic
Work through algorithms, complexity, computability, or ciphers	algorithmic, engineering, computability, cryptanalytic
Do literature synthesis, structured argument, critique, or qualitative analysis	synthesis, argumentation, critique, analysis
Reason about physical or mathematical structure	mathematics, physics
Supervise your own reasoning and switch approach when it stalls	metareasoning, recursive, modal, stochastic

Not sure which applies? deepthinking_session with action: "recommend_mode" picks one from a problem description or a set of problem characteristics.

Capabilities

Proof decomposition — breaks an argument into atomic statements, then finds the gaps: missing justifications, unstated assumptions, circular reasoning, and inconsistencies. Reports a verified dependency graph of the argument rather than a verdict.

Visual export — a session exports to 8 formats over the tool API: markdown, latex, json, html, jupyter, mermaid, dot, ascii. Exports return inline or write to disk via MCP_EXPORT_PATH.

ExportService also implements SVG, GraphML, TikZ, Modelica, and UML, with working builder classes behind them — but ExportFormatEnum (src/tools/schemas/shared.ts) does not accept those names, and src/index.ts strips svg from profile exports. They are not reachable through the MCP API today. See docs/architecture/API.md.

Session management — thoughts accumulate in a session you can summarise, export, branch, or switch modes within. File-backed storage with cross-process locking supports several server instances over one session store.

Validation and safety — every tool input is Zod-validated with bounded string, array, and record sizes (src/tools/schemas/shared.ts), and export paths are sandboxed to MCP_EXPORT_PATH. Content is length-capped and cleaned by src/utils/sanitization.ts; there is no PII redaction — do not put sensitive content in a thought you intend to export.

Architecture

src/index.ts receives a tool call, validates it, and hands off to ThoughtFactory, which asks ModeHandlerRegistry for the handler matching the requested mode. Each of the 37 handlers owns its mode's validation and enrichment; a generic handler backs modes without a specialised one. Results land in SessionManager. Exports take a parallel path through ExportService.

Documentation

Architecture documents live in docs/architecture/. Every authored document ends with a ## Verification block, and a drift gate re-checks those claims against a fresh parse — see DRIFT_REPORT.md for what the checker verifies and where its limits are.

Document	Contents
OVERVIEW.md	What this is, key metrics, layout, how code gets loaded
ARCHITECTURE.md	Design decisions and the constraints behind them
COMPONENTS.md	Module-by-module reference with real signatures
DATAFLOW.md	How a request travels, end to end
API.md	The full public surface, per export
FILE_INVENTORY.md	Every file, its area and disposition (generated)
TEST_COVERAGE.md	What is tested, and the gaps that matter
DEPENDENCY_GRAPH.md	Who imports whom (generated)
unused-analysis.md	Files and exports with no importer (generated)
duplicate-symbols.md	Names defined in more than one file (generated)
DIRECTORY_STRUCTURE.md	What each directory is for
DRIFT_REPORT.md	Refresh record, findings, analyzer limits

Also: CHANGELOG.md for version history and CLAUDE.md for the full environment-variable reference and working notes.

Development

npm run typecheck     # types only, no emit
npm run test:run      # full suite with coverage
npm run lint          # ESLint over src/
npm run build         # tsup → dist/
npm run docs:deps     # regenerate the dependency graph docs

Run one file with npm test -- tests/unit/session/manager.test.ts, or one pattern with npm test -- -t "SessionManager".

Contributing

Adding a reasoning mode touches eight places — type definition, mode enum, thought union, handler, registry, factory, validator, and visual exporter. docs/setup/ADDING_NEW_MODE.md walks the whole path with templates. Conventions and architectural constraints are in CLAUDE.md.

License

MIT — see LICENSE.

Release history is in CHANGELOG.md. Issues and questions: GitHub Issues.