DeepThinking MCP
danielsimonjr/deepthinking-mcp
34 modos de raciocínio unificado: sequencial, histórico, matemático, jogos, lógica formal
Ver no GitHubServidor MCP com 34 modos de raciocínio especializado (sequencial, Shannon, matemático, histórico, teoria dos jogos, lógica formal) para análise complexa, resolução de problemas e tomada de decisão. Inclui recomendação inteligente de modo, classificação por taxonomia e recursos enterprise. Status: DEPRECADO em abril de 2026 — migre para deepthinking-plugin.
Instalação
npx convez-ai danielsimonjr/deepthinking-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Análise matemática e prova de teoremas
- Raciocínio histórico com avaliação de fontes
- Resolução de problemas complexos em física e engenharia
- Meta-raciocínio para decisões estratégicas
- Análise de jogos e teoria dos jogos
Veredito

DEPRECADO oficialmente desde abril/2026 — não use para novos projetos. A solução sucessora é deepthinking-plugin (Claude Code plugin nativo). Se já usa v9.1.3, continua funcional com suporte até outubro/2026. Excelente arquitetura MCP com 34 modos, mas migração obrigatória para manter suporte.
README
A tradução para o português deste README ainda está na fila.
DeepThinking MCP
⚠️ DEPRECATED as of 2026-04-12
deepthinking-mcpis no longer under active development. It has been replaced by deepthinking-plugin — a Claude Code plugin that delivers the same 34 reasoning modes as native prompt-based skills, with no Node.js server, no dependency footprint, and no context pollution.New users: skip this repo and install the plugin.
Existing users: v9.1.3 keeps working indefinitely. Security fixes land through 2026-10-12; after that, maintenance-only. See DEPRECATED.md for the full migration guide (~10 minutes), rationale, and timeline.
Quick links New plugin repo https://github.com/danielsimonjr/deepthinking-plugin Migration guide DEPRECATED.md#migration-guide Why it was replaced DEPRECATED.md#why-it-was-replaced Latest plugin release v0.4.1
A comprehensive Model Context Protocol (MCP) server featuring 34 reasoning modes (30 with dedicated thought types, 4 advanced runtime modes) including historical reasoning, meta-reasoning for strategic oversight, with intelligent mode recommendation, taxonomy-based classification, enterprise security, and production-ready features for complex problem-solving, analysis, and decision-making.
📋 Final feature release: v9.1.3 — see DEPRECATED.md for the migration path to
deepthinking-plugin. Security fixes through 2026-10-12.🎉 v9.1.0 added: Historical Reasoning Mode — analyze historical events, evaluate sources, identify patterns, trace causal chains, and define periods with 5 thought types.
✨ Codebase: 237 TypeScript files | ~102,500 LOC | 15 modules | 5,148+ tests passing
Table of Contents
- Features
- Installation
- Quick Start
- Reasoning Modes
- Proof Decomposition
- Usage Examples
- Production Features
- API Documentation
- Contributing
- License
Features
- 34 Specialized Reasoning Modes - From sequential thinking to historical analysis, game theory, formal logic, and meta-reasoning (30 with full thought types, 4 advanced runtime modes)
- ModeHandler Architecture (v9.x) - Strategy pattern with 37 specialized handlers providing advanced validation and enhancements for all 34 modes
- Historical Reasoning (v9.1.0) - Event analysis, source evaluation, pattern identification, causal chains, periodization with 5 thought types
- Specialized Handler Enhancements - Systems Archetypes (8 patterns), Socratic Questions (6 categories), auto Bayesian posteriors, Nash equilibria, source reliability scoring
- Visual Builder APIs - 14 fluent builder classes: DOTGraphBuilder, MermaidGraphBuilder, MermaidGanttBuilder, MermaidStateDiagramBuilder, ASCIIDocBuilder, SVGBuilder, TikZBuilder, UMLBuilder, HTMLDocBuilder, MarkdownBuilder, ModelicaBuilder, JSONExportBuilder, GraphMLBuilder, SVGGroupBuilder
- Academic Research Modes - Synthesis (literature review), Argumentation (Toulmin), Critique (peer review), Analysis (qualitative methods)
- Algorithmic Reasoning - Comprehensive CLRS coverage with 100+ named algorithms, complexity analysis, design patterns
- Historical Computing Extensions - Computability (Turing machines), Cryptanalytic (decibans), extended Game Theory (von Neumann)
- Proof Decomposition - Break proofs into atomic statements, detect gaps, track assumption chains
- Native SVG Export - Direct SVG generation without external tools for proof visualizations
- Meta-Reasoning - Strategic oversight that monitors effectiveness, recommends mode switches, and assesses quality
- Intelligent Mode Recommendation - Automatic mode selection based on problem characteristics
- Taxonomy Classifier - 69 reasoning types across 12 categories for intelligent task classification (110 planned)
- Visual Exports - Generate Mermaid diagrams, DOT graphs, ASCII art, SVG graphics, and LaTeX documents
- File Export System - Export sessions to files with configurable output directory and profiles
- Production-Ready - Search engine, session management, caching, multi-instance support
- Enterprise Security - Input validation (Zod), path sanitization, PII redaction
- High Performance - LRU caching with auto-eviction, async I/O
- Type-Safe - 100% TypeScript with comprehensive type coverage
- Extensible - Plugin architecture for custom reasoning modes
- MCP Compatible - Full integration with Model Context Protocol
Installation
NPM Package
npm install deepthinking-mcp
From Source
git clone https://github.com/danielsimonjr/deepthinking-mcp.git
cd deepthinking-mcp
npm install
npm run build
MCP Configuration
Add to your MCP settings file:
{
"mcpServers": {
"deepthinking": {
"command": "npx",
"args": ["deepthinking-mcp"]
}
}
}
Configuration with Environment Variables
Configure the server with environment variables:
{
"mcpServers": {
"deepthinking": {
"command": "npx",
"args": ["deepthinking-mcp"],
"env": {
"MCP_EXPORT_PATH": "C:/deepthinking-exports",
"MCP_EXPORT_OVERWRITE": "false",
"MCP_LOG_LEVEL": "info"
}
}
}
}
| Variable | Description | Default |
|---|---|---|
MCP_EXPORT_PATH | Default directory for file exports | `` (returns content) |
MCP_EXPORT_OVERWRITE | Overwrite existing files | false |
MCP_LOG_LEVEL | Log level (debug/info/warn/error) | info |
MCP_MAX_SESSIONS | Maximum active sessions | 100 |
MCP_SESSION_TIMEOUT_MS | Session timeout (0 = none) | 0 |
SESSION_DIR | Shared session storage for multi-instance | `` (in-memory) |
Quick Start
MCP Tool Usage
DeepThinking MCP provides 13 focused tools for different reasoning domains:
| Tool | Modes | Description |
|---|---|---|
deepthinking_core | inductive, deductive, abductive | Fundamental reasoning |
deepthinking_standard | sequential, shannon, hybrid | Standard workflow modes |
deepthinking_mathematics | mathematics, physics, computability | Math/physics/computability |
deepthinking_temporal | temporal | Time-based reasoning |
deepthinking_probabilistic | bayesian, evidential | Probabilistic reasoning |
deepthinking_causal | causal, counterfactual | Cause-effect analysis |
deepthinking_strategic | gametheory, optimization | Strategic reasoning |
deepthinking_analytical | analogical, firstprinciples, metareasoning, cryptanalytic | Analytical reasoning |
deepthinking_scientific | scientificmethod, systemsthinking, formallogic | Scientific reasoning |
deepthinking_engineering | engineering, algorithmic | Engineering/algorithmic |
deepthinking_academic | synthesis, argumentation, critique, analysis | Academic research |
deepthinking_session | - | Session management |
deepthinking_analyze | Multi-mode | Analysis with presets and merge strategies |
Example: Sequential Reasoning
{
"tool": "deepthinking_standard",
"arguments": {
"mode": "sequential",
"thought": "First, identify the main bottlenecks in the distributed system",
"thoughtNumber": 1,
"totalThoughts": 5,
"nextThoughtNeeded": true
}
}
Example: Causal Analysis
{
"tool": "deepthinking_causal",
"arguments": {
"mode": "causal",
"thought": "Analyzing the root cause of the service outage",
"thoughtNumber": 1,
"totalThoughts": 3,
"nextThoughtNeeded": true,
"causalGraph": {
"nodes": [
{"id": "n1", "name": "High Load", "type": "cause"},
{"id": "n2", "name": "Memory Exhaustion", "type": "mediator"},
{"id": "n3", "name": "Service Crash", "type": "effect"}
],
"edges": [
{"from": "n1", "to": "n2", "strength": 0.9},
{"from": "n2", "to": "n3", "strength": 0.95}
]
}
}
}
Example: Session Export
{
"tool": "deepthinking_session",
"arguments": {
"action": "export",
"sessionId": "session-123",
"exportFormat": "markdown"
}
}
Reasoning Modes
The server supports 34 reasoning modes organized into categories:
- Core Modes (5): Sequential, Shannon, Mathematics, Physics, Hybrid
- Causal/Probabilistic (7): Causal, Bayesian, Counterfactual, Temporal, Historical, GameTheory, Evidential
- Historical Computing (2): Computability (Turing), Cryptanalytic (Turing) - v7.2.0
- Algorithmic (1): Algorithmic (CLRS) - v7.3.0
- Academic Research (4): Synthesis, Argumentation, Critique, Analysis - v7.4.0
- Advanced Runtime Modes (6): Metareasoning, Recursive, Modal, Stochastic, Constraint, Optimization
- Fundamental Modes (3): Inductive, Deductive, Abductive
- Systems/Scientific (3): SystemsThinking, ScientificMethod, FormalLogic
- Analogical (2): Analogical, FirstPrinciples
- Engineering (1): Engineering
Core Modes
Sequential
Iterative refinement with revision capabilities. Perfect for step-by-step problem solving.
mode: 'sequential'
// Use for: Debugging, algorithmic thinking, systematic analysis
Shannon
5-stage systematic problem-solving methodology (problem → constraints → model → proof → implementation).
mode: 'shannon'
// Use for: Engineering problems, system design, complex optimizations
Mathematics
Theorem proving, lemma derivation, symbolic computation with LaTeX support.
mode: 'mathematics'
// Use for: Proofs, mathematical modeling, symbolic algebra
Physics
Tensor mathematics, dimensional analysis, conservation laws, field theory.
mode: 'physics'
// Use for: Physical modeling, dimensional analysis, scientific computing
Hybrid
Intelligently combines multiple reasoning modes based on problem characteristics.
mode: 'hybrid'
// Use for: Complex multi-faceted problems requiring diverse approaches
Historical Reasoning (v9.1.0)
Historical
Comprehensive historical analysis with source evaluation, pattern recognition, and causal chain analysis.
mode: 'historical'
// Use for: Historical research, source criticism, event analysis, periodization
// Features: 5 thought types, aggregate reliability scoring, pattern detection
5 Thought Types:
event_analysis- Analyze historical events with significance ratingssource_evaluation- Evaluate primary/secondary/tertiary sources with reliability scoringpattern_identification- Identify recurring patterns across time (cyclical, structural, contingent)causal_chain- Trace cause-effect relationships with confidence scoresperiodization- Define and analyze historical periods with characteristics
Data Structures:
HistoricalEvent- Events with dates, actors, causes/effects, significance levelsHistoricalSource- Sources with type, reliability (0-1), bias analysis, corroborationHistoricalPeriod- Time periods with characteristics, key events, transitionsCausalChain- Linked causal relationships with evidence and confidenceHistoricalActor- Individuals, groups, institutions, nations, movements
Handler Features:
- Aggregate reliability calculation (weighted by source type with corroboration bonus)
- Causal chain continuity validation
- Automatic pattern detection from events
- Temporal span calculation
- Cross-reference validation (events ↔ sources ↔ actors)
Advanced Modes
Causal
Build causal graphs, analyze interventions and effects.
mode: 'causal'
// Use for: Impact analysis, system design, decision making
Bayesian
Probabilistic reasoning with priors, likelihoods, and evidence updates.
mode: 'bayesian'
// Use for: Risk assessment, A/B testing, uncertainty quantification
Counterfactual
Explore alternative scenarios and compare outcomes.
mode: 'counterfactual'
// Use for: Post-mortems, strategic planning, what-if analysis
Analogical
Transfer knowledge across domains by identifying structural similarities.
mode: 'analogical'
// Use for: Design patterns, innovative problem-solving, knowledge transfer
Specialized Modes
Temporal
Model events, intervals, and temporal relationships using Allen's interval algebra.
mode: 'temporal'
// Use for: Timeline analysis, scheduling, event sequencing
Game Theory
Analyze strategic interactions, compute Nash equilibria, build game trees.
mode: 'game-theory'
// Use for: Competitive analysis, mechanism design, strategic decisions
Evidential
Dempster-Shafer theory for reasoning with uncertain evidence.
mode: 'evidential'
// Use for: Sensor fusion, intelligence analysis, incomplete information
First Principles
Derive conclusions from foundational axioms using deductive reasoning.
mode: 'first-principles'
// Use for: Fundamental analysis, conceptual understanding, basic truths
Meta-Reasoning
Strategic oversight of reasoning process - monitors effectiveness, recommends mode switches, assesses quality.
mode: 'metareasoning'
// Use for: Strategy evaluation, adaptive mode switching, quality assessment
// Metrics: Effectiveness, Efficiency, Confidence, Quality (6 dimensions)
// Auto-switches at effectiveness < 0.3
See full documentation for detailed usage.
Systems Thinking
Holistic analysis of complex systems, feedback loops, and emergence.
mode: 'systems-thinking'
// Use for: Complex systems, organizational design, ecosystem analysis
Scientific Method
Hypothesis-driven experimentation with research design and statistical analysis.
mode: 'scientific-method'
// Use for: Experimental design, hypothesis testing, research
Optimization
Constraint satisfaction and optimization with decision variables.
mode: 'optimization'
// Use for: Resource allocation, scheduling, constrained optimization
Formal Logic
Rigorous logical reasoning with formal systems and proof verification.
mode: 'formal-logic'
// Use for: Proof verification, logical analysis, formal methods
Advanced Runtime Modes
Recursive
Recursive problem decomposition - break complex problems into smaller subproblems.
mode: 'recursive'
// Use for: Divide-and-conquer, tree-structured problems, recursive algorithms
Modal
Possibility and necessity reasoning using modal logic.
mode: 'modal'
// Use for: What's possible vs necessary, requirement analysis, constraint exploration
Stochastic
Probabilistic state transitions and Markov chain reasoning.
mode: 'stochastic'
// Use for: Process modeling, state machines, probabilistic sequences
Constraint
Constraint satisfaction problem solving.
mode: 'constraint'
// Use for: Scheduling, resource allocation, constraint propagation
Fundamental Modes
Inductive
Reasoning from specific observations to general principles.
mode: 'inductive'
// Use for: Pattern recognition, generalization, empirical reasoning
Deductive
Reasoning from general principles to specific conclusions.
mode: 'deductive'
// Use for: Logical proofs, applying rules, deriving conclusions
Abductive
Generate and evaluate hypotheses to explain observations.
mode: 'abductive'
// Use for: Debugging, root cause analysis, diagnostic reasoning
Historical Computing Modes (v7.2.0)
Tributes to Alan Turing and John von Neumann's foundational work.
Computability
Turing machines, decidability proofs, reductions, and diagonalization arguments.
mode: 'computability'
// Use for: Decidability analysis, algorithm limits, computational complexity
// Features: Turing machine simulation, reduction chains, halting problem analysis
Cryptanalytic
Turing's deciban evidence system from Bletchley Park.
mode: 'cryptanalytic'
// Use for: Evidence quantification, hypothesis testing, code-breaking analysis
// Features: Deciban accumulation (10 db ≈ 10:1 odds), frequency analysis, Banburismus
Extended Game Theory (v7.2.0)
Von Neumann's minimax theorem, cooperative games, and Shapley values.
mode: 'gametheory'
// Enhanced with: Minimax analysis, cooperative game theory, coalition analysis
// Use for: Zero-sum games, fair value distribution, strategic decision-making
Algorithmic Mode (v7.3.0)
Algorithmic
Comprehensive coverage of algorithms from "Introduction to Algorithms" (CLRS) with 100+ named algorithms.
mode: 'algorithmic'
// Use for: Algorithm design, complexity analysis, correctness proofs
// Features: Divide-and-conquer, dynamic programming, greedy, graph algorithms
// Coverage: Sorting, searching, graph, string, computational geometry
Academic Research Modes (v7.4.0)
Designed for PhD students and scientific paper writing.
Synthesis
Literature review and knowledge integration.
mode: 'synthesis'
// Use for: Literature reviews, theme extraction, knowledge integration
// Features: Source synthesis, pattern identification, gap analysis
Argumentation
Academic argumentation using the Toulmin model.
mode: 'argumentation'
// Use for: Building arguments, dialectical reasoning, rhetorical analysis
// Features: Toulmin model (claim, data, warrant, backing), counter-arguments
Critique
Critical analysis and peer review frameworks.
mode: 'critique'
// Use for: Peer review, methodology evaluation, evidence assessment
// Features: Systematic critique, strengths/weaknesses analysis
Analysis
Qualitative analysis methods.
mode: 'analysis'
// Use for: Thematic analysis, grounded theory, discourse analysis
// Features: Multiple qualitative analysis frameworks, coding support
Specialized Mode Handlers (v9.x)
The ModeHandler system provides 37 specialized handlers with advanced validation and enhancements. Key examples:
| Handler | Mode | Key Enhancements |
|---|---|---|
| HistoricalHandler | historical | Aggregate reliability scoring, causal chain validation, pattern detection |
| CausalHandler | causal | Validates graph structure, detects cycles, propagates interventions |
| BayesianHandler | bayesian | Auto-calculates posteriors from prior × likelihood, validates probability sums |
| GameTheoryHandler | gametheory | Validates payoff matrix dimensions, computes Nash equilibria |
| CounterfactualHandler | counterfactual | Tracks world states, validates divergence points, compares outcomes |
| SynthesisHandler | synthesis | Tracks source coverage, validates theme extraction, detects contradictions |
| SystemsThinkingHandler | systemsthinking | Detects 8 Systems Archetypes, adds warning signs and interventions |
| CritiqueHandler | critique | 6 Socratic question categories for rigorous critical analysis |
Systems Archetypes Detection
SystemsThinkingHandler automatically detects Peter Senge's 8 archetypes:
- Fixes that Fail - Short-term fixes with unintended consequences
- Shifting the Burden - Symptomatic vs fundamental solutions
- Limits to Growth - Growth hitting constraints
- Success to the Successful - Winner-take-all dynamics
- Tragedy of the Commons - Shared resource depletion
- Escalation - Competitive escalation spirals
- Accidental Adversaries - Alliance deterioration
- Growth and Underinvestment - Capacity constraints
Socratic Question Framework
CritiqueHandler uses Richard Paul's 6 categories:
- Clarification - "What do you mean by...?"
- Assumptions - "What are you assuming?"
- Evidence - "What evidence supports this?"
- Perspectives - "Are there alternative viewpoints?"
- Implications - "What are the consequences?"
- Meta - "Why is this question important?"
Proof Decomposition
New in v7.0.0! The proof decomposition system provides advanced mathematical reasoning capabilities:
Components
| Component | Purpose |
|---|---|
| ProofDecomposer | Breaks proofs into atomic statements with dependency tracking |
| GapAnalyzer | Detects missing steps, unjustified leaps, and implicit assumptions |
| AssumptionTracker | Traces conclusions back to their supporting assumptions |
| InconsistencyDetector | Detects circular dependencies and contradictions |
| MathematicsReasoningEngine | Integrated proof analysis with improvement suggestions |
Features
- Atomic Statement Types: axiom, hypothesis, definition, derived, lemma, conclusion
- Inference Rules: algebraic_manipulation, substitution, modus_ponens, universal_instantiation, etc.
- Gap Detection: Identify missing steps with severity levels (minor, significant, critical)
- Rigor Levels: informal, textbook, rigorous, formal
- Visual Export: Mermaid, DOT, ASCII, and native SVG formats
Example: Proof Analysis
{
"tool": "deepthinking_mathematics",
"arguments": {
"mode": "mathematics",
"thought": "Analyzing the proof that n² is even when n is even",
"thoughtNumber": 1,
"totalThoughts": 3,
"nextThoughtNeeded": true,
"proofDecomposition": {
"theorem": "If n is even, then n² is even",
"atoms": [
{"id": "a1", "content": "n is an even integer", "type": "hypothesis"},
{"id": "a2", "content": "n = 2k for some integer k", "type": "definition"},
{"id": "a3", "content": "n² = 4k² = 2(2k²)", "type": "derived"},
{"id": "a4", "content": "n² is even", "type": "conclusion"}
],
"dependencies": {
"nodes": ["a1", "a2", "a3", "a4"],
"edges": [
{"from": "a1", "to": "a2"},
{"from": "a2", "to": "a3"},
{"from": "a3", "to": "a4"}
]
}
}
}
}
Visual Export Formats
Export proof decompositions to multiple visual formats:
// Native SVG (no external tools required)
exportProofDecomposition(decomposition, {
format: 'svg',
colorScheme: 'default', // 'default' | 'pastel' | 'monochrome'
includeMetrics: true,
svgWidth: 1200,
svgHeight: 800
});
// Mermaid diagram
exportProofDecomposition(decomposition, { format: 'mermaid' });
// GraphViz DOT
exportProofDecomposition(decomposition, { format: 'dot' });
// ASCII text
exportProofDecomposition(decomposition, { format: 'ascii' });
Usage Examples
Example 1: Debugging with Abductive Reasoning
// Step 1: Start with observation
{
"tool": "deepthinking_core",
"arguments": {
"mode": "abductive",
"thought": "Observed: Users report intermittent 500 errors on checkout during high traffic periods",
"thoughtNumber": 1,
"totalThoughts": 4,
"nextThoughtNeeded": true,
"observations": ["Errors occur during high traffic", "Checkout page affected", "Intermittent pattern"]
}
}
// Step 2: Generate hypothesis
{
"tool": "deepthinking_core",
"arguments": {
"sessionId": "session-from-step-1",
"mode": "abductive",
"thought": "Hypothesis: Database connection pool exhaustion under load",
"thoughtNumber": 2,
"totalThoughts": 4,
"nextThoughtNeeded": true,
"hypotheses": [{
"id": "h1",
"explanation": "Connection pool exhausted",
"assumptions": ["Fixed pool size", "No connection recycling"],
"predictions": ["Errors correlate with traffic spikes"],
"score": 0.8
}]
}
}
Example 2: Impact Analysis with Causal Reasoning
{
"tool": "deepthinking_causal",
"arguments": {
"mode": "causal",
"thought": "Analyzing impact of increasing API rate limits on system behavior",
"thoughtNumber": 1,
"totalThoughts": 3,
"nextThoughtNeeded": true,
"causalGraph": {
"nodes": [
{"id": "rate_limit", "name": "Rate Limit", "type": "cause", "description": "API rate limit setting"},
{"id": "server_load", "name": "Server Load", "type": "mediator", "description": "CPU/Memory usage"},
{"id": "response_time", "name": "Response Time", "type": "effect", "description": "API latency"},
{"id": "satisfaction", "name": "User Satisfaction", "type": "effect", "description": "User experience"}
],
"edges": [
{"from": "rate_limit", "to": "server_load", "strength": 0.9, "confidence": 0.85},
{"from": "server_load", "to": "response_time", "strength": 0.85, "confidence": 0.9},
{"from": "response_time", "to": "satisfaction", "strength": -0.7, "confidence": 0.8}
]
}
}
}
Example 3: Strategic Analysis with Game Theory
{
"tool": "deepthinking_strategic",
"arguments": {
"mode": "gametheory",
"thought": "Analyzing pricing strategy in competitive market using game theory",
"thoughtNumber": 1,
"totalThoughts": 3,
"nextThoughtNeeded": true,
"game": {
"type": "strategic",
"players": ["Company A", "Company B"],
"strategies": {
"Company A": ["premium", "competitive", "discount"],
"Company B": ["premium", "competitive", "discount"]
},
"payoffMatrix": [
[{"A": 10, "B": 10}, {"A": 5, "B": 15}, {"A": 2, "B": 12}],
[{"A": 15, "B": 5}, {"A": 8, "B": 8}, {"A": 4, "B": 10}],
[{"A": 12, "B": 2}, {"A": 10, "B": 4}, {"A": 6, "B": 6}]
]
}
}
}
Production Features
Note: DeepThinking MCP is an MCP server, not a library. These features are accessed through MCP tools and internal architecture. The examples below describe the internal capabilities.
Proof Decomposition (v7.0.0)
Advanced mathematical reasoning with proof analysis:
- ProofDecomposer: Break proofs into atomic statements with dependency graphs
- GapAnalyzer: Detect missing steps, unjustified leaps, implicit assumptions
- AssumptionTracker: Trace conclusions to their supporting assumptions
- InconsistencyDetector: Find circular dependencies and contradictions
- Native SVG Export: Generate proof visualizations without external tools
Search Engine
Full-text search with faceted filtering and relevance ranking. Used internally to search across reasoning sessions by mode, tags, date ranges, and content.
Template System
Pre-built templates for common reasoning patterns, accessible through session creation.
File Export System
Export reasoning sessions directly to files with automatic directory organization:
- Automatic File Output - Configure
MCP_EXPORT_PATHto write exports to disk instead of returning content - Session Subdirectories - Files organized by session ID for easy management
- Export Profiles - Pre-configured bundles:
academic(LaTeX+Markdown+JSON),presentation(Mermaid+HTML+ASCII),documentation,archive,minimal - 8 Export Formats - Markdown, LaTeX, JSON, HTML, Jupyter, Mermaid, DOT, ASCII
- Overwrite Protection - Files won't be overwritten unless
overwrite: trueorMCP_EXPORT_OVERWRITE=true
// Export single format
{ "action": "export", "sessionId": "...", "exportFormat": "mermaid" }
// Export with profile
{ "action": "export", "sessionId": "...", "exportProfile": "academic" }
// Export all 8 formats
{ "action": "export_all", "sessionId": "..." }
Security & Validation
Enterprise-grade security features built into the MCP server:
- Input Validation - Zod schemas validate all 33 mode inputs
- Rate Limiting - Sliding window rate limiter for API protection
- Path Sanitization - Prevents directory traversal attacks
- PII Redaction - GDPR-compliant log sanitization
Taxonomy Classifier
Intelligent classification of reasoning tasks using 69 reasoning types across 12 categories. Use the recommend_mode action in deepthinking_session to get mode recommendations based on problem characteristics.
API Documentation
MCP Tool Interface
All reasoning is done through MCP tools. Each tool accepts arguments and returns JSON responses.
Common Parameters (all thinking tools)
| Parameter | Type | Required | Description |
|---|---|---|---|
sessionId | string | No | Session ID (auto-created if omitted) |
thought | string | Yes | The reasoning content |
thoughtNumber | integer | Yes | Current thought number (1-based) |
totalThoughts | integer | Yes | Estimated total thoughts |
nextThoughtNeeded | boolean | Yes | Whether more reasoning needed |
mode | string | Yes | The reasoning mode |
Session Actions (deepthinking_session)
| Action | Parameters | Description |
|---|---|---|
summarize | sessionId | Generate session summary |
export | sessionId, exportFormat | Export to format (json, markdown, latex, html, jupyter, mermaid, dot, ascii, svg) |
get_session | sessionId | Get session details |
switch_mode | sessionId, newMode | Switch reasoning mode |
recommend_mode | problemType or problemCharacteristics | Get mode recommendations |
Example Response
{
"sessionId": "session-abc123",
"thoughtId": "thought-xyz789",
"thoughtNumber": 1,
"mode": "sequential",
"nextThoughtNeeded": true,
"sessionComplete": false,
"totalThoughts": 3
}
For architecture details, see docs/architecture/.
Project Stats
| Metric | Value |
|---|---|
| TypeScript Files | 237 |
| Lines of Code | ~102,500 |
| Test Files | 181 |
| Passing Tests | 5,048 |
| Thinking Modes | 34 (30 with thought types) |
| ModeHandlers | 37 specialized handlers |
| MCP Tools | 13 focused tools |
| Export Formats | 8 + native SVG |
| Visual Exporters | 42 files (24 mode-specific) |
| Builder Classes | 14 fluent APIs |
| Reasoning Types | 69 (110 planned) |
| Modules | 15 |
| Total Exports | 1,275 (571 re-exports) |
Architecture
The codebase is organized into 15 modules with clean separation of concerns. See docs/architecture/DEPENDENCY_GRAPH.md for the complete dependency graph.
Core Structure
src/
├── index.ts # MCP server entry point (tool handlers)
├── types/ # Type definitions including 33 mode types (36 files)
│ ├── core.ts # ThinkingMode enum, Thought union type
│ └── modes/ # One file per reasoning mode
├── services/ # Business logic layer (2 files)
│ ├── ThoughtFactory.ts # Thought creation with handler integration
│ └── ExportService.ts # Multi-format export handling
├── session/ # SessionManager, persistence, storage (4 files)
├── modes/ # ModeHandler architecture (v9.x) - 52 files
│ ├── handlers/ # 38 specialized handlers (all modes covered)
│ │ ├── CausalHandler.ts # Graph validation, cycle detection
│ │ ├── BayesianHandler.ts # Auto posterior calculation
│ │ ├── GameTheoryHandler.ts # Nash equilibria detection
│ │ ├── CounterfactualHandler.ts # World state tracking
│ │ ├── SynthesisHandler.ts # Source coverage tracking
│ │ ├── SystemsThinkingHandler.ts # 8 Systems Archetypes
│ │ ├── CritiqueHandler.ts # 6 Socratic categories
│ │ └── [+ 31 more specialized handlers]
│ └── registry.ts # ModeHandlerRegistry singleton
├── proof/ # Proof decomposition system (13 files)
│ ├── decomposer.ts # ProofDecomposer class
│ ├── gap-analyzer.ts # GapAnalyzer class
│ └── assumption-tracker.ts # AssumptionTracker class
└── tools/ # MCP tool definitions and schemas (18 files)
ModeHandler Architecture (v9.x)
The ModeHandler pattern (Strategy pattern) provides mode-specific processing, with all 33 modes fully covered:
// Handler interface
interface ModeHandler {
mode: ThinkingMode;
validate(input: ThinkingToolInput): ValidationResult;
enhance(thought: Thought, context: SessionContext): Thought;
getSuggestions(thought: Thought): string[];
}
// Registry manages all 38 handlers
const registry = ModeHandlerRegistry.getInstance();
registry.hasSpecializedHandler('causal'); // true for ALL 33 modes
Benefits:
- All 33 modes have specialized validation logic
- Automatic enhancements (posteriors, equilibria, archetypes)
- Mode-specific suggestions and warnings
- Clean separation from ThoughtFactory
- 38 total handlers (33 modes + GenericModeHandler + CustomHandler + utilities)
Feature Modules
src/
├── taxonomy/ # 69 reasoning types, classifier, suggestion engine (5 files)
│ ├── reasoning-types.ts # Full taxonomy definitions
│ ├── classifier.ts # Task classification
│ └── suggestion-engine.ts # Mode recommendations
├── export/ # Visual and document exporters (44 files)
│ ├── visual/ # Mode-specific visual exporters + native SVG
│ │ ├── proof-decomposition.ts # Proof visualization
│ │ ├── utils/ # 14 builder classes
│ │ └── modes/ # 22 mode-specific exporters
│ └── latex.ts # LaTeX document generation
├── search/ # Full-text search with TF-IDF (3 files)
├── cache/ # LRU caching strategies (3 files)
├── validation/ # Zod schemas (44 files, 35 validators)
└── utils/ # Utility functions (6 files)
Security Features
Security is built into multiple modules:
- validation/ - Input validation with Zod schemas for all 33 modes (35 validators)
- utils/sanitization.ts - Path sanitization & traversal prevention
- utils/log-sanitizer.ts - PII redaction for GDPR compliance
- utils/errors.ts - Standardized error hierarchy with context
Contributing
We welcome contributions! Please open an issue or pull request on GitHub.
Adding New Reasoning Modes
Want to add a new reasoning mode? We've made it easy:
📖 Complete Guide: Adding a New Mode
This guide includes:
- Step-by-step instructions for all 8 required files
- Template files in
templates/mode-scaffolding/ - Code examples and common patterns
- Complete checklist to ensure nothing is missed
- Testing guidelines
Quick Start:
# Copy template files
cp templates/mode-scaffolding/example-mode.type.ts src/types/modes/yourmode.ts
cp templates/mode-scaffolding/example-mode.validator.ts src/validation/validators/modes/yourmode.ts
# Follow the guide
cat docs/ADDING_NEW_MODE.md
Development Setup
# Clone repository
git clone https://github.com/danielsimonjr/deepthinking-mcp.git
cd deepthinking-mcp
# Install dependencies
npm install
# Run tests
npm test
# Run type checking
npm run typecheck
# Build
npm run build
Running Tests
# Run all tests
npm test
# Run specific test file
npm test -- path/to/test.test.ts
# Run with coverage
npm run test:coverage
License
MIT License - see LICENSE file for details.
Acknowledgments
This project builds upon foundational work from the MCP community:
- Anthropic's sequential-thinking MCP - The original sequential thinking server that inspired this project's core architecture
- olaservo's shannon-thinking MCP - Introduced the Shannon 5-stage methodology that became one of our core reasoning modes
Additional acknowledgments:
- Built on the Model Context Protocol
- Inspired by research in cognitive science and AI reasoning
- Community contributions from researchers and practitioners
Support
Made with ❤️ by the DeepThinking MCP team