Code Summarizer

Una herramienta de línea de comandos que resume archivos de código en un directorio usando Gemini Flash 2.0.

GitHub
6
Prueba este MCPPatrocinado

Documentación

Code Summarizer

Una herramienta de línea de comandos que resume archivos de código en un directorio determinado usando Gemini Flash 2.0. ¡Ahora con soporte de servidor MCP para 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
  • Genera resúmenes en 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 fácil integración en otras aplicaciones
  • Gestión segura de claves API
  • Autenticación para endpoints del servidor MCP
  • Mecanismo de reintento con retroceso exponencial para llamadas LLM
  • Limitación de velocidad para prevenir abuso

Requisitos

  • Node.js 18+

Instalación

  1. Clona el repositorio

    git clone https://github.com/nicobailon/code-summarizer.git
cd code-summarizer

  2. Instala las dependencias:

    npm install

  3. Crea un archivo .env con tu clave API de Google:

    GOOGLE_API_KEY=your_api_key_here

  4. Compila 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 herramientas LLM como Claude Desktop, Cursor AI y Cline accedan a resúmenes de código y contenido de archivos.

Iniciando el Servidor MCP

# Start the MCP server
npm start -- server

Por defecto, el servidor se ejecuta en el puerto 24312. Puedes cambiar esto en tu configuración:

# Set custom MCP server port
npm start -- config set --port 8080

Conexión con Claude Desktop

  1. Inicia el servidor MCP de code-summarizer
  2. Abre Claude Desktop y haz clic en el menú de Claude, luego en "Settings..."
  3. Navega a la sección "Developer"
  4. Crea un archivo en ~/.claude/claude_desktop_config.json (macOS/Linux) o %USERPROFILE%\.claude\claude_desktop_config.json (Windows) con este contenido:
{
  "code-summarizer": {
    "command": "npx",
    "args": ["-y", "your-path-to-code-summarizer/bin/code-summarizer.js", "server"],
    "env": {
      "GOOGLE_API_KEY": "your_api_key_here"
    }
  }
}
  1. Reinicia Claude Desktop
  2. Después de reiniciar, puedes pedirle a Claude que acceda a tu código, por ejemplo, "Resume los archivos en mi proyecto"

Ejemplos de prompts para Claude Desktop:

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

Conexión con Cursor AI

  1. Inicia el servidor MCP de code-summarizer
  2. Crea un archivo .cursor/mcp.json en tu directorio de proyecto:
{
  "mcpServers": {
    "code-summarizer": {
      "transport": "sse",
      "url": "http://localhost:24312/sse",
      "headers": {
        "x-api-key": "your_api_key_here"
      }
    }
  }
}
  1. Reinicia Cursor o recarga tu proyecto
  2. Pregunta a Cursor sobre tu código, por ejemplo, "¿Puedes resumir mi código?"

Ejemplos de prompts para Cursor:

  • "Resume la estructura de este código para mí."
  • "¿Cuáles son los componentes clave en 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."

Conexión con Cline

  1. Inicia el servidor MCP de code-summarizer
  2. En Cline, puedes agregar el servidor MCP con un comando:
/mcp add code-summarizer http://localhost:24312/sse
  1. Luego autentícate con tu clave API:
/mcp config code-summarizer headers.x-api-key your_api_key_here
  1. Puedes pedirle a Cline que use code-summarizer, por ejemplo, "Por favor, resume mis archivos de código"

Ejemplos de prompts para Cline:

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

Qué Puedes Hacer con la Integración MCP

Usando la integración MCP, puedes:

  1. Obtener resúmenes de archivos: Solicitar explicaciones concisas de qué hacen archivos específicos
  2. Explorar directorios: Navegar por la estructura de tu código
  3. Procesamiento por lotes: Resumir múltiples archivos a la vez
  4. Consultas dirigidas: Encontrar patrones o funcionalidades específicas en tu código
  5. Personalizar resúmenes: Controlar el nivel de detalle y la longitud del resumen
  6. Actualizar configuraciones: Cambiar opciones de configuración a través de la interfaz MCP

El servidor MCP expone tu código a las herramientas LLM de manera estructurada, permitiéndoles leer, navegar y resumir tu código sin tener que pegar fragmentos de código manualmente.

Detalles de Integración del Servidor MCP

Recursos MCP

  • code://file/* - Accede a archivos de código individuales
  • code://directory/* - Lista archivos de código en un directorio
  • summary://file/* - Obtén el resumen de un archivo específico
  • summary://batch/* - Obtén resúmenes de múltiples archivos

Herramientas MCP

  • summarize_file - Resume un solo archivo con opciones
  • summarize_directory - Resume un directorio con opciones
  • set_config - Actualiza opciones de configuración

Prompts MCP

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

Solución de Problemas

Problemas Comunes de Conexión MCP

  1. Conexión Rechazada

    • Asegúrate de que el servidor MCP esté ejecutándose (npm start -- server)
    • Verifica que el puerto sea correcto en tu configuración
    • Revisa si hay problemas de firewall que bloqueen la conexión

  2. Errores de Autenticación

    • Verifica que hayas agregado la clave API correcta en los encabezados (x-api-key)
    • Comprueba que tu clave API sea válida y esté formateada correctamente
    • Asegúrate de que las variables de entorno estén configuradas correctamente

  3. Errores de Transporte

    • Asegúrate de que el tipo de transporte especificado sea correcto (SSE)
    • Comprueba que la URL incluya el endpoint correcto (/sse)
    • Verifica la conectividad de red entre el cliente y el servidor

  4. Problemas de Permisos

    • Asegúrate de que el servidor MCP tenga acceso de lectura a tu código
    • Revisa los permisos de archivos si falla el resumen de archivos específicos

  5. Claude Desktop No Encuentra el Servidor MCP

    • Verifica que la ruta en claude_desktop_config.json sea correcta
    • Asegúrate de que el comando y los argumentos apunten a la ubicación correcta
    • Revisa los registros de Claude Desktop para ver errores de configuración

  6. Limitación de Velocidad

    • Si ves errores de "Demasiadas solicitudes", espera e inténtalo de nuevo más tarde
    • Considera ajustar la configuración de limitación de velocidad en el código del servidor

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

Uso

Interfaz de Línea de Comandos

# Default command (summarize)
npm start -- summarize [directory] [output-file] [options]

# Summarize code in the current directory (output to summaries.txt)
npm start -- summarize

# Summarize code with specific detail level and max length
npm start -- summarize --detail high --max-length 1000

# Show help
npm start -- --help

Gestión de Configuración

# Set your API key
npm start -- config set --api-key "your-api-key" 

# Set default detail level and max length
npm start -- config set --detail-level high --max-length 1000

# Set MCP server port (default: 24312)
npm start -- config set --port 8080

# Show current configuration
npm start -- config show

# Reset configuration to defaults
npm start -- config reset

Autenticación de API

Al conectarte al servidor MCP, debes incluir tu clave API en los encabezados de la solicitud:

x-api-key: your_api_key_here

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

Opciones

  • --detail, -d: Establece el nivel de detalle de los resúmenes. Las opciones son 'low', 'medium' o 'high'. El valor predeterminado es 'medium'.
  • --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 verificar su formato antes de su uso
  • Las claves API nunca se exponen en registros o mensajes de error
  • El archivo de configuración no almacena claves API cuando se proporcionan mediante variables de entorno

Autenticación

  • Todos los endpoints del servidor MCP (excepto la verificación de salud) requieren autenticación mediante 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 monitoreo de seguridad

Limitación de Velocidad

  • La limitación de velocidad integrada previene el abuso del servicio
  • Valor predeterminado: 60 solicitudes por minuto por dirección IP
  • Configurable a través de la configuración del servidor

Manejo de Errores

  • Sistema de errores estructurado con categorización
  • La información sensible nunca se expone en mensajes de error
  • Se devuelven códigos de error adecuados para diferentes escenarios de fallo

Resiliencia de Llamadas LLM

  • Reintento automático con retroceso exponencial para fallos transitorios
  • Configuración de reintento ajustable que incluye reintentos máximos, retrasos y factor de retroceso
  • Se agrega jitter al tiempo de reintento para prevenir problemas de avalancha
  • Seguimiento de ID de solicitud para rastrear problemas en todo el sistema

Tipos de Archivos Soportados

  • TypeScript (.ts, .tsx)
  • JavaScript (.js, .jsx)
  • Python (.py)
  • Java (.java)
  • C++ (.cpp)
  • C (.c)
  • Go (.go)
  • Ruby (.rb)
  • PHP (.php)
  • C# (.cs)
  • Swift (.swift)
  • Rust (.rs)
  • Kotlin (.kt)
  • Scala (.scala)
  • Vue (.vue)
  • HTML (.html)
  • CSS (.css, .scss, .less)

Cómo Funciona

  1. La herramienta escanea el directorio especificado recursivamente, respetando las reglas de .gitignore.
  2. Filtra archivos según las extensiones soportadas.
  3. Para cada archivo soportado, lee el contenido y determina el lenguaje de programación.
  4. Envía el código a Gemini Flash 2.0 con un prompt para resumir, incluyendo restricciones de nivel de detalle y 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:

relative/path/to/file
Summary text here

relative/path/to/next/file
Next summary text here

Estructura del Proyecto

  • index.ts: Implementación principal de CLI
  • src/: Directorio de código fuente
    • summarizer/: Funcionalidad principal de resumen
    • mcp/: Implementación del servidor MCP
    • config/: Gestión de configuración
  • bin/: Punto de entrada de 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: Código de prueba simulado

Variables de Entorno

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

VariableDescripciónValor Predeterminado
GOOGLE_API_KEYTu clave API de Google GeminiNinguno (requerido)
PORTPuerto para el servidor MCP24312
ALLOWED_ORIGINSLista separada por comas de orígenes CORS permitidoshttp://localhost:3000
LOG_LEVELNivel de registro (error, warn, info, debug)info

Consulta .env.example para ver una plantilla.

Desarrollo

Ejecutando Pruebas

# Run all tests
npm test

# Run tests with coverage
npm test -- --coverage

# Test MCP server setup
npm run test:setup

Mejoras Futuras

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