`mcp-sage`

Un servidor MCP (Protocolo de Contexto de Modelo) que proporciona herramientas para enviar solicitudes a otro LLM (actualmente solo Gemini 2.5 Pro) que integra todas las rutas de archivo referenciadas (de forma recursiva para carpetas) en la solicitud. Resulta útil para obtener segundas opiniones o revisiones de código detalladas de un modelo que puede 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 el amplio contexto de Gemini 2.5 Pro para ampliar el contexto limitado de Claude Code.

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

Descripción general

Este proyecto implementa un servidor MCP que expone dos herramientas:

`second-opinion`

Toma un mensaje y una lista de rutas de archivos/directorios como entrada
Empaqueta los archivos en un formato XML estructurado
Comprueba si el contenido combinado está dentro del límite de tokens de Gemini (1 millón de tokens)
Envía el mensaje combinado + contexto a Gemini 2.5 Pro
Devuelve la respuesta del modelo.

`expert-review`

Toma una instrucción para cambios de código y una lista de rutas de archivos/directorios como entrada
Empaqueta los archivos en un formato XML estructurado
Comprueba si el contenido combinado está dentro del límite de tokens de Gemini (1 millón de tokens)
Crea un mensaje especializado que indica al modelo cómo formatear las respuestas usando bloques BUSCAR/REEMPLAZAR
Envía el contexto combinado + instrucción a Gemini 2.5 Pro
Devuelve sugerencias de edición formateadas como bloques de BÚSQUEDA/REEMPLAZAR para una fácil implementación

Prerrequisitos

Node.js (v18 o posterior)
Una clave API de Google Gemini

Instalación

# 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

Variables de entorno

Establezca la siguiente variable de entorno:

GEMINI_API_KEY : Su clave API de Google Gemini

Uso

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

GEMINI_API_KEY=XXX node /path/to/this/repo/dist/index.js

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 (tokens utilizados vs. límite de tokens)
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:

Token usage: 1,234 / 1,000,000 tokens (0.12%)
Files included: 3, Document count: 3
Sending request to Gemini with 1,234 tokens...
Received response from Gemini in 982ms

Usando las herramientas

herramienta de segunda opinión

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

prompt (cadena, obligatorio): El mensaje que se enviará a Gemini
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):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "second-opinion",
    "arguments": {
      "prompt": "Explain how this code works",
      "paths": ["path/to/file1.js", "path/to/file2.js"]
    }
  }
}

Herramienta de revisión por expertos

La herramienta expert-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):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "expert-review",
    "arguments": {
      "instruction": "Add error handling to the function",
      "paths": ["path/to/file1.js", "path/to/file2.js"]
    }
  }
}

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

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

Ejecución de las pruebas

Para probar las herramientas:

# Test the second-opinion tool
GEMINI_API_KEY=your_api_key_here node test/run-test.js

# Test the expert-review tool
GEMINI_API_KEY=your_api_key_here node test/test-expert.js

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
test/run-test.js : Prueba para la herramienta de segunda opinión
test/test-expert.js : Prueba para la herramienta de revisión de expertos

Licencia

ISC