顺序思维多智能体系统（MAS）

English |简体中文

该项目使用基于Agno框架构建并通过MCP提供服务的**多智能体系统 (MAS)**实现了先进的顺序思维过程。它通过利用协调一致的专用智能体进行更深入的分析和问题分解，代表了从简单的状态跟踪方法到更大规模的演进。

概述

该服务器提供了一个先进的顺序sequentialthinking工具，旨在解决复杂的问题。与前代产品不同，此版本采用了真正的多智能体系统 (MAS) 架构，其中：

• 协调代理（ coordinate模式下的Team对象）管理工作流程。

• 专门的代理（规划者、研究员、分析师、评论家、综合者）根据其定义的角色和专业知识处理特定的子任务。

• 代理团队会主动处理、分析和综合传入的想法，而不仅仅是记录下来。

• 该系统支持复杂的思维模式，包括修改先前的步骤和分支以探索替代路径。

• 与Exa等外部工具的集成（通过研究人员代理）允许动态信息收集。

• 强大的Pydantic验证可确保思考步骤的数据完整性。

• 详细日志记录跟踪该过程，包括代理交互（由协调员处理）。

目标是通过利用专业角色协同工作的力量，实现比单个代理或简单状态跟踪更高质量的分析和更细致的思考过程。

Related MCP server: Sequential-Thinking

与原始版本（TypeScript）的主要区别

这个 Python/Agno 实现标志着与原始 TypeScript 版本的根本转变：

本质上，该系统从一个被动的思维记录器演变为一个由人工智能代理协作团队驱动的主动思维处理器。

工作原理（坐标模式）

1. **启动：**外部 LLM 使用sequential-thinking-starter提示来定义问题并启动流程。

2. 工具调用： LLM 使用第一个（或后续）想法调用sequentialthinking工具，根据ThoughtData Pydantic 模型进行构建。

3. **验证和日志记录：**该工具接收调用，使用 Pydantic 验证输入，记录传入的想法，并通过AppContext更新历史记录/分支状态。

4. **协调器调用：**核心思想内容（以及有关修订/分支的上下文）被传递给SequentialThinkingTeam的arun方法。

5. 协调员分析与委派： Team （充当协调员）分析输入的想法，将其分解为子任务，并将这些子任务委派给最相关的专业代理（例如，分析任务的分析师、信息需求的研究人员）。

6. **专家执行：**委托代理使用其指令、模型和工具（如ThinkingTools或ExaTools ）执行其特定的子任务。

7. **答复收集：**专家将结果返回给协调员。

8. **综合与指导：**协调员将专家的反馈整合成一份统一且连贯的成果。该成果可能包含基于专家发现（尤其是来自评论员和分析员的发现）的修改或分支建议。它还为法学硕士（LLM）的下一步思路提供指导。

9. **返回值：**该工具返回一个 JSON 字符串，其中包含协调器的合成响应、状态和更新的上下文（分支、历史长度）。

10. **迭代：**调用 LLM 使用协调员的响应和指导来制定下一个sequentialthinking工具调用，可能会根据建议触发修订或分支。

代币消耗警告

⚠️高令牌使用率：由于采用了多智能体系统架构，此工具比单智能体替代方案或之前的 TypeScript 版本消耗的令牌明显更多。每次sequentialthinking调用都会调用：

• 协调员代理（ Team本身）。

• 多名专业代理（可能是规划师、研究员、分析师、评论家、合成师，取决于协调员的授权）。

与单智能体或状态跟踪方法相比，这种并行处理可以显著提高令牌使用率（每个思考步骤可能提高 3-6 倍或更多）。请根据实际情况制定预算和计划。此工具优先考虑**分析深度和质量，**而非令牌效率。

先决条件

• Python 3.10+

• 访问兼容的 LLM API（已针对agno配置）。系统目前支持：

  • **Groq：**需要GROQ_API_KEY 。

  • **DeepSeek：**需要DEEPSEEK_API_KEY 。

  • **OpenRouter：**需要OPENROUTER_API_KEY 。

  • 使用LLM_PROVIDER环境变量（默认为deepseek ）配置所需的提供程序。

• Exa API 密钥（仅在使用研究员代理的功能时需要）

  • 通过EXA_API_KEY环境变量设置。

• uv包管理器（推荐）或pip 。

MCP 服务器配置（客户端）

此服务器以标准可执行脚本的形式运行，并通过 stdio 进行通信，这与 MCP 的预期一致。具体配置方法取决于您具体的 MCP 客户端实现。有关集成外部工具服务器的详细信息，请参阅客户端的文档。

MCP 客户端配置中的env部分应包含您选择的LLM_PROVIDER的 API 密钥。

{
  "mcpServers": {
      "mas-sequential-thinking": {
         "command": "uvx", // Or "python", "path/to/venv/bin/python" etc.
         "args": [
            "mcp-server-mas-sequential-thinking" // Or the path to your main script, e.g., "main.py"
         ],
         "env": {
            "LLM_PROVIDER": "deepseek", // Or "groq", "openrouter"
            // "GROQ_API_KEY": "your_groq_api_key", // Only if LLM_PROVIDER="groq"
            "DEEPSEEK_API_KEY": "your_deepseek_api_key", // Default provider
            // "OPENROUTER_API_KEY": "your_openrouter_api_key", // Only if LLM_PROVIDER="openrouter"
            "DEEPSEEK_BASE_URL": "your_base_url_if_needed", // Optional: If using a custom endpoint for DeepSeek
            "EXA_API_KEY": "your_exa_api_key" // Only if using Exa
         }
      }
   }
}

安装和设置

通过 Smithery 安装

要通过Smithery自动为 Claude Desktop 安装顺序思维多代理系统：

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

手动安装

1. 克隆存储库：

   git clone git@github.com:FradSer/mcp-server-mas-sequential-thinking.git
   cd mcp-server-mas-sequential-thinking

2. **设置环境变量：**在项目根目录中创建一个.env文件或将变量直接导出到您的环境中：

   # --- LLM Configuration ---
   # Select the LLM provider: "deepseek" (default), "groq", or "openrouter"
   LLM_PROVIDER="deepseek"
   
   # Provide the API key for the chosen provider:
   # GROQ_API_KEY="your_groq_api_key"
   DEEPSEEK_API_KEY="your_deepseek_api_key"
   # OPENROUTER_API_KEY="your_openrouter_api_key"
   
   # Optional: Base URL override (e.g., for custom DeepSeek endpoints)
   # DEEPSEEK_BASE_URL="your_base_url_if_needed"
   
   # Optional: Specify different models for Team Coordinator and Specialist Agents
   # Defaults are set within the code based on the provider if these are not set.
   # Example for Groq:
   # GROQ_TEAM_MODEL_ID="llama3-70b-8192"
   # GROQ_AGENT_MODEL_ID="llama3-8b-8192"
   # Example for DeepSeek:
   # DEEPSEEK_TEAM_MODEL_ID="deepseek-chat" # Note: `deepseek-reasoner` is not recommended as it doesn't support function calling
   # DEEPSEEK_AGENT_MODEL_ID="deepseek-chat" # Recommended for specialists
   # Example for OpenRouter:
   # OPENROUTER_TEAM_MODEL_ID="deepseek/deepseek-r1" # Example, adjust as needed
   # OPENROUTER_AGENT_MODEL_ID="deepseek/deepseek-chat" # Example, adjust as needed
   
   # --- External Tools ---
   # Required ONLY if the Researcher agent is used and needs Exa
   EXA_API_KEY="your_exa_api_key"

   选型注意事项：

   • TEAM_MODEL_ID由协调员（ Team对象）使用。此角色拥有强大的推理、综合和委托能力。建议在此使用更强大的模型（例如deepseek-chat 、 claude-3-opus 、 gpt-4-turbo ），从而在性能与成本/速度之间取得平衡。

   • AGENT_MODEL_ID由专业代理（规划师、研究员等）使用。这些代理负责处理重点子任务。根据任务复杂性和预算/性能需求，速度更快或更经济高效的模型（例如deepseek-chat 、 claude-3-sonnet 、 llama3-8b ）可能更合适。

   • 如果未设置这些环境变量，则代码中（例如，在main.py中）会提供默认值。建议您进行实验，以找到适合您用例的最佳平衡点。

3. **安装依赖项：**强烈建议使用虚拟环境。

   • 使用uv （推荐）：

     # Install uv if you don't have it:
     # curl -LsSf https://astral.sh/uv/install.sh | sh
     # source $HOME/.cargo/env # Or restart your shell
     
     # Create and activate a virtual environment (optional but recommended)
     python -m venv .venv
     source .venv/bin/activate # On Windows use `.venv\\Scripts\\activate`
     
     # Install dependencies
     uv pip install -r requirements.txt
     # Or if a pyproject.toml exists with dependencies defined:
     # uv pip install .

   • 使用pip ：

     # Create and activate a virtual environment (optional but recommended)
     python -m venv .venv
     source .venv/bin/activate # On Windows use `.venv\\Scripts\\activate`
     
     # Install dependencies
     pip install -r requirements.txt
     # Or if a pyproject.toml exists with dependencies defined:
     # pip install .

用法

确保您的环境变量已设置并且虚拟环境（如果使用）处于活动状态。

运行服务器。选择以下方法之一：

1. 使用uv run （推荐）：

   uv --directory /path/to/mcp-server-mas-sequential-thinking run mcp-server-mas-sequential-thinking

2. 直接使用 Python：

   python main.py

服务器将启动并通过 stdio 监听请求，使配置为使用该工具的兼容 MCP 客户端可以使用sequentialthinking工具。

sequentialthinking工具参数

该工具需要与ThoughtData Pydantic 模型匹配的参数：

# Simplified representation from src/models.py
class ThoughtData(BaseModel):
    thought: str                 # Content of the current thought/step
    thoughtNumber: int           # Sequence number (>=1)
    totalThoughts: int           # Estimated total steps (>=1, suggest >=5)
    nextThoughtNeeded: bool      # Is another step required after this?
    isRevision: bool = False     # Is this revising a previous thought?
    revisesThought: Optional[int] = None # If isRevision, which thought number?
    branchFromThought: Optional[int] = None # If branching, from which thought?
    branchId: Optional[str] = None # Unique ID for the new branch being created
    needsMoreThoughts: bool = False # Signal if estimate is too low before last step

与工具交互（概念示例）

LLM 将与该工具进行迭代交互：

1. **LLM：**使用带有问题定义的启动提示（如sequential-thinking-starter ）。

2. **LLM：**使用thoughtNumber: 1 、初始thought （例如，“计划分析......”）、估计的totalThoughts和nextThoughtNeeded: True调用sequentialthinking工具。

3. 服务器： MAS 处理想法。协调员整合专家的反馈并提供指导（例如，“分析计划已完成。建议下一步研究 X。暂无修改建议。”）。

4. **LLM：**接收包含coordinatorResponse JSON 响应。

5. **LLM：**根据coordinatorResponse制定下一个想法（例如，“使用可用工具研究 X...”）。

6. **LLM：**使用thoughtNumber: 2调用sequentialthinking工具，即新的thought ，可能更新了totalThoughts ， nextThoughtNeeded: True 。

7. 服务器： MAS 处理。协调员进行综合（例如，“研究完成。研究结果表明，想法 1 的假设存在缺陷。建议：修改想法 1……”）。

8. **LLM：**收到回复，注意到建议。

9. **LLM：**制定修订思路。

10. **LLM：**使用thoughtNumber: 3 、修订thought 、 isRevision: True 、 revisesThought: 1 、 nextThoughtNeeded: True调用sequentialthinking工具。

11. ...等等，根据需要可能分支或扩展流程。

工具响应格式

该工具返回一个 JSON 字符串，包含以下内容：

{
  "processedThoughtNumber": int,          // The thought number that was just processed
  "estimatedTotalThoughts": int,          // The current estimate of total thoughts
  "nextThoughtNeeded": bool,              // Whether the process indicates more steps are needed
  "coordinatorResponse": "...",           // Synthesized output from the agent team, including analysis, findings, and guidance for the next step.
  "branches": ["main", "branch-id-1"],  // List of active branch IDs
  "thoughtHistoryLength": int,          // Total number of thoughts processed so far (across all branches)
  "branchDetails": {
    "currentBranchId": "main",            // The ID of the branch the processed thought belongs to
    "branchOriginThought": null | int,    // The thought number where the current branch diverged (null for 'main')
    "allBranches": {                      // Count of thoughts in each active branch
      "main": 5,
      "branch-id-1": 2
     }
  },
  "isRevision": bool,                     // Was the processed thought a revision?
  "revisesThought": null | int,           // Which thought number was revised (if isRevision is true)
  "isBranch": bool,                       // Did this thought start a new branch?
  "status": "success | validation_error | failed", // Outcome status
  "error": null | "Error message..."     // Error details if status is not 'success'
}

日志记录

• 日志默认写入~/.sequential_thinking/logs/sequential_thinking.log 。（配置可以在日志设置代码中调整）。

• 使用 Python 的标准logging模块。

• 包括旋转文件处理程序（例如，10MB 限制、5 个备份）和控制台处理程序（通常为 INFO 级别）。

• 日志包括时间戳、级别、记录器名称和消息，包括正在处理的想法的结构化表示。

发展

1. **克隆存储库：（**与安装中相同）

   git clone git@github.com:FradSer/mcp-server-mas-sequential-thinking.git
   cd mcp-server-mas-sequential-thinking

2. **设置虚拟环境：（**推荐）

   python -m venv .venv
   source .venv/bin/activate # On Windows use `.venv\\Scripts\\activate`

3. **安装依赖项（包括 dev）：**确保您的requirements-dev.txt或pyproject.toml指定开发工具（如pytest 、 ruff 、 black 、 mypy ）。

   # Using uv
   uv pip install -r requirements.txt
   uv pip install -r requirements-dev.txt # Or install extras if defined in pyproject.toml: uv pip install -e ".[dev]"
   
   # Using pip
   pip install -r requirements.txt
   pip install -r requirements-dev.txt # Or install extras if defined in pyproject.toml: pip install -e ".[dev]"

4. **运行检查：**执行 linters、格式化程序和测试（根据您的项目设置调整命令）。

   # Example commands (replace with actual commands used in the project)
   ruff check . --fix
   black .
   mypy .
   pytest

5. **贡献：（**考虑添加贡献指南：分支策略、拉取请求流程、代码风格）。

执照

麻省理工学院