{"id":29015424,"url":"https://github.com/fradser/mcp-server-mas-sequential-thinking","last_synced_at":"2026-02-02T08:53:21.605Z","repository":{"id":285975874,"uuid":"959358539","full_name":"FradSer/mcp-server-mas-sequential-thinking","owner":"FradSer","description":"An advanced sequential thinking process using a Multi-Agent System (MAS) built with the Agno framework and served via MCP.","archived":false,"fork":false,"pushed_at":"2025-04-30T08:50:03.000Z","size":301,"stargazers_count":191,"open_issues_count":2,"forks_count":20,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-17T13:12:56.340Z","etag":null,"topics":["agno","mcp","mcp-server","sequential-thinking"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FradSer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-02T16:59:22.000Z","updated_at":"2025-06-17T04:08:25.000Z","dependencies_parsed_at":"2025-04-22T11:03:26.326Z","dependency_job_id":"f05e84dc-b4ad-4c45-b224-81574f2a081b","html_url":"https://github.com/FradSer/mcp-server-mas-sequential-thinking","commit_stats":null,"previous_names":["fradser/mcp-server-mas-sequential-thinking"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/FradSer/mcp-server-mas-sequential-thinking","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FradSer%2Fmcp-server-mas-sequential-thinking","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FradSer%2Fmcp-server-mas-sequential-thinking/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FradSer%2Fmcp-server-mas-sequential-thinking/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FradSer%2Fmcp-server-mas-sequential-thinking/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FradSer","download_url":"https://codeload.github.com/FradSer/mcp-server-mas-sequential-thinking/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FradSer%2Fmcp-server-mas-sequential-thinking/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261953214,"owners_count":23235457,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agno","mcp","mcp-server","sequential-thinking"],"created_at":"2025-06-25T21:06:57.604Z","updated_at":"2026-02-02T08:53:21.599Z","avatar_url":"https://github.com/FradSer.png","language":"Python","funding_links":[],"categories":["Other Tools and Integrations"],"sub_categories":["How to Submit"],"readme":"# Sequential Thinking Multi-Agent System (MAS) ![](https://img.shields.io/badge/A%20FRAD%20PRODUCT-WIP-yellow)\n\n[![smithery badge](https://smithery.ai/badge/@FradSer/mcp-server-mas-sequential-thinking)](https://smithery.ai/server/@FradSer/mcp-server-mas-sequential-thinking) [![Twitter Follow](https://img.shields.io/twitter/follow/FradSer?style=social)](https://twitter.com/FradSer) [![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/) [![Framework](https://img.shields.io/badge/Framework-Agno-orange.svg)](https://github.com/cognitivecomputations/agno)\n\nEnglish | [简体中文](README.zh-CN.md)\n\nThis 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.\n\n[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/fradser-mcp-server-mas-sequential-thinking-badge.png)](https://mseep.ai/app/fradser-mcp-server-mas-sequential-thinking)\n\n## What is This?\n\nThis 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.\n\n## Core Architecture: Multi-Dimensional Thinking Agents\n\nThe system employs **6 specialized thinking agents**, each focused on a distinct cognitive perspective:\n\n### 1. **Factual Agent**\n- **Focus**: Objective facts and verified data\n- **Approach**: Analytical, evidence-based reasoning\n- **Capabilities**:\n  - Web research for current facts (via ExaTools)\n  - Data verification and source citation\n  - Information gap identification\n- **Time allocation**: 120 seconds for thorough analysis\n\n### 2. **Emotional Agent**\n- **Focus**: Intuition and emotional intelligence\n- **Approach**: Gut reactions and feelings\n- **Capabilities**:\n  - Quick intuitive responses (30-second snapshots)\n  - Visceral reactions without justification\n  - Emotional pattern recognition\n- **Time allocation**: 30 seconds (quick reaction mode)\n\n### 3. **Critical Agent**\n- **Focus**: Risk assessment and problem identification\n- **Approach**: Logical scrutiny and devil's advocate\n- **Capabilities**:\n  - Research counterexamples and failures (via ExaTools)\n  - Identify logical flaws and risks\n  - Challenge assumptions constructively\n- **Time allocation**: 120 seconds for deep analysis\n\n### 4. **Optimistic Agent**\n- **Focus**: Benefits, opportunities, and value\n- **Approach**: Positive exploration with realistic grounding\n- **Capabilities**:\n  - Research success stories (via ExaTools)\n  - Identify feasible opportunities\n  - Explore best-case scenarios logically\n- **Time allocation**: 120 seconds for balanced optimism\n\n### 5. **Creative Agent**\n- **Focus**: Innovation and alternative solutions\n- **Approach**: Lateral thinking and idea generation\n- **Capabilities**:\n  - Cross-industry innovation research (via ExaTools)\n  - Divergent thinking techniques\n  - Multiple solution generation\n- **Time allocation**: 240 seconds (creativity needs time)\n\n### 6. **Synthesis Agent**\n- **Focus**: Integration and metacognitive orchestration\n- **Approach**: Holistic synthesis and final answer generation\n- **Capabilities**:\n  - Integrate all perspectives into coherent response\n  - Answer the original question directly\n  - Provide actionable, user-friendly insights\n- **Time allocation**: 60 seconds for synthesis\n- **Note**: Uses enhanced model, does NOT include ExaTools (focuses on integration)\n\n## AI-Powered Intelligent Routing\n\nThe system uses **AI-driven complexity analysis** to determine the optimal thinking sequence:\n\n### Processing Strategy:\n- **Single fixed strategy**: `full_exploration` is mandatory for all requests\n- **No legacy modes**: single/double/triple routing paths are removed\n- **Complexity analysis retained**: metrics are still generated for observability\n\nThe AI analyzer still evaluates:\n- Problem complexity and semantic depth\n- Primary problem type (factual, emotional, creative, philosophical, etc.)\n- Required thinking modes for observability and diagnostics\n- Model behavior metadata (Enhanced vs Standard usage)\n\n### AI Routing Flow Diagram\n\n```mermaid\nflowchart TD\n    A[Input Thought] --\u003e B[AI Complexity Analyzer]\n    B --\u003e C[Complexity Metadata Stored]\n    C --\u003e D[Fixed Strategy: full_exploration]\n    D --\u003e E[Step 1: Initial Synthesis]\n    E --\u003e F[Step 2: Parallel Specialist Agents]\n    F --\u003e G[Step 3: Final Synthesis]\n    G --\u003e H[Unified Response]\n```\n\n**Key Insights:**\n- **Deterministic behavior**: every request runs the same full multi-step path\n- **Parallel execution**: non-synthesis agents still run simultaneously\n- **Synthesis integration**: orchestration and final answer are both synthesis-driven\n\n## Research Capabilities (ExaTools Integration)\n\n**4 out of 6 agents** are equipped with web research capabilities via ExaTools:\n\n- **Factual Agent**: Search for current facts, statistics, verified data\n- **Critical Agent**: Find counterexamples, failed cases, regulatory issues\n- **Optimistic Agent**: Research success stories, positive case studies\n- **Creative Agent**: Discover innovations across different industries\n- **Emotional \u0026 Synthesis Agents**: No ExaTools (focused on internal processing)\n\nResearch is **optional** - requires `EXA_API_KEY` environment variable. The system works perfectly without it, using pure reasoning capabilities.\n\n## Model Intelligence\n\n### Dual Model Strategy:\n- **Enhanced Model**: Used for Synthesis agent (complex integration tasks)\n- **Standard Model**: Used for individual thinking agents\n- **AI Selection**: System automatically chooses the right model based on task complexity\n\n### Supported Providers:\n- **DeepSeek** (default) - High performance, cost-effective\n- **Groq** - Ultra-fast inference\n- **OpenRouter** - Access to multiple models\n- **GitHub Models** - OpenAI models via GitHub API\n- **Anthropic** - Claude models with prompt caching\n- **Ollama** - Local model execution\n\n## Key Differences from Original Version (TypeScript)\n\nThis Python/Agno implementation marks a fundamental shift from the original TypeScript version:\n\n| Feature/Aspect      | Python/Agno Version (Current)                                        | TypeScript Version (Original)                        |\n| :------------------ | :------------------------------------------------------------------- | :--------------------------------------------------- |\n| **Architecture**    | **Multi-Agent System (MAS)**; Active processing by a team of agents. | **Single Class State Tracker**; Simple logging/storing. |\n| **Intelligence**    | **Distributed Agent Logic**; Embedded in specialized agents \u0026 Coordinator. | **External LLM Only**; No internal intelligence.     |\n| **Processing**      | **Active Analysis \u0026 Synthesis**; Agents *act* on the thought.      | **Passive Logging**; Merely recorded the thought.    |\n| **Frameworks**      | **Agno (MAS) + FastMCP (Server)**; Uses dedicated MAS library.     | **MCP SDK only**.                                    |\n| **Coordination**    | **Explicit Team Coordination Logic** (`Team` in `coordinate` mode).  | **None**; No coordination concept.                   |\n| **Validation**      | **Pydantic Schema Validation**; Robust data validation.            | **Basic Type Checks**; Less reliable.              |\n| **External Tools**  | **Integrated (Exa via Researcher)**; Can perform research tasks.   | **None**.                                            |\n| **Logging**         | **Structured Python Logging (File + Console)**; Configurable.      | **Console Logging with Chalk**; Basic.             |\n| **Language \u0026 Ecosystem** | **Python**; Leverages Python AI/ML ecosystem.                    | **TypeScript/Node.js**.                              |\n\nIn essence, the system evolved from a passive thought *recorder* to an active thought *processor* powered by a collaborative team of AI agents.\n\n## How it Works (Multi-Dimensional Processing)\n\n1.  **Initiation:** An external LLM uses the `sequentialthinking` tool to define the problem and initiate the process.\n2.  **Tool Call:** The LLM calls the `sequentialthinking` tool with the current thought, structured according to the `ThoughtData` model.\n3.  **AI Complexity Analysis:** The system still performs AI-powered analysis to capture complexity metadata and diagnostic signals.\n4.  **Fixed Strategy Execution:** The system always runs the mandatory `full_exploration` multi-step sequence.\n5.  **Parallel Processing:** Multiple thinking agents process the thought simultaneously from their specialized perspectives:\n   - Factual agents gather objective data (with optional web research)\n   - Critical agents identify risks and problems\n   - Optimistic agents explore opportunities and benefits\n   - Creative agents generate innovative solutions\n   - Emotional agents provide intuitive insights\n6.  **Research Integration:** Agents equipped with ExaTools conduct targeted web research to enhance their analysis.\n7.  **Synthesis \u0026 Integration:** The Synthesis agent integrates all perspectives into a coherent, actionable response using enhanced models.\n8.  **Response Generation:** The system returns a comprehensive analysis with guidance for next steps.\n9.  **Iteration:** The calling LLM uses the synthesized response to formulate the next thinking step or conclude the process.\n\n## Token Consumption Warning\n\n**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).\n\nThis 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.\n\n## MCP Tool: `sequentialthinking`\n\nThe server exposes a single MCP tool that processes sequential thoughts:\n\n### Parameters:\n```typescript\n{\n  thought: string,               // One focused reasoning step\n  thoughtNumber: number,         // 1-based step index; increment each call\n  totalThoughts: number,         // Planned number of steps\n  nextThoughtNeeded: boolean,    // true for intermediate steps, false on final step\n  isRevision: boolean,           // true only when revising earlier conclusions\n  branchFromThought?: number,    // Set with branchId to branch from a prior step\n  branchId?: string,             // Branch identifier (required when branching)\n  needsMoreThoughts: boolean     // true only when extending beyond totalThoughts\n}\n```\n\n### Response:\nThe tool returns both:\n- `content`: human-readable synthesis text\n- `structuredContent`: machine-readable loop control fields\n\n```typescript\n{\n  should_continue: boolean,      // Canonical continuation signal\n  next_thought_number: number?,  // Recommended next thoughtNumber\n  stop_reason: string,           // Why to continue/stop/retry\n  current_thought_number: number,\n  total_thoughts: number,\n  next_call_arguments?: {        // Suggested next-call arguments when applicable\n    thoughtNumber: number,\n    totalThoughts: number,\n    nextThoughtNeeded: boolean,\n    needsMoreThoughts: boolean\n  },\n  parameter_usage: Record\u003cstring, string\u003e\n}\n```\n\n### Call Contract (Important)\n- Use this tool as a **multi-step loop**, not a one-shot call.\n- After every response, read `structuredContent.should_continue`.\n- Continue calling `sequentialthinking` until `should_continue` is `false`.\n- Actively use reflection: when a step is weak or incorrect, send a revision step with `isRevision=true`.\n- Prefer `structuredContent.next_thought_number` and `next_call_arguments` when building the next request.\n\n## Installation\n\n### Prerequisites\n\n- Python 3.10+\n- LLM API access (choose one):\n    - **DeepSeek**: `DEEPSEEK_API_KEY` (default, recommended)\n    - **Groq**: `GROQ_API_KEY`\n    - **OpenRouter**: `OPENROUTER_API_KEY`\n    - **GitHub Models**: `GITHUB_TOKEN`\n    - **Anthropic**: `ANTHROPIC_API_KEY`\n    - **Ollama**: Local installation (no API key)\n- **Optional**: `EXA_API_KEY` for web research capabilities\n- `uv` package manager (recommended) or `pip`\n\n### Quick Start\n\n#### 1. Install via Smithery (Recommended)\n\n```bash\nnpx -y @smithery/cli install @FradSer/mcp-server-mas-sequential-thinking --client claude\n```\n\n#### 2. Manual Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/FradSer/mcp-server-mas-sequential-thinking.git\ncd mcp-server-mas-sequential-thinking\n\n# Install with uv (recommended)\nuv pip install .\n\n# Or with pip\npip install .\n```\n\n### Configuration\n\n#### For MCP Clients (Claude Desktop, etc.)\n\nAdd to your MCP client configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"sequential-thinking\": {\n      \"command\": \"mcp-server-mas-sequential-thinking\",\n      \"env\": {\n        \"LLM_PROVIDER\": \"deepseek\",\n        \"DEEPSEEK_API_KEY\": \"your_api_key\",\n        \"EXA_API_KEY\": \"your_exa_key_optional\"\n      }\n    }\n  }\n}\n```\n\n#### Environment Variables\n\nCreate a `.env` file or set these variables:\n\n```bash\n# LLM Provider (required)\nLLM_PROVIDER=\"deepseek\"  # deepseek, groq, openrouter, github, anthropic, ollama\nDEEPSEEK_API_KEY=\"sk-...\"\n\n# Optional: Enhanced/Standard Model Selection\n# DEEPSEEK_ENHANCED_MODEL_ID=\"deepseek-chat\"  # For synthesis\n# DEEPSEEK_STANDARD_MODEL_ID=\"deepseek-chat\"  # For other agents\n\n# Optional: Web Research (enables ExaTools)\n# EXA_API_KEY=\"your_exa_api_key\"\n\n# Optional: Custom endpoint\n# LLM_BASE_URL=\"https://custom-endpoint.com\"\n```\n\n### Model Configuration Examples\n\n```bash\n# Groq with different models\nGROQ_ENHANCED_MODEL_ID=\"openai/gpt-oss-120b\"\nGROQ_STANDARD_MODEL_ID=\"openai/gpt-oss-20b\"\n\n# Anthropic with Claude models\nANTHROPIC_ENHANCED_MODEL_ID=\"claude-3-5-sonnet-20241022\"\nANTHROPIC_STANDARD_MODEL_ID=\"claude-3-5-haiku-20241022\"\n\n# GitHub Models\nGITHUB_ENHANCED_MODEL_ID=\"gpt-4o\"\nGITHUB_STANDARD_MODEL_ID=\"gpt-4o-mini\"\n```\n\n## Usage\n\n### As MCP Server\n\nOnce installed and configured in your MCP client:\n\n1. The `sequentialthinking` tool becomes available\n2. Your LLM can use it to process complex thoughts\n3. The system automatically routes to appropriate thinking agents\n4. Results are synthesized and returned to your LLM\n\n### Direct Execution\n\nRun the server manually for testing:\n\n```bash\n# Using installed script\nmcp-server-mas-sequential-thinking\n\n# Using uv\nuv run mcp-server-mas-sequential-thinking\n\n# Using Python\npython src/mcp_server_mas_sequential_thinking/main.py\n```\n\n## Development\n\n### Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/FradSer/mcp-server-mas-sequential-thinking.git\ncd mcp-server-mas-sequential-thinking\n\n# Create virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n# Install with dev dependencies\nuv pip install -e \".[dev]\"\n```\n\n### Code Quality\n\n```bash\n# Format and lint\nuv run ruff check . --fix\nuv run ruff format .\nuv run mypy .\n\n# Run tests (when available)\nuv run pytest\n```\n\n### Testing with MCP Inspector\n\n```bash\nnpx @modelcontextprotocol/inspector uv run mcp-server-mas-sequential-thinking\n```\n\nOpen http://127.0.0.1:6274/ and test the `sequentialthinking` tool.\n\n## System Characteristics\n\n### Strengths:\n- **Multi-perspective analysis**: 6 different cognitive approaches\n- **AI-powered analysis**: Complexity metrics for observability\n- **Research capabilities**: 4 agents with web search (optional)\n- **Deterministic processing**: Fixed full multi-step sequence\n- **Model optimization**: Enhanced/Standard model selection\n- **Provider agnostic**: Works with multiple LLM providers\n\n### Considerations:\n- **Token usage**: Multi-agent processing uses more tokens than single-agent\n- **Processing time**: Complex sequences take longer but provide deeper insights\n- **API costs**: Research capabilities require separate Exa API subscription\n- **Model selection**: Enhanced models cost more but provide better synthesis\n\n## Project Structure\n\n```\nmcp-server-mas-sequential-thinking/\n├── src/mcp_server_mas_sequential_thinking/\n│   ├── main.py                          # MCP server entry point\n│   ├── processors/\n│   │   ├── multi_thinking_core.py       # 6 thinking agents definition\n│   │   └── multi_thinking_processor.py  # Sequential processing logic\n│   ├── routing/\n│   │   ├── ai_complexity_analyzer.py    # AI-powered analysis\n│   │   └── multi_thinking_router.py     # Intelligent routing\n│   ├── services/\n│   │   ├── server_core.py                   # ThoughtProcessor implementation\n│   │   ├── workflow_executor.py\n│   │   └── context_builder.py\n│   └── config/\n│       ├── modernized_config.py         # Provider strategies\n│       └── constants.py                 # System constants\n├── pyproject.toml                       # Project configuration\n└── README.md                            # This file\n```\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history.\n\n## Contributing\n\nContributions are welcome! Please ensure:\n\n1. Code follows project style (ruff, mypy)\n2. Commit messages use conventional commits format\n3. All tests pass before submitting PR\n4. Documentation is updated as needed\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Acknowledgments\n\n- Built with [Agno](https://github.com/agno-agi/agno) v2.0+ framework\n- Model Context Protocol by [Anthropic](https://www.anthropic.com/)\n- Research capabilities powered by [Exa](https://exa.ai/) (optional)\n- Multi-dimensional thinking inspired by Edward de Bono's work\n\n## Support\n\n- GitHub Issues: [Report bugs or request features](https://github.com/FradSer/mcp-server-mas-sequential-thinking/issues)\n- Documentation: Check CLAUDE.md for detailed implementation notes\n- MCP Protocol: [Official MCP Documentation](https://modelcontextprotocol.io/)\n\n---\n\n**Note**: This is an MCP server, designed to work with MCP-compatible clients like Claude Desktop. It is not a standalone chat application.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffradser%2Fmcp-server-mas-sequential-thinking","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffradser%2Fmcp-server-mas-sequential-thinking","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffradser%2Fmcp-server-mas-sequential-thinking/lists"}