@machina.ai/maven-quality-mcp 1.0.0

package/README.md

@@ -0,0 +1,1210 @@
+# Maven Quality MCP Server
+
+[![Tests](https://img.shields.io/badge/tests-545%20passing-brightgreen)](.)
+[![Test Suites](https://img.shields.io/badge/test%20suites-26%20passed-brightgreen)](.)
+[![Coverage](https://img.shields.io/badge/coverage-91.69%25-brightgreen)](.)
+[![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3.3-blue)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/license-UNLICENSED-red)](.)
+
+Servidor MCP (Model Context Protocol) para análisis automático de calidad de código, migraciones Java/Spring Boot y corrección asistida por IA en proyectos Maven.
+
+## 📋 Tabla de Contenidos
+
+- [¿Qué es Maven Quality MCP?](#-qué-es-maven-quality-mcp)
+- [Características](#-características)
+- [Requisitos](#-requisitos)
+- [Instalación](#-instalación)
+- [Configuración](#-configuración)
+- [Uso](#-uso)
+- [Herramientas Disponibles](#-herramientas-disponibles)
+- [Arquitectura del Proyecto](#-arquitectura-del-proyecto)
+- [Desarrollo](#-desarrollo)
+- [Testing](#-testing)
+- [Solución de Problemas](#-solución-de-problemas)
+
+## 🎯 ¿Qué es Maven Quality MCP?
+
+Maven Quality MCP es un servidor que implementa el protocolo MCP (Model Context Protocol), permitiendo que asistentes de IA puedan:
+
+✅ **Configurar automáticamente** herramientas de calidad en proyectos Maven
+✅ **Analizar código** usando SpotBugs, Checkstyle, PMD y JaCoCo
+✅ **Corregir automáticamente** problemas de estilo de código
+✅ **Analizar dependencias** y detectar vulnerabilidades de seguridad (CVEs)
+✅ **Migrar proyectos Java/Spring Boot** usando OpenRewrite con detectores inteligentes
+
+**¿Por qué usarlo?**
+
+- ⚡ **Ahorra tiempo**: 30-60 segundos vs 10-15 minutos manualmente
+- 🤖 **Integración con IA**: Usa lenguaje natural con tu asistente MCP
+- 🔒 **100% local**: Tu código nunca sale de tu máquina
+- 📊 **Análisis completo**: 4 herramientas de calidad integradas
+
+## ✨ Características
+
+### Análisis de Calidad
+
+- **SpotBugs**: Detección de bugs y problemas de seguridad
+- **Checkstyle**: Verificación de estándares de código Java
+- **PMD**: Análisis de código problemático y duplicado
+- **JaCoCo**: Medición de cobertura de tests
+
+### Corrección Automática
+
+- Formateo automático de código según Google Java Format
+- Corrección de imports no utilizados
+- Normalización de indentación y espacios
+- 100% seguro: solo aplica cambios de formato, sin modificar lógica
+
+### Configuración Inteligente
+
+- Detecta versión de Java automáticamente (8, 11, 17, 21, 23)
+- Configura plugins compatibles con la versión detectada
+- Mantiene configuración existente del proyecto
+- No sobrescribe personalizaciones del usuario
+
+## 📦 Requisitos
+
+### Requisitos del Sistema
+
+- **Node.js**: 18.0.0 o superior
+- **Maven**: 3.6.0 o superior
+- **Java**: 8 o superior (para ejecutar Maven)
+
+### Clientes MCP Compatibles
+
+- [Cell CLI](https://cell-cli.xyz/) (Terminal) - **Recomendado**
+- Cualquier cliente compatible con MCP
+
+## 🚀 Instalación
+
+### Desde npm (Recomendado)
+
+```bash
+# Instalación global
+npm install -g maven-quality-mcp
+
+# Verificar instalación
+maven-quality-mcp --version
+```
+
+### Desde Código Fuente
+
+```bash
+# 1. Clonar el repositorio
+git clone <url-del-repositorio>
+cd maven-quality-mcp
+
+# 2. Instalar dependencias
+npm install
+
+# 3. Compilar el proyecto
+npm run build
+
+# 4. Verificar instalación
+node dist/index.js
+```
+
+## ⚙️ Configuración
+
+### Configuración en Cell CLI (Instalación Global)
+
+**Opción 1: Usando comando (Recomendado)**
+
+```bash
+cell mcp add maven-quality maven-quality-mcp
+```
+
+**Opción 2: Configuración manual**
+
+1. **Localiza el archivo de configuración:**
+   - `~/.cell/settings.json` (Linux/macOS)
+   - `%USERPROFILE%\.cell\settings.json` (Windows)
+
+2. **Agrega el servidor MCP:**
+
+```json
+{
+  "mcpServers": {
+    "maven-quality": {
+      "command": "maven-quality-mcp",
+      "env": {
+        "MCP_ROOT": "/ruta/donde/guardar/logs",
+        "LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+```
+
+**Ejemplo Windows:**
+```json
+{
+  "mcpServers": {
+    "maven-quality": {
+      "command": "maven-quality-mcp",
+      "env": {
+        "MCP_ROOT": "C:\\Users\\TuUsuario\\maven-quality-logs",
+        "LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+```
+
+3. **Reinicia Cell CLI**
+
+---
+
+### Configuración en Cell CLI (Instalación desde Código Fuente)
+
+**Opción 1: Usando comando**
+
+```bash
+cell mcp add maven-quality node /ruta/completa/maven-quality-mcp/dist/index.js
+```
+
+**Opción 2: Configuración manual**
+
+```json
+{
+  "mcpServers": {
+    "maven-quality": {
+      "command": "node",
+      "args": ["/ruta/completa/maven-quality-mcp/dist/index.js"],
+      "env": {
+        "MCP_ROOT": "/ruta/completa/maven-quality-mcp",
+        "LOG_LEVEL": "info"
+      }
+    }
+  }
+}
+```
+
+### Variables de Entorno
+
+| Variable | Valores | Descripción |
+|----------|---------|-------------|
+| `MCP_ROOT` | Ruta absoluta | **Requerido**. Directorio raíz del MCP donde se escriben los logs |
+| `LOG_LEVEL` | `debug`, `info`, `warn`, `error` | Nivel de detalle de logs (default: `info`) |
+| `NVD_API_KEY` | API key string | **Opcional**. API key de NVD para escaneos 10x más rápidos (gratis en https://nvd.nist.gov/developers/request-an-api-key) |
+
+**Niveles de Log:**
+- `debug` - Muestra todos los logs (debug, info, warn, error) - **Recomendado para desarrollo**
+- `info` - Muestra info, warn, error (default)
+- `warn` - Muestra solo warn y error
+- `error` - Muestra solo errores críticos
+
+**NVD API Key:**
+- **Sin API key**: Escaneos funcionan pero son lentos (10-15 min primera vez, 30-60 seg después)
+- **Con API key**: Escaneos 10x más rápidos (2-3 min primera vez, 10-20 seg después)
+- **Es gratis**: Obtén uno en 5 minutos en https://nvd.nist.gov/developers/request-an-api-key
+- Ver instrucciones detalladas en la sección de `maven_dependency_analyze`
+
+### Verificar Configuración
+
+```bash
+# Ver servidores MCP configurados (Cell CLI)
+cell mcp list
+
+# Probar conexión
+cell "Hola, ¿qué herramientas Maven tienes disponibles?"
+```
+
+## 💡 Uso
+
+### Uso Básico con Cell CLI
+
+Una vez configurado, simplemente usa lenguaje natural:
+
+```bash
+cd /ruta/a/tu/proyecto
+cell "Analiza la calidad de mi proyecto Maven"
+```
+
+Cell CLI automáticamente usará las herramientas MCP según sea necesario.
+
+### Ejemplos de Comandos
+
+#### Configurar Herramientas de Calidad
+
+```bash
+cell "Configura las herramientas de calidad en mi proyecto"
+```
+
+Cell CLI ejecutará `maven_setup_quality` y configurará todos los plugins necesarios.
+
+#### Analizar Código
+
+```bash
+cell "¿Qué problemas de calidad tiene mi código?"
+```
+
+Cell CLI ejecutará `maven_analyze` y te mostrará un reporte detallado.
+
+#### Corregir Problemas de Estilo
+
+```bash
+cell "Arregla los problemas de formateo en mi código"
+```
+
+Cell CLI ejecutará `maven_fix_style` y aplicará las correcciones.
+
+### Flujo de Trabajo Completo
+
+```bash
+$ cd /home/user/mi-proyecto
+$ cell "Mejora la calidad de mi proyecto Maven"
+
+Cell CLI: "Voy a analizar y mejorar la calidad de tu proyecto..."
+
+[Ejecuta maven_setup_quality]
+✅ Plugins configurados
+
+[Ejecuta maven_analyze]
+📊 Encontrados:
+   - 23 bugs (5 críticos)
+   - 156 violaciones de estilo
+   - 45% cobertura de código
+
+[Ejecuta maven_fix_style]
+✅ Corregidas 156 violaciones de estilo
+
+Cell CLI: "He mejorado el formateo del código. Quedan 5 bugs críticos que requieren revisión manual:
+1. PaymentService.java:45 - Posible NullPointerException
+   [Muestra código y sugerencia]
+..."
+```
+
+## 🛠️ Herramientas Disponibles
+
+El servidor proporciona **8 herramientas MCP** (5 para análisis de calidad + 3 para migraciones Java/Spring):
+
+### 1. `maven_setup_quality`
+
+**Descripción**: Configura automáticamente los plugins de calidad en el `pom.xml`
+
+**Parámetros**:
+- `projectPath` (string, requerido): Ruta al proyecto Maven
+
+**Qué hace**:
+- Detecta versión de Java del proyecto
+- Configura SpotBugs, Checkstyle, PMD, JaCoCo
+- Usa versiones compatibles con la versión de Java
+- Mantiene configuración existente
+
+**Ejemplo de salida**:
+```json
+{
+  "success": true,
+  "javaVersion": "17",
+  "pluginsConfigured": ["spotbugs", "checkstyle", "pmd", "jacoco"],
+  "message": "Quality plugins configured successfully for Java 17"
+}
+```
+
+### 2. `maven_analyze`
+
+**Descripción**: Ejecuta análisis completo de calidad y retorna reporte estructurado
+
+**Parámetros**:
+- `projectPath` (string, requerido): Ruta al proyecto Maven
+
+**Qué hace**:
+- Ejecuta `mvn clean verify -Pquality -fn` (`-fn` = fail-never)
+- Continúa análisis incluso si tests fallan (enfoque híbrido)
+- Parsea reportes de SpotBugs, Checkstyle, PMD, JaCoCo
+- Detecta tests fallidos y marca cobertura como "unreliable" si aplica
+- **Manejo inteligente de errores**: Detecta y reporta errores específicos de Maven
+- Agrupa y prioriza problemas
+- Retorna JSON estructurado con advertencias claras
+
+**Detección de Errores Maven**:
+Cuando Maven falla o no genera reportes, el sistema detecta automáticamente el tipo de error:
+- **Errores de red**: Timeout, conexión rechazada, repositorios inaccesibles
+- **Errores de compilación**: Errores de sintaxis en código Java
+- **Dependencias faltantes**: Artefactos no encontrados en repositorios
+- **Configuración faltante**: Perfil de calidad no configurado (sugiere `maven_setup_quality`)
+- **Problemas de recursos**: Memoria insuficiente, espacio en disco, permisos
+- **Timeout**: Comando Maven excede tiempo máximo de ejecución
+
+Esto evita mensajes confusos y proporciona soluciones específicas para cada tipo de error.
+
+**Manejo de Tests Fallidos**:
+- Los tests pueden fallar sin detener el análisis
+- Se detectan y reportan tests fallidos
+- Las métricas de cobertura se marcan como potencialmente inexactas
+- Se incluyen advertencias visibles en el reporte formateado
+- La IA recibe toda la información para tomar decisiones informadas
+
+**Ejemplo de salida (tests pasando)**:
+```json
+{
+  "success": true,
+  "spotbugs": {
+    "totalBugs": 23,
+    "critical": [
+      {
+        "type": "NP_NULL_ON_SOME_PATH",
+        "file": "PaymentService.java",
+        "line": 45,
+        "message": "Posible null pointer dereference"
+      }
+    ],
+    "high": [...],
+    "medium": [...]
+  },
+  "checkstyle": {
+    "totalViolations": 156,
+    "errors": [...],
+    "warnings": [...],
+    "autoFixable": 142
+  },
+  "pmd": {
+    "totalIssues": 18,
+    "issues": [...]
+  },
+  "jacoco": {
+    "lineCoverage": 45.2,
+    "branchCoverage": 38.7,
+    "uncoveredClasses": [...]
+  },
+  "formattedReport": "# 🔍 ANÁLISIS DE CALIDAD\n\n..."
+}
+```
+
+**Ejemplo de salida (con tests fallidos)**:
+```json
+{
+  "success": true,
+  "spotbugs": { ... },
+  "checkstyle": { ... },
+  "pmd": { ... },
+  "jacoco": {
+    "lineCoverage": 45.2,
+    "branchCoverage": 38.7,
+    "uncoveredClasses": [...],
+    "unreliable": true
+  },
+  "warnings": {
+    "testFailures": {
+      "testsRun": 150,
+      "failures": 2,
+      "errors": 1,
+      "failedTestDetails": [
+        "UserServiceTest.shouldValidateEmail",
+        "PaymentProcessorTest.shouldProcessPayment",
+        "ValidationUtilsTest.shouldCheckFormat"
+      ]
+    },
+    "message": "3 test(s) failed. Coverage metrics may be unreliable."
+  },
+  "formattedReport": "# 🔍 ANÁLISIS DE CALIDAD\n\n## ⚠️  ADVERTENCIA - Tests Fallidos\n\n**3 test(s) fallaron de 150 ejecutados**\n\n⚠️  La cobertura de código reportada puede ser **INEXACTA**..."
+}
+```
+
+### 3. `maven_fix_style`
+
+**Descripción**: Aplica correcciones automáticas de estilo
+
+**Parámetros**:
+- `projectPath` (string, requerido): Ruta al proyecto Maven
+
+**Qué hace**:
+- Ejecuta `mvn spotless:apply`
+- Aplica Google Java Format
+- Corrige imports no utilizados
+- Normaliza indentación y espacios en blanco
+- 100% seguro: solo cambios de formato, sin tocar lógica
+
+**Ejemplo de salida**:
+```json
+{
+  "success": true,
+  "filesModified": 34,
+  "breakdown": {
+    "imports": 45,
+    "indentation": 78,
+    "whitespace": 19
+  }
+}
+```
+
+### 4. `maven_dependency_analyze`
+
+**Descripción**: Analiza dependencias del proyecto para encontrar actualizaciones, problemas y vulnerabilidades de seguridad
+
+**Parámetros**:
+- `projectPath` (string, requerido): Ruta al proyecto Maven
+- `checkVulnerabilities` (boolean, opcional, default: false): Escanear vulnerabilidades CVE conocidas
+- `timeout` (number, opcional): Timeout en milisegundos
+
+**Qué hace**:
+- Detecta dependencias desactualizadas con versiones disponibles
+- Identifica dependencias declaradas pero no usadas
+- Encuentra dependencias usadas pero no declaradas explícitamente
+- Escanea vulnerabilidades CVE con OWASP Dependency-Check (opcional)
+
+**Análisis Rápido (sin vulnerabilidades, ~20 segundos)**:
+```json
+{
+  "success": true,
+  "executionTime": 18.5,
+  "summary": {
+    "total": 45,
+    "direct": 12,
+    "transitive": 33
+  },
+  "outdated": [
+    {
+      "groupId": "junit",
+      "artifactId": "junit",
+      "currentVersion": "4.12",
+      "latestVersion": "4.13.2"
+    }
+  ],
+  "unused": [
+    {
+      "groupId": "commons-lang3",
+      "artifactId": "commons-lang3",
+      "version": "3.12.0"
+    }
+  ],
+  "undeclared": [],
+  "formattedReport": "# 📦 ANÁLISIS DE DEPENDENCIAS\n\n..."
+}
+```
+
+**Análisis Completo con CVEs (primera vez: 10-15 min, luego: 30-60 seg)**:
+```json
+{
+  "success": true,
+  "executionTime": 45.2,
+  "summary": { ... },
+  "outdated": [ ... ],
+  "unused": [ ... ],
+  "undeclared": [ ... ],
+  "vulnerabilities": {
+    "scanned": true,
+    "critical": [
+      {
+        "name": "CVE-2021-44228",
+        "severity": "CRITICAL",
+        "cvssScore": 10.0,
+        "cve": "CVE-2021-44228",
+        "description": "Apache Log4j2 Remote Code Execution (Log4Shell)",
+        "dependency": "log4j-core-2.14.1.jar",
+        "references": ["https://nvd.nist.gov/vuln/detail/CVE-2021-44228"]
+      }
+    ],
+    "high": [ ... ],
+    "medium": [ ... ],
+    "low": [ ... ],
+    "totalCount": 5
+  },
+  "formattedReport": "..."
+}
+```
+
+**Nota sobre Vulnerabilidades**:
+⚠️ La primera ejecución con `checkVulnerabilities: true` descarga la base de datos de CVE (~250MB) que toma 10-15 minutos. Esta descarga se hace automáticamente en background durante `npm install`, pero puede que aún no esté lista. Ejecuciones posteriores son rápidas (30-60 seg).
+
+**⚡ Acelera los Scans 10x con NVD API Key (Recomendado)**:
+
+El escaneo de vulnerabilidades puede ser **10x más rápido** con un API key gratuito de NVD:
+
+| Operación | Sin API Key 🐌 | Con API Key 🚀 |
+|-----------|----------------|----------------|
+| Primera descarga | 10-15 min | 2-3 min |
+| Scan normal | 30-60 seg | 10-20 seg |
+
+**Cómo obtener tu API Key (5 minutos):**
+
+1. **Solicitar**: https://nvd.nist.gov/developers/request-an-api-key
+2. **Llenar formulario**: Nombre, email, tipo de organización
+3. **Recibir email** con link de activación (inmediato)
+4. **Activar y copiar** el API key (solo se muestra una vez)
+5. **Configurar en Cell CLI**:
+
+```json
+{
+  "mcpServers": {
+    "maven-quality": {
+      "command": "node",
+      "args": ["/ruta/maven-quality-mcp/dist/index.js"],
+      "env": {
+        "MCP_ROOT": "/ruta/maven-quality-mcp",
+        "LOG_LEVEL": "info",
+        "NVD_API_KEY": "tu-api-key-aqui"
+      }
+    }
+  }
+}
+```
+
+6. **Reiniciar Cell CLI** y listo!
+
+**Comandos útiles**:
+```bash
+# Ver estado de descarga de CVE database
+npm run nvd-status
+
+# Descargar manualmente base de datos CVE
+npm run download-nvd
+
+# Limpiar base de datos CVE (libera ~250MB)
+npm run nvd-purge
+```
+
+---
+
+## 🔄 Herramientas de Migración (OpenRewrite)
+
+### 5. `maven_rewrite_discover`
+
+**Descripción**: Descubre migraciones disponibles y recomienda path óptimo según tu proyecto
+
+**Parámetros**:
+- `projectPath` (string, requerido): Ruta al proyecto Maven
+- `currentJavaVersion` (string, opcional): Versión actual de Java (se detecta automáticamente)
+- `targetJavaVersion` (string, opcional): Versión objetivo (se sugiere automáticamente)
+- `detectFrameworks` (boolean, opcional, default: true): Detectar frameworks usados
+
+**Qué hace**:
+- Detecta versión actual de Java del proyecto y del sistema
+- Escanea frameworks: Spring Boot, JUnit, Mockito, Hibernate, Swagger, Logging
+- Recomienda migraciones según frameworks detectados
+- Sugiere target version automático (Java 8→11, 11→17, 17→21, 21→25)
+- Genera advertencias sobre cambios incompatibles (Jakarta EE, SecurityManager, Log4j CVEs)
+- Usa versiones dinámicas de OpenRewrite desde Maven Central (cache de 24h)
+
+**Ejemplo de salida**:
+```json
+{
+  "success": true,
+  "currentJavaVersion": "11",
+  "frameworksDetected": {
+    "spring": { "version": "5.3.20", "springBoot": "2.7.0" },
+    "junit": { "version": "4" },
+    "logging": { "framework": "log4j", "version": "1.2.17" }
+  },
+  "availableMigrations": [
+    {
+      "id": "java-17",
+      "name": "Migrate to Java 17",
+      "category": "java",
+      "recommended": true,
+      "breakingChanges": true
+    },
+    {
+      "id": "spring-boot-2-to-3",
+      "name": "Spring Boot 2 to 3",
+      "category": "spring",
+      "recommended": true,
+      "requires": "java-17+"
+    },
+    {
+      "id": "junit4-to-junit5",
+      "name": "JUnit 4 to 5",
+      "category": "testing",
+      "recommended": true
+    }
+  ],
+  "warnings": [
+    "Spring Boot 3.x requires Java 17+",
+    "Spring Boot 3.x uses Jakarta EE namespace (jakarta.* instead of javax.*)",
+    "⚠️ CRITICAL: Log4j 1.x has security vulnerabilities (CVE-2021-44228)"
+  ],
+  "suggestedPath": [
+    "1. Migrate to Java 17 first (required for Spring Boot 3)",
+    "2. Upgrade to Spring Boot 3 (includes javax → jakarta migration)",
+    "3. Migrate JUnit 4 → JUnit 5 (modern testing best practices)",
+    "4. Update Log4j to 2.x (CRITICAL security fix)"
+  ],
+  "versionsUsed": {
+    "rewrite-migrate-java": "2.35.0",
+    "rewrite-spring": "5.28.0",
+    "rewrite-testing-frameworks": "2.24.0"
+  }
+}
+```
+
+### 6. `maven_rewrite_preview`
+
+**Descripción**: Previsualiza cambios SIN modificar archivos (dry-run)
+
+**Parámetros**:
+- `projectPath` (string, requerido): Ruta al proyecto Maven
+- `recipes` (string[], requerido): Recetas OpenRewrite a aplicar
+
+**Qué hace**:
+- Ejecuta OpenRewrite en modo `dryRun` (no modifica archivos)
+- Muestra qué archivos cambiarán y estadísticas de líneas
+- Identifica issues que requieren migración manual
+- Parsea cambios en pom.xml (plugins, properties, dependencies)
+- Genera reporte con top 5 errores críticos
+- Timeout: 15 minutos
+
+**Ejemplo de salida**:
+```json
+{
+  "success": true,
+  "executionTime": 45200,
+  "summary": {
+    "totalFilesAnalyzed": 120,
+    "filesWillChange": 45,
+    "linesAdded": 350,
+    "linesRemoved": 280
+  },
+  "fileChanges": [
+    { "path": "src/main/java/App.java", "changeType": "modified" },
+    { "path": "pom.xml", "changeType": "modified" }
+  ],
+  "buildFileChanges": {
+    "pomUpdates": {
+      "propertiesChanged": {
+        "java.version": { "old": "11", "new": "17" }
+      },
+      "pluginsUpdated": ["maven-compiler-plugin: 3.8.1 → 3.10.1"]
+    }
+  },
+  "unmigratableIssues": [
+    {
+      "file": "src/main/java/Security.java",
+      "line": 100,
+      "issue": "SecurityManager removed",
+      "severity": "error",
+      "reason": "SecurityManager API removed in Java 21",
+      "suggestedAction": "Refactor to use alternative security mechanisms"
+    }
+  ],
+  "unmigratableStats": {
+    "totalIssues": 5,
+    "errors": 2,
+    "warnings": 3,
+    "manualRequired": 2
+  }
+}
+```
+
+### 7. `maven_rewrite_apply`
+
+**Descripción**: Aplica migraciones con backup automático y validación
+
+**Parámetros**:
+- `projectPath` (string, requerido): Ruta al proyecto Maven
+- `recipes` (string[], requerido): Recetas OpenRewrite a aplicar
+- `createBackup` (boolean, opcional, default: true): Crear backup antes de aplicar
+- `createGitCommit` (boolean, opcional, default: false): Crear commit de Git
+- `validateAfter` (boolean, opcional, default: true): Validar compilación después
+- `generateTodoFile` (boolean, opcional, default: true): Generar MIGRATION-TODO.md
+- `insertCodeComments` (boolean, opcional, default: true): Insertar TODOs en código
+
+**Qué hace**:
+1. **Backup automático**: Copia el proyecto a `backup-{timestamp}/`
+2. **Ejecución OpenRewrite**: Aplica recetas en modo `run`
+3. **Parsing de resultados**: Extrae archivos modificados y estadísticas
+4. **Detección de issues**: Identifica código que requiere migración manual
+5. **Generación de TODO**: Crea `MIGRATION-TODO.md` con tareas pendientes
+6. **Comentarios en código**: Inserta `// MIGRATION TODO:` en líneas problemáticas
+7. **Validación**: Ejecuta `mvn clean compile -DskipTests` (5 min timeout)
+8. **Git commit** (opcional): Crea commit con mensaje estructurado
+9. **Rollback automático**: Restaura backup si falla
+
+**Ejemplo de salida (migración exitosa)**:
+```json
+{
+  "success": true,
+  "executionTime": 52300,
+  "filesModified": 48,
+  "backupLocation": "/proyecto/backup-2025-01-15T10-30-00/",
+  "validationResult": {
+    "compiles": true
+  },
+  "todoFileGenerated": "/proyecto/MIGRATION-TODO.md",
+  "gitCommit": {
+    "hash": "a1b2c3d",
+    "message": "feat: Apply OpenRewrite migrations..."
+  },
+  "partialMigration": true,
+  "unmigratableIssues": [
+    {
+      "file": "src/main/java/Security.java",
+      "line": 100,
+      "issue": "SecurityManager removed",
+      "severity": "error",
+      "autoFixable": false
+    }
+  ],
+  "postMigrationSteps": [
+    "1. Review MIGRATION-TODO.md for 2 manual tasks",
+    "2. Fix issues marked as errors (blockers)",
+    "3. Run full test suite: mvn clean verify",
+    "4. Test application startup and basic functionality",
+    "5. Review and update documentation"
+  ]
+}
+```
+
+**Recetas OpenRewrite más comunes**:
+```bash
+# Java Migrations
+org.openrewrite.java.migrate.Java11
+org.openrewrite.java.migrate.Java17
+org.openrewrite.java.migrate.Java21
+
+# Spring Boot
+org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_0
+org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_1
+org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_2
+
+# Jakarta EE (javax → jakarta)
+org.openrewrite.java.migrate.jakarta.JavaxMigrationToJakarta
+
+# Testing
+org.openrewrite.java.testing.junit5.JUnit5BestPractices
+org.openrewrite.java.testing.mockito.Mockito1to5Migration
+```
+
+**Notas importantes**:
+- ⚠️ El backup consume espacio en disco temporal
+- 🔄 Usa `validateAfter: true` para detectar problemas de compilación inmediatamente
+- 📝 El archivo MIGRATION-TODO.md incluye enlaces a documentación oficial
+- 🔍 Los comentarios insertados tienen formato `// MIGRATION TODO (error): {descripción}`
+- ⏱️ Primera ejecución descarga dependencias de OpenRewrite (~2-5 min)
+
+---
+
+## 🏗️ Arquitectura del Proyecto
+
+### Estructura de Directorios
+
+```
+maven-quality-mcp-server/
+├── src/
+│   ├── index.ts                  # Punto de entrada del servidor MCP
+│   ├── server.ts                 # Clase principal MavenQualityServer
+│   ├── core/                     # 8 componentes core
+│   │   ├── backup_manager.ts     # Gestor de backups y rollback
+│   │   ├── framework_detector.ts # Detector de frameworks (Spring, JUnit, etc.)
+│   │   ├── java_detector.ts      # Detector de versión Java
+│   │   ├── maven_executor.ts     # Ejecutor de comandos Maven con timeout
+│   │   ├── pom_modifier.ts       # Modificador de pom.xml
+│   │   ├── recipe_manager.ts     # Gestor de recetas OpenRewrite
+│   │   ├── rewrite_executor.ts   # Ejecutor de migraciones OpenRewrite
+│   │   └── rewrite_version_manager.ts # Gestor de versiones dinámicas
+│   ├── parsers/                  # 8 parsers especializados
+│   │   ├── checkstyle_parser.ts  # Parser de reportes Checkstyle
+│   │   ├── dependency_parser.ts  # Parser de análisis de dependencias
+│   │   ├── jacoco_parser.ts      # Parser de reportes JaCoCo
+│   │   ├── migration_todo_generator.ts # Generador de MIGRATION-TODO.md
+│   │   ├── pmd_parser.ts         # Parser de reportes PMD
+│   │   ├── rewrite_issues_parser.ts    # Parser de issues no migrables
+│   │   ├── rewrite_result_parser.ts    # Parser de resultados OpenRewrite
+│   │   └── spotbugs_parser.ts    # Parser de reportes SpotBugs
+│   ├── tools/                    # 8 herramientas MCP
+│   │   ├── analyze.ts            # Herramienta: analizar calidad
+│   │   ├── dependency_analyze.ts # Herramienta: analizar dependencias
+│   │   ├── fix_style.ts          # Herramienta: corregir estilo
+│   │   ├── rewrite_apply.ts      # Herramienta: aplicar migraciones
+│   │   ├── rewrite_discover.ts   # Herramienta: descubrir migraciones
+│   │   ├── rewrite_preview.ts    # Herramienta: previsualizar migraciones
+│   │   ├── setup_quality.ts      # Herramienta: configurar plugins
+│   │   └── vulnerability_scan.ts # Herramienta: escanear vulnerabilidades
+│   ├── types/                    # Definiciones TypeScript
+│   │   ├── analysis.ts           # Tipos de análisis
+│   │   ├── index.ts              # Tipos base
+│   │   └── rewrite.ts            # Tipos de OpenRewrite
+│   └── utils/                    # 3 utilidades
+│       ├── error_classifier.ts   # Clasificador de errores Maven
+│       ├── logger.ts             # Sistema de logging (Winston)
+│       └── version_comparator.ts # Comparador de versiones semánticas
+├── tests/                        # 26 suites, 545 tests, 91.69% cobertura
+│   ├── core/                     # 8 test suites
+│   ├── parsers/                  # 8 test suites
+│   ├── tools/                    # 8 test suites
+│   └── utils/                    # 2 test suites
+├── config/
+│   ├── plugin-versions.json      # Versiones de plugins por Java version
+│   └── rewrite-recipes.json      # 40+ recetas OpenRewrite catalogadas
+├── scripts/                      # Scripts de utilidad
+│   ├── check-nvd-status.js       # Verificar estado de descarga CVE
+│   ├── copy-config.cjs           # Copiar config al directorio dist
+│   └── nvd-background-download.js # Descarga CVE database en background
+├── docs/                         # Documentación técnica (C4 diagrams)
+│   ├── c4-component.md           # C4 Component diagram
+│   ├── c4-container.md           # C4 Container diagram
+│   ├── c4-context.md             # C4 Context diagram
+│   ├── openrewrite-integration-plan.md # Plan de integración OpenRewrite
+│   ├── README.md                 # Índice de documentación
+│   └── sequence-diagrams.md      # Diagramas de secuencia de las 8 herramientas
+├── dist/                         # Código compilado (generado por TypeScript)
+├── coverage/                     # Reportes de cobertura de tests
+├── CHANGELOG.md                  # Log de desarrollo
+├── IMPLEMENTATION_STATUS.md      # Estado de implementación de features
+├── MVP_DELIVERY_SUMMARY.md       # Resumen de entrega del MVP
+├── package.json                  # Dependencias y scripts
+├── tsconfig.json                 # Configuración de TypeScript
+└── jest.config.js                # Configuración de Jest (ESM mode)
+```
+
+### Diagrama de Arquitectura (C4 - Contexto)
+
+```mermaid
+graph TB
+    Dev[Desarrollador Java] -->|Comandos| Cell[Cell CLI]
+    Cell -->|MCP/stdio| MCP[Maven Quality MCP Server]
+    MCP -->|Ejecuta| Maven[Apache Maven]
+    Maven -->|Invoca| Tools[Herramientas de Calidad<br/>SpotBugs, Checkstyle, PMD, JaCoCo]
+    MCP -->|Lee reportes| Tools
+
+    style MCP fill:#90EE90
+    style Cell fill:#87CEEB
+    style Maven fill:#FFB6C1
+    style Tools fill:#DDA0DD
+```
+
+### Flujo de Datos Detallado
+
+```mermaid
+sequenceDiagram
+    participant Cell as Cell CLI
+    participant MCP as MCP Server
+    participant Tool as Tool Handler
+    participant Exec as Maven Executor
+    participant Parser as XML Parsers
+
+    Cell->>MCP: Invoca herramienta MCP
+    MCP->>Tool: Delega ejecución
+    Tool->>Exec: Ejecuta Maven
+    Exec-->>Tool: Resultado
+    Tool->>Parser: Parsea reportes XML
+    Parser-->>Tool: Datos estructurados
+    Tool-->>MCP: Respuesta JSON
+    MCP-->>Cell: Resultado final
+```
+
+### 📐 Documentación Completa de Arquitectura
+
+Para una comprensión profunda de la arquitectura, consulta la [documentación técnica completa](./docs/):
+
+- **[Diagrama C4 - Contexto](./docs/c4-context.md)**: Vista general del sistema
+- **[Diagrama C4 - Contenedores](./docs/c4-container.md)**: Módulos y aplicaciones
+- **[Diagrama C4 - Componentes](./docs/c4-component.md)**: Componentes internos
+- **[Diagramas de Secuencia](./docs/sequence-diagrams.md)**: Flujos de ejecución de cada herramienta
+
+## 👨‍💻 Desarrollo
+
+### Configurar Entorno de Desarrollo
+
+```bash
+# 1. Instalar dependencias
+npm install
+
+# 2. Compilar en modo watch
+npm run dev
+
+# 3. En otra terminal, ejecutar tests en modo watch
+npm run test:watch
+```
+
+### Scripts Disponibles
+
+```bash
+# Compilar proyecto
+npm run build
+
+# Compilar en modo watch (desarrollo)
+npm run dev
+
+# Ejecutar tests
+npm test
+
+# Ejecutar tests con cobertura
+npm run test:coverage
+
+# Ejecutar tests en modo watch
+npm run test:watch
+
+# Linting
+npm run lint
+
+# Corregir problemas de linting
+npm run lint:fix
+
+# Formatear código
+npm run format
+```
+
+### Estructura de un Test
+
+```typescript
+describe('ToolName', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should do something', async () => {
+    // Arrange
+    const input = 'test';
+
+    // Act
+    const result = await tool.execute(input);
+
+    // Assert
+    expect(result).toBe(expected);
+  });
+});
+```
+
+### Agregar Nueva Herramienta
+
+1. **Crear archivo en `src/tools/`**:
+
+```typescript
+// src/tools/my_tool.ts
+export const myToolDefinition = {
+  name: 'maven_my_tool',
+  description: 'Description of my tool',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      projectPath: {
+        type: 'string',
+        description: 'Path to Maven project'
+      }
+    },
+    required: ['projectPath']
+  }
+};
+
+export async function handleMyTool(args: any) {
+  // Implementación
+  return { success: true };
+}
+```
+
+2. **Registrar en `src/index.ts`**:
+
+```typescript
+import { myToolDefinition, handleMyTool } from './tools/my_tool';
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    // ... otras herramientas
+    myToolDefinition
+  ]
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name === 'maven_my_tool') {
+    return await handleMyTool(request.params.arguments);
+  }
+  // ...
+});
+```
+
+3. **Crear tests en `tests/tools/`**:
+
+```typescript
+// tests/tools/my_tool.test.ts
+import { handleMyTool } from '../../src/tools/my_tool';
+
+describe('MyTool', () => {
+  it('should work correctly', async () => {
+    // Test implementation
+  });
+});
+```
+
+## 🧪 Testing
+
+### Ejecutar Tests
+
+```bash
+# Todos los tests
+npm test
+
+# Con cobertura
+npm run test:coverage
+
+# Modo watch (desarrollo)
+npm run test:watch
+
+# Test específico
+npm test -- spotbugs_parser.test.ts
+```
+
+### Cobertura Actual
+
+```
+--------------------|---------|----------|---------|---------|
+File                | % Stmts | % Branch | % Funcs | % Lines |
+--------------------|---------|----------|---------|---------|
+All files           |   91.69 |     84.6 |   92.09 |    92.2 |
+ core               |   83.92 |    77.17 |   83.63 |   84.52 |
+ parsers            |   96.01 |    87.29 |   97.61 |   97.15 |
+ tools              |   96.36 |    88.72 |   97.18 |   96.57 |
+ utils              |    90.9 |     87.3 |   96.15 |   90.37 |
+--------------------|---------|----------|---------|---------|
+```
+
+✅ **545 tests pasando** en 26 suites con 0 fallos
+
+### Tests por Componente
+
+- **Parsers (8 suites)**: SpotBugs, Checkstyle, PMD, JaCoCo, Dependency, Rewrite Issues, Rewrite Result, Migration TODO Generator
+- **Core (8 suites)**: Maven Executor, Java Detector, POM Modifier, Backup Manager, Framework Detector, Recipe Manager, Rewrite Executor, Rewrite Version Manager
+- **Tools (8 suites)**: Setup Quality, Analyze, Fix Style, Dependency Analyze, Vulnerability Scan, Rewrite Discover, Rewrite Preview, Rewrite Apply
+- **Utils (2 suites)**: Logger, Error Classifier, Version Comparator
+
+## 🔧 Solución de Problemas
+
+### Detección Automática de Errores
+
+El servidor detecta automáticamente diferentes tipos de errores Maven y proporciona soluciones específicas:
+
+#### Error de Red
+**Síntoma**: "Network error while downloading Maven dependencies"
+
+**Causa**: Problemas de conectividad, proxy, o repositorio inaccesible
+
+**Solución automática sugerida**:
+- Verificar conexión a internet
+- Configurar proxy en `~/.m2/settings.xml` si corresponde
+- Ejecutar Maven con flag `-U` para forzar actualización
+
+#### Error de Compilación
+**Síntoma**: "Java code has compilation errors"
+
+**Causa**: Errores de sintaxis o tipos en código Java
+
+**Solución automática sugerida**:
+- Revisar los errores específicos en la salida de Maven
+- Corregir errores de compilación antes del análisis de calidad
+
+#### Perfil de Calidad Faltante
+**Síntoma**: "Quality profile not configured in pom.xml"
+
+**Causa**: El proyecto no tiene configurado el perfil `-Pquality`
+
+**Solución automática sugerida**:
+- Ejecutar `maven_setup_quality` para configurar automáticamente
+
+#### Dependencias Faltantes
+**Síntoma**: "Maven dependency not found in any repository"
+
+**Causa**: Coordenadas incorrectas o repositorio no configurado
+
+**Solución automática sugerida**:
+- Verificar groupId, artifactId, version en pom.xml
+- Configurar repositorios necesarios
+
+### Error: "Maven not found"
+
+**Problema**: El servidor no encuentra Maven
+
+**Solución**:
+```bash
+# Verificar que Maven está instalado
+mvn --version
+
+# Si no está instalado:
+# macOS: brew install maven
+# Ubuntu: sudo apt install maven
+# Windows: Descargar de https://maven.apache.org/
+```
+
+### Error: "Cannot find module '@modelcontextprotocol/sdk'"
+
+**Problema**: Dependencias no instaladas
+
+**Solución**:
+```bash
+npm install
+npm run build
+```
+
+### Error: "Permission denied" (Linux/macOS)
+
+**Problema**: Permisos incorrectos
+
+**Solución**:
+```bash
+chmod +x build/index.js
+```
+
+### Tests Fallan Localmente
+
+**Problema**: Entorno de test no configurado
+
+**Solución**:
+```bash
+# Limpiar caché de Jest
+npm test -- --clearCache
+
+# Reinstalar dependencias
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### Cell CLI no ve el servidor
+
+**Problema**: Configuración incorrecta
+
+**Solución**:
+1. Verifica la ruta absoluta en la configuración
+2. Compila el proyecto: `npm run build`
+3. Verifica que el archivo `dist/index.js` existe
+4. Lista los servidores: `cell mcp list`
+5. Reinicia Cell CLI
+
+### Logs para Debugging
+
+El servidor genera logs en el directorio configurado en `MCP_ROOT`:
+
+```
+{MCP_ROOT}/logs/
+├── combined.log    # Todos los logs (info, warn, error, debug)
+└── error.log       # Solo errores
+```
+
+**Ver logs en tiempo real:**
+
+```bash
+# Linux/macOS
+tail -f /ruta/al/mcp/logs/combined.log
+
+# Windows (PowerShell)
+Get-Content C:\ruta\al\mcp\logs\combined.log -Wait -Tail 50
+```
+
+**Filtrar logs por nivel:**
+
+```bash
+# Solo errores
+tail -f logs/error.log
+
+# Solo INFO y superiores
+grep "INFO\|WARN\|ERROR" logs/combined.log
+
+# Solo DEBUG
+grep "DEBUG" logs/combined.log
+```
+
+**Configurar nivel de log:**
+
+Para ver más detalles durante debugging, configura `LOG_LEVEL=debug` en tu archivo de configuración de Cell CLI y reinicia.
+
+**Ejemplo de logs:**
+
+```log
+[2025-10-30T04:05:14.867Z] INFO: Quality profile added to pom.xml
+[2025-10-30T04:05:15.123Z] INFO: SpotBugs: Upgrading from 4.7.3.0 to 4.9.3.0
+[2025-10-30T04:05:15.456Z] WARN: Java version not specified in pom.xml
+[2025-10-30T04:05:16.789Z] ERROR: Failed to parse JaCoCo report
+[2025-10-30T04:05:17.012Z] DEBUG: Parsing XML with 1500 lines
+```
+
+---
+