mcp-sage

MCP（モデルコンテキストプロトコル）サーバーは、トークン数に基づいてOpenAIのO3モデルまたはGoogleのGemini 2.5 Proにプロンプトを送信するためのツールを提供します。これらのツールは、参照されているすべてのファイルパス（フォルダの場合は再帰的に）をプロンプトに埋め込みます。これは、大量のコンテキストを正確に処理できるモデルからセカンドオピニオンや詳細なコードレビューを得るのに役立ちます。

根拠

Claude Codeを頻繁に使用しています。私のワークフローに非常によく合う素晴らしい製品です。大容量のコンテキストを備えた新しいモデルは、より多くのコンテキストが必要となる複雑なコードベースを扱う際に非常に便利です。これにより、Claude Codeを開発ツールとして使い続けながら、O3とGemini 2.5 Proの大容量コンテキスト機能を活用して、Claude Codeの限られたコンテキストを補うことができます。

Related MCP server: Claude Code Review MCP

モデル選択

サーバーは、トークン数と利用可能な API キーに基づいて適切なモデルを自動的に選択します。

• 小さいコンテキスト（20万トークン以下）の場合：OpenAIのO3モデルを使用します（OPENAI_API_KEYが設定されている場合）

• より大きなコンテキスト（200K以上100万トークン以下）の場合：GoogleのGemini 2.5 Proを使用します（GEMINI_API_KEYが設定されている場合）

• コンテンツが100万トークンを超える場合: 情報エラーを返します

フォールバック動作:

• APIキーフォールバック:

  • OPENAI_API_KEY がない場合、100万トークン制限内のすべてのコンテキストで Gemini が使用されます。

  • GEMINI_API_KEY がない場合、O3 では小さいコンテキスト (≤ 200K トークン) のみを処理できます。

  • 両方のAPIキーが欠落している場合は、情報エラーが返されます。

• ネットワーク接続フォールバック:

  • OpenAI APIにアクセスできない場合（ネットワークエラー）、システムは自動的にGeminiにフォールバックします。

  • これにより、1つのプロバイダによる一時的なネットワーク問題に対する耐性が強化されます。

  • フォールバックが機能するには GEMINI_API_KEY を設定する必要があります

インスピレーション

このプロジェクトは、他の 2 つのオープン ソース プロジェクトからインスピレーションを得ています。

• simonw/files-to-prompt でファイル圧縮を要求

• アイデアを提供してくれたasadm/vibemode さん、そしてリポジトリ全体を Gemini に送信して編集の提案をまとめてもらえるよう促してくれた

• PhialsBasement/Chain-of-Recursive-Thoughts は、 sage-plan ツールのインスピレーションとなりました。

概要

このプロジェクトでは、次の 3 つのツールを公開する MCP サーバーを実装します。

sage-opinion

1. プロンプトとファイル/ディレクトリパスのリストを入力として受け取ります

2. ファイルを構造化されたXML形式にパックします

3. トークン数を測定し、適切なモデルを選択します。

   • 20万トークン以下の場合はO3

   • 20万トークン以上100万トークン以下のGemini 2.5 Pro

4. 選択したモデルにプロンプトとコンテキストの組み合わせを送信します

5. モデルの応答を返す

sage-review

1. コード変更の指示とファイル/ディレクトリパスのリストを入力として受け取ります

2. ファイルを構造化されたXML形式にパックします

3. トークン数を測定し、適切なモデルを選択します。

   • 20万トークン以下の場合はO3

   • 20万トークン以上100万トークン以下のGemini 2.5 Pro

4. SEARCH/REPLACEブロックを使用してモデルに応答をフォーマットするように指示する特別なプロンプトを作成します。

5. 選択したモデルにコンテキストと指示の組み合わせを送信します

6. 簡単に実装できるように、SEARCH/REPLACE ブロックとしてフォーマットされた編集候補を返します。

sage-plan

1. 実装計画とファイル/ディレクトリパスのリストを要求するプロンプトを入力として受け取ります

2. ファイルを構造化されたXML形式にパックします

3. 複数のモデルに関する議論を調整し、高品質の実装計画を作成します。

4. モデルは複数のラウンドを通じて互いの計画を批評し、改良する

5. 詳細な手順を含む、成功した実装計画を返します

sage-plan - マルチモデルと自己討論ワークフロー

sage-planツールは、単一のモデルにプランを求めるのではなく、1ラウンド以上にわたる構造化されたディベートを編成し、その後、別の審査員モデル（または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）は次のようになります。

  • 最適なプランを1つ選択するか、複数のプランを1つの優れたプランに統合します

  • 選択/合成の信頼スコアを提供する

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

利用できるモデルが 1 つしかない場合は、 Chain of Recursive Thoughts (CoRT)アプローチが使用されます。

1. 初期バースト- モデルは3つの異なる計画を生成し、それぞれ異なるアプローチを採用します。

2. 改良ラウンド- 後続の各ラウンド (2 ～ N、デフォルト N = 3):

   • モデルは過去の計画をすべて見直す

   • 内部的に批評し、強みと弱みを特定する

   • 以前の計画の限界を克服した新しい改善計画を1つ作成する

3. 最終選択- 最後に生成された計画が最終的な実装計画になります

コード内で実際に何が起こるか（クイックリファレンス）

パフォーマンスとコストの考慮

⚠️ 重要: sage-plan ツールでは次のことが可能です。

• 完了するまでにかなりの時間がかかります（複数のモデルの場合は 5 ～ 10 分）

• 複数回の議論により大量のAPIトークンを消費する

• 単一モデルのアプローチよりもコストが高くなる

一般的なリソース使用量:

• マルチモデルの議論：単一モデルアプローチよりも2～4倍多くのトークン

• 処理時間: 複雑さとモデルの可用性に応じて 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

シェル プロファイルなど、他の場所で設定された環境変数を使用することもできます。

促す

何かについてセカンドオピニオンを得るには、セカンドオピニオンを求めてください。

コードレビューを受けるには、コードレビューまたは専門家によるレビューを依頼してください。

これらは両方とも、コンテキストに含めるファイルのパスを提供することでメリットを得られますが、省略すると、ホスト 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 : モデル選択ロジックのテスト

ライセンス

ISC