mcp-sage

Сервер MCP (Model Context Protocol), который предоставляет инструменты для отправки запросов либо в модель O3 OpenAI, либо в Gemini 2.5 Pro от Google на основе количества токенов. Инструменты встраивают все указанные пути к файлам (рекурсивно для папок) в запрос. Это полезно для получения вторых мнений или подробных обзоров кода из модели, которая может точно обрабатывать множество контекстов.

Обоснование

Я активно использую Claude Code. Это отличный продукт, который хорошо подходит для моего рабочего процесса. Новые модели с большим объемом контекста кажутся действительно полезными для работы с более сложными кодовыми базами, где требуется больше контекста. Это позволяет мне продолжать использовать Claude Code в качестве инструмента разработки, одновременно используя возможности большого контекста O3 и Gemini 2.5 Pro для расширения ограниченного контекста Claude Code.

Related MCP server: Gemini Thinking MCP Server

Выбор модели

Сервер автоматически выбирает подходящую модель на основе количества токенов и доступных ключей API:

• Для меньших контекстов (≤ 200 тыс. токенов): использует модель O3 OpenAI (если установлен OPENAI_API_KEY)

• Для больших контекстов (> 200 тыс. и ≤ 1 млн токенов): использует Gemini 2.5 Pro от Google (если установлен GEMINI_API_KEY)

• Если содержимое превышает 1 млн токенов: возвращает информационную ошибку.

Резервное поведение:

• Резервный ключ API :

  • Если OPENAI_API_KEY отсутствует, Gemini будет использоваться для всех контекстов в пределах лимита в 1 млн токенов.

  • Если GEMINI_API_KEY отсутствует, с помощью O3 можно обрабатывать только меньшие контексты (≤ 200 тыс. токенов)

  • Если оба ключа API отсутствуют, возвращается информационная ошибка.

• Резервное сетевое подключение :

  • Если API OpenAI недоступен (ошибка сети), система автоматически возвращается к Gemini.

  • Это обеспечивает устойчивость к временным сбоям в работе сети у одного провайдера.

  • Для работы резервного варианта требуется установить GEMINI_API_KEY

Вдохновение

Этот проект черпает вдохновение из двух других проектов с открытым исходным кодом:

• simonw/files-to-prompt для сжатия файлов

• asadm/vibemode за идею и предложение отправить весь репозиторий в Gemini для предложений по оптовому редактированию

• PhialsBasement/Chain-of-Recursive-Thoughts вдохновение для инструмента sage-plan

Обзор

В этом проекте реализован сервер MCP, предоставляющий три инструмента:

sage-opinion

1. Принимает в качестве входных данных приглашение и список путей к файлам/каталогам.

2. Упаковывает файлы в структурированный формат XML

3. Измеряет количество токенов и выбирает подходящую модель:

   • O3 для ≤ 200 тыс. токенов

   • Gemini 2.5 Pro для > 200 тыс. и ≤ 1 млн токенов

4. Отправляет объединенную подсказку + контекст в выбранную модель

5. Возвращает ответ модели

sage-review

1. Принимает в качестве входных данных инструкцию по изменению кода и список путей к файлам/каталогам.

2. Упаковывает файлы в структурированный формат XML

3. Измеряет количество токенов и выбирает подходящую модель:

   • O3 для ≤ 200 тыс. токенов

   • Gemini 2.5 Pro для > 200 тыс. и ≤ 1 млн токенов

4. Создает специализированную подсказку, указывающую модели форматировать ответы с использованием блоков ПОИСК/ЗАМЕНА

5. Отправляет объединенный контекст + инструкцию выбранной модели

6. Возвращает предложения по редактированию, отформатированные как блоки ПОИСК/ЗАМЕНА для легкой реализации

sage-plan

1. Принимает в качестве входных данных запрос на план внедрения и список путей к файлам/каталогам.

2. Упаковывает файлы в структурированный формат XML

3. Организует многомодельные дебаты для разработки высококачественного плана внедрения

4. Модели критикуют и совершенствуют планы друг друга в ходе нескольких раундов.

5. Возвращает выигрышный план внедрения с подробными шагами

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<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 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

Ключевые этапы дискуссии о мультимоделях:

Фаза настройки

• Система определяет доступные модели, выбирает судью и распределяет бюджеты токенов.

Раунд 1

• Фаза генерации — каждая доступная модель (A, B, C и т. д.) параллельно пишет свой собственный план внедрения.

• Фаза критики — каждая модель рассматривает все другие планы (но не свои собственные) и параллельно выдает структурированную критику.

Округляет от 2 до N (N по умолчанию равно 3)

1. Фаза синтеза — каждая модель улучшает свой предыдущий план, используя полученные критические замечания (модели работают параллельно).

2. Проверка консенсуса — модель судьи оценивает сходство между всеми текущими планами.

   • Если оценка ≥ 0,9, дебаты прекращаются раньше времени и переходят к суждению.

3. Фаза критики — если консенсус не достигнут И мы не в финальном раунде, каждая модель снова критикует все остальные планы (параллельно)

Фаза суждения

• После завершения всех раундов (или достижения раннего консенсуса) модель судьи (по умолчанию 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<br/>*different approach*]
    P2 --> P3[Generate Plan 3<br/>*different approach*]
  end

  subgraph RN["Rounds 2 to N"]
    direction TB
    REF[Generate Improved Plan<br/>*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) :

1. Начальный всплеск — модель генерирует три отдельных плана, каждый из которых использует свой подход.

2. Раунды уточнения — для каждого последующего раунда (от 2 до N, по умолчанию N=3):

   • Модель рассматривает все предыдущие планы

   • Он критикует их изнутри, выявляя сильные и слабые стороны.

   • Создает один новый улучшенный план, который устраняет ограничения более ранних планов.

3. Окончательный выбор — последний сформированный план становится окончательным планом реализации.

Что на самом деле происходит в коде (краткая справка)

Соображения производительности и стоимости

⚠️ Важно: инструмент sage-plan может:

• Выполнение займет значительное время (5–10 минут для нескольких моделей)

• Потребление значительных токенов API из-за многочисленных раундов дебатов

• Более высокие затраты, чем при подходах с одной моделью

Типичное использование ресурсов:

• Многомодельные дебаты: в 2–4 раза больше токенов, чем при подходе с одной моделью

• Время обработки: 5-10 минут в зависимости от сложности и доступности модели.

• Стоимость API: 0,30–1,50 долл. США за генерацию плана (зависит от используемых моделей и сложности плана)

Предпосылки

• Node.js (v18 или более поздняя версия)

• Ключ API Google Gemini (для более масштабных контекстов)

• Ключ API OpenAI (для меньших контекстов)

Установка

# 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 : Ваш ключ API Google Gemini (для 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

Вы также можете использовать переменные окружения, заданные в другом месте, например, в профиле оболочки.

Подсказка

Чтобы получить второе мнение по какому-либо вопросу, просто попросите высказать второе мнение.

Чтобы получить обзор кода, попросите провести обзор кода или экспертную оценку.

Оба варианта выигрывают от предоставления путей к файлам, которые вы хотите включить в контекст, но если они не указаны, то хост-LLM, вероятно, сам определит, что именно следует включить.

Отладка и мониторинг

Сервер предоставляет подробную информацию о мониторинге через возможность ведения журнала MCP. Эти журналы включают:

• Статистика использования токенов и выбор модели

• Количество файлов и документов, включенных в запрос

• Метрики времени обработки запроса

• Информация об ошибке при превышении лимита токенов

Журналы отправляются с помощью метода notifications/message протокола MCP, что гарантирует, что они не будут мешать коммуникации 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 принимает следующие параметры:

• 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 принимает следующие параметры:

• 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. Потенциальные проблемы и пути их смягчения

Этот план использует коллективный интеллект нескольких моделей ИИ (или тщательную самопроверку одной моделью) и обычно содержит более надежные, продуманные и подробные рекомендации, чем подход с одним проходом.

Проведение тестов

Для тестирования инструментов:

# 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

Примечание : выполнение теста на мудрый план может занять 5–15 минут, поскольку он организует многомодельные дебаты.

Структура проекта

• src/index.ts : Основная реализация сервера MCP с определениями инструментов

• src/pack.ts : Инструмент для упаковки файлов в структурированный формат XML

• src/tokenCounter.ts : Утилиты для подсчета токенов в приглашении

• src/gemini.ts : Реализация клиента API Gemini

• src/openai.ts : Реализация клиента API OpenAI для модели O3

• 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 : Тест логики выбора модели

Лицензия

МСК