MCP 思维服务器

一个强大的服务器，通过模型上下文协议 (MCP) 提供高级思维工具，以增强 Cline 等 AI 代理的推理、规划和迭代改进能力。

核心目的

此服务器提供专门的 MCP 工具，旨在引导 AI 代理完成结构化的认知过程，使它们能够通过模拟高级推理、分解问题、生成和批判解决方案以及可靠地跟踪进度，更有效地处理复杂的任务。

主要特性 / 可用工具

该服务器通过 MCP 提供以下结构化思维工具：

顺序思维 (sequentialThinking)

• 目的： 通过分析、假设、验证、修订和解决方案等阶段，指导结构化的、逐步的问题解决。

• 关键概念： 管理不同的思维阶段和状态，包括思想编号和分支，用于探索替代方案。

• 工作流程图：

  graph TD
      A[分析] --> H{假设};
      H --> V{验证};
      V -- 成功 --> S[解决方案];
      V -- 失败/不确定 --> R{修订};
      R --> H;
      H -- 替代方案 --> B[分支：新假设];
      B --> V;
  

• 使用说明： 即使在第一次调用 (thoughtNumber: 1) 时，thought 参数也是必需的，并且必须包含初始问题陈述或分析。

• 参数参考： 有关详细的参数、描述和使用示例，请参见 src/tools/sequentialThinkingParams.ts。

草稿链 (chainOfDraft)

• 目的： 通过起草、评论和修订的循环，促进迭代的内容生成和改进。

• 关键概念： 管理不同的起草阶段（初始、评论、修订、最终）和状态，包括草稿编号。草稿历史记录使用 SQLite 持久化。

• 工作流程图：

  graph TD
      I[初始草稿] --> C{评论};
      C -- 需要修订 --> R[修订];
      R --> C;
      C -- 足够好 --> F[最终草稿];
  

• 参数参考： 有关详细的参数、描述和使用示例，请参见 src/tools/chainOfDraftParams.ts。

集成思维 (integratedThinking)

• 目的： 结合顺序思维和草稿链，用于需要结构化推理和迭代内容改进的复杂任务。

• 关键概念： 集成两种方法，并管理组合状态（思想和草稿编号）。依赖 SQLite 通过底层的 ChainOfDraftService 进行草稿历史记录持久化。

• 工作流程图（简化）：

  graph TD
      Start[开始：初始思想/草稿] --> Step1{评论 / 分析};
      Step1 -- 需要改进 --> Step2[修订 / 假设];
      Step2 --> Step1;
      Step1 -- 看起来不错 --> Step3{验证 / 最终审查};
      Step3 -- 通过 --> Finish[最终输出];
      Step3 -- 失败 --> Step2;
  

  （注意：此图简化了潜在的复杂交互）

• 使用说明： 只有当 thoughtNumber 等于 totalThoughts 时，才能使用 category.type: 'final'。

• 参数参考： 有关详细的参数、描述和使用示例，请参见 src/tools/integratedParams.ts。

设置特性 (setFeature)

• 目的： 一个调试工具，用于在运行时启用或禁用特定的内部服务器特性，例如详细的日志记录或指标跟踪。
• 关键概念： 旨在用于调试和诊断。
• 参数参考： 有关详细的参数和可用特性，请参见 src/tools/setFeatureParams.ts。

高级置信度评分

该服务器采用高级置信度评分系统，以提供对 AI 输出质量和相关性的更准确评估，取代了旧的、更简单的方法。该系统有两个主要组成部分：

• 语义相关性 (RFC-009)： 衡量 AI 的输出（思想/草稿）与提供的任务上下文（问题范围、约束、假设）的相关程度。它使用本地文本嵌入（通过 @xenova/transformers，默认模型 Xenova/all-MiniLM-L6-v2）和余弦相似度来理解超出简单关键词的含义。（有关技术细节，请参见 docs/rfcs/009-semantic-relevance-confidence.md）。
• 可选的 LLM 一致性检查 (RFC-010)： 如果通过环境变量启用，这将使用外部 LLM 来评估 AI 输出的逻辑一致性和质量。它要求配置的 LLM 支持结构化的 JSON 输出（特别是 {"rating": N}，其中 N 为 1-5），通过 response_format 参数请求。此检查是可选的；如果禁用或 LLM 调用失败，系统将优雅地回退到中性的默认分数 (0.7) 作为一致性组件，确保服务器继续运行。（有关技术细节，请参见 docs/rfcs/010-llm-coherence-check.md）。

使用示例（顺序思维 - 步骤 1）

// 启动顺序思维过程的示例调用
{
  "tool_name": "sequentialThinking",
  "arguments": {
    "thought": "对用户请求重构身份验证模块的初步分析。", // 必需！
    "nextThoughtNeeded": true,
    "thoughtNumber": 1,
    "totalThoughts": 5, // 初始估计
    "category": {
      "type": "analysis",
      "confidence": 0.6
    },
    "context": {
      "problemScope": "重构现有的身份验证模块，以提高安全性并使用现代实践。",
      "constraints": ["必须保持与现有用户数据库的兼容性。", "最大限度地减少部署期间的停机时间。"]
    }
  }
}

安装

确保您已安装 Node.js（建议版本 >= 16.0.0）和 npm。

# 克隆存储库（如果尚未克隆）
# git clone <repository-url>
# cd mcp-thought-server

# 安装依赖项（包括 sqlite3）
npm install

注意：首次安装后运行服务器时，@xenova/transformers 库可能会下载嵌入模型（默认情况下为 Xenova/all-MiniLM-L6-v2），这需要互联网连接，并且可能需要一些时间。

开发 & 使用

# 构建项目（将 TypeScript 编译为 JavaScript 到 build/ 目录）
npm run build

# 运行测试
npm test

# 启动服务器（运行 node build/index.js）
npm start

# 在开发模式下运行，具有自动重新加载功能
# (使用 cross-env 设置 LOG_LEVEL=debug 以获得详细输出)
npm run dev

服务器将启动并侦听 MCP 连接（通常是通过 stdio，当由 MCP 客户端启动时）。

配置（环境变量）

可以使用环境变量配置服务器行为。您可以直接在 shell 中设置这些变量，也可以使用 .env 文件（需要 dotenv 包，该包已包含在内）。

SQLite 持久化 (RFC-012)

为了确保跨请求的可靠状态持久化（例如草稿历史记录），尤其是在可能重置进程内存的环境中，服务器使用嵌入式 SQLite 数据库。

• MCP_SQLITE_PATH：（可选）指定 SQLite 数据库的文件路径。
  • 如果未设置，则默认为相对于项目根目录的 data/mcp-thought-server.sqlite。如果使用默认值，将记录一条警告。
  • 如果包含该文件的目录不存在，将自动创建该目录。
• 注意： 确保将 data/ 目录（或指定的自定义目录）和 *.sqlite 文件添加到您的 .gitignore 中。

日志详细程度

• LOG_LEVEL：（可选）控制显示的最低日志级别。
  • 值：debug、info、warn、error。
  • 如果未设置，则默认为 info。
  • 示例：LOG_LEVEL=debug npm start（或在脚本中使用 cross-env）。

核心 MCP 连接

• MCP_SERVER_URL：（可选）如果特定配置需要 MCP 服务器 URL（默认值：http://localhost:3000 - 如果 stdio 是传输方式，则通常未使用）。
• MCP_API_KEY：（可选）如果 MCP 客户端需要身份验证，则使用 API 密钥（默认值：default-key）。

可选的 LLM 一致性检查 (RFC-010)

使用外部 LLM 启用更准确的一致性检查。需要设置 COHERENCE_API_KEY 和 COHERENCE_CHECK_MODEL。配置的 LLM 必须支持结构化的 JSON 输出。

• COHERENCE_API_KEY：(启用时必需) LLM 服务的 API 密钥。
• COHERENCE_CHECK_MODEL：(启用时必需) 模型标识符（例如，openai/gpt-3.5-turbo、google/gemma-7b-it）。
• COHERENCE_API_BASE：（可选）与 OpenAI 兼容的端点的基本 URL（例如，OpenRouter、Azure、本地 Ollama）。如果未设置，则默认为官方 OpenAI API。
• COHERENCE_HTTP_REFERER：（可选）站点 URL 标头，可能被某些代理服务（如 OpenRouter）用于排名/识别。
• COHERENCE_X_TITLE：（可选）站点标题标头，可能被某些代理服务（如 OpenRouter）用于排名/识别。

回退： 如果未设置 COHERENCE_API_KEY 或 COHERENCE_CHECK_MODEL，或者 LLM API 调用失败或返回无效响应，则一致性检查将使用默认的中性分数 (0.7)。

详细输出控制

这些布尔值 (true/false) 变量控制工具响应有效负载中包含的详细程度。

核心输出控制（默认值：true）

• MCP_SHOW_PROCESSING_METRICS：显示处理时间和资源使用情况。
• MCP_SHOW_SERVICE_METRICS：显示特定于服务的指标。
• MCP_SHOW_MCP_METRICS：显示 MCP 集成指标。

详细输出控制（默认值：false）

• MCP_SHOW_ADAPTATION_HISTORY：显示适应历史记录。
• MCP_SHOW_CATEGORY_HISTORY：显示类别转换历史记录。
• MCP_SHOW_DEPENDENCY_CHAIN：显示思想/草稿依赖关系。
• MCP_SHOW_DEBUG_METRICS：显示详细的调试指标。

性能监控（默认值：false）

• MCP_SHOW_MEMORY_USAGE：显示内存使用情况统计信息。
• MCP_SHOW_PARALLEL_TASK_INFO：显示并行处理信息。

向后兼容性（默认值：true）

• MCP_SHOW_FULL_RESPONSE：显示完整响应（如果为 true，则覆盖其他 MCP_SHOW_* 设置）。设置为 false 以使用其他标志启用细粒度控制。

使用示例

要以最小输出运行，仅启用核心指标：

export MCP_SHOW_FULL_RESPONSE=false
export MCP_SHOW_PROCESSING_METRICS=true
export MCP_SHOW_SERVICE_METRICS=true
export MCP_SHOW_MCP_METRICS=false
# ... 其他 MCP_SHOW_* 标志默认为 false ...
npm start

要使用 OpenRouter 启用 LLM 一致性检查：

export COHERENCE_API_KEY="your-openrouter-key"
export COHERENCE_CHECK_MODEL="google/gemma-7b-it" # 或其他模型
export COHERENCE_API_BASE="https://openrouter.ai/api/v1"
export COHERENCE_HTTP_REFERER="http://localhost:3000" # 您的站点 URL
export COHERENCE_X_TITLE="MCPThoughtServer" # 您的应用名称
npm start

要指定自定义 SQLite 数据库位置：

export MCP_SQLITE_PATH="/path/to/your/data/custom_thoughts.sqlite"
npm start

故障排除

• 连接问题： 确保服务器正在运行 (npm start 或 node build/index.js)。验证 MCP 客户端配置是否指向正确的传输方式（例如，stdio）。
• 工具错误 (InvalidParams 等)： 仔细检查工具的必需参数和类型，并对照链接的 *Params.ts 文件（例如，src/tools/sequentialThinkingParams.ts）。Zod 验证非常严格。如果可能，请检查服务器日志以获取详细的验证错误。
  • 常见错误： 对于 sequentialThinking，即使在第一次调用 (thoughtNumber: 1) 时，也要确保提供 thought 参数。
  • 常见错误： 对于 integratedThinking，确保仅当 thoughtNumber 等于 totalThoughts 时才使用 category.type: 'final'。
• “未找到原始草稿 X”错误： 这表明检索草稿历史记录时出现问题。确保 SQLite 数据库文件路径（通过 MCP_SQLITE_PATH 或默认的 data/mcp-thought-server.sqlite 配置）正确，并且服务器进程具有对该位置的写入权限。检查服务器日志以获取数据库错误。如果数据库文件 (.sqlite) 似乎已损坏，删除它可能会解决问题（但会丢失历史记录）。
• LLM 一致性检查问题： 如果启用，请验证 COHERENCE_API_KEY、COHERENCE_CHECK_MODEL 和 COHERENCE_API_BASE 环境变量是否已正确设置。检查外部 LLM 服务的状态。确保所选模型支持所需的结构化 JSON 输出格式。检查服务器日志以获取 API 错误。
• 低置信度分数： 可能表明 AI 的输出确实不相关（检查语义相似度分数组成部分）或不连贯（如果启用了 LLM 检查），或者提供给工具的 context 不足或定义不明确。
• 嵌入模型下载失败： 确保服务器首次运行时可以连接到互联网以下载句子转换器模型。检查缓存目录的权限（例如，~/.cache/huggingface/hub/）。
• SQLite 错误： 检查数据库文件及其目录的文件系统权限。确保在 npm install 期间正确构建了 sqlite3 本机插件（有时需要构建工具，如 Python、C++ 编译器）。
• 常规： 检查服务器的控制台输出 (stdout/stderr) 以获取更详细的错误消息或日志记录信息。

架构概述（简要）

该服务器是一个用 TypeScript 构建的 Node.js 应用程序。它遵循标准的 MCP 服务器模式，使用 @modelcontextprotocol/sdk。关键逻辑分为：

• 工具 (src/tools/)： 定义 MCP 工具接口（使用 Zod 模式）并处理请求验证/路由。
• 服务 (src/services/)： 封装每种思维策略（sequentialThinking、chainOfDraft、integratedThinking）和持久性 (StorageService) 的核心逻辑。
• 配置 (src/config/)： 管理设置和环境变量。
• 实用程序 (src/utils/)： 用于日志记录、嵌入、相似性和一致性检查等任务的共享函数。
• 类型 (src/types/)： 集中式 TypeScript 定义。

贡献

1. Fork 存储库。
2. 创建您的特性分支 (git checkout -b feature/amazing-feature)。
3. 提交您的更改 (git commit -m 'Add some amazing feature')。
4. 推送到分支 (git push origin feature/amazing-feature)。
5. 打开一个 Pull Request。

许可证

ISC - 有关详细信息，请参见 LICENSE 文件（注意：提供的文件列表中当前不存在 LICENSE 文件）。