@gotza02/seq-thinking 1.1.0

package/README.md

@@ -0,0 +1,149 @@
+# 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)
+[![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.
+
+## Overview
+
+This system provides advanced sequential thinking capabilities with:
+
+- **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
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/mcp-sequential-thinking.git
+cd mcp-sequential-thinking
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+```
+
+## Configuration (MCP JSON)
+
+Add this to your MCP settings file (e.g., `claude_desktop_config.json`, `gemini-cli.json`, or Kimi's `mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "advanced-thinking": {
+      "command": "node",
+      "args": ["/absolute/path/to/dist/mcp-server.js"],
+      "env": {
+        "provider": "gemini", 
+        "MOCK_LLM": "false"
+      }
+    }
+  }
+}
+```
+
+### 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` |
+
+## Persistence
+
+Thinking sessions are automatically persisted to the `./data` directory. 
+- **Sessions**: Stored in `./data/sessions/`
+- **Agents**: Stored in `./data/agents/`
+
+This ensures that your reasoning state is preserved even if the MCP server restarts.
+
+## Enhanced Swarm Logic
+
+- **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.
+
+## API Documentation
+
+*(Standard Sequential Thinking and Swarm Coordination operations are supported as documented in the internal tool definitions)*
+
+## Testing
+
+```bash
+# Run tests with mock LLM responses
+export MOCK_LLM=true
+npm test
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## Changelog
+
+### 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.0.0 (2025-02-03)
+- Initial release with core swarm and sequential thinking logic.

package/SYSTEM_INSTRUCTIONS.md

@@ -0,0 +1,50 @@
+# AI System Instructions for MCP Sequential Thinking
+
+This document provides instructions for AI models (like Gemini or Claude) on how to effectively utilize this MCP server to solve complex problems.
+
+## 1. When to Use These Tools
+
+You should invoke the `advanced_sequential_thinking` tool when:
+- The user's request is complex, ambiguous, or requires multi-step planning.
+- You need to explore multiple hypotheses or alternative solutions.
+- You need to perform self-correction or verify your own reasoning.
+- The task requires a "System 2" thinking approach (deliberative and analytical).
+
+## 2. Decision Logic for Tools
+
+| tool | Use Case |
+|------|----------|
+| `advanced_sequential_thinking` | Core reasoning, branching, and meta-reflection. |
+| `swarm_agent_coordination` | Delegating specific sub-tasks to specialized agents (e.g., Fact-checking, Code Critique). |
+
+## 3. Recommended Workflow
+
+### Phase A: Initialization
+1.  **Initialize**: Create a session with a clear `topic`.
+2.  **Adjust Granularity**: Check if the topic is complex enough to require high detail.
+
+### Phase B: Iterative Reasoning
+1.  **Add Thoughts**: Progress step-by-step. Use `thoughtType` (analysis, hypothesis, etc.) correctly.
+2.  **Branching**: If you reach a decision point with multiple viable paths, use `branch_thought` to explore them in parallel.
+3.  **Self-Correction**: Periodically call `self_correct` or `add_meta_thought` to reflect on your progress.
+
+### Phase C: Swarm Delegation (Optional)
+1.  **Register Agents**: If you need specialized help, register a `critic` or `reasoner`.
+2.  **Delegate**: Use `delegate_to_swarm` to let another "brain" analyze a specific thought.
+3.  **Consensus**: Use `reach_consensus` if multiple agents have different outputs.
+
+### Phase D: Conclusion
+1.  **Merge**: Combine successful branches using `merge_branches`.
+2.  **Complete**: Finalize the session and present the consolidated result to the user.
+
+## 4. Best Practices for the AI
+
+- **Maintain Context**: Keep track of the `sessionId`. Use it for all related thoughts.
+- **Calibrate Confidence**: Be honest about confidence levels. If confidence drops below 0.5, explicitly use a `self_correction` thought.
+- **Label Everything**: Use `tags` and `thoughtType` diligently. This helps the system (and the user) understand your mental map.
+- **Meta-Reflection**: Don't just think; think about *how* you are thinking. If you get stuck, use `add_meta_thought` to analyze the pattern.
+
+## 5. System Prompt Template
+
+When using this MCP server, you may internalize this instruction:
+> "I will use the Sequential Thinking MCP to map out my reasoning process. I will treat complex problems as a graph of thoughts, allowing myself to branch, backtrack, and consult specialized swarm agents when needed to ensure the highest quality output."

package/agents_test.log

@@ -0,0 +1,15 @@
+✖ dist/__tests__/agents.test.js (9856.244616ms)
+ℹ tests 1
+ℹ suites 0
+ℹ pass 0
+ℹ fail 0
+ℹ cancelled 1
+ℹ skipped 0
+ℹ todo 0
+ℹ duration_ms 9872.053462
+
+✖ failing tests:
+
+test at dist/__tests__/agents.test.js:1:1
+✖ dist/__tests__/agents.test.js (9856.244616ms)
+  'Promise resolution is still pending but the event loop has already resolved'

package/dist/__tests__/agents.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agents.test.d.ts.map

package/dist/__tests__/agents.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/agents.test.ts"],"names":[],"mappings":""}