MCP Sage

mcp-sage

Un servidor MCP (Protocolo de Contexto de Modelo) que proporciona herramientas para enviar solicitudes al modelo O3 de OpenAI o a Gemini 2.5 Pro de Google, según el número de tokens. Las herramientas integran todas las rutas de archivo referenciadas (de forma recursiva para las carpetas) en la solicitud. Esto resulta útil para obtener segundas opiniones o revisiones de código detalladas de un modelo capaz de gestionar gran cantidad de contexto con precisión.

Razón fundamental

Uso Claude Code con frecuencia. Es un producto excelente que se adapta bien a mi flujo de trabajo. Sin embargo, los modelos más recientes con gran cantidad de contexto parecen muy útiles para trabajar con bases de código más complejas donde se necesita más contexto. Esto me permite seguir usando Claude Code como herramienta de desarrollo y, al mismo tiempo, aprovechar las amplias capacidades de contexto de O3 y Gemini 2.5 Pro para ampliar el contexto limitado de Claude Code.

Selección de modelos

El servidor selecciona automáticamente el modelo apropiado según el recuento de tokens y las claves API disponibles:

• Para contextos más pequeños (≤ 200 000 tokens): utiliza el modelo O3 de OpenAI (si OPENAI_API_KEY está configurado)
• Para contextos más grandes (> 200 000 y ≤ 1 000 000 de tokens): utiliza Gemini 2.5 Pro de Google (si GEMINI_API_KEY está configurado)
• Si el contenido supera 1 millón de tokens: devuelve un error informativo

Comportamiento de respaldo:

• Clave API de respaldo :
  • Si falta OPENAI_API_KEY, se utilizará Gemini para todos los contextos dentro de su límite de tokens de 1 millón
  • Si falta GEMINI_API_KEY, solo se pueden procesar contextos más pequeños (≤ 200K tokens) con O3
  • Si faltan ambas claves API, se devuelve un error informativo
• Conectividad de red alternativa :
  • Si la API de OpenAI no está disponible (error de red), el sistema recurre automáticamente a Gemini.
  • Esto proporciona resiliencia frente a problemas de red temporales con un proveedor.
  • Requiere que GEMINI_API_KEY esté configurado para que la opción de respaldo funcione

Inspiración

Este proyecto se inspira en otros dos proyectos de código abierto:

• simonw/files-to-prompt para la compresión de archivos
• asadm/vibemode por la idea y la solicitud para enviar el repositorio completo a Gemini para obtener sugerencias de edición al por mayor
• PhialsBasement/Chain-of-Recursive-Thoughts, inspiración para la herramienta Sage-Plan

Descripción general

Este proyecto implementa un servidor MCP que expone tres herramientas:

sage-opinion

1. Toma un mensaje y una lista de rutas de archivos/directorios como entrada
2. Empaqueta los archivos en un formato XML estructurado
3. Mide el número de tokens y selecciona el modelo apropiado:
   • O3 para ≤ 200K tokens
   • Gemini 2.5 Pro para más de 200 000 y menos de 1 000 tokens
4. Envía el mensaje combinado + contexto al modelo seleccionado
5. Devuelve la respuesta del modelo.

sage-review

1. Toma una instrucción para cambios de código y una lista de rutas de archivos/directorios como entrada
2. Empaqueta los archivos en un formato XML estructurado
3. Mide el número de tokens y selecciona el modelo apropiado:
   • O3 para ≤ 200K tokens
   • Gemini 2.5 Pro para más de 200 000 y menos de 1 000 tokens
4. Crea un mensaje especializado que indica al modelo cómo formatear las respuestas usando bloques BUSCAR/REEMPLAZAR
5. Envía el contexto + instrucción combinado al modelo seleccionado
6. Devuelve sugerencias de edición formateadas como bloques de BÚSQUEDA/REEMPLAZAR para una fácil implementación

sage-plan

1. Toma un mensaje solicitando un plan de implementación y una lista de rutas de archivos/directorios como entrada
2. Empaqueta los archivos en un formato XML estructurado
3. Orquesta un debate multimodelo para generar un plan de implementación de alta calidad
4. Los modelos critican y refinan los planes de los demás a través de múltiples rondas.
5. Devuelve el plan de implementación ganador con pasos detallados.

sage-plan - Flujos de trabajo multimodelo y de autodebate

La herramienta sage-plan no le pide a un solo modelo un plan. En cambio, organiza un debate estructurado que se desarrolla en una o más rondas y luego le pide a un modelo de juez independiente (o al mismo modelo en modo CoRT) que elija al ganador.

1. Flujo de debate multimodelo

Fases clave en el debate multimodelo:

Fase de configuración

• El sistema determina los modelos disponibles, selecciona un juez y asigna presupuestos de tokens.

Ronda 1

• Fase de generación : cada modelo disponible (A, B, C, etc.) escribe su propio plan de implementación en paralelo
• Fase de crítica : cada modelo revisa todos los demás planes (nunca el suyo propio) y produce críticas estructuradas en paralelo.

Rondas 2 a N (N por defecto es 3)

1. Fase de síntesis : cada modelo mejora su plan anterior utilizando las críticas que recibió (los modelos trabajan en paralelo)
2. Comprobación de consenso : el modelo del juez evalúa la similitud entre todos los planes actuales
   • Si la puntuación es ≥ 0,9, el debate se detiene antes de tiempo y pasa al Juicio.
3. Fase de crítica : si no se llega a un consenso Y no estamos en la ronda final, cada modelo vuelve a criticar todos los demás planes (en paralelo).

Fase de juicio

• Después de completar todas las rondas (o alcanzar un consenso temprano), el modelo de juez (O3 por defecto):
  • Selecciona el mejor plan único O fusiona varios planes en uno superior
  • Proporciona una puntuación de confianza para su selección/síntesis

2. Flujo de autodebate: modelo único disponible

Cuando solo hay un modelo disponible, se utiliza un enfoque de cadena de pensamientos recursivos (CoRT) :

1. Explosión inicial : el modelo genera tres planes distintos, cada uno con un enfoque diferente
2. Rondas de refinamiento : para cada ronda subsiguiente (2 a N, predeterminado N=3):
   • El modelo revisa todos los planes anteriores
   • Los critica internamente, identificando fortalezas y debilidades.
   • Produce un nuevo plan mejorado que aborda las limitaciones de los planes anteriores.
3. Selección final : el último plan generado se convierte en el plan de implementación final

Qué sucede realmente en el código (referencia rápida)

Consideraciones sobre rendimiento y costos

⚠️ Importante: La herramienta sage-plan puede:

• Toma una cantidad significativa de tiempo completarlo (5 a 10 minutos con varios modelos)
• Consumir una cantidad sustancial de tokens API debido a múltiples rondas de debate
• Incurren en costos más altos que los enfoques de modelo único

Uso típico de recursos:

• Debate multimodelo: 2-4 veces más tokens que con un enfoque de modelo único
• Tiempo de procesamiento: 5-10 minutos dependiendo de la complejidad y disponibilidad del modelo.
• Costos de API: $0,30 a $1,50 por generación de plan (varía según los modelos utilizados y la complejidad del plan)

Prerrequisitos

• Node.js (v18 o posterior)
• Una clave API de Google Gemini (para contextos más amplios)
• Una clave API de OpenAI (para contextos más pequeños)

Instalación

Variables de entorno

Establezca las siguientes variables de entorno:

• OPENAI_API_KEY : Su clave API de OpenAI (para el modelo O3)
• GEMINI_API_KEY : Su clave API de Google Gemini (para Gemini 2.5 Pro)

Uso

Después de compilar con npm run build , agregue lo siguiente a su configuración de MCP:

También puedes utilizar variables de entorno configuradas en otro lugar, como en tu perfil de shell.

Incitación

Para obtener una segunda opinión sobre algo, simplemente solicite una segunda opinión.

Para obtener una revisión de código, solicite una revisión de código o una revisión de un experto.

Ambos se benefician al proporcionar rutas de archivos que desea que se incluyan en el contexto, pero si se omiten, el LLM del host probablemente inferirá qué incluir.

Depuración y monitorización

El servidor proporciona información de monitorización detallada mediante la función de registro de MCP. Estos registros incluyen:

• Estadísticas de uso de tokens y selección de modelos
• Número de archivos y documentos incluidos en la solicitud
• Métricas del tiempo de procesamiento de solicitudes
• Información de error cuando se superan los límites de tokens

Los registros se envían mediante el método notifications/message del protocolo MCP, lo que garantiza que no interfieran con la comunicación JSON-RPC. Los clientes MCP compatibles con el registro mostrarán estos registros correctamente.

Ejemplos de entradas de registro:

Usando las herramientas

Herramienta de opinión de sabios

La herramienta sage-opinion acepta los siguientes parámetros:

• prompt (cadena, obligatorio): el mensaje que se enviará al modelo seleccionado
• paths (matriz de cadenas, obligatoria): lista de rutas de archivos para incluir como contexto

Ejemplo de llamada a la herramienta MCP (usando JSON-RPC 2.0):

Herramienta de revisión de sage

La herramienta sage-review acepta los siguientes parámetros:

• instruction (cadena, obligatoria): Los cambios o mejoras específicos necesarios
• paths (matriz de cadenas, obligatoria): lista de rutas de archivos para incluir como contexto

Ejemplo de llamada a la herramienta MCP (usando JSON-RPC 2.0):

La respuesta contendrá bloques BUSCAR/REEMPLAZAR que puedes usar para implementar los cambios sugeridos:

Herramienta de planificación de salvia

La herramienta sage-plan acepta los siguientes parámetros:

• prompt (cadena, obligatorio): Descripción de lo que necesita un plan de implementación para
• paths (matriz de cadenas, obligatoria): lista de rutas de archivos para incluir como contexto

Ejemplo de llamada a la herramienta MCP (usando JSON-RPC 2.0):

La respuesta contiene un plan de implementación detallado con:

1. Descripción general de la arquitectura de alto nivel
2. Pasos de implementación específicos
3. Se necesitan cambios de archivo
4. Estrategia de prueba
5. Posibles desafíos y mitigaciones

Este plan se beneficia de la inteligencia colectiva de múltiples modelos de IA (o de una autoevaluación exhaustiva por parte de un solo modelo) y generalmente contiene recomendaciones más sólidas, reflexivas y detalladas que un enfoque de una sola pasada.

Ejecución de las pruebas

Para probar las herramientas:

Nota : La prueba del plan sabio puede tardar entre 5 y 15 minutos en ejecutarse, ya que organiza un debate de múltiples modelos.

Estructura del proyecto

• src/index.ts : La implementación principal del servidor MCP con definiciones de herramientas
• src/pack.ts : Herramienta para empaquetar archivos en un formato XML estructurado
• src/tokenCounter.ts : Utilidades para contar tokens en un mensaje
• src/gemini.ts : Implementación del cliente API de Gemini
• src/openai.ts : Implementación del cliente de API de OpenAI para el modelo O3
• src/debateOrchestrator.ts : Orquestación de debates multimodelo para sage-plan
• src/prompts/debatePrompts.ts : Plantillas para indicaciones e instrucciones de debate
• test/run-test.js : Prueba para la herramienta sage-opinion
• test/test-expert.js : Prueba para la herramienta sage-review
• test/run-sage-plan.js : Prueba para la herramienta sage-plan
• test/test-o3.js : Prueba de la lógica de selección del modelo

Licencia

ISC