`mcp-sage`

MCP（模型上下文协议）服务器提供工具，可根据令牌数量向 OpenAI 的 O3 模型或 Google 的 Gemini 2.5 Pro 发送提示。这些工具会将所有引用的文件路径（文件夹路径则以递归方式）嵌入到提示中。这对于从能够准确处理大量上下文的模型中获取第二意见或详细的代码审查非常有用。

基本原理

我大量使用 Claude Code。它是一款非常棒的产品，非常适合我的工作流程。不过，拥有大量上下文的较新模型似乎在处理需要更多上下文的更复杂代码库时非常有用。这让我可以继续使用 Claude Code 作为开发工具，同时利用 O3 和 Gemini 2.5 Pro 的海量上下文功能来增强 Claude Code 有限的上下文功能。

Related MCP server: Gemini Thinking MCP Server

模型选择

服务器根据令牌数量和可用的 API 密钥自动选择适当的模型：

对于较小的上下文（≤ 200K 个令牌）：使用 OpenAI 的 O3 模型（如果设置了 OPENAI_API_KEY）
对于更大的上下文（> 200K 和 ≤ 1M 个令牌）：使用 Google 的 Gemini 2.5 Pro（如果设置了 GEMINI_API_KEY）
如果内容超过 1M 个令牌：返回信息错误

后备行为：

API 密钥后备：
- 如果缺少 OPENAI_API_KEY，Gemini 将用于其 1M 令牌限制内的所有上下文
- 如果缺少 GEMINI_API_KEY，则只有较小的上下文（≤ 200K 个令牌）才能使用 O3 处理
- 如果两个 API 密钥均缺失，则会返回信息错误
网络连接回退：
- 如果 OpenAI API 无法访问（网络错误），系统将自动回退到 Gemini
- 这可以抵御单一提供商的临时网络问题
- 需要设置 GEMINI_API_KEY 才能使回退功能正常工作

灵感

该项目从另外两个开源项目中汲取灵感：

simonw/files-to-prompt用于文件压缩
asadm/vibemode提出想法并提示将整个 repo 发送给 Gemini 以获取批量编辑建议
PhialsBasement/Chain-of-Recursive-Thoughts对 sage-plan 工具的启发

概述

该项目实现了一个 MCP 服务器，它公开了三个工具：

`sage-opinion`

接受提示和文件/目录路径列表作为输入
将文件打包成结构化的 XML 格式
测量令牌数量并选择适当的模型：
- O3 ≤ 20 万个令牌
- Gemini 2.5 Pro 适用于 > 20 万且 ≤ 100 万个代币
将组合提示+上下文发送给选定的模型
返回模型的响应

`sage-review`

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

`sage-plan`

接受请求实施计划和文件/目录路径列表作为输入的提示
将文件打包成结构化的 XML 格式
组织多模型辩论以制定高质量的实施计划
模特们通过多轮评审来完善彼此的计划
返回获胜的实施计划，包含详细步骤

sage-plan - 多模型和自我辩论工作流程

sage-plan工具不会要求单个模型制定计划。相反，它会精心策划一场持续一轮或多轮的结构化辩论，然后要求单独的评判模型（或在 CoRT 模式下使用同一个模型）选出获胜者。

1. 多模式辩论流程

flowchart TD S0[Start Debate] -->|determine models, judge, budgets| R1 subgraph R1["Round 1"] direction TB R1GEN["Generation Phase *ALL models run in parallel*"] R1GEN --> R1CRIT["Critique Phase *ALL models critique others in parallel*"] end subgraph RN["Rounds 2 to N"] direction TB SYNTH["Synthesis Phase *every model refines own plan*"] SYNTH --> CONS[Consensus Check] CONS -->|Consensus reached| JUDGE CONS -->|No consensus & round < N| CRIT["Critique Phase *models critique in parallel*"] CRIT --> SYNTH end R1 --> RN JUDGE[Judgment Phase *judge model selects/merges plan*] JUDGE --> FP[Final Plan] 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，辩论将提前结束并进入判断环节
批评阶段- 如果未达成共识且未进入最后一轮，则每个模型将再次批评所有其他计划（并行）

判断阶段

完成所有轮次（或达成早期共识）后，评判模型（默认为 O3）：
- 选择单个最佳计划或将多个计划合并为一个更优的计划
- 为其选择/合成提供置信度评分

2. 自我辩论流程 - 单一模式可选

flowchart TD SD0[Start Self-Debate] --> R1 subgraph R1["Round 1 - Initial Plans"] direction TB P1[Generate Plan 1] --> P2[Generate Plan 2 *different approach*] P2 --> P3[Generate Plan 3 *different approach*] end subgraph RN["Rounds 2 to N"] direction TB REF[Generate Improved Plan *addresses weaknesses in all previous plans*] DEC{More rounds left?} REF --> DEC DEC -->|Yes| REF end R1 --> RN DEC -->|No| FP[Final Plan = last plan generated] style FP fill:#D0F0D7,stroke:#2F855A,stroke-width:2px

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

初始爆发- 该模型生成三个不同的计划，每个计划采用不同的方法
细化轮次- 对于每个后续轮次（2 到 N，默认 N=3）：
- 该模型回顾了所有先前的计划
- 它在内部进行批评，找出优势和劣势
- 它制定了一个新的改进计划，解决了早期计划中的局限性
最终选择——最后生成的计划将成为最终实施计划

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

阶段/功能	代码位置	笔记
生成提示	提示/debatePrompts.generatePrompt	添加标题“#实施计划（模型X）”
批评提示	提示/debatePrompts.critiquePrompt	使用“## 批评计划 {ID}”部分
综合提示	提示/debatePrompts.synthesizePrompt	模型修改了自己的计划
共识检查	辩论Orchestrator.checkConsensus	评判模型返回带有 `consensusScore` 的 JSON
判断	提示/辩论提示.judgePrompt	法官返回“#最终实施计划”+置信度
自我辩论提示	提示/debatePrompts.selfDebatePrompt	递归思路链循环

性能和成本考虑

⚠️重要提示： sage-plan 工具可以：

需要花费大量时间才能完成（多个模型需要 5-10 分钟）
由于多轮争论，消耗了大量 API 令牌
比单一模型方法成本更高

典型的资源使用情况：

多模型争论：比单模型方法多 2-4 倍的 token
处理时间：5-10 分钟，取决于复杂性和模型可用性
API 成本：每生成一个计划 0.30-1.50 美元（根据使用的模型和计划复杂性而有所不同）

先决条件

Node.js（v18 或更高版本）
Google Gemini API 密钥（用于更大的上下文）
OpenAI API 密钥（适用于较小的上下文）

安装

# 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 密钥（适用于 O3 模型）
GEMINI_API_KEY ：您的 Google Gemini API 密钥（适用于 Gemini 2.5 Pro）

用法

使用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: o3-2025-04-16 (limit: 200,000 tokens) Files included: 3, Document count: 3 Sending request to OpenAI o3-2025-04-16 with 1,234 tokens... Received response from o3-2025-04-16 in 982ms

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

使用工具

sage-opinion 工具

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

prompt （字符串，必需）：发送给所选模型的提示
paths （字符串数组，必需）：作为上下文包含的文件路径列表

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 （字符串数组，必需）：作为上下文包含的文件路径列表

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

sage-plan工具

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

prompt （字符串，必需）：您需要实施计划的描述
paths （字符串数组，必需）：作为上下文包含的文件路径列表

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

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "sage-plan", "arguments": { "prompt": "Create an implementation plan for adding user authentication to this application", "paths": ["src/index.js", "src/models/", "src/routes/"] } } }

答复中包含详细的实施计划，其中包括：

高级架构概述
具体实施步骤
需要更改文件
测试策略
潜在的挑战和缓解措施

该计划受益于多个 AI 模型的集体智慧（或单个模型的彻底自我审查），并且通常比单次方法包含更强大、更周到和更详细的建议。

运行测试

测试工具：

# 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 the sage-plan tool OPENAI_API_KEY=your_openai_key GEMINI_API_KEY=your_gemini_key node test/run-sage-plan.js # Test the model selection logic specifically OPENAI_API_KEY=your_openai_key GEMINI_API_KEY=your_gemini_key node test/test-o3.js

注意：由于 sage-plan 测试需要协调多模型辩论，因此可能需要 5-15 分钟才能运行。

项目结构

src/index.ts ：包含工具定义的主要 MCP 服务器实现
src/pack.ts ：将文件打包成结构化 XML 格式的工具
src/tokenCounter.ts ：用于计数提示中的令牌的实用程序
src/gemini.ts ：Gemini API 客户端实现
src/openai.ts ：O3 模型的 OpenAI API 客户端实现
src/debateOrchestrator.ts ：Sage Plan 的多模型辩论编排
src/prompts/debatePrompts.ts ：辩论提示和说明的模板
test/run-test.js ：测试 sage-opinion 工具
test/test-expert.js ：测试 sage-review 工具
test/run-sage-plan.js ：测试 sage-plan 工具
test/test-o3.js ：测试模型选择逻辑

执照

国际学习中心

MCP Sage

`mcp-sage`

基本原理

模型选择

灵感

概述

`sage-opinion`

`sage-review`

`sage-plan`

sage-plan - 多模型和自我辩论工作流程

1. 多模式辩论流程

2. 自我辩论流程 - 单一模式可选

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

性能和成本考虑

先决条件

安装

环境变量

用法

提示

调试和监控

使用工具

sage-opinion 工具

sage-review 工具

sage-plan工具

运行测试

项目结构

执照

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API