ndlovu-code-reviewer

Servidor MCP de Revisión de Código

Un asistente de revisión de código impulsado por Gemini-CLI (por ahora), que se ejecuta como un servidor del Protocolo de Contexto de Modelo (MCP).

Por qué existe este proyecto

Las revisiones de código manuales consumen mucho tiempo y a menudo pierden la oportunidad de combinar el análisis estático con comentarios contextuales y amigables para humanos. Este proyecto se creó para experimentar con herramientas MCP que brindan a los asistentes de IA acceso a un revisor especializado:

• Automatiza el trabajo tedioso de recopilar diferencias y resultados de lint de cambios locales no confirmados.
• Transmite ese contexto al CLI de Gemini para que el modelo pueda enfocarse en información accionable.
• Devuelve una revisión JSON estructurada que encaja naturalmente en clientes compatibles con MCP.

Qué hace

• Se conecta a clientes MCP a través de stdio usando el @modelcontextprotocol/sdk oficial.
• Ejecuta un flujo de trabajo de revisión "híbrido" que recopila la salida de git diff y los hallazgos del linter.
• Alterna entre ESLint, JSHint y TypeScript para maximizar la cobertura en todos los proyectos.
• Invoca de forma segura el CLI de Gemini, manejando prompts largos y tiempos de espera.
• Se distribuye como TypeScript con tipos respaldados por Zod para respuestas MCP predecibles.

Requisitos

• Node.js 18 o posterior (se utilizan módulos ES y AbortSignals en todo el proyecto).
• npm (instalado con Node.js).
• Git (se utiliza para recopilar diferencias locales).
• CLI de Google Gemini (gemini) instalado y autenticado. Consulta la guía de inicio rápido de Gemini para instrucciones de configuración.

Instalación

git clone https://github.com/<your-org>/ndlovu-code-reviewer.git
cd ndlovu-code-reviewer
npm install
npm run build

Si planeas iterar sobre el código fuente de TypeScript, puedes omitir npm run build y confiar en el script de desarrollo descrito a continuación.

Uso

Iniciar el servidor MCP

npm start

El servidor se comunica a través de stdio, por lo que está listo para registrarse con cualquier cliente compatible con MCP (por ejemplo, integraciones de IDE o entornos de asistente). Una vez conectado, llama a la herramienta review-local-changes para activar el análisis híbrido y recibir la revisión JSON.

Cómo llamar a la herramienta MCP

El servidor expone una única herramienta llamada review-local-changes que realiza un análisis exhaustivo de tus cambios de código locales no confirmados.

Requisitos previos:

• Debes tener cambios no confirmados en tu repositorio git
• Los archivos modificados deben ser archivos JavaScript, TypeScript o Vue (.js, .ts, .tsx, .vue)
• El CLI de Gemini debe estar instalado y autenticado

Usando la herramienta:

Una vez que tu cliente MCP esté conectado al servidor, puedes llamar a la herramienta review-local-changes. La herramienta:

1. Detecta cambios automáticamente - Encuentra todos los archivos JS/TS/Vue modificados o añadidos usando git diff
2. Ejecuta análisis estático - Ejecuta el mejor linter disponible (ESLint, JSHint o compilador de TypeScript)
3. Realiza revisión de IA - Envía el contexto combinado al CLI de Gemini para un análisis inteligente
4. Devuelve resultados estructurados - Proporciona una respuesta JSON con hallazgos y recomendaciones

Cómo usarlo con Claude Code:

Para obtener los mejores resultados, sé explícito sobre el uso de la funcionalidad de revisión de código. Aunque las solicitudes en lenguaje natural a veces funcionan, el enfoque más confiable es usar palabras clave específicas:

Solicitudes más confiables (recomendadas):

• "Usa la herramienta de revisión de código para analizar mis cambios"
• "Ejecuta una revisión de código en mis cambios locales"
• "Realiza una revisión de código exhaustiva de mis cambios no confirmados"
• "Analiza mis cambios de código con análisis estático"

Solicitudes en lenguaje natural (pueden funcionar pero son menos confiables):

• "Por favor revisa mis cambios locales"
• "¿Puedes analizar los cambios de código que he hecho?"

Invocación explícita de la herramienta (la más confiable):

• "Usa la herramienta review-local-changes"
• "Llama a la herramienta review-local-changes para verificar mis modificaciones"

La herramienta ha sido mejorada con descripciones más detalladas para ayudar a Claude a reconocer cuándo usarla, pero ser específico sobre "revisión de código", "analizar cambios" o mencionar el nombre de la herramienta directamente te dará los resultados más consistentes.

Formato de salida de ejemplo:

{
  "summary": "Overview of changes made",
  "assessment": "Overall code quality evaluation",
  "findings": [
    {
      "filePath": "src/example.js",
      "lineNumber": 42,
      "severity": "warning",
      "category": "style",
      "comment": "Detailed explanation of the issue",
      "suggestion": "Specific recommendation for improvement"
    }
  ]
}

Nota: Si no se han modificado archivos relevantes, la herramienta devolverá un mensaje de "No se modificaron archivos relevantes", lo cual es un comportamiento normal.

Desarrollo local

• npm run dev – Inicia el servidor con ts-node para iteración rápida.
• npm run build – Produce la salida de JavaScript compilado en dist/.

La estructura del proyecto es intencionalmente pequeña:

• src/ – Código fuente de TypeScript para el servidor MCP.
• dist/ – JavaScript compilado creado por npm run build.
• assets/ – Recursos estáticos, incluido el logotipo utilizado arriba.

Conexión desde clientes MCP

Antes de conectar el servidor a cualquier cliente, asegúrate de haber ejecutado npm run build para que dist/index.js exista. Los comandos a continuación asumen que ejecutas el cliente desde la raíz del repositorio para que el servidor pueda leer tu espacio de trabajo git.

Claude Code (extensión de VS Code)

1. En VS Code, abre la paleta de comandos (Cmd/Ctrl+Shift+P) y ejecuta Claude: Edit Config File.

2. Localiza la sección mcpServers (crédala si es necesario) y añade una entrada similar a:

   {
     "mcpServers": {
       "ndlovu-code-reviewer": {
         "command": "node",
         "args": ["/absolute/path/to/ndlovu-code-reviewer/dist/index.js"],
         "cwd": "/absolute/path/to/ndlovu-code-reviewer"
       }
     }
   }
   

3. Guarda el archivo y ejecuta Claude: Restart Claude Code (o recarga VS Code) para que el servidor aparezca en Herramientas.

4. Habilita la herramienta para una conversación; Claude Code transmitirá los resultados de review-local-changes directamente en la barra lateral.

CLI de Gemini

1. Desde la raíz del proyecto ejecuta:

   gemini mcp add ndlovu-code-reviewer node $(pwd)/dist/index.js
   

2. Verifica el registro con gemini mcp list.

3. Inicia gemini desde el mismo directorio del repositorio y usa la herramienta review-local-changes (por ejemplo, ejecuta :tools en el CLI y selecciónala). El CLI inicia el servidor y reenvía la salida estándar de vuelta como la revisión JSON.

Roo Code

1. Abre Roo Code y haz clic en el icono del servidor en la parte superior del panel de Roo.

2. Elige Añadir Servidor MCP → STDIO y completa:

   • Nombre: ndlovu-code-reviewer
   • Comando: node
   • Argumentos: /absolute/path/to/ndlovu-code-reviewer/dist/index.js
   • Directorio de trabajo: /absolute/path/to/ndlovu-code-reviewer

3. Guarda la configuración y habilita el servidor para tu espacio de trabajo. Roo lo almacena en el archivo global mcp_settings.json o en el del proyecto .roo/mcp.json.

4. Para compartir con compañeros de equipo, confirma un .roo/mcp.json que contenga tu comando de inicio preferido, por ejemplo:

   {
     "mcpServers": {
       "ndlovu-code-reviewer": {
         "command": "npm",
         "args": ["run", "start"],
         "cwd": "."
       }
     }
   }
   

   Roo resuelve el directorio de trabajo relativo a la raíz del proyecto, por lo que el script npm run start se basa en los scripts de paquete del propio repositorio.

CLI de Codex

1. Registra el servidor una vez:

   codex mcp add ndlovu-code-reviewer node $(pwd)/dist/index.js
   

2. Usa codex mcp list para confirmar la entrada, luego inicia Codex desde la raíz del repositorio. El CLI expone review-local-changes como una herramienta que puedes llamar dentro de ejecuciones interactivas.

Contribuciones

Las contribuciones son muy bienvenidas. Si tienes ideas para nuevas herramientas, mejores linters o prompts mejorados:

1. Abre un issue o discusión para alinear el alcance.
2. Haz un fork del repositorio y crea una rama de características.
3. Añade o actualiza documentación/pruebas donde ayude a futuros contribuyentes.
4. Envía una solicitud de extracción describiendo el cambio y cómo lo validaste.

Si no estás seguro de por dónde empezar, no dudes en contactarnos—hay mucho espacio para expandir las capacidades del revisor, añadir ejemplos de clientes y ajustar los prompts.

Licencia

Este proyecto está licenciado bajo la Licencia ISC. Consulta LICENSE (si está presente) para más detalles.