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

토큰 개수에 따라 OpenAI의 O3 모델 또는 Google의 Gemini 2.5 Pro에 프롬프트를 전송하는 도구를 제공하는 MCP(Model Context Protocol) 서버입니다. 이 도구는 참조된 모든 파일 경로(폴더에 대해 재귀적으로)를 프롬프트에 포함합니다. 이는 방대한 컨텍스트를 정확하게 처리할 수 있는 모델로부터 다른 의견이나 자세한 코드 검토를 받는 데 유용합니다.

이론적 해석

저는 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가 누락된 경우 O3에서는 더 작은 컨텍스트(≤ 200K 토큰)만 처리할 수 있습니다.
    • 두 API 키가 모두 누락된 경우 정보 오류가 반환됩니다.
  • 네트워크 연결 대체 :
    • OpenAI API에 접근할 수 없는 경우(네트워크 오류) 시스템은 자동으로 Gemini로 돌아갑니다.
    • 이는 한 공급자와의 일시적인 네트워크 문제에 대한 회복성을 제공합니다.
    • 폴백이 작동하려면 GEMINI_API_KEY를 설정해야 합니다.

영감

이 프로젝트는 두 가지 다른 오픈 소스 프로젝트에서 영감을 얻었습니다.

개요

이 프로젝트는 세 가지 도구를 제공하는 MCP 서버를 구현합니다.

sage-opinion

  1. 프롬프트와 파일/디렉토리 경로 목록을 입력으로 받습니다.
  2. 파일을 구조화된 XML 형식으로 압축합니다.
  3. 토큰 수를 측정하고 적절한 모델을 선택합니다.
    • ≤ 200K 토큰의 경우 O3
    • Gemini 2.5 Pro는 20만 개 이상, 100만 개 이하 토큰에 적용됩니다.
  4. 선택된 모델에 결합된 프롬프트 + 컨텍스트를 보냅니다.
  5. 모델��� 응답을 반환합니다.

sage-review

  1. 코드 변경에 대한 지침과 파일/디렉토리 경로 목록을 입력으로 받습니다.
  2. 파일을 구조화된 XML 형식으로 압축합니다.
  3. 토큰 수를 측정하고 적절한 모델을 선택합니다.
    • ≤ 200K 토큰의 경우 O3
    • 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. 다중 모델 토론 흐름

지엑스피1

다중 모델 논쟁의 주요 단계:

설정 단계

  • 시스템은 사용 가능한 모델을 결정하고, 심사위원을 선정하고, 토큰 예산을 할당합니다.

1라운드

  • 생성 단계 - 사용 가능한 모든 모델(A, B, C 등)이 병렬로 자체 구현 계획을 작성합니다.
  • 비판 단계 - 각 모델은 다른 모든 계획(자체 계획은 절대 아님)을 검토하고 동시에 구조화된 비판을 생성합니다.

2에서 N까지 라운드 (N은 기본적으로 3)

  1. 합성 단계 - 각 모델은 받은 비판을 사용하여 이전 계획을 개선합니다(모델은 병렬로 작동합니다)
  2. 합의 확인 - 심사 모델은 모든 현재 계획 간의 유사성을 평가합니다.
    • 점수 ≥ 0.9인 경우 토론은 조기에 중단되고 판단으로 넘어갑니다.
  3. 비판 단계 - 합의에 도달하지 못하고 최종 라운드에 진출하지 못한 경우 각 모델은 다른 모든 계획을 다시 비판합니다(병렬로).

판단 단계

  • 모든 라운드를 완료한 후(또는 조기 합의에 도달한 후), 심사 위원 모델(기본적으로 O3)은 다음과 같습니다.
    • 가장 좋은 단일 계획을 선택하거나 여러 계획을 더 우수한 계획으로 병합합니다.
    • 선택/합성에 대한 신뢰도 점수를 제공합니다.
2. 자기 토론 흐름 - 단일 모델 사용 가능

하나의 모델만 사용 가능한 경우 CoRT(Chain of Recursive Thoughts) 접근 방식이 사용됩니다.

  1. 초기 버스트 - 모델은 각각 다른 접근 방식을 취하는 세 가지 고유한 계획을 생성합니다.
  2. 개선 라운드 - 이후 각 라운드(2~N, 기본값 N=3):
    • 이 모델은 이전의 모든 계획을 검토합니다.
    • 내부적으로 비판하여 강점과 약점을 파악합니다.
    • 이는 이전 계획의 한계를 해결하는 새로운 개선된 계획을 생성합니다.
  3. 최종 선택 - 마지막으로 생성된 계획이 최종 구현 계획이 됩니다.

실제로 코드에서 무슨 일이 일어나는가(빠른 참조)

단계/기능코드 위치노트
세대 프롬프트프롬프트/토론 프롬프트. 생성 프롬프트"#구현 계획(모델 X)"이라는 제목을 추가합니다.
비판적 촉구프롬프트/토론 프롬프트.비평 프롬프트"## 계획 비판 {ID}" 섹션을 사용합니다.
합성 프롬프트프롬프트/토론 프롬프트.합성 프롬프트모델은 자체 계획을 수정합니다.
합의 확인debateOrchestrator.checkConsensus판사 모델은 consensusScore 와 함께 JSON을 반환합니다.
심판프롬프트/토론 프롬프트.판사 프롬프트판사는 "#최종 실행 계획" + 자신감을 반환합니다.
자기 토론 촉구프롬프트/토론Prompts.selfDebatePrompt재귀적 사고의 사슬 루프
성능 및 비용 고려 사항

⚠️ 중요: 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 도구는 다음과 같은 매개변수를 허용합니다.

  • 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 도구는 다음과 같은 매개변수를 허용합니다.

  • 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. 잠재적인 과제와 완화책

이 계획은 여러 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

참고사항 : 세이지 플랜 테스트는 다중 모델 토론을 조직하기 때문에 실행하는 데 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

Gemini 2.5 Pro에서 파일 내용을 프롬프트에 내장하여 다른 사람의 의견이나 자세한 코드 검토를 얻을 수 있는 도구를 제공하는 MCP 서버로, 광범위한 컨텍스트를 가진 대규모 코드베이스를 처리할 수 있습니다.

  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