mcp-智者

Name: mcp-智者
Author: jalehman

作者：jalehman7 星标更新：2025-09-05

安装使用来源：spider==github.com

项目介绍

`mcp-sage`

一个MCP（模型上下文协议）服务器，提供工具将提示发送到OpenAI的GPT-5、GPT-4.1、Google的Gemini 2.5 Pro或Anthropic的Claude Opus 4.1，基于令牌数和配置。这些工具会将所有引用的文件路径（递归处理文件夹）嵌入到提示中。这对于从能够准确处理大量上下文的模型中获取第二意见或详细的代码审查非常有用。

背景

我经常使用Claude Code。它是一个很好的产品，非常适合我的工作流程。然而，具有大量上下文的新模型对于处理更复杂的代码库似乎非常有用，因为需要更多的上下文。这让我可以在继续使用Claude Code作为开发工具的同时，利用GPT-5、Gemini 2.5 Pro和其他模型的大上下文能力来增强Claude Code的有限上下文。

模型选择

服务器根据令牌数自动选择合适的模型，配置定义在models.yaml中：

对于较小的上下文（≤ 400K 令牌）：使用OpenAI的GPT-5（如果设置了OPENAI_API_KEY）
对于中等大小的上下文（≤ 1M 令牌）：使用Google的Gemini 2.5 Pro（如果设置了GEMINI_API_KEY）
备选方案（≤ 1M 令牌）：使用OpenAI的GPT-4.1
如果内容超过1M 令牌：返回一个有用的错误

备选行为：

API密钥备选：
- 如果缺少OPENAI_API_KEY，Gemini将在其1M 令牌限制内用于所有上下文
- 如果缺少GEMINI_API_KEY，只能使用OpenAI模型处理较小的上下文
- 如果缺少所需的API密钥，返回一个有用的错误

灵感来源

这个项目借鉴了两个其他开源项目：

simonw/files-to-prompt 用于文件压缩
asadm/vibemode 用于将整个仓库发送给Gemini以获得整体编辑建议的想法和提示
PhialsBasement/Chain-of-Recursive-Thoughts 用于辩论功能的灵感

概述

该项目实现了一个MCP服务器，提供了两个主要工具：

`sage-opinion`

接受提示和文件/目录路径列表作为输入
将文件打包成结构化的XML格式
测量令牌数并选择合适的模型：
- GPT-5 用于 ≤ 400K 令牌
- Gemini 2.5 Pro 用于 > 400K 且 ≤ 1M 令牌
- GPT-4.1 作为备选方案用于 ≤ 1M 令牌
将组合的提示+上下文发送到选定的模型
返回模型的响应

`sage-review`

接受代码更改指令和文件/目录路径列表作为输入
将文件打包成结构化的XML格式
测量令牌数并选择合适的模型：
- GPT-5 用于 ≤ 400K 令牌
- Gemini 2.5 Pro 用于 > 400K 且 ≤ 1M 令牌
- GPT-4.1 作为备选方案用于 ≤ 1M 令牌
创建一个专门的提示，指示模型使用SEARCH/REPLACE块格式化响应
将组合的上下文+指令发送到选定的模型
返回格式化为SEARCH/REPLACE块的编辑建议，以便轻松实施

辩论模式

sage-opinion 和 sage-review 都支持可选的辩论模式，可以通过在参数中添加 debate: true 来启用。启用后，系统会在多个模型之间组织结构化的辩论，以生成更高品质的响应。

1. 多模型辩论流程

flowchart TD
  S0[开始辩论] -->|确定模型、裁判、预算| R1

  subgraph R1["第一轮"]
    direction TB
    R1GEN["生成阶段<br/>*所有模型并行运行*"]
    R1GEN --> R1CRIT["批评阶段<br/>*所有模型并行批评他人*"]
  end

  subgraph RN["第2轮至第N轮"]
    direction TB
    SYNTH["综合阶段<br/>*每个模型改进自己的计划*"]
    SYNTH --> CONS[共识检查]
    CONS -->|达成共识| JUDGE
    CONS -->|未达成共识且轮次 < N| CRIT["批评阶段<br/>*模型并行批评他人*"]
    CRIT --> SYNTH
  end

  R1 --> RN
  JUDGE[裁决阶段<br/>*裁判模型选择/合并响应*]
  JUDGE --> FP[最终响应]

  classDef round fill:#e2eafe,stroke:#4169E1;
  class R1GEN,R1CRIT,SYNTH,CRIT round;
  style FP fill:#D0F0D7,stroke:#2F855A,stroke-width:2px
  style JUDGE fill:#E8E8FF,stroke:#555,stroke-width:1px

多模型辩论的关键阶段：

设置阶段

系统确定可用模型，选择裁判，并分配令牌预算

第一轮

生成阶段 - 每个可用模型（A、B、C等）并行生成其响应
批评阶段 - 每个模型审查所有其他响应（从不审查自己的），并并行生成结构化的批评

第2轮至第N轮（默认N为3）

综合阶段 - 每个模型使用收到的批评改进其先前的响应（模型并行工作）
共识检查 - 裁判模型对所有当前响应的相似性进行评分
- 如果评分 ≥ 0.9，辩论提前结束并跳转到裁决
批评阶段 - 如果未达成共识且不是最后一轮，每个模型再次并行批评所有其他响应

裁决阶段

完成所有轮次（或提前达成共识）后，裁判模型（默认为Claude Opus 4.1）：
- 对于 sage-opinion：选择最佳响应（不进行综合）
- 对于 sage-review：可以选择最佳响应或合并多个响应
- 提供对其选择/综合的信心评分

2. 自我辩论流程 - 仅有一个模型可用

flowchart TD
  SD0[开始自我辩论] --> R1

  subgraph R1["第1轮 - 初始响应"]
    direction TB
    P1[生成响应1] --> P2[生成响应2<br/>*不同方法*]
    P2 --> P3[生成响应3<br/>*不同方法*]
  end

  subgraph RN["第2轮至第N轮"]
    direction TB
    REF[生成改进响应<br/>*解决所有先前响应的弱点*]
    DEC{还有更多轮次？}
    REF --> DEC
    DEC -->|是| REF
  end

  R1 --> RN
  DEC -->|否| FP[最终响应 = 最后生成的响应]

  style FP fill:#D0F0D7,stroke:#2F855A,stroke-width:2px

当只有一个模型可用时，采用递归思维链 (CoRT) 方法：

初始爆发 - 模型生成三个不同的响应，每个响应采取不同的方法
改进轮次 - 对于每个后续轮次（2到N，默认N为3）：
- 模型审查所有先前的响应
- 内部批评它们，识别优缺点
- 生成一个新的改进响应，解决早期响应中的局限性
最终选择 - 最后生成的响应成为最终输出

代码实际发生的情况（快速参考）

阶段 / 功能	代码位置	备注
生成提示	prompts/debatePrompts.generatePrompt	从每个模型创建初始响应
批评提示	prompts/debatePrompts.critiquePrompt	使用 "## 批评 {ID}" 部分
综合提示	prompts/debatePrompts.synthesizePrompt	模型修订自己的响应
共识检查	orchestrator/debateOrchestrator	裁判模型返回包含 `consensusScore` 的JSON
裁决	prompts/debatePrompts.judgePrompt	裁判返回最终响应 + 信心评分
自我辩论提示	prompts/debatePrompts.selfDebatePrompt	递归思维链循环

性能和成本考虑

⚠️ 重要提示： 使用辩论模式时：

完成时间可能更长（使用多个模型时为2-5分钟）
由于多轮辩论，消耗更多API令牌
成本高于单模型方法

典型资源使用情况：

多模型辩论：比单模型方法多2-4倍的令牌
处理时间：根据复杂性和模型可用性，2-5分钟
API成本因使用的模型和复杂性而异

前提条件

Node.js（v18或更高版本）
您要使用的模型的API密钥：
- OpenAI API密钥（用于GPT-5和GPT-4.1）
- Google Gemini API密钥（用于Gemini 2.5 Pro）
- Anthropic API密钥（用于辩论中的Claude Opus 4.1作为裁判）

注意： 虽然服务器只需一个API密钥即可运行，但提供所有三个密钥可以实现最佳效果。这确保了：

根据令牌数选择最优模型
多模型辩论生成更高品质的响应
在辩论模式中，Claude Opus 4.1作为公正的裁判

安装

通过Smithery安装

要通过 Smithery 自动安装Sage for Claude Desktop：

npx -y @smithery/cli install @jalehman/mcp-sage --client claude

手动安装

# 克隆仓库
git clone https://github.com/your-username/mcp-sage.git
cd mcp-sage

# 安装依赖
npm install

# 构建项目
npm run build

环境变量

设置以下环境变量：

OPENAI_API_KEY：您的OpenAI API密钥（用于GPT-5和GPT-4.1模型）
GEMINI_API_KEY：您的Google Gemini API密钥（用于Gemini 2.5 Pro）
ANTHROPIC_API_KEY：您的Anthropic API密钥（用于辩论中的Claude Opus 4.1）

推荐： 提供所有三个API密钥以获得最佳体验。这确保了：

服务器可以根据任何令牌数选择最优模型
辩论模式可以使用多个多样化的模型
Claude Opus 4.1在辩论中担任有效的裁判

使用

构建完成后使用 npm run build，将以下内容添加到您的MCP配置中：

OPENAI_API_KEY=your_openai_key GEMINI_API_KEY=your_gemini_key node /path/to/this/repo/dist/index.js

您也可以使用在其他地方设置的环境变量，例如在您的shell配置文件中。

提示

要获取第二意见，只需请求第二意见。

要获取代码审查，请求代码审查或专家审查。

这两种情况都受益于提供要包含在上下文中的文件路径，但如果省略，主机LLM可能会推断出要包含的内容。

调试和监控

服务器通过MCP日志功能提供详细的监控信息。这些日志包括：

令牌使用统计和模型选择
请求中包含的文件和文档数量
请求处理时间指标
超出令牌限制时的错误信息

日志通过MCP协议的 notifications/message 方法发送，确保它们不会干扰JSON-RPC通信。支持日志记录的MCP客户端将适当显示这些日志。

示例日志条目：

令牌使用：1,234 令牌。选定模型：gpt-5-2025-08-07（限制：400,000 令牌）
包含文件：3，文档数量：3
向OpenAI gpt-5-2025-08-07 发送请求，包含 1,234 令牌...
从 gpt-5-2025-08-07 收到响应，耗时 982ms

令牌使用：435,678 令牌。选定模型：gemini-2.5-pro（限制：1,000,000 令牌）
包含文件：25，文档数量：18
向Gemini发送请求，包含 435,678 令牌...
从 gemini-2.5-pro 收到响应，耗时 3240ms

使用工具

sage-opinion 工具

sage-opinion 工具接受以下参数：

prompt（字符串，必需）：要发送到选定模型的提示
paths（字符串数组，必需）：要包含在上下文中的文件路径列表
debate（布尔值，可选）：启用多模型辩论模式以获得更高品质的响应

示例MCP工具调用（使用JSON-RPC 2.0）：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "sage-opinion",
    "arguments": {
      "prompt": "解释这段代码是如何工作的",
      "paths": ["path/to/file1.js", "path/to/file2.js"]
    }
  }
}

sage-review 工具

sage-review 工具接受以下参数：

instruction（字符串，必需）：所需的具体更改或改进
paths（字符串数组，必需）：要包含在上下文中的文件路径列表
debate（布尔值，可选）：启用多模型辩论模式以获得更高品质的响应

示例MCP工具调用（使用JSON-RPC 2.0）：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "sage-review",
    "arguments": {
      "instruction": "为该函数添加错误处理",
      "paths": ["path/to/file1.js", "path/to/file2.js"]
    }
  }
}

响应将包含SEARCH/REPLACE块，您可以使用这些块来实施建议的更改：

<<<<<<< SEARCH
function getData() {
  return fetch('/api/data')
    .then(res => res.json());
}
=======
function getData() {
  return fetch('/api/data')
    .then(res => {
      if (!res.ok) {
        throw new Error(`HTTP error! Status: ${res.status}`);
      }
      return res.json();
    })
    .catch(error => {
      console.error('Error fetching data:', error);
      throw error;
    });
}
>>>>>>> REPLACE

使用辩论模式时，系统将：

从多个模型（默认为GPT-5和Gemini）生成初始响应
让模型互相批评响应
允许模型根据批评改进其响应
使用裁判模型（默认为Claude Opus 4.1）选择或综合最佳响应

这将以额外的时间和API使用为代价，生成更深入和全面的响应。

运行测试

要测试工具：

# 测试 sage-opinion 工具
OPENAI_API_KEY=your_openai_key GEMINI_API_KEY=your_gemini_key node test/run-test.js

# 测试 sage-review 工具
OPENAI_API_KEY=your_openai_key GEMINI_API_KEY=your_gemini_key node test/test-expert.js

# 测试辩论模式
OPENAI_API_KEY=your_openai_key GEMINI_API_KEY=your_gemini_key ANTHROPIC_API_KEY=your_anthropic_key node test/run-sage-opinion-debate.js

注意： 使用辩论模式的测试可能需要2-5分钟才能完成，因为它们协调多模型交互。

项目结构

src/index.ts：主要的MCP服务器实现和工具定义
src/pack.ts：将文件打包成结构化XML格式的工具
src/tokenCounter.ts：用于计算提示中令牌数的实用程序
src/gemini.ts：Gemini API客户端实现
src/openai.ts：OpenAI API客户端实现（用于O3模型）
src/orchestrator/debateOrchestrator.ts：多模型辩论编排
src/prompts/debatePrompts.ts：辩论提示和指令模板
test/run-test.js：sage-opinion 工具的测试
test/test-expert.js：sage-review 工具的测试
test/run-sage-opinion-debate.js：辩论模式功能的测试

许可证

ISC