结构化推理MCP服务

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:

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

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.

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 36 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.

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.