An advanced Model Context Protocol (MCP) server that implements reflective sequential thinking through a dual-team multi-agent system. This tool enables AI models to engage in sophisticated, structured thinking with self-reflection and intelligent tool selection.
- Dual-Team Architecture: Primary thinking team + reflection team for meta-analysis
- Async-Native Design: Custom team coordination without asyncio.run() conflicts
- Intelligent Tool Selection: Built-in tool recommendation engine with confidence scoring
- Reflective Reasoning: Meta-analysis of thinking processes with quality assessment
- Branching & Revision Support: Non-linear thinking with thought revision capabilities
- Circuit Breaker Pattern: Fault tolerance with graceful degradation
- In-Memory Context: Lightweight shared context (no persistence by design)
┌─────────────────────────────────────────────────────────────┐
│ MCP Client (LLM) │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ FastMCP Server │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Reflective Thinking Tool │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ │ │
│ │ │ Primary Team │ │ Reflection Team │ │ │
│ │ │ • Planner │ │ • MetaAnalyzer │ │ │
│ │ │ • Researcher │ │ • PatternRecog │ │ │
│ │ │ • Analyzer │ │ • QualityAssess │ │ │
│ │ │ • Critic │ │ • DecisionCrit │ │ │
│ │ │ • Synthesizer │ │ │ │ │
│ │ └─────────────────┘ └─────────────────┘ │ │
│ │ │ │ │ │
│ │ └──────────┬───────────┘ │ │
│ │ ▼ │ │
│ │ Shared Context │ │
│ │ (In-Memory State Management) │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
- Python 3.13 or higher
- An API key for one of the supported LLM providers:
- OpenAI (recommended)
- OpenRouter
- Google Gemini
- Groq
-
Clone the repository:
git clone https://github.com/yourusername/reflective-sequential-thinking-mcp.git cd reflective-sequential-thinking-mcp -
Install dependencies with uv (recommended):
# Install uv if you haven't already curl -LsSf https://astral.sh/uv/install.sh | sh # Install project dependencies uv pip install -e ".[dev]"
-
Set up environment variables:
# Create .env file cat > .env << EOF # LLM Provider Configuration REFLECTIVE_LLM_PROVIDER=openai # or: openrouter, gemini, groq OPENAI_API_KEY=your_openai_api_key # Model IDs (optional - defaults provided) OPENAI_TEAM_MODEL_ID=gpt-4-turbo OPENAI_AGENT_MODEL_ID=gpt-4-mini EOF
-
Run the MCP server:
uv run python src/main.py
The server runs in stdio mode by default, communicating via standard input/output as required by the MCP protocol.
Main tool for processing thoughts through the dual-team system.
@mcp.tool()
async def reflectivethinking(thought_data: ThoughtData) -> str:
"""Process a thought through primary and reflection teams."""Parameters:
thought: The thought content (min 10 characters)thoughtNumber: Current thought number (≥1)totalThoughts: Total estimated thoughts (≥5)nextThoughtNeeded: Whether more thoughts are neededdomain: Domain type (general, technical, creative, analytical, strategic)- Additional optional parameters for revision, branching, etc.
Intelligent tool selection based on thought content and context.
@mcp.tool()
async def toolselectthinking(
thought: str,
available_tools: Optional[List[str]] = None,
domain: str = "general",
context: Optional[Dict[str, Any]] = None
) -> str:
"""Get tool recommendations for a given thought."""Review and analyze a sequence of thoughts from the current session.
@mcp.tool()
async def reflectivereview(
session_id: Optional[str] = None,
branch_id: Optional[str] = None,
min_quality_threshold: float = 0.0
) -> str:
"""Review thought sequence with quality analysis."""The server provides four pre-configured prompts:
sequential-thinking: Starter prompt for sequential thinkingtool-selection: Guide for intelligent tool selectionthought-review: Template for reviewing thought sequencescomplex-problem: Advanced prompt for complex problem-solving
# LLM Provider Selection
REFLECTIVE_LLM_PROVIDER=openai # Options: openai, openrouter, gemini, groq
# Provider-specific API Keys
OPENAI_API_KEY=your_key
OPENROUTER_API_KEY=your_key
GOOGLE_API_KEY=your_key
GROQ_API_KEY=your_key
# Model Configuration (optional)
OPENAI_TEAM_MODEL_ID=gpt-4-turbo # For team coordination
OPENAI_AGENT_MODEL_ID=gpt-4-mini # For individual agents
# Advanced Settings
ENABLE_REFLECTION=true # Enable/disable reflection team
REFLECTION_DELAY_MS=500 # Delay before reflection starts
MAX_CONTEXT_ITEMS=100 # Maximum items in shared contextThe server operates in stdio mode (standard input/output) which is the default for MCP servers.
For Claude Desktop or other MCP clients:
{
"mcpServers": {
"reflective-thinking": {
"command": "uv",
"args": ["--directory", "/path/to/project", "run", "python", "src/main.py"],
"env": {
"REFLECTIVE_LLM_PROVIDER": "openai",
"OPENAI_API_KEY": "your_api_key"
}
}
}
}# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov=src --cov-report=html
# Run specific test file
uv run pytest tests/test_thought_models.py -v# Run all checks (recommended before commits)
uv run ruff check . --fix && uv run ruff format . && uv run pyright .- ✅ 88 tests passing
- 🔧 35 tests need updates for AsyncTeam migration
- 📊 Core functionality fully operational
-
"Empty response from team"
- Cause: Model API issues or timeout
- Solution: Check API keys and network connectivity
-
Validation errors on thoughts
- Cause: Thoughts too short or invalid parameters
- Solution: Ensure thoughts are ≥10 characters, totalThoughts ≥5
-
High token usage
- Cause: Dual-team architecture processes each thought multiple times
- Solution: This is by design for quality; adjust models if needed
This project is licensed under the MIT License.