Resumidor de código

Una herramienta de línea de comandos que resume los archivos de código en un directorio determinado mediante Gemini Flash 2.0. ¡Ahora compatible con el servidor MCP para la integración con herramientas LLM!

Características

• Procesa recursivamente archivos de código en un directorio
• Respeta las reglas de .gitignore
• Omite directorios irrelevantes como node_modules , dist , etc.
• Resume archivos de código usando Gemini Flash 2.0
• Envía resúmenes a un archivo de texto
• Nivel de detalle y longitud de resumen configurables
• Servidor MCP para integración con Claude Desktop y otras herramientas LLM
• Diseño modular para una fácil integración con otras aplicaciones.
• Gestión segura de claves API
• Autenticación para puntos finales del servidor MCP
• Mecanismo de reintento con retroceso exponencial para llamadas LLM
• Limitación de velocidad para evitar abusos

Requisitos

• Node.js 18+

Instalación

1. Clonar el repositorio
   git clone https://github.com/nicobailon/code-summarizer.git cd code-summarizer
2. Instalar dependencias:
   npm install
3. Crea un archivo .env con tu clave API de Google:
   GOOGLE_API_KEY=your_api_key_here
4. Construir el proyecto:
   npm run build

Configuración e integración del servidor MCP

El resumidor de código incluye un servidor de Protocolo de contexto de modelo (MCP) que permite que las herramientas LLM como Claude Desktop, Cursor AI y Cline accedan a resúmenes de código y contenido de archivos.

Iniciar el servidor MCP

De forma predeterminada, el servidor se ejecuta en el puerto 24312. Puede cambiarlo en su configuración:

Conectando con Claude Desktop

1. Iniciar el servidor MCP del resumen de código
2. Abra Claude Desktop y haga clic en el menú Claude, luego en "Configuración..."
3. Vaya a la sección "Desarrollador"
4. Cree un archivo en ~/.claude/claude_desktop_config.json (macOS/Linux) o %USERPROFILE%\.claude\claude_desktop_config.json (Windows) con este contenido:

5. Reiniciar Claude Desktop
6. Después de reiniciar, puedes pedirle a Claude que acceda a tu base de código, por ejemplo, "Resumir los archivos de mi proyecto".

Ejemplos de indicaciones para Claude Desktop:

• "¿Puedes resumir todos los archivos JavaScript en mi proyecto?"
• "Por favor, deme una descripción general de alto nivel de mi base de código".
• "Explique qué hace el archivo 'src/config/config.ts'".
• "Encuentra todas las funciones relacionadas con la autenticación en mi código".

Conexión con Cursor AI

1. Iniciar el servidor MCP del resumen de código
2. Cree un archivo .cursor/mcp.json en el directorio de su proyecto:

3. Reiniciar el cursor o recargar el proyecto
4. Pregúntele a Cursor sobre su código, por ejemplo, "¿Puede resumir mi código base?"

Ejemplos de indicaciones para el cursor:

• "Resúmeme la estructura de este código base".
• "¿Cuáles son los componentes clave de este proyecto?"
• "Dame una explicación detallada de la implementación del servidor MCP".
• "Ayúdame a entender cómo funciona el mecanismo de reintento".

Conectando con Cline

1. Iniciar el servidor MCP del resumen de código
2. En Cline, puedes agregar el servidor MCP con un comando:

3. Luego autentícate con tu clave API:

4. Luego puedes pedirle a Cline que use el resumidor de código, por ejemplo: "Por favor, resuma mis archivos de código".

Ejemplos de indicaciones para Cline:

• "¿Qué hace cada archivo en mi proyecto?"
• "Crea un resumen de todos los archivos TypeScript".
• "Explique el flujo de autenticación en esta base de código".
• "¿Cuáles son las funciones principales del directorio 'summarizador'?"

Qué puede hacer con la integración de MCP

Al utilizar la integración de MCP, puede:

1. Obtener resúmenes de archivos : solicita explicaciones concisas de lo que hacen archivos específicos
2. Explorar directorios : navegue a través de la estructura de su base de código
3. Procesamiento por lotes : resuma varios archivos a la vez
4. Consultas específicas : encuentre patrones o funcionalidades específicas en su código
5. Personalizar resúmenes : controlar el nivel de detalle y la longitud del resumen
6. Actualizar configuración : cambiar las opciones de configuración a través de la interfaz MCP

El servidor MCP expone su base de código a las herramientas LLM de manera estructurada, lo que les permite leer, navegar y resumir su código sin tener que pegar fragmentos de código manualmente.

Detalles de la integración del servidor MCP

Recursos de MCP

• code://file/* - Acceder a archivos de código individuales
• code://directory/* - Lista los archivos de código en un directorio
• summary://file/* - Obtener el resumen de un archivo específico
• summary://batch/* - Obtener resúmenes de varios archivos

Herramientas MCP

• summarize_file - Resumir un solo archivo con opciones
• summarize_directory - Resumir un directorio con opciones
• set_config - Actualizar las opciones de configuración

Indicaciones de MCP

• code_summary - Plantilla de solicitud para resumir el código
• directory_summary - Plantilla de solicitud para resumir directorios completos

Solución de problemas

Problemas comunes de conexión de MCP

1. Conexión rechazada
   • Asegúrese de que el servidor MCP esté ejecutándose ( npm start -- server )
   • Verifique que el puerto sea correcto en su configuración
   • Comprueba si hay problemas de firewall que bloqueen la conexión
2. Errores de autenticación
   • Verifique que haya agregado la clave API correcta en los encabezados ( x-api-key )
   • Comprueba que tu clave API sea válida y tenga el formato correcto
   • Asegúrese de que las variables de entorno estén configuradas correctamente
3. Errores de transporte
   • Asegúrese de que se especifique el tipo de transporte correcto (SSE)
   • Compruebe que la URL incluya el punto final correcto ( /sse )
   • Verificar la conectividad de red entre el cliente y el servidor
4. Problemas de permisos
   • Asegúrese de que el servidor MCP tenga acceso de lectura a su código base
   • Verifique los permisos de archivo si el resumen falla para archivos específicos
5. Claude Desktop no encuentra el servidor MCP
   • Verifique que la ruta en claude_desktop_config.json sea correcta
   • Asegúrese de que el comando y los argumentos apunten a la ubicación correcta
   • Verifique los registros de Claude Desktop para detectar cualquier error de configuración
6. Limitación de velocidad
   • Si ve errores de "Demasiadas solicitudes", espere y vuelva a intentarlo más tarde.
   • Considere ajustar la configuración de limitación de velocidad en el código del servidor

Para otros problemas, verifique los registros del servidor o abra un problema en el repositorio de GitHub.

Uso

Interfaz de línea de comandos

Gestión de la configuración

Autenticación de API

Al conectarse al servidor MCP, debe incluir su clave API en los encabezados de solicitud:

Todos los puntos finales (excepto /health ) requieren autenticación.

Opciones

• --detail , -d : Define el nivel de detalle de los resúmenes. Las opciones son 'bajo', 'medio' o 'alto'. El valor predeterminado es 'medio'.
• --max-length , -l : Longitud máxima de cada resumen en caracteres. El valor predeterminado es 500.

Características de seguridad

Gestión de claves API

• Las claves API se almacenan de forma segura y priorizan las variables de entorno sobre los archivos de configuración
• Las claves se validan para comprobar que tienen el formato adecuado antes de su uso
• Las claves API nunca se exponen en registros ni mensajes de error.
• El archivo de configuración no almacena claves API cuando se proporcionan a través de variables de entorno

Autenticación

• Todos los puntos finales del servidor MCP (excepto la comprobación de estado) requieren autenticación mediante una clave API
• La autenticación utiliza el encabezado x-api-key para una transmisión segura
• Los intentos de autenticación fallidos se registran para la supervisión de seguridad.

Limitación de velocidad

• La limitación de velocidad incorporada evita el abuso del servicio
• Predeterminado: 60 solicitudes por minuto por dirección IP
• Configurable a través de la configuración del servidor

Manejo de errores

• Sistema de error estructurado con categorización
• La información confidencial nunca se expone en los mensajes de error.
• Se devuelven códigos de error adecuados para diferentes escenarios de falla.

LLM Llamada Resiliencia

• Reintento automático con retroceso exponencial para fallas transitorias
• Configuraciones de reintento configurables que incluyen reintentos máximos, demoras y factor de retroceso
• Se agregó jitter al tiempo de reintento para evitar problemas de rebaño atronador
• Solicitar seguimiento de ID para rastrear problemas en todo el sistema

Tipos de archivos admitidos

• TypeScript (.ts, .tsx)
• JavaScript (.js, .jsx)
• Python (.py)
• Java (.java)
• C++ (.cpp)
• C (.c)
• Ir (.go)
• Rubí (.rb)
• PHP (.php)
• C# (.cs)
• Swift (.swift)
• Óxido (.rs)
• Kotlin (.kt)
• Scala (.scala)
• Vista (.vue)
• HTML (.html)
• CSS (.css, .scss, .less)

Cómo funciona

1. La herramienta escanea el directorio especificado de forma recursiva, respetando las reglas .gitignore .
2. Filtra archivos según las extensiones compatibles.
3. Para cada archivo compatible, lee el contenido y determina el lenguaje de programación.
4. Envía el código a Gemini Flash 2.0 con un mensaje para resumir, incluyendo el nivel de detalle y las restricciones de longitud.
5. Los resúmenes se recopilan y escriben en el archivo de salida especificado.

Formato de salida

El archivo de salida tendrá el siguiente formato:

Estructura del proyecto

• index.ts : Implementación principal de la CLI
• src/ : Directorio del código fuente
  • summarizer/ : Funcionalidad principal de resumen
  • mcp/ : Implementación del servidor MCP
  • config/ : Gestión de configuración
• bin/ : punto de entrada CLI
• config.json : archivo de configuración predeterminado
• tsconfig.json : configuración de TypeScript
• package.json : Dependencias y scripts del proyecto
• .env.example : Plantilla para configurar variables de entorno
• .gitignore : Archivos y directorios a ignorar en Git
• __tests__ : Pruebas unitarias y de integración
• __mocks__/mock-codebase : Base de código simulada para pruebas

Variables de entorno

Las siguientes variables de entorno se pueden utilizar para configurar la aplicación:

Consulte .env.example para obtener una plantilla.

Desarrollo

Ejecución de pruebas

Mejoras futuras

• Compatibilidad con más tipos de archivos
• Apoyo a proveedores alternativos de LLM
• Integración con una aplicación Electron para una interfaz GUI
• Capacidades mejoradas del servidor MCP
• Seguimiento avanzado del uso de tokens
• Observabilidad basada en OpenTelemetry
• Capacidades mejoradas de registro de auditoría
• Integración de escaneo secreto