使用说明

`mcp-sage`

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

依据

我大量使用克劳德密码。这是一个很好的产品，非常适合我的工作流程。尽管对于处理需要更多上下文的更复杂的代码库来说，具有大量上下文的较新模型似乎非常有用。这让我可以继续使用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/要提示的文件用于文件压缩
asadm/vibemode 对于将整个回购发送给Gemini以获取批量编辑建议的想法和提示
网络基础/递归思维链辩论功能的启示

概述

此项目实现了一个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[Start Debate] -->|determine models, judge, budgets| R1

  subgraph R1["Round 1"]
    direction TB
    R1GEN["Generation Phase<br/>*ALL models run in parallel*"]
    R1GEN --> R1CRIT["Critique Phase<br/>*ALL models critique others in parallel*"]
  end

  subgraph RN["Rounds 2 to N"]
    direction TB
    SYNTH["Synthesis Phase<br/>*every model refines own plan*"]
    SYNTH --> CONS[Consensus Check]
    CONS -->|Consensus reached| JUDGE
    CONS -->|No consensus & round < N| CRIT["Critique Phase<br/>*models critique in parallel*"]
    CRIT --> SYNTH
  end

  R1 --> RN
  JUDGE[Judgment Phase<br/>*judge model selects/merges response*]
  JUDGE --> FP[Final Response]

  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，辩论将提前停止并跳到评判
批评阶段 -如果没有达成共识，我们也没有进入最后一轮，每个模型都会再次（并行）对所有其他答案进行批评

判断阶段

在完成所有轮次（或达成早期共识）后，裁判模型（默认为克劳德·奥普斯4.1）：
- 对于明智的意见：选择单一的最佳回应（无综合）
- 对于明智的评论：可以选择最佳答案或合并多个答案
- 为其选择/合成提供置信度评分

2.自我辩论流-单一模型可用

flowchart TD
  SD0[Start Self-Debate] --> R1

  subgraph R1["Round 1 - Initial Responses"]
    direction TB
    P1[Generate Response 1] --> P2[Generate Response 2<br/>*different approach*]
    P2 --> P3[Generate Response 3<br/>*different approach*]
  end

  subgraph RN["Rounds 2 to N"]
    direction TB
    REF[Generate Improved Response<br/>*addresses weaknesses in all previous responses*]
    DEC{More rounds left?}
    REF --> DEC
    DEC -->|Yes| REF
  end

  R1 --> RN
  DEC -->|No| FP[Final Response = last response generated]

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

当只有一个型号可用时递归思维链（CoRT）使用方法：

突释 -该模型生成了三种不同的响应，每种响应都采用了不同的方法
细化轮次 -对于接下来的每一轮（2到N，默认N=3）：
- 该模型会审查之前的所有回复
- 它在内部对他们进行批评，找出他们的优缺点
- 它产生了一种新的改进响应，解决了早期响应中的局限性
最终选择 -生成的最后一个响应将成为最终输出

代码中实际发生了什么（快速参考）

阶段/功能	代码位置	注释
生成提示	提示/辩论比较.generateCompt	从每个模型创建初始响应
评论提示	提示/辩论Compts.critiquePrompt	使用“##对{ID}的评论”部分
综合提示	提示/辩论比较.synthesizePrompt	模型修改自己的响应
共识检查	编排器/辩论编排器	判断模型返回JSON `consensusScore`
裁判	提示/辩论裁判.judgePrompt	裁判返回最终回应+信心
自我辩论提示	提示/辩论对手.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）
- 无烟煤API键 （Claude Opus 4.1担任辩论法官）

注：虽然服务器只需一个API键就可以运行，但当提供所有这三个键时，效果最好。这使得：

基于令牌计数的最优模型选择
多模式辩论，以获得更高质量的回应
Claude Opus 4.1作为辩论模式中的公正法官

安装

通过Smithery安装

通过以下方式自动安装Sage for Claude Desktop 史密瑟里:

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

手动安装

# Clone the repository
git clone https://github.com/your-username/mcp-sage.git
cd mcp-sage

# Install dependencies
npm install

# Build the project
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客户端将适当地显示这些日志。

日志条目示例：

Token usage: 1,234 tokens. Selected model: gpt-5-2025-08-07 (limit: 400,000 tokens)
Files included: 3, Document count: 3
Sending request to OpenAI gpt-5-2025-08-07 with 1,234 tokens...
Received response from gpt-5-2025-08-07 in 982ms

Token usage: 435,678 tokens. Selected model: gemini-2.5-pro (limit: 1,000,000 tokens)
Files included: 25, Document count: 18
Sending request to Gemini with 435,678 tokens...
Received response from gemini-2.5-pro in 3240ms

使用工具

圣人意见工具

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

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

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "sage-opinion",
    "arguments": {
      "prompt": "Explain how this code works",
      "paths": ["path/to/file1.js", "path/to/file2.js"]
    }
  }
}

sage评论工具

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

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

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "sage-review",
    "arguments": {
      "instruction": "Add error handling to the function",
      "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使用为代价的更周到、更全面的响应。

运行测试

测试工具：

# Test the sage-opinion tool
OPENAI_API_KEY=your_openai_key GEMINI_API_KEY=your_gemini_key node test/run-test.js

# Test the sage-review tool
OPENAI_API_KEY=your_openai_key GEMINI_API_KEY=your_gemini_key node test/test-expert.js

# Test debate mode
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：用于O3模型的OpenAI API客户端实现
src/orchestrator/debateOrchestrator.ts：多模式辩论编排
src/prompts/debatePrompts.ts：辩论提示和说明模板
test/run-test.js：圣人意见工具测试
test/test-expert.js：sage审查工具测试
test/run-sage-opinion-debate.js：辩论模式功能测试

许可证

国际协调委员会

使用说明

mcp-sage

依据

模型选择

灵感

概述

sage-opinion

sage-review