mcp-deep-think

An MCP server for active reasoning — persistent, analytical, strategy-driven thinking that adapts to your codebase.

Built as an enhanced successor to the Sequential Thinking MCP, mcp-deep-think goes beyond passive thought recording to provide cross-thought analysis, branching with merge, persistent checkpoints, configurable reasoning strategies, and per-repo best practices.

Why?

Sequential Thinking records thoughts but never reads them. It has no persistence, no analysis, no session recovery.

mcp-deep-think makes AI reasoning visible, persistent, and steerable:

Feature	Sequential Thinking	mcp-deep-think
Thought recording	Yes	Yes (enhanced)
Persistence	None (in-memory only)	JSON file checkpoints
Cross-thought analysis	None	Circular, contradictions, gaps
Branch merging	No	Compare + merge with rationale
Session recovery	No	Save/load checkpoints
Reasoning strategies	No	6 built-in + custom
Per-repo config	No	.deep-think.json
Active feedback	No	Warns about patterns and issues

Quick Start

Install

npm install -g mcp-deep-think

Configure in Claude Code

Add to your MCP settings (~/.claude/settings.json or project .claude/settings.json):

{
  "mcpServers": {
    "deep-think": {
      "command": "mcp-deep-think"
    }
  }
}

Use

The server exposes 5 tools:

think        → Record a reasoning step (enhanced sequential thinking)
reflect      → Analyze the thought chain for patterns and issues
branch       → List, compare, and merge reasoning branches
checkpoint   → Save/restore reasoning state across sessions
strategize   → Switch reasoning frameworks

Tools

think

Enhanced drop-in replacement for sequentialthinking. Records a thought step with optional metadata.

Input:

Parameter	Type	Required	Description
thought	string	Yes	Your current thinking step
thoughtNumber	number	Yes	Current position (1-indexed)
totalThoughts	number	Yes	Estimated total (adjustable)
nextThoughtNeeded	boolean	Yes	Continue thinking?
confidence	number	No	0-1 confidence in this step
tags	string[]	No	Semantic labels
assumptions	string[]	No	Explicit assumptions
evidence	string[]	No	Supporting evidence
isRevision	boolean	No	Revises previous thinking?
revisesThought	number	No	Which thought to revise
branchFromThought	number	No	Branch point
branchId	string	No	Branch identifier
strategy	string	No	Set active strategy

Returns: Thought metadata + active feedback (warnings about chain length, confidence drops, missing tags).

reflect

Analyzes the thought chain. The key differentiator — this tool reads thought content.

Input:

Parameter	Type	Default	Description
focus	enum	"all"	"all", "progress", "contradictions", "gaps", "patterns"

Detects:

• Circular reasoning: Thoughts with >60% word overlap (Jaccard similarity)
• Contradictions: Negation patterns on similar topics
• Gaps: Missing assumptions, evidence, branches
• Practice violations: Checks against .deep-think.json rules

branch

Manage alternative reasoning paths.

Input:

Parameter	Type	Required	Description
operation	enum	Yes	"list", "compare", "merge"
branchA	string	For compare/merge	First branch ID
branchB	string	For compare/merge	Second branch ID
mergeConclusion	string	For merge	Your synthesis
winningBranch	string	No	Which approach won
rationale	string	No	Why it won

Note: Create branches using the think tool with branchFromThought and branchId.

checkpoint

Save and restore reasoning state.

Input:

Parameter	Type	Required	Description
operation	enum	Yes	"save", "load", "list", "delete"
name	string	For save/load/delete	Checkpoint name

Checkpoints are stored as JSON files in the configured directory (default: .deep-think/sessions/).

strategize

Switch reasoning frameworks.

Input:

Parameter	Type	Required	Description
operation	enum	Yes	"set", "get", "list"
strategy	string	For set	Strategy name

Built-in strategies:

Strategy	When to Use
first-principles	Decomposing complex problems from ground truth
red-team	Attacking your own conclusions
convergent	Narrowing options to a decision
divergent	Brainstorming without judgment
root-cause	Debugging and investigation
decision-matrix	Weighted criteria comparison

Per-Repo Configuration

Create a .deep-think.json in your repo root to teach the MCP how to reason for your codebase:

{
  "$schema": "https://unpkg.com/mcp-deep-think/schema.json",
  "project": {
    "name": "my-api",
    "type": "backend",
    "language": "typescript"
  },
  "thinking": {
    "defaultStrategy": "first-principles",
    "maxThoughts": 20,
    "autoCheckpointEvery": 5
  },
  "practices": {
    "rules": [
      "Always consider backwards compatibility",
      "Database migrations must be reversible"
    ],
    "antiPatterns": [
      "Never store secrets in config files",
      "Avoid N+1 queries"
    ]
  },
  "strategies": {
    "custom": [
      {
        "name": "api-design",
        "description": "For designing new API endpoints",
        "steps": [
          "Define the resource",
          "Choose HTTP methods",
          "Design request/response schemas",
          "Plan error responses"
        ],
        "checkpoints": ["after schema design"]
      }
    ]
  },
  "persistence": {
    "directory": ".deep-think/sessions",
    "maxCheckpoints": 10
  }
}

The config flows through all tools:

• think: Applies thought limits, triggers auto-checkpoints
• reflect: Checks thoughts against your rules and anti-patterns
• strategize: Lists custom strategies alongside built-ins
• checkpoint: Uses configured directory and rotation limits

Environment Variables

Variable	Default	Description
MCP_DEEP_THINK_CONFIG	.deep-think.json in CWD	Path to config file

Development

git clone https://github.com/bis-code/mcp-deep-think.git
cd mcp-deep-think
npm install
npm test          # Run tests
npm run build     # Build TypeScript
npm run dev       # Watch mode

License

MIT