MCP 服务器

Sequential Thinking Multi-Agent System (MAS)

镜子 (jìng zi)

MCP-Mirror

研究与数据

访问服务器

README

顺序思考多智能体系统 (MAS)

English | 简体中文

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

概述

此服务器提供了一个复杂的 sequentialthinking 工具，专为解决复杂问题而设计。与其前身不同，此版本使用真正的多智能体系统 (MAS) 架构，其中：

协调智能体（coordinate 模式下的 Team 对象）管理工作流程。
专业智能体（Planner、Researcher、Analyzer、Critic、Synthesizer）根据其定义的角色和专业知识处理特定的子任务。
输入的想法由智能体团队主动处理、分析和综合，而不仅仅是记录。
该系统支持复杂的思考模式，包括修订先前的步骤和分支以探索替代路径。
与 Exa 等外部工具的集成（通过 Researcher 智能体）允许动态信息收集。
强大的 Pydantic 验证确保了思考步骤的数据完整性。
详细的日志记录跟踪整个过程，包括智能体交互（由协调器处理）。

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

与原始版本 (TypeScript) 的主要区别

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

特性/方面	Python/Agno 版本（当前）	TypeScript 版本（原始）
架构	多智能体系统 (MAS)；由智能体团队主动处理。	单类状态跟踪器；简单的日志记录/存储。
智能	分布式智能体逻辑；嵌入在专业智能体和协调器中。	仅外部 LLM；没有内部智能。
处理	主动分析与综合；智能体对想法进行操作。	被动日志记录；仅记录想法。
框架	Agno (MAS) + FastMCP (服务器)；使用专用 MAS 库。	仅 MCP SDK。
协调	显式团队协调逻辑（`coordinate` 模式下的 `Team`）。	无；没有协调概念。
验证	Pydantic 模式验证；强大的数据验证。	基本类型检查；可靠性较低。
外部工具	已集成（通过 Researcher 集成 Exa）；可以执行研究任务。	无。
日志记录	结构化 Python 日志记录（文件 + 控制台）；可配置。	带有 Chalk 的控制台日志记录；基本。
语言 & 生态系统	Python；利用 Python AI/ML 生态系统。	TypeScript/Node.js。

本质上，该系统从被动的想法记录器演变为由 AI 智能体协作团队驱动的主动想法处理器。

工作原理（Coordinate 模式）

启动： 外部 LLM 使用 sequential-thinking-starter 提示来定义问题并启动流程。
工具调用： LLM 使用根据 ThoughtData 模型构建的第一个（或后续）想法调用 sequentialthinking 工具。
验证和日志记录： 该工具接收调用，使用 Pydantic 验证输入，记录传入的想法，并通过 AppContext 更新历史记录/分支状态。
协调器调用： 核心想法内容（包含有关修订/分支的上下文）被传递给 SequentialThinkingTeam 的 arun 方法。
协调器分析和委派： Team（充当协调器）分析输入想法，将其分解为子任务，并将这些子任务委派给最相关的专家智能体（例如，用于分析任务的 Analyzer，用于信息需求的 Researcher）。
专家执行： 被委派的智能体使用其指令、模型和工具（如 ThinkingTools 或 ExaTools）执行其特定的子任务。
响应收集： 专家将结果返回给协调器。
综合和指导： 协调器将专家的响应综合为单个、有凝聚力的输出。它可能包括基于专家发现（尤其是 Critic 和 Analyzer）的修订或分支建议。它还为 LLM 提供了关于如何制定下一个想法的指导。
返回值： 该工具返回一个 JSON 字符串，其中包含协调器综合的响应、状态和更新的上下文（分支、历史记录长度）。
迭代： 调用 LLM 使用协调器的响应和指导来制定下一个 sequentialthinking 工具调用，可能会根据建议触发修订或分支。

Token 消耗警告

⚠️ 高 Token 使用量： 由于多智能体系统架构，此工具消耗的 token 比单智能体替代方案或之前的 TypeScript 版本多得多。每次 sequentialthinking 调用都会调用： * 协调器智能体（Team 本身）。 * 多个专家智能体（可能包括 Planner、Researcher、Analyzer、Critic、Synthesizer，具体取决于协调器的委派）。

与单智能体或状态跟踪方法相比，这种并行处理导致更高的 token 使用量（每个思考步骤可能高出 3-6 倍或更多）。请相应地制定预算和计划。此工具优先考虑分析深度和质量，而不是 token 效率。

前提条件

Python 3.10+
访问兼容的 LLM API（配置为 agno）。该系统现在支持：
- Groq： 需要 GROQ_API_KEY。
- DeepSeek： 需要 DEEPSEEK_API_KEY。
- OpenRouter： 需要 OPENROUTER_API_KEY。
- 使用 LLM_PROVIDER 环境变量配置所需的提供商（默认为 deepseek）。
Exa API 密钥（如果使用 Researcher 智能体的功能）
- EXA_API_KEY 环境变量。
uv 包管理器（推荐）或 pip。

MCP 服务器配置（客户端）

此服务器作为标准可执行脚本运行，并通过 stdio 进行通信，正如 MCP 所期望的那样。确切的配置方法取决于您的特定 MCP 客户端实现。有关详细信息，请参阅客户端的文档。

env 部分应包含您选择的 LLM_PROVIDER 的 API 密钥。

{
  "mcpServers": {
      "mas-sequential-thinking": {
         "command": "uvx",
         "args": [
            "mcp-server-mas-sequential-thinking"
         ],
         "env": {
            "LLM_PROVIDER": "deepseek", // 或 "groq", "openrouter"
            // "GROQ_API_KEY": "your_groq_api_key", // 仅当 LLM_PROVIDER="groq"
            "DEEPSEEK_API_KEY": "your_deepseek_api_key", // 默认提供商
            // "OPENROUTER_API_KEY": "your_openrouter_api_key", // 仅当 LLM_PROVIDER="openrouter"
            "DEEPSEEK_BASE_URL": "your_base_url_if_needed", // 可选：如果使用 DeepSeek 的自定义端点
            "EXA_API_KEY": "your_exa_api_key" // 仅当使用 Exa
         }
      }
   }
}

安装和设置

克隆存储库：

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

设置环境变量： 在根目录中创建一个 .env 文件或导出变量：

# --- LLM 配置 ---
# 选择 LLM 提供商：“deepseek”（默认）、“groq”或“openrouter”
LLM_PROVIDER="deepseek"

# 提供所选提供商的 API 密钥：
# GROQ_API_KEY="your_groq_api_key"
DEEPSEEK_API_KEY="your_deepseek_api_key"
# OPENROUTER_API_KEY="your_openrouter_api_key"

# 可选：基本 URL 覆盖（例如，用于自定义 DeepSeek 端点）
DEEPSEEK_BASE_URL="your_base_url_if_needed"

# 可选：为团队协调器和专家智能体指定不同的模型
# 如果未设置这些，则默认值在代码中根据提供商设置。
# Groq 示例：
# GROQ_TEAM_MODEL_ID="llama3-70b-8192"
# GROQ_AGENT_MODEL_ID="llama3-8b-8192"
# DeepSeek 示例：
# DEEPSEEK_TEAM_MODEL_ID="deepseek-reasoner" # 推荐用于协调
# DEEPSEEK_AGENT_MODEL_ID="deepseek-chat"     # 推荐用于专家
# OpenRouter 示例：
# OPENROUTER_TEAM_MODEL_ID="anthropic/claude-3-haiku-20240307"
# OPENROUTER_AGENT_MODEL_ID="google/gemini-flash-1.5"

# --- 外部工具 ---
# 仅当使用 Researcher 智能体并且需要 Exa 时才需要
EXA_API_KEY="your_exa_api_key"

关于模型选择的说明：

TEAM_MODEL_ID 由协调器（Team 对象本身）使用。此角色需要强大的推理、综合和委派能力。即使速度较慢或成本较高，使用更强大的模型（如 deepseek-reasoner、claude-3-opus 或 gpt-4-turbo）通常也很有益处。
AGENT_MODEL_ID 由专家智能体（Planner、Researcher 等）使用。这些智能体处理更集中的子任务。您可以为专家选择更快或更具成本效益的模型（如 deepseek-chat、claude-3-sonnet、llama3-70b），具体取决于他们通常处理的任务的复杂性以及您的预算/性能要求。
main.py 中提供的默认值（例如，使用 DeepSeek 时，智能体的 deepseek-reasoner）是起点。鼓励进行实验，以找到适合您特定用例的最佳平衡。

安装依赖项：

使用 uv（推荐）：

# 如果您没有 uv，请安装它：
# curl -LsSf [https://astral.sh/uv/install.sh](https://astral.sh/uv/install.sh) | sh
# source $HOME/.cargo/env # 或重启您的 shell

uv pip install -r requirements.txt
# 或者，如果存在带有依赖项的 pyproject.toml：
# uv pip install .

使用 pip：

pip install -r requirements.txt
# 或者，如果存在带有依赖项的 pyproject.toml：
# pip install .

用法

运行服务器脚本（假设主脚本名为 main.py 或类似名称，具体取决于您的文件结构）：

python your_main_script_name.py

服务器将启动并侦听通过 stdio 发出的请求，从而使 sequentialthinking 工具可用于兼容的 MCP 客户端（如某些 LLM 或测试框架）。

`sequentialthinking` 工具参数

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

# 简化表示
{
    "thought": str,              # 当前想法/步骤的内容
    "thoughtNumber": int,        # 序列号 (>=1)
    "totalThoughts": int,        # 估计的总步骤数 (>=1, 建议 >=5)
    "nextThoughtNeeded": bool,   # 此步骤之后是否需要另一个步骤？
    "isRevision": bool = False,  # 这是否是修改先前的想法？
    "revisesThought": Optional[int] = None, # 如果 isRevision，则修改哪个想法编号？
    "branchFromThought": Optional[int] = None, # 如果分支，则从哪个想法分支？
    "branchId": Optional[str] = None, # 分支的唯一 ID
    "needsMoreThoughts": bool = False # 在最后一步之前发出信号，表明估计值太低
}

与工具交互（概念示例）

LLM 将以迭代方式与此工具交互：

LLM： 使用带有问题的 sequential-thinking-starter 提示。
LLM： 使用 thoughtNumber: 1、初始 thought（例如，“计划分析...”）、totalThoughts 估计值、nextThoughtNeeded: True 调用 sequentialthinking 工具。
服务器： MAS 处理想法 -> 协调器综合响应并提供指导（例如，“分析计划完成。建议接下来研究 X。目前不建议进行修订。”）。
LLM： 接收包含 coordinatorResponse 的 JSON 响应。
LLM： 根据 coordinatorResponse 制定下一个想法（例如，“使用 Exa 研究 X...”）。
LLM： 使用 thoughtNumber: 2、新的 thought、更新的 totalThoughts（如果需要）、nextThoughtNeeded: True 调用 sequentialthinking 工具。
服务器： MAS 处理 -> 协调器综合（例如，“研究完成。调查结果表明想法 #1 的假设存在缺陷。建议：修订想法 #1...”）。
LLM： 接收响应，看到建议。
LLM： 制定修订想法。
LLM： 使用 thoughtNumber: 3、修订 thought、isRevision: True、revisesThought: 1、nextThoughtNeeded: True 调用 sequentialthinking 工具。
...等等，可能会根据需要进行分支或扩展。

工具响应格式

该工具返回一个 JSON 字符串，其中包含：

{
  "processedThoughtNumber": int,
  "estimatedTotalThoughts": int,
  "nextThoughtNeeded": bool,
  "coordinatorResponse": "来自智能体团队的综合输出，包括分析、发现和下一步的指导...",
  "branches": ["list", "of", "branch", "ids"],
  "thoughtHistoryLength": int,
  "branchDetails": {
    "currentBranchId": "main | branchId",
    "branchOriginThought": null | int,
    "allBranches": {"main": count, "branchId": count, ...}
  },
  "isRevision": bool,
  "revisesThought": null | int,
  "isBranch": bool,
  "status": "success | validation_error | failed",
  "error": "如果状态不是 success，则显示错误消息" // 可选
}

日志记录

日志写入到 ~/.sequential_thinking/logs/sequential_thinking.log。
使用 Python 的标准 logging 模块。
包括轮换文件处理程序（10MB 限制，5 个备份）和控制台处理程序（INFO 级别）。
日志包括时间戳、级别、记录器名称和消息，包括格式化的想法表示。

开发

（如果适用，请在此处添加开发指南，例如，设置开发环境、运行测试、进行代码检查。）

克隆存储库。
设置虚拟环境。

安装依赖项，可能包括开发扩展：

# 使用 uv
uv pip install -e ".[dev]"
# 使用 pip
pip install -e ".[dev]"

运行代码检查器/格式化程序/测试。

许可证

MIT