deepthinking-mcp 3.0.2 → 3.1.0

package/README.md

@@ -1,10 +1,10 @@
-# DeepThinking MCP v3.0.2
+# DeepThinking MCP v3.1.0
 
-A comprehensive Model Context Protocol (MCP) server featuring **13 advanced reasoning modes** with intelligent mode recommendation, visual export capabilities, high-performance validation caching, comprehensive testing, and automated CI/CD for complex problem-solving, analysis, and decision-making.
+A comprehensive Model Context Protocol (MCP) server featuring **14 advanced reasoning modes** with intelligent mode recommendation, visual export capabilities, high-performance validation caching, comprehensive testing, and automated CI/CD for complex problem-solving, analysis, and decision-making.
 
 ## Overview
 
-DeepThinking MCP v3.0 provides a complete toolkit for structured reasoning with 13 specialized modes, an intelligent recommendation system, powerful visual export capabilities, and optimized performance through validation caching:
+DeepThinking MCP v3.1 provides a complete toolkit for structured reasoning with 14 specialized modes, an intelligent recommendation system, powerful visual export capabilities, and optimized performance through validation caching:
 
 ### Core Modes
 - **Sequential**: Iterative refinement with revision capabilities
@@ -23,6 +23,7 @@ n### Phase 3 Modes (v2.3+)
 - **Temporal**: Event timelines, temporal constraints, Allen's interval algebra, causal relations over time
 - **Game Theory**: Nash equilibria, strategic analysis, payoff matrices, dominant strategies, game trees
 - **Evidential**: Dempster-Shafer theory, belief functions, evidence combination, uncertainty intervals
+- **First-Principles**: Deductive reasoning from foundational axioms and principles
 
 ## Features
 
@@ -45,6 +46,7 @@ n#### Phase 3 Reasoning Modes (v2.3+)
 - **Temporal**: Model events, intervals, and temporal relationships using Allen's interval algebra. Track causality over time with timestamps, durations, and temporal constraints. Perfect for timeline analysis, scheduling problems, and understanding event sequences.
 - **Game Theory**: Analyze strategic interactions between rational agents. Define games, players, and strategies. Compute Nash equilibria (pure and mixed), identify dominant strategies, construct payoff matrices, and build extensive-form game trees. Ideal for competitive analysis, mechanism design, and strategic decision-making.
 - **Evidential**: Apply Dempster-Shafer theory for reasoning with uncertain and incomplete evidence. Define hypotheses, collect evidence with reliability scores, assign belief functions with mass assignments, combine evidence using Dempster's rule, compute belief and plausibility intervals, and make decisions under uncertainty. Ideal for sensor fusion, diagnostic reasoning, intelligence analysis, and situations with incomplete information.
+- **First-Principles**: Derive conclusions from foundational axioms and principles using deductive reasoning. Define principles (axioms, definitions, observations), build derivation chains with logical inferences, track confidence levels, and reach conclusions with certainty analysis. Ideal for fundamental analysis, conceptual understanding, and reasoning from basic truths.
 
 ### Mathematical Enhancements
 - **Symbolic computation** support with LaTeX and symbolic formats
@@ -192,11 +194,7 @@ Export your reasoning sessions as visual diagrams in multiple formats for presen
 - **DOT**: Graphviz format for professional graph visualization and publication-quality diagrams
 - **ASCII**: Plain text diagrams for terminal output, logs, and text-based documentation
 
-#### Supported Modes
-- **Causal Mode**: Export causal graphs showing cause-effect relationships with node types (causes, effects, mediators, confounders) and edge strengths
-- **Temporal Mode**: Export timelines as Gantt charts showing events, intervals, and temporal relationships
-- **Game Theory Mode**: Export game trees with strategies, decision nodes, and payoffs
-- **Bayesian Mode**: Export Bayesian networks showing prior/posterior relationships and evidence flow
+#### Supported Modes**All 14 modes now support visual export (100% coverage):**- **Causal Mode**: Export causal graphs showing cause-effect relationships with node types (causes, effects, mediators, confounders) and edge strengths- **Temporal Mode**: Export timelines as Gantt charts showing events, intervals, and temporal relationships- **Game Theory Mode**: Export game trees with strategies, decision nodes, and payoffs- **Bayesian Mode**: Export Bayesian networks showing prior/posterior relationships and evidence flow- **First-Principles Mode**: Export derivation chains showing question → principles → derivation steps → conclusion flow- **All Other Modes**: Generic thought sequence visualization showing reasoning progression for Sequential, Shannon, Mathematics, Physics, Hybrid, Abductive, Counterfactual, Analogical, and Evidential modes
 
 #### Visual Export Examples
 
@@ -279,7 +277,7 @@ Visual exports work seamlessly with:
 - `thoughtNumber` (number, required): Position in sequence
 - `totalThoughts` (number, required): Estimated total thoughts needed
 - `nextThoughtNeeded` (boolean, required): Whether to continue thinking
-- `mode` (string, optional): `sequential`, `shannon`, `mathematics`, `physics`, `hybrid`, `abductive`, `causal`, `bayesian`, `counterfactual`, `analogical`, or `temporal` (default: `hybrid`)
+- `mode` (string, optional): `sequential`, `shannon`, `mathematics`, `physics`, `hybrid`, `abductive`, `causal`, `bayesian`, `counterfactual`, `analogical`, or `temporal`, `gametheory`, `evidential`, `firstprinciple` (default: `hybrid`)
 
 ### Mode-Specific Parameters
 
@@ -366,6 +364,26 @@ n#### Temporal Mode
 - `combinedBelief`: Belief function resulting from Dempster-Shafer combination (includes conflictMass)
 - `plausibility`: Plausibility function with belief/plausibility values and uncertainty intervals
 - `decisions`: Decision analysis (selectedHypothesis, confidence, reasoning, alternatives)
+n#### First-Principles Mode
+- `question`: The question being answered from first principles
+- `principles`: Array of foundational principles with:
+  - `id`: Unique identifier
+  - `type`: Principle type (axiom, definition, observation, logical_inference, assumption)
+  - `statement`: The principle statement
+  - `justification`: Why this principle is valid
+  - `dependsOn`: Optional array of principle IDs this depends on
+- `derivationSteps`: Chain of reasoning steps with:
+  - `stepNumber`: Step position in derivation
+  - `principle`: The principle being applied
+  - `inference`: What is inferred from this principle
+  - `logicalForm`: Optional formal logic representation
+  - `confidence`: Confidence in this step (0-1)
+- `conclusion`: Final conclusion with:
+  - `statement`: The conclusion statement
+  - `derivationChain`: Array of step numbers leading to conclusion
+  - `certainty`: Overall certainty level (0-1)
+  - `limitations`: Optional array of known limitations or assumptions
+- `alternativeInterpretations`: Optional array of other possible interpretations
 
 ### Actions
 - `add_thought` (default): Add a new thought to session
@@ -748,7 +766,7 @@ deepthinking-mcp/
 - ✅ Comprehensive test suite (77 tests)
 - ✅ Enhanced type safety
 
-### Phase 3 (Completed - v3.0.2)
+### Phase 3 (Completed - v3.1.0)
 - ✅ Temporal reasoning mode (v2.1)
 - ✅ Game theory mode (v2.2)
 - ✅ Evidential reasoning mode (v2.3)
@@ -758,6 +776,8 @@ deepthinking-mcp/
 - ✅ Performance optimization with validation caching (v3.0)
 - ✅ Integration tests & MCP compliance (v3.0.2)
 - ✅ CI/CD pipeline with GitHub Actions (v3.0.2)
+- ✅ First-Principles reasoning mode (v3.1.0)
+- ✅ Universal visual export support for all 14 modes (v3.1.0)
 
 ### Phase 4 (Planned)
 - [ ] Math-MCP integration

package/dist/index.js

@@ -10,7 +10,7 @@ import { z } from 'zod';
 
 var ThinkingToolSchema = z.object({
   sessionId: z.string().optional(),
-  mode: z.enum(["sequential", "shannon", "mathematics", "physics", "hybrid", "abductive", "causal", "bayesian", "counterfactual", "analogical", "temporal", "gametheory", "evidential"]).default("hybrid"),
+  mode: z.enum(["sequential", "shannon", "mathematics", "physics", "hybrid", "abductive", "causal", "bayesian", "counterfactual", "analogical", "temporal", "gametheory", "evidential", "firstprinciple"]).default("hybrid"),
   thought: z.string(),
   thoughtNumber: z.number().int().positive(),
   totalThoughts: z.number().int().positive(),
@@ -397,9 +397,38 @@ var ThinkingToolSchema = z.object({
       risk: z.number()
     }))
   })).optional(),
+  // First-principles reasoning properties (v3.1.0)
+  question: z.string().optional(),
+  principles: z.array(z.object({
+    id: z.string(),
+    type: z.enum(["axiom", "definition", "observation", "logical_inference", "assumption"]),
+    statement: z.string(),
+    justification: z.string(),
+    dependsOn: z.array(z.string()).optional()
+  })).optional(),
+  derivationSteps: z.array(z.object({
+    stepNumber: z.number(),
+    principle: z.object({
+      id: z.string(),
+      type: z.enum(["axiom", "definition", "observation", "logical_inference", "assumption"]),
+      statement: z.string(),
+      justification: z.string(),
+      dependsOn: z.array(z.string()).optional()
+    }),
+    inference: z.string(),
+    logicalForm: z.string().optional(),
+    confidence: z.number().min(0).max(1)
+  })).optional(),
+  conclusion: z.object({
+    statement: z.string(),
+    derivationChain: z.array(z.number()),
+    certainty: z.number().min(0).max(1),
+    limitations: z.array(z.string()).optional()
+  }).optional(),
+  alternativeInterpretations: z.array(z.string()).optional(),
   action: z.enum(["add_thought", "summarize", "export", "switch_mode", "get_session", "recommend_mode"]).default("add_thought"),
   exportFormat: z.enum(["markdown", "latex", "json", "html", "jupyter", "mermaid", "dot", "ascii"]).optional(),
-  newMode: z.enum(["sequential", "shannon", "mathematics", "physics", "hybrid", "abductive", "causal", "bayesian", "counterfactual", "analogical", "temporal", "gametheory", "evidential"]).optional(),
+  newMode: z.enum(["sequential", "shannon", "mathematics", "physics", "hybrid", "abductive", "causal", "bayesian", "counterfactual", "analogical", "temporal", "gametheory", "evidential", "firstprinciple"]).optional(),
   // Mode recommendation parameters (v2.4)
   problemType: z.string().optional(),
   problemCharacteristics: z.object({
@@ -2447,6 +2476,215 @@ Bayes Factor: ${thought.bayesFactor.toFixed(2)}
   sanitizeId(id) {
     return id.replace(/[^a-zA-Z0-9_]/g, "_");
   }
+  // ===== Generic Thought Sequence Export =====
+  /**
+   * Export any thought sequence as a flow diagram
+   * Works for sequential, shannon, mathematics, physics, hybrid, abductive,
+   * counterfactual, analogical, and evidential modes
+   */
+  exportThoughtSequence(thoughts, options) {
+    const { format, colorScheme = "default" } = options;
+    switch (format) {
+      case "mermaid":
+        return this.thoughtSequenceToMermaid(thoughts, colorScheme);
+      case "dot":
+        return this.thoughtSequenceToDOT(thoughts);
+      case "ascii":
+        return this.thoughtSequenceToASCII(thoughts);
+      default:
+        throw new Error(`Unsupported format: ${format}`);
+    }
+  }
+  thoughtSequenceToMermaid(thoughts, colorScheme) {
+    let mermaid = "graph TD\n";
+    for (let i = 0; i < thoughts.length; i++) {
+      const thought = thoughts[i];
+      const nodeId = `T${i + 1}`;
+      const content = thought.content.substring(0, 60).replace(/\n/g, " ");
+      const label = `${i + 1}. ${content}${thought.content.length > 60 ? "..." : ""}`;
+      mermaid += `  ${nodeId}["${label}"]
+`;
+      if (i > 0) {
+        mermaid += `  T${i} --> ${nodeId}
+`;
+      }
+    }
+    if (colorScheme !== "monochrome" && thoughts.length > 0) {
+      mermaid += "\n";
+      const color = colorScheme === "pastel" ? "#e1f5ff" : "#a8d5ff";
+      mermaid += `  style T1 fill:${color}
+`;
+      if (thoughts.length > 1) {
+        const endColor = colorScheme === "pastel" ? "#e8f5e9" : "#c8e6c9";
+        mermaid += `  style T${thoughts.length} fill:${endColor}
+`;
+      }
+    }
+    return mermaid;
+  }
+  thoughtSequenceToDOT(thoughts) {
+    let dot = "digraph ThoughtSequence {\n";
+    dot += "  rankdir=TD;\n";
+    dot += "  node [shape=box, style=rounded];\n\n";
+    for (let i = 0; i < thoughts.length; i++) {
+      const thought = thoughts[i];
+      const nodeId = `T${i + 1}`;
+      const content = thought.content.substring(0, 60).replace(/"/g, '\\"').replace(/\n/g, " ");
+      const label = `${i + 1}. ${content}${thought.content.length > 60 ? "..." : ""}`;
+      dot += `  ${nodeId} [label="${label}"];
+`;
+      if (i > 0) {
+        dot += `  T${i} -> ${nodeId};
+`;
+      }
+    }
+    dot += "}\n";
+    return dot;
+  }
+  thoughtSequenceToASCII(thoughts) {
+    let ascii = "Thought Sequence:\n";
+    ascii += "=================\n\n";
+    for (let i = 0; i < thoughts.length; i++) {
+      const thought = thoughts[i];
+      ascii += `${i + 1}. ${thought.content}
+`;
+      if (i < thoughts.length - 1) {
+        ascii += "   \u2193\n";
+      }
+      ascii += "\n";
+    }
+    return ascii;
+  }
+  // ===== First-Principles Export =====
+  /**
+   * Export first-principles reasoning to visual format
+   */
+  exportFirstPrinciples(thought, options) {
+    const { format, colorScheme = "default" } = options;
+    switch (format) {
+      case "mermaid":
+        return this.firstPrinciplesToMermaid(thought, colorScheme);
+      case "dot":
+        return this.firstPrinciplesToDOT(thought);
+      case "ascii":
+        return this.firstPrinciplesToASCII(thought);
+      default:
+        throw new Error(`Unsupported format: ${format}`);
+    }
+  }
+  firstPrinciplesToMermaid(thought, colorScheme) {
+    let mermaid = "graph TD\n";
+    mermaid += `  Q["Question: ${thought.question}"]
+`;
+    for (const principle of thought.principles) {
+      const pid = this.sanitizeId(principle.id);
+      mermaid += `  ${pid}["${principle.type}: ${principle.statement}"]
+`;
+    }
+    for (const step of thought.derivationSteps) {
+      const sid = `S${step.stepNumber}`;
+      const pid = this.sanitizeId(step.principle.id);
+      mermaid += `  ${sid}["Step ${step.stepNumber}: ${step.inference}"]
+`;
+      mermaid += `  ${pid} --> ${sid}
+`;
+      if (step.stepNumber > 1) {
+        mermaid += `  S${step.stepNumber - 1} --> ${sid}
+`;
+      } else {
+        mermaid += `  Q --> ${pid}
+`;
+      }
+    }
+    mermaid += `  C[["Conclusion: ${thought.conclusion.statement}"]]:
+`;
+    if (thought.derivationSteps.length > 0) {
+      mermaid += `  S${thought.derivationSteps.length} --> C
+`;
+    }
+    if (colorScheme !== "monochrome") {
+      mermaid += "\n";
+      const qColor = colorScheme === "pastel" ? "#fff3e0" : "#ffeb3b";
+      const cColor = colorScheme === "pastel" ? "#e8f5e9" : "#4caf50";
+      mermaid += `  style Q fill:${qColor}
+`;
+      mermaid += `  style C fill:${cColor}
+`;
+    }
+    return mermaid;
+  }
+  firstPrinciplesToDOT(thought) {
+    let dot = "digraph FirstPrinciples {\n";
+    dot += "  rankdir=TD;\n";
+    dot += "  node [shape=box, style=rounded];\n\n";
+    dot += `  Q [label="Question:\\n${thought.question}", shape=ellipse];
+`;
+    for (const principle of thought.principles) {
+      const pid = this.sanitizeId(principle.id);
+      dot += `  ${pid} [label="${principle.type}:\\n${principle.statement}"];
+`;
+    }
+    for (const step of thought.derivationSteps) {
+      const sid = `S${step.stepNumber}`;
+      const pid = this.sanitizeId(step.principle.id);
+      dot += `  ${sid} [label="Step ${step.stepNumber}:\\n${step.inference}"];
+`;
+      dot += `  ${pid} -> ${sid};
+`;
+      if (step.stepNumber > 1) {
+        dot += `  S${step.stepNumber - 1} -> ${sid};
+`;
+      } else {
+        dot += `  Q -> ${pid};
+`;
+      }
+    }
+    dot += `  C [label="Conclusion:\\n${thought.conclusion.statement}", shape=doubleoctagon];
+`;
+    if (thought.derivationSteps.length > 0) {
+      dot += `  S${thought.derivationSteps.length} -> C;
+`;
+    }
+    dot += "}\n";
+    return dot;
+  }
+  firstPrinciplesToASCII(thought) {
+    let ascii = "First-Principles Reasoning:\n";
+    ascii += "===========================\n\n";
+    ascii += `Question: ${thought.question}
+
+`;
+    ascii += "Foundational Principles:\n";
+    for (const principle of thought.principles) {
+      ascii += `  \u2022 [${principle.type}] ${principle.statement}
+`;
+      ascii += `    Justification: ${principle.justification}
+`;
+    }
+    ascii += "\n";
+    ascii += "Derivation Chain:\n";
+    for (const step of thought.derivationSteps) {
+      ascii += `  ${step.stepNumber}. ${step.inference}
+`;
+      ascii += `     (From: ${step.principle.statement})
+`;
+      ascii += `     Confidence: ${(step.confidence * 100).toFixed(0)}%
+`;
+    }
+    ascii += "\n";
+    ascii += `Conclusion: ${thought.conclusion.statement}
+`;
+    ascii += `Certainty: ${(thought.conclusion.certainty * 100).toFixed(0)}%
+`;
+    if (thought.conclusion.limitations && thought.conclusion.limitations.length > 0) {
+      ascii += "\nLimitations:\n";
+      for (const limitation of thought.conclusion.limitations) {
+        ascii += `  \u2022 ${limitation}
+`;
+      }
+    }
+    return ascii;
+  }
 };
 
 // src/utils/type-guards.ts
@@ -2637,8 +2875,16 @@ async function handleExport(input) {
         includeLabels: true,
         includeMetrics: true
       });
+    } else if (lastThought.mode === "firstprinciple" && "question" in lastThought) {
+      exported2 = visualExporter.exportFirstPrinciples(lastThought, {
+        format,
+        colorScheme: "default"
+      });
     } else {
-      throw new Error(`Visual export not supported for mode: ${lastThought.mode}`);
+      exported2 = visualExporter.exportThoughtSequence(session.thoughts, {
+        format,
+        colorScheme: "default"
+      });
     }
     return {
       content: [{
@@ -2873,6 +3119,8 @@ function createThought(input, sessionId) {
         plausibility: input.plausibility,
         decisions: input.decisions || []
       };
+    case "firstprinciple":
+      return { ...baseThought, mode: "firstprinciple" /* FIRSTPRINCIPLE */, question: input.question || "", principles: input.principles || [], derivationSteps: input.derivationSteps || [], conclusion: input.conclusion || { statement: "", derivationChain: [], certainty: 0 }, alternativeInterpretations: input.alternativeInterpretations || [] };
     case "hybrid":
     default:
       return {