@gotza02/seq-thinking 1.1.2 → 1.1.4

package/README.md

@@ -1,73 +1,21 @@
 # MCP Sequential Thinking with Swarm Coordination
 
-[![Version](https://img.shields.io/badge/version-1.1.0-blue.svg)](https://github.com/yourusername/mcp-sequential-thinking)
+[![Version](https://img.shields.io/badge/version-1.1.4-blue.svg)](https://github.com/yourusername/mcp-sequential-thinking)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
 
-Advanced Sequential Thinking MCP Tool with Swarm Agent Coordination - A superior alternative to Claude's sequential thinking capabilities, integrated with real LLM power via your favorite CLI tools.
+**Advanced Sequential Thinking MCP Server** with integrated Swarm Intelligence. This tool empowers your AI environment with structured reasoning, self-correction, and a coordinated team of specialized agents, leveraging your existing local LLM CLI tools.
 
-## Overview
+## 🚀 Key Features
 
-This system provides advanced sequential thinking capabilities with:
+*   **🧠 Advanced Sequential Thinking**: Supports branching, merging, and pruning of thought paths.
+*   **🤖 Swarm Intelligence**: Coordinates specialized agents (**Reasoner**, **Critic**, **Synthesizer**, **Meta-Reasoner**) to solve complex problems.
+*   **🔌 BYO-LLM (Bring Your Own LLM)**: Connects directly to **Gemini**, **Claude**, **Kimi**, and **OpenCode** via their CLI tools—no extra API keys required if you're already logged in.
+*   **🔄 Auto-Fallback & Robustness**: Automatically switches providers if one fails (e.g., `gemini` -> `claude`). Includes retry logic for resilient task execution.
+*   **💾 Persistence**: Automatically saves sessions and agent states to disk (`./data/`), allowing you to resume complex reasoning tasks anytime.
+*   **🔍 Self-Correction**: Proactively detects logical fallacies and confidence dips, triggering corrective actions.
 
-- **Real LLM Integration**: Connects directly to Gemini, Claude (Claude Code), Kimi, and OpenCode via CLI.
-- **Self-Correction Loops**: Automatically detect and fix reasoning errors.
-- **Parallel Hypothesis Generation**: Explore multiple reasoning paths simultaneously.
-- **Meta-Reasoning**: Reflect on and improve the thinking process.
-- **Adaptive Granularity**: Adjust detail level based on problem complexity.
-- **Persistence Layer**: All thinking sessions and agent states are saved to disk.
-- **Swarm Agent Coordination**: Multiple specialized agents working together with retry logic.
-
-## AI System Instructions
-
-This project includes a [SYSTEM_INSTRUCTIONS.md](./SYSTEM_INSTRUCTIONS.md) file specifically designed to guide AI models on how to use these tools effectively. It covers initialization, branching, and swarm delegation strategies.
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                    MCP TOOL INTERFACE                            │
-│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
-│  │ Sequential  │  │   Swarm     │  │      Tool Registry      │  │
-│  │  Thinking   │  │ Coordination│  │                         │  │
-│  └──────┬──────┘  └──────┬──────┘  └─────────────────────────┘  │
-└─────────┼────────────────┼──────────────────────────────────────┘
-          │                │
-┌─────────┼────────────────┼──────────────────────────────────────┐
-│         │    ORCHESTRATION ENGINE                               │
-│  ┌──────┴──────┐  ┌──────────────┐  ┌──────────────────────┐   │
-│  │State Manager│  │ Flow Control │  │     Scheduler        │   │
-│  │(Persistence)│  │ (Retry Logic)│  │                      │   │
-│  └──────┴──────┘  └──────────────┘  └──────────────────────┘   │
-└─────────┬───────────────────────────────────────────────────────┘
-          │
-┌─────────┴──────────────────────────────────────────────────────┐
-│         │         SWARM AGENT COORDINATOR                        │
-│  ┌──────┴──────┐  ┌─────────────┐  ┌──────────────────────┐    │
-│  │  Reasoner   │  │   Critic    │  │    Synthesizer       │    │
-│  │   Agents    │  │   Agents    │  │      Agents          │    │
-│  └──────┬──────┘  └──────┬──────┘  └───────────┬──────────┘    │
-└─────────┼────────────────┼─────────────────────┼────────────────┘
-          │                │                     │
-┌─────────┴────────────────┴─────────────────────┴────────────────┐
-│                  LLM ADAPTER (CLI BRIDGE)                       │
-│    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐ │
-│    │  Gemini  │    │  Claude  │    │   Kimi   │    │ OpenCode │ │
-│    └──────────┘    └──────────┘    └──────────┘    └──────────┘ │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## LLM Providers (CLI Integration)
-
-The system is designed to use LLMs that you have already logged into via your command line. This simplifies authentication and leverages your existing CLI tools.
-
-Supported Providers:
-- **gemini**: Uses `gemini ask "..."`
-- **claude**: Uses `claude "..." --non-interactive` (Compatible with Claude Code)
-- **kimi**: Uses `kimi chat "..."`
-- **opencode**: Uses `opencode ask "..."`
-
-## Installation
+## 📦 Installation
 
 ```bash
 # Clone the repository
@@ -81,18 +29,18 @@ npm install
 npm run build
 ```
 
-## Configuration (MCP JSON)
+## ⚙️ Configuration
 
-Add this to your MCP settings file (e.g., `claude_desktop_config.json`, `gemini-cli.json`, or Kimi's `mcp.json`):
+Add this configuration to your MCP client (e.g., `claude_desktop_config.json`, `gemini-cli.json`):
 
 ```json
 {
   "mcpServers": {
     "advanced-thinking": {
       "command": "node",
-      "args": ["/absolute/path/to/dist/mcp-server.js"],
+      "args": ["/absolute/path/to/mcp-sequential-thinking/dist/mcp-server.js"],
       "env": {
-        "provider": "gemini", 
+        "provider": "gemini,claude", 
         "MOCK_LLM": "false"
       }
     }
@@ -102,48 +50,69 @@ Add this to your MCP settings file (e.g., `claude_desktop_config.json`, `gemini-
 
 ### Environment Variables
 
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `provider` | The LLM provider to use (`gemini`, `claude`, `kimi`, `opencode`) | `gemini` |
-| `MOCK_LLM` | If `true`, returns mock data instead of calling the CLI (useful for testing) | `false` |
+| Variable | Description | Default | Example |
+|----------|-------------|---------|---------|
+| `provider` | Comma-separated list of LLM CLIs to use. The system tries them in order. | `gemini` | `gemini,claude,kimi` |
+| `MOCK_LLM` | If `true`, returns mock responses (for testing without API costs). | `false` | `true` |
 
-## Persistence
+**Supported CLI Tools:**
+*   **Gemini:** Requires `gemini` CLI installed and authenticated.
+*   **Claude:** Requires `claude` (Claude Code) CLI installed and authenticated.
+*   **Kimi:** Requires `kimi` CLI.
+*   **OpenCode:** Requires `opencode` CLI.
 
-Thinking sessions are automatically persisted to the `./data` directory. 
-- **Sessions**: Stored in `./data/sessions/`
-- **Agents**: Stored in `./data/agents/`
+## 🛠️ Usage
 
-This ensures that your reasoning state is preserved even if the MCP server restarts.
+This server provides two main tools to your AI client:
 
-## Enhanced Swarm Logic
+### 1. `advanced_sequential_thinking`
+The core thinking engine.
+*   **Operations:** `initialize`, `add_thought`, `branch_thought`, `self_correct`, `complete_session`, etc.
+*   **Use Case:** Deep, step-by-step problem solving with ability to backtrack.
 
-- **Automated Retries**: Tasks assigned to agents will automatically retry up to 3 times with exponential backoff on failure.
-- **Intelligent Context**: When reaching consensus, agents receive current swarm statistics and history of previous votes to make more informed decisions.
-- **Async Workflow**: All operations are non-blocking, ensuring the MCP server remains responsive during long reasoning tasks.
+### 2. `swarm_agent_coordination`
+The workforce manager.
+*   **Operations:** `register_agent`, `assign_task`, `reach_consensus`, `resolve_conflict`.
+*   **Use Case:** Delegating sub-tasks to specialized "virtual experts" (e.g., asking a "Critic" agent to review a plan).
 
-## API Documentation
-
-*(Standard Sequential Thinking and Swarm Coordination operations are supported as documented in the internal tool definitions)*
-
-## Testing
+## 🧪 Testing & Development
 
+### Run Unit Tests
+Verifies the logic of all components (Agents, Graph, Persistence).
 ```bash
-# Run tests with mock LLM responses
+# Run all tests using mock LLM data
 export MOCK_LLM=true
 npm test
 ```
 
-## License
+### Run Real-World Scenario
+Simulates a full end-to-end workflow: creating a session, registering agents, delegating tasks, and self-correction.
+```bash
+# Run the E2E simulation
+export MOCK_LLM=true
+node dist/real_world_test.js
+```
+
+## 🏗️ Architecture
 
-MIT License - see [LICENSE](LICENSE) file for details.
+The system is built on a modular architecture:
+*   **Orchestration Layer:** Manages state, flow control, and error handling.
+*   **Swarm Coordinator:** Assigns tasks based on agent capabilities and availability.
+*   **Thought Graph:** A directed acyclic graph (DAG) representing the reasoning process.
+*   **LLM Adapter:** A unified interface for communicating with various CLI-based models.
+
+## 📝 Changelog
 
-## Changelog
+### v1.1.4 (2026-02-03)
+- **Fix:** Fixed a critical bug in `MetaReasoningAgent` that caused crashes when analyzing thoughts with missing confidence data.
+- **Improvement:** Enhanced robustness of `overall` confidence calculation across all agents.
+- **Doc:** Updated README with comprehensive usage and testing instructions.
 
-### v1.1.0 (2026-02-03)
-- Added CLI-based LLM Adapters (Gemini, Claude, Kimi, OpenCode).
-- Implemented Disk Persistence for sessions and agents.
-- Added Task Retry logic in Swarm Coordinator.
-- Updated all tests to support asynchronous operations.
+### v1.1.3 (2026-02-03)
+- **Feature:** Multi-Provider Auto-Fallback.
+- **Feature:** Dynamic Provider Selection per task.
+- **Refactor:** Replaced console logs with structured `Logger`.
 
-### v1.0.0 (2025-02-03)
-- Initial release with core swarm and sequential thinking logic.
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.

package/data/agents/1770106504306-dljh9ef.json

@@ -0,0 +1,68 @@
+{
+  "config": {
+    "id": "1770106504306-dljh9ef",
+    "name": "LogicMaster",
+    "type": "reasoner",
+    "subtype": "chain_of_thought",
+    "capabilities": [
+      {
+        "name": "chain_of_thought",
+        "description": "Step-by-step reasoning",
+        "confidence": 0.9,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "tree_of_thought",
+        "description": "Explore multiple reasoning paths",
+        "confidence": 0.85,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "analogical_reasoning",
+        "description": "Reason by analogy",
+        "confidence": 0.8,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "abductive_reasoning",
+        "description": "Inference to best explanation",
+        "confidence": 0.75,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "problem_solving",
+        "description": "General problem-solving",
+        "confidence": 0.8,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      }
+    ],
+    "maxConcurrentTasks": 3,
+    "confidenceThreshold": 0.7,
+    "metadata": {
+      "createdAt": "2026-02-03T08:15:04.306Z",
+      "version": "1.0.0",
+      "config": {}
+    }
+  },
+  "performanceHistory": []
+}

package/data/agents/1770106504310-4oarrst.json

@@ -0,0 +1,58 @@
+{
+  "config": {
+    "id": "1770106504310-4oarrst",
+    "name": "SafetyCheck",
+    "type": "critic",
+    "subtype": "safety",
+    "capabilities": [
+      {
+        "name": "evaluation",
+        "description": "Evaluate outputs from other agents",
+        "confidence": 0.85,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "validation",
+        "description": "Validate correctness and accuracy",
+        "confidence": 0.8,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "feedback",
+        "description": "Provide constructive feedback",
+        "confidence": 0.9,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "logical_analysis",
+        "description": "Analyze logical consistency",
+        "confidence": 0.85,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      }
+    ],
+    "maxConcurrentTasks": 5,
+    "confidenceThreshold": 0.7,
+    "metadata": {
+      "createdAt": "2026-02-03T08:15:04.310Z",
+      "version": "1.0.0",
+      "config": {}
+    }
+  },
+  "performanceHistory": []
+}

package/data/agents/1770106540588-pvitt55.json

@@ -0,0 +1,68 @@
+{
+  "config": {
+    "id": "1770106540588-pvitt55",
+    "name": "LogicMaster",
+    "type": "reasoner",
+    "subtype": "chain_of_thought",
+    "capabilities": [
+      {
+        "name": "chain_of_thought",
+        "description": "Step-by-step reasoning",
+        "confidence": 0.9,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "tree_of_thought",
+        "description": "Explore multiple reasoning paths",
+        "confidence": 0.85,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "analogical_reasoning",
+        "description": "Reason by analogy",
+        "confidence": 0.8,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "abductive_reasoning",
+        "description": "Inference to best explanation",
+        "confidence": 0.75,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "problem_solving",
+        "description": "General problem-solving",
+        "confidence": 0.8,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      }
+    ],
+    "maxConcurrentTasks": 3,
+    "confidenceThreshold": 0.7,
+    "metadata": {
+      "createdAt": "2026-02-03T08:15:40.588Z",
+      "version": "1.0.0",
+      "config": {}
+    }
+  },
+  "performanceHistory": []
+}

package/data/agents/1770106540595-z2ya871.json

@@ -0,0 +1,58 @@
+{
+  "config": {
+    "id": "1770106540595-z2ya871",
+    "name": "SafetyCheck",
+    "type": "critic",
+    "subtype": "safety",
+    "capabilities": [
+      {
+        "name": "evaluation",
+        "description": "Evaluate outputs from other agents",
+        "confidence": 0.85,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "validation",
+        "description": "Validate correctness and accuracy",
+        "confidence": 0.8,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "feedback",
+        "description": "Provide constructive feedback",
+        "confidence": 0.9,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "logical_analysis",
+        "description": "Analyze logical consistency",
+        "confidence": 0.85,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      }
+    ],
+    "maxConcurrentTasks": 5,
+    "confidenceThreshold": 0.7,
+    "metadata": {
+      "createdAt": "2026-02-03T08:15:40.595Z",
+      "version": "1.0.0",
+      "config": {}
+    }
+  },
+  "performanceHistory": []
+}

package/data/agents/1770106710890-0e2naq1.json

@@ -0,0 +1,68 @@
+{
+  "config": {
+    "id": "1770106710890-0e2naq1",
+    "name": "LogicMaster",
+    "type": "reasoner",
+    "subtype": "chain_of_thought",
+    "capabilities": [
+      {
+        "name": "chain_of_thought",
+        "description": "Step-by-step reasoning",
+        "confidence": 0.9,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "tree_of_thought",
+        "description": "Explore multiple reasoning paths",
+        "confidence": 0.85,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "analogical_reasoning",
+        "description": "Reason by analogy",
+        "confidence": 0.8,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "abductive_reasoning",
+        "description": "Inference to best explanation",
+        "confidence": 0.75,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "problem_solving",
+        "description": "General problem-solving",
+        "confidence": 0.8,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      }
+    ],
+    "maxConcurrentTasks": 3,
+    "confidenceThreshold": 0.7,
+    "metadata": {
+      "createdAt": "2026-02-03T08:18:30.890Z",
+      "version": "1.0.0",
+      "config": {}
+    }
+  },
+  "performanceHistory": []
+}

package/data/agents/1770106710893-r076yxx.json

@@ -0,0 +1,58 @@
+{
+  "config": {
+    "id": "1770106710893-r076yxx",
+    "name": "SafetyCheck",
+    "type": "critic",
+    "subtype": "safety",
+    "capabilities": [
+      {
+        "name": "evaluation",
+        "description": "Evaluate outputs from other agents",
+        "confidence": 0.85,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "validation",
+        "description": "Validate correctness and accuracy",
+        "confidence": 0.8,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "feedback",
+        "description": "Provide constructive feedback",
+        "confidence": 0.9,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "logical_analysis",
+        "description": "Analyze logical consistency",
+        "confidence": 0.85,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      }
+    ],
+    "maxConcurrentTasks": 5,
+    "confidenceThreshold": 0.7,
+    "metadata": {
+      "createdAt": "2026-02-03T08:18:30.893Z",
+      "version": "1.0.0",
+      "config": {}
+    }
+  },
+  "performanceHistory": []
+}

package/data/agents/1770109212161-4ybd0i7.json

@@ -0,0 +1,68 @@
+{
+  "config": {
+    "id": "1770109212161-4ybd0i7",
+    "name": "LogicMaster",
+    "type": "reasoner",
+    "subtype": "chain_of_thought",
+    "capabilities": [
+      {
+        "name": "chain_of_thought",
+        "description": "Step-by-step reasoning",
+        "confidence": 0.9,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "tree_of_thought",
+        "description": "Explore multiple reasoning paths",
+        "confidence": 0.85,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "analogical_reasoning",
+        "description": "Reason by analogy",
+        "confidence": 0.8,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "abductive_reasoning",
+        "description": "Inference to best explanation",
+        "confidence": 0.75,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      },
+      {
+        "name": "problem_solving",
+        "description": "General problem-solving",
+        "confidence": 0.8,
+        "performanceMetrics": {
+          "tasksCompleted": 0,
+          "averageQuality": 0,
+          "averageTimeMs": 0
+        }
+      }
+    ],
+    "maxConcurrentTasks": 3,
+    "confidenceThreshold": 0.7,
+    "metadata": {
+      "createdAt": "2026-02-03T09:00:12.161Z",
+      "version": "1.0.0",
+      "config": {}
+    }
+  },
+  "performanceHistory": []
+}