Mcp Sage

mcp-sage

一个 MCP（Model Context Protocol）服务，提供用于根据令牌数量和配置向 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
  • 如果缺少 GEMINI_API_KEY，则只能使用 OpenAI 模型处理较小的上下文
  • 如果缺少所需的 API 密钥，则返回说明性错误

灵感来源

本项目受到另外两个开源项目的启发：

• simonw/files-to-prompt，用于文件压缩
• asadm/vibemode，提供了将整个代码库发送给 Gemini 以征求整体编辑建议的构想和提示词
• PhialsBasement/Chain-of-Recursive-Thoughts，为辩论功能提供了灵感

概述

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

sage-opinion

1. 接收一个提示词以及文件/目录路径列表作为输入
2. 将文件打包为结构化 XML 格式
3. 测量令牌数量并选择合适的模型：
   • ≤ 400K 个令牌时使用 GPT-5

   • 400K 且 ≤ 1M 个令牌时使用 Gemini 2.5 Pro

   • ≤ 1M 个令牌时将 GPT-4.1 作为备用选项
4. 将组合后的提示词和上下文发送给所选模型
5. 返回模型的回复

sage-review

1. 接收一条代码修改指令以及文件/目录路径列表作为输入
2. 将文件打包为结构化 XML 格式
3. 测量令牌数量并选择合适的模型：
   • ≤ 400K 个令牌时使用 GPT-5

   • 400K 且 ≤ 1M 个令牌时使用 Gemini 2.5 Pro

   • ≤ 1M 个令牌时将 GPT-4.1 作为备用选项
4. 创建专用提示词，要求模型使用 SEARCH/REPLACE 块格式化回复
5. 将组合后的上下文和指令发送给所选模型
6. 返回以 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

多模型辩论的关键阶段：

设置阶段

• 系统确定可用模型、选择评审模型并分配令牌预算

第 1 轮

• 生成阶段 - 每个可用模型（A、B、C 等）并行生成回复
• 批评阶段 - 每个模型审阅其他所有回复（绝不审阅自己的回复），并行生成结构化批评

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

1. 综合阶段 - 每个模型根据收到的批评改进之前的回复（模型并行工作）
2. 共识检查 - 评审模型对当前所有回复之间的相似度进行评分
   • 如果得分 ≥ 0.9，辩论将提前结束并跳转至评判阶段
3. 批评阶段 - 如果尚未达成共识且当前不是最后一轮，每个模型会再次批评其他所有回复（并行进行）

评判阶段

• 完成所有轮次（或提前达成共识）后，评审模型（默认为 Claude Opus 4.1）：
  • 对于 sage-opinion：选出单个最佳回复（不进行综合）
  • 对于 sage-review：可以选出最佳回复，也可以合并多个回复
  • 为其选择或综合结果提供置信度评分

---

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）方法：

1. 初始生成 - 模型生成三个不同的回复，每个回复都采用不同的方法
2. 优化轮次 - 对于每个后续轮次（第 2 至 N 轮，N 默认为 3）：
   • 模型审阅所有之前的回复
   • 模型在内部进行批评，指出优点和缺点
   • 模型生成一条新的改进回复，以解决之前回复的不足
3. 最终选择 - 最后生成的回复将作为最终输出

---

代码中的实际流程（快速参考）

阶段 / 功能	代码位置	说明
生成提示词	prompts/debatePrompts.generatePrompt	为每个模型创建初始回复
批评提示词	prompts/debatePrompts.critiquePrompt	使用“## Critique of {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 自动为 Claude Desktop 安装 Sage：

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 密钥，以获得最佳体验。这样可以确保：

• 服务能够根据任意 token 数量选择最合适的模型
• 辩论模式可以使用多个不同的模型
• 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 配置文件中的变量。

提示

要征求第二意见，只需提出征求第二意见。

要进行代码审查，请提出代码审查或专家审查。

提供希望纳入上下文的文件路径有助于这两种操作；如果未提供，宿主大模型可能会推断应纳入哪些内容。

调试和监控

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

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

日志通过 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 工具

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

• prompt（字符串，必需）：要发送给所选模型的提示词
• 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-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": "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

使用任一工具的辩论模式时，系统将：

1. 生成多个模型的初始回复（默认使用 GPT-5 和 Gemini）
2. 让模型相互批评对方的回复
3. 允许模型根据批评完善回复
4. 使用评判模型（默认使用 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：用于统计提示词中 token 数量的实用工具
• src/gemini.ts：Gemini API 客户端实现
• src/openai.ts：用于 O3 模型的 OpenAI API 客户端实现
• 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