Skip to main content
Glama
Sign In
deenesjakoruzh

MCP Sage

by jalehman
GitHub
JavaScript
4
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

mcp-sage

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

基本原理

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

模型选择

服务器根据令牌数量和可用的 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 才能使回退功能正常工作

灵感

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

概述

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

sage-opinion

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

sage-review

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

sage-plan

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

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

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

1. 多模式辩论流程

多模式辩论的关键阶段：

设置阶段

  • 系统确定可用模型，选择评委，并分配代币预算

第一轮

  • 生成阶段- 每个可用模型（A、B、C 等）并行编写自己的实施计划
  • 批判阶段——每个模型都会审查所有其他计划（而不是自己的计划），并同时产生结构化批判

将 2 舍入到 N （N 默认为 3）

  1. 综合阶段——每个模型使用收到的批评来改进其先前的计划（模型并行工作）
  2. 共识检查——评判模型对所有当前计划之间的相似性进行评分
    • 如果分数≥0.9，辩论将提前结束并进入判断环节
  3. 批评阶段- 如果未达成共识且未进入最后一轮，则每个模型将再次批评所有其他计划（并行）

判断阶段

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

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

  1. 初始爆发- 该模型生成三个不同的计划，每个计划采用不同的方法
  2. 细化轮次- 对于每个后续轮次（2 到 N，默认 N=3）：
    • 该模型回顾了所有先前的计划
    • 它在内部进行批评，找出优势和劣势
    • 它制定了一个新的改进计划，解决了早期计划中的局限性
  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/"] } } }

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

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

该计划受益于多个 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 ：测试模型选择逻辑

执照

国际学习中心

You must be authenticated.

A
security – no known vulnerabilities
F
license - not found
A
quality - confirmed to work

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

MCP 服务器通过在提示中嵌入文件内容，提供从 Gemini 2.5 Pro 获取第二意见或详细代码审查的工具，使其能够处理具有广泛上下文的大型代码库。

  1. 基本原理
    1. 模型选择
      1. 灵感
        1. 概述
          1. sage-opinion
          2. sage-review
          3. sage-plan
          4. sage-plan - 多模型和自我辩论工作流程
          5. 代码中实际发生了什么（快速参考）
        2. 先决条件
          1. 安装
            1. 环境变量
              1. 用法
                1. 提示
                  1. 调试和监控
                  2. 使用工具
                2. 运行测试
                  1. 项目结构
                    1. 执照

                      Related MCP Servers

                      • Gemini Thinking Server

                        bartekke8it56w2
                        A
                        security
                        F
                        license
                        A
                        quality
                        An MCP server implementation that leverages Google's Gemini API to provide analytical problem-solving capabilities through sequential thinking steps without code generation.
                        Last updated -
                        1
                        14
                        JavaScript

                      • Yellhorn MCP

                        msnidal
                        A
                        security
                        F
                        license
                        A
                        quality
                        An MCP server that connects Gemini 2.5 Pro to Claude Code, enabling users to generate detailed implementation plans based on their codebase and receive feedback on code changes.
                        Last updated -
                        2
                        3
                        Python
                        • Linux
                        • Apple

                      • MCP Gemini Server

                        Novakiki
                        -
                        security
                        A
                        license
                        -
                        quality
                        An MCP server that enables other AI models (like Claude) to use Google's Gemini models as tools for specific tasks through a standardized interface.
                        Last updated -
                        1
                        TypeScript
                        MIT License

                      • Gemini Thinking MCP Server

                        falahgs
                        -
                        security
                        -
                        license
                        -
                        quality
                        A Model Context Protocol (MCP) server implementation for the Google Gemini language model. This server allows Claude Desktop users to access the powerful reasoning capabilities of Gemini-2.0-flash-thinking-exp-01-21 model.
                        Last updated -
                        JavaScript
                        MIT License

                      View all related MCP servers

                      New MCP Servers

                      MCP directory API

                      We provide all the information about MCP servers via our MCP API.

                      curl -X GET 'https://glama.ai/api/mcp/v1/servers/jalehman/mcp-sage'

                      If you have feedback or need assistance with the MCP directory API, please join our Discord server