Sequential Thinking Multi-Agent System (MAS)

English | 简体中文

This project implements an advanced sequential thinking process using a Multi-Agent System (MAS) built with the Agno framework and served via MCP. It represents a significant evolution from simpler state-tracking approaches by leveraging coordinated, specialized agents for deeper analysis and problem decomposition.

What is This?

This is an MCP server - not a standalone application. It runs as a background service that extends your LLM client (like Claude Desktop) with sophisticated sequential thinking capabilities. The server provides a sequentialthinking tool that processes thoughts through multiple specialized AI agents, each examining the problem from a different cognitive angle.

Core Architecture: Multi-Dimensional Thinking Agents

The system employs 6 specialized thinking agents, each focused on a distinct cognitive perspective:

1. Factual Agent

Focus: Objective facts and verified data
Approach: Analytical, evidence-based reasoning
Capabilities:
- Web research for current facts (via ExaTools)
- Data verification and source citation
- Information gap identification
Time allocation: 120 seconds for thorough analysis

2. Emotional Agent

Focus: Intuition and emotional intelligence
Approach: Gut reactions and feelings
Capabilities:
- Quick intuitive responses (30-second snapshots)
- Visceral reactions without justification
- Emotional pattern recognition
Time allocation: 30 seconds (quick reaction mode)

3. Critical Agent

Focus: Risk assessment and problem identification
Approach: Logical scrutiny and devil's advocate
Capabilities:
- Research counterexamples and failures (via ExaTools)
- Identify logical flaws and risks
- Challenge assumptions constructively
Time allocation: 120 seconds for deep analysis

4. Optimistic Agent

Focus: Benefits, opportunities, and value
Approach: Positive exploration with realistic grounding
Capabilities:
- Research success stories (via ExaTools)
- Identify feasible opportunities
- Explore best-case scenarios logically
Time allocation: 120 seconds for balanced optimism

5. Creative Agent

Focus: Innovation and alternative solutions
Approach: Lateral thinking and idea generation
Capabilities:
- Cross-industry innovation research (via ExaTools)
- Divergent thinking techniques
- Multiple solution generation
Time allocation: 240 seconds (creativity needs time)

6. Synthesis Agent

Focus: Integration and metacognitive orchestration
Approach: Holistic synthesis and final answer generation
Capabilities:
- Integrate all perspectives into coherent response
- Answer the original question directly
- Provide actionable, user-friendly insights
Time allocation: 60 seconds for synthesis
Note: Uses enhanced model, does NOT include ExaTools (focuses on integration)

AI-Powered Intelligent Routing

The system uses AI-driven complexity analysis to determine the optimal thinking sequence:

Processing Strategies:

Single Agent (Simple questions)
- Direct factual or emotional response
- Fastest processing for straightforward queries
Double Agent (Moderate complexity)
- Two-step sequences (e.g., Optimistic → Critical)
- Balanced perspectives for evaluation tasks
Triple Agent (Core thinking)
- Factual → Creative → Synthesis
- Philosophical and analytical problems
Full Sequence (Complex problems)
- All 6 agents orchestrated together
- Comprehensive multi-perspective analysis

The AI analyzer evaluates:

Problem complexity and semantic depth
Primary problem type (factual, emotional, creative, philosophical, etc.)
Required thinking modes for optimal solution
Appropriate model selection (Enhanced vs Standard)

AI Routing Flow Diagram

flowchart TD
    A[Input Thought] --> B[AI Complexity Analyzer]

    B --> C{Problem Analysis}
    C --> C1[Complexity Score<br/>0-100]
    C --> C2[Problem Type<br/>FACTUAL/EMOTIONAL/<br/>CREATIVE/PHILOSOPHICAL]
    C --> C3[Required Thinking Modes]

    C1 --> D{Routing Decision}
    C2 --> D
    C3 --> D

    D -->|Score: 0-25<br/>Simple| E1[Single Agent Strategy]
    D -->|Score: 26-50<br/>Moderate| E2[Double Agent Strategy]
    D -->|Score: 51-75<br/>Complex| E3[Triple Agent Strategy]
    D -->|Score: 76-100<br/>Highly Complex| E4[Full Sequence Strategy]

    %% Single Agent Flow
    E1 --> F1[Factual Agent<br/>120s + ExaTools]
    F1 --> G1[Direct Response]

    %% Double Agent Flow (Full Parallel)
    E2 --> DA1[Both Agents Run in Parallel]
    DA1 --> DA2["Agent 1 e.g. Optimistic<br/>120s + ExaTools"]
    DA1 --> DA3["Agent 2 e.g. Critical<br/>120s + ExaTools"]
    DA2 --> G2[Programmatic Synthesis<br/>Combines both parallel results]
    DA3 --> G2

    %% Triple Agent Flow (Full Parallel)
    E3 --> TA1[All 3 Agents Run in Parallel]
    TA1 --> TA2[Factual Agent<br/>120s + ExaTools]
    TA1 --> TA3[Creative Agent<br/>240s + ExaTools]
    TA1 --> TA4[Critical Agent<br/>120s + ExaTools]
    TA2 --> G3[Programmatic Synthesis<br/>Integrates all 3 results]
    TA3 --> G3
    TA4 --> G3

    %% Full Sequence Flow (3-Step Process)
    E4 --> FS1[Step 1: Initial Synthesis<br/>60s Enhanced Model<br/>Initial orchestration]
    FS1 --> FS2[Step 2: Parallel Execution<br/>5 Agents Run Simultaneously]

    FS2 --> FS2A[Factual Agent<br/>120s + ExaTools]
    FS2 --> FS2B[Emotional Agent<br/>30s Quick Response]
    FS2 --> FS2C[Optimistic Agent<br/>120s + ExaTools]
    FS2 --> FS2D[Critical Agent<br/>120s + ExaTools]
    FS2 --> FS2E[Creative Agent<br/>240s + ExaTools]

    FS2A --> FS3[Step 3: Final Synthesis<br/>60s Enhanced Model<br/>Integrates all parallel results]
    FS2B --> FS3
    FS2C --> FS3
    FS2D --> FS3
    FS2E --> FS3

    FS3 --> G4[Final Synthesis Output<br/>Comprehensive integrated result]

    G1 --> H[Next Iteration or<br/>Final Answer]
    G2 --> H
    G3 --> H
    G4 --> H

    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#fff3e0
    style D fill:#e8f5e8
    style TA1 fill:#ffecb3
    style FS2 fill:#ffecb3
    style G1 fill:#fce4ec
    style G2 fill:#fce4ec
    style G3 fill:#fce4ec
    style G4 fill:#fce4ec
    style H fill:#f1f8e9

Key Insights:

Parallel Execution: Non-synthesis agents run simultaneously for maximum efficiency
Synthesis Integration: Synthesis agents process parallel results sequentially
Two Processing Types:
- Synthesis Agent: Real AI agent using Enhanced Model for integration
- Programmatic Synthesis: Code-based combination when no Synthesis Agent
Performance: Parallel processing optimizes both speed and quality

Research Capabilities (ExaTools Integration)

4 out of 6 agents are equipped with web research capabilities via ExaTools:

Factual Agent: Search for current facts, statistics, verified data
Critical Agent: Find counterexamples, failed cases, regulatory issues
Optimistic Agent: Research success stories, positive case studies
Creative Agent: Discover innovations across different industries
Emotional & Synthesis Agents: No ExaTools (focused on internal processing)

Research is optional - requires EXA_API_KEY environment variable. The system works perfectly without it, using pure reasoning capabilities.

Model Intelligence

Dual Model Strategy:

Enhanced Model: Used for Synthesis agent (complex integration tasks)
Standard Model: Used for individual thinking agents
AI Selection: System automatically chooses the right model based on task complexity

Supported Providers:

DeepSeek (default) - High performance, cost-effective
Groq - Ultra-fast inference
OpenRouter - Access to multiple models
GitHub Models - OpenAI models via GitHub API
Anthropic - Claude models with prompt caching
Ollama - Local model execution

Key Differences from Original Version (TypeScript)

This Python/Agno implementation marks a fundamental shift from the original TypeScript version:

Feature/Aspect	Python/Agno Version (Current)	TypeScript Version (Original)
Architecture	Multi-Agent System (MAS); Active processing by a team of agents.	Single Class State Tracker; Simple logging/storing.
Intelligence	Distributed Agent Logic; Embedded in specialized agents & Coordinator.	External LLM Only; No internal intelligence.
Processing	Active Analysis & Synthesis; Agents act on the thought.	Passive Logging; Merely recorded the thought.
Frameworks	Agno (MAS) + FastMCP (Server); Uses dedicated MAS library.	MCP SDK only.
Coordination	Explicit Team Coordination Logic (`Team` in `coordinate` mode).	None; No coordination concept.
Validation	Pydantic Schema Validation; Robust data validation.	Basic Type Checks; Less reliable.
External Tools	Integrated (Exa via Researcher); Can perform research tasks.	None.
Logging	Structured Python Logging (File + Console); Configurable.	Console Logging with Chalk; Basic.
Language & Ecosystem	Python; Leverages Python AI/ML ecosystem.	TypeScript/Node.js.

In essence, the system evolved from a passive thought recorder to an active thought processor powered by a collaborative team of AI agents.

How it Works (Multi-Dimensional Processing)

Initiation: An external LLM uses the sequentialthinking tool to define the problem and initiate the process.
Tool Call: The LLM calls the sequentialthinking tool with the current thought, structured according to the ThoughtData model.
AI Complexity Analysis: The system uses AI-powered analysis to determine the optimal thinking sequence based on problem complexity and type.
Agent Routing: Based on the analysis, the system routes the thought to the appropriate thinking agents (single, double, triple, or full sequence).
Parallel Processing: Multiple thinking agents process the thought simultaneously from their specialized perspectives:

Factual agents gather objective data (with optional web research)
Critical agents identify risks and problems
Optimistic agents explore opportunities and benefits
Creative agents generate innovative solutions
Emotional agents provide intuitive insights

Research Integration: Agents equipped with ExaTools conduct targeted web research to enhance their analysis.
Synthesis & Integration: The Synthesis agent integrates all perspectives into a coherent, actionable response using enhanced models.
Response Generation: The system returns a comprehensive analysis with guidance for next steps.
Iteration: The calling LLM uses the synthesized response to formulate the next thinking step or conclude the process.

Token Consumption Warning

High Token Usage: Due to the Multi-Agent System architecture, this tool consumes significantly more tokens than single-agent alternatives or the previous TypeScript version. Each sequentialthinking call invokes multiple specialized agents simultaneously, leading to substantially higher token usage (potentially 5-10x more than simple approaches).

This parallel processing leads to substantially higher token usage (potentially 5-10x more) compared to simpler sequential approaches, but provides correspondingly deeper and more comprehensive analysis.

MCP Tool: `sequentialthinking`

The server exposes a single MCP tool that processes sequential thoughts:

Parameters:

{
  thought: string,              // Current thinking step content
  thoughtNumber: number,         // Sequence number (≥1)
  totalThoughts: number,         // Estimated total steps
  nextThoughtNeeded: boolean,    // Is another step required?
  isRevision: boolean,           // Revising previous thought?
  branchFromThought?: number,    // Branch point (for exploration)
  branchId?: string,             // Branch identifier
  needsMoreThoughts: boolean     // Need to extend sequence?
}

Response:

Returns synthesized analysis from the multi-agent system with:

Processed thought analysis
Guidance for next steps
Branch and revision tracking
Status and metadata

Installation

Prerequisites

Python 3.10+
LLM API access (choose one):
- DeepSeek: DEEPSEEK_API_KEY (default, recommended)
- Groq: GROQ_API_KEY
- OpenRouter: OPENROUTER_API_KEY
- GitHub Models: GITHUB_TOKEN
- Anthropic: ANTHROPIC_API_KEY
- Ollama: Local installation (no API key)
Optional: EXA_API_KEY for web research capabilities
uv package manager (recommended) or pip

Quick Start

1. Install via Smithery (Recommended)

npx -y @smithery/cli install @FradSer/mcp-server-mas-sequential-thinking --client claude

2. Manual Installation

# Clone the repository
git clone https://github.com/FradSer/mcp-server-mas-sequential-thinking.git
cd mcp-server-mas-sequential-thinking

# Install with uv (recommended)
uv pip install .

# Or with pip
pip install .

Configuration

For MCP Clients (Claude Desktop, etc.)

Add to your MCP client configuration:

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "mcp-server-mas-sequential-thinking",
      "env": {
        "LLM_PROVIDER": "deepseek",
        "DEEPSEEK_API_KEY": "your_api_key",
        "EXA_API_KEY": "your_exa_key_optional"
      }
    }
  }
}

Environment Variables

Create a .env file or set these variables:

# LLM Provider (required)
LLM_PROVIDER="deepseek"  # deepseek, groq, openrouter, github, anthropic, ollama
DEEPSEEK_API_KEY="sk-..."

# Optional: Enhanced/Standard Model Selection
# DEEPSEEK_ENHANCED_MODEL_ID="deepseek-chat"  # For synthesis
# DEEPSEEK_STANDARD_MODEL_ID="deepseek-chat"  # For other agents

# Optional: Web Research (enables ExaTools)
# EXA_API_KEY="your_exa_api_key"

# Optional: Custom endpoint
# LLM_BASE_URL="https://custom-endpoint.com"

Model Configuration Examples

# Groq with different models
GROQ_ENHANCED_MODEL_ID="openai/gpt-oss-120b"
GROQ_STANDARD_MODEL_ID="openai/gpt-oss-20b"

# Anthropic with Claude models
ANTHROPIC_ENHANCED_MODEL_ID="claude-3-5-sonnet-20241022"
ANTHROPIC_STANDARD_MODEL_ID="claude-3-5-haiku-20241022"

# GitHub Models
GITHUB_ENHANCED_MODEL_ID="gpt-4o"
GITHUB_STANDARD_MODEL_ID="gpt-4o-mini"

Usage

As MCP Server

Once installed and configured in your MCP client:

The sequentialthinking tool becomes available
Your LLM can use it to process complex thoughts
The system automatically routes to appropriate thinking agents
Results are synthesized and returned to your LLM

Direct Execution

Run the server manually for testing:

# Using installed script
mcp-server-mas-sequential-thinking

# Using uv
uv run mcp-server-mas-sequential-thinking

# Using Python
python src/mcp_server_mas_sequential_thinking/main.py

Development

Setup

# Clone repository
git clone https://github.com/FradSer/mcp-server-mas-sequential-thinking.git
cd mcp-server-mas-sequential-thinking

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install with dev dependencies
uv pip install -e ".[dev]"

Code Quality

# Format and lint
uv run ruff check . --fix
uv run ruff format .
uv run mypy .

# Run tests (when available)
uv run pytest

Testing with MCP Inspector

npx @modelcontextprotocol/inspector uv run mcp-server-mas-sequential-thinking

Open http://127.0.0.1:6274/ and test the sequentialthinking tool.

System Characteristics

Strengths:

Multi-perspective analysis: 6 different cognitive approaches
AI-powered routing: Intelligent complexity analysis
Research capabilities: 4 agents with web search (optional)
Flexible processing: Single to full sequence strategies
Model optimization: Enhanced/Standard model selection
Provider agnostic: Works with multiple LLM providers

Considerations:

Token usage: Multi-agent processing uses more tokens than single-agent
Processing time: Complex sequences take longer but provide deeper insights
API costs: Research capabilities require separate Exa API subscription
Model selection: Enhanced models cost more but provide better synthesis

Project Structure

mcp-server-mas-sequential-thinking/
├── src/mcp_server_mas_sequential_thinking/
│   ├── main.py                          # MCP server entry point
│   ├── processors/
│   │   ├── multi_thinking_core.py       # 6 thinking agents definition
│   │   └── multi_thinking_processor.py  # Sequential processing logic
│   ├── routing/
│   │   ├── ai_complexity_analyzer.py    # AI-powered analysis
│   │   └── multi_thinking_router.py     # Intelligent routing
│   ├── services/
│   │   ├── thought_processor_refactored.py
│   │   ├── workflow_executor.py
│   │   └── context_builder.py
│   └── config/
│       ├── modernized_config.py         # Provider strategies
│       └── constants.py                 # System constants
├── pyproject.toml                       # Project configuration
└── README.md                            # This file

Changelog

See CHANGELOG.md for version history.

Contributing

Contributions are welcome! Please ensure:

Code follows project style (ruff, mypy)
Commit messages use conventional commits format
All tests pass before submitting PR
Documentation is updated as needed

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Built with Agno v2.0+ framework
Model Context Protocol by Anthropic
Research capabilities powered by Exa (optional)
Multi-dimensional thinking inspired by Edward de Bono's work

Support

GitHub Issues: Report bugs or request features
Documentation: Check CLAUDE.md for detailed implementation notes
MCP Protocol: Official MCP Documentation

Note: This is an MCP server, designed to work with MCP-compatible clients like Claude Desktop. It is not a standalone chat application.