@machina.ai/maven-quality-mcp

v1.3.0

Published

5 months ago

MCP server for Maven code quality analysis and automated fixes

0High
0Medium
0Low

djmartinez

reboot-machina

maven mcp code-quality spotbugs checkstyle pmd jacoco dependencies vulnerabilities owasp security ai

Maven Quality MCP Server

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?

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)

Compatibilidad Java/JDK

El servidor es compatible con JDK 8 - JDK 25 y configura automáticamente los flags JVM necesarios:

JDK 17 - 25 (Recomendado)

✅ Soporte completo con configuración automática de flags
🔧 Flags --add-opens agregados automáticamente para evitar warnings de reflexión
⚡ Mejor rendimiento y features modernos de Java

JDK 11 - 16

✅ Soporte completo sin configuración adicional
Recomendado para proyectos legacy

JDK 8 - 10

⚠️ Soporte básico - algunas features de migración limitadas
Recomendado migrar a JDK 17+ para mejor experiencia

Nota sobre JDK 25: Algunos plugins (como Spotless/Google Java Format) pueden mostrar warnings sobre "restricted method access" al usar reflexión para acceder a APIs internas. Estos warnings son esperados y no bloquean la ejecución. El servidor configura automáticamente los flags JVM necesarios para minimizarlos.

Si deseas configurar MAVEN_OPTS manualmente:

export MAVEN_OPTS="-Xmx2048m --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.util=ALL-UNNAMED"

Clientes MCP Compatibles

Cell CLI (Terminal) - Recomendado
Cualquier cliente compatible con MCP

🚀 Instalación

Desde npm (Recomendado)

# Instalación global
npm install -g maven-quality-mcp

# Verificar instalación
maven-quality-mcp --version

Desde Código Fuente

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

cell mcp add maven-quality maven-quality-mcp

Opción 2: Configuración manual

Localiza el archivo de configuración:
- ~/.cell/settings.json (Linux/macOS)
- %USERPROFILE%\.cell\settings.json (Windows)
Agrega el servidor MCP:

{
  "mcpServers": {
    "maven-quality": {
      "command": "maven-quality-mcp",
      "env": {
        "MCP_ROOT": "/ruta/donde/guardar/logs",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Ejemplo Windows:

{
  "mcpServers": {
    "maven-quality": {
      "command": "maven-quality-mcp",
      "env": {
        "MCP_ROOT": "C:\\Users\\TuUsuario\\maven-quality-logs",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Reinicia Cell CLI

Configuración en Cell CLI (Instalación desde Código Fuente)

Opción 1: Usando comando

cell mcp add maven-quality node /ruta/completa/maven-quality-mcp/dist/index.js

Opción 2: Configuración manual

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

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

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

cell "Configura las herramientas de calidad en mi proyecto"

Cell CLI ejecutará maven_setup_quality y configurará todos los plugins necesarios.

Analizar Código

cell "¿Qué problemas de calidad tiene mi código?"

Cell CLI ejecutará maven_analyze y te mostrará un reporte detallado.

Corregir Problemas de Estilo

cell "Arregla los problemas de formateo en mi código"

Cell CLI ejecutará maven_fix_style y aplicará las correcciones.

Flujo de Trabajo Completo

$ 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 9 herramientas MCP (6 para análisis de calidad/seguridad + 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:

{
  "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):

{
  "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):

{
  "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:

{
  "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):

{
  "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):

{
  "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):

Solicitar: https://nvd.nist.gov/developers/request-an-api-key
Llenar formulario: Nombre, email, tipo de organización
Recibir email con link de activación (inmediato)
Activar y copiar el API key (solo se muestra una vez)
Configurar en Cell CLI:

{
  "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"
      }
    }
  }
}

Reiniciar Cell CLI y listo!

Comandos útiles:

# 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

5. `maven_security_scan`

Descripción: Ejecuta análisis de seguridad OWASP con Find Security Bugs (plugin de SpotBugs)

Parámetros:

projectPath (string, requerido): Ruta al proyecto Maven
timeout (number, opcional, default: 300000): Timeout en milisegundos (5 minutos)

Qué hace:

Ejecuta SpotBugs con el plugin Find Security Bugs de OWASP
Detecta 144+ tipos de vulnerabilidades de seguridad
Categoriza vulnerabilidades por tipo (Injection, Cryptography, Authentication, XXE, etc.)
Mapea a OWASP Top 10 2021 y CWE (Common Weakness Enumeration)
Genera reporte detallado con severidad (CRITICAL, HIGH, MEDIUM, LOW)

Tipos de Vulnerabilidades Detectadas:

Injection: SQL, Command, XPath, LDAP, Script Engine, SpEL, EL
Cryptography: Weak hashing (MD5/SHA1), weak ciphers, DES usage, static IV, ECB mode
Authentication: Hard-coded passwords/keys, weak trust managers
XXE: XML External Entity attacks
Path Traversal: Directory traversal, file upload vulnerabilities
XSS: Cross-Site Scripting
Security Misconfiguration: Insecure cookies, Android permissions
Insecure Deserialization: Object deserialization gadgets

Ejemplo de salida:

{
  "success": true,
  "executionTime": 45200,
  "totalSecurityIssues": 23,
  "summary": {
    "bySeverity": {
      "critical": 3,
      "high": 8,
      "medium": 10,
      "low": 2
    },
    "byCategory": {
      "injection": 5,
      "cryptography": 8,
      "authentication": 3,
      "xxe": 2,
      "pathTraversal": 3,
      "xss": 1,
      "securityMisconfiguration": 1,
      "insecureDeserialization": 0,
      "other": 0
    }
  },
  "securityIssues": {
    "injection": [
      {
        "file": "UserService.java",
        "line": 123,
        "type": "SQL_INJECTION_JDBC",
        "category": "INJECTION",
        "severity": "CRITICAL",
        "message": "This SQL query is vulnerable to SQL injection",
        "cwe": "CWE-89",
        "owaspCategory": "A03:2021 – Injection",
        "className": "com.example.UserService"
      }
    ],
    "cryptography": [
      {
        "file": "EncryptionUtil.java",
        "line": 45,
        "type": "WEAK_MESSAGE_DIGEST_MD5",
        "category": "CRYPTOGRAPHY",
        "severity": "HIGH",
        "message": "MD5 is a weak hashing algorithm",
        "cwe": "CWE-327",
        "owaspCategory": "A02:2021 – Cryptographic Failures"
      }
    ]
    // ... otras categorías
  },
  "formattedReport": "# 🔒 SECURITY SCAN (OWASP Find Security Bugs)\n\n..."
}

Comandos útiles:

# Análisis de seguridad completo
cell "Ejecuta un análisis de seguridad OWASP de mi proyecto"

# Solo vulnerabilidades críticas
cell "Muéstrame solo las vulnerabilidades críticas de seguridad"

# Comparar con maven_vulnerability_scan
# - maven_vulnerability_scan: Escanea dependencias para CVEs conocidos
# - maven_security_scan: Analiza el código fuente para vulnerabilidades OWASP

Notas importantes:

⚡ Más rápido que maven_vulnerability_scan (~5 min vs 15+ min primera vez)
🔍 Análisis de código: Revisa tu código fuente, no solo dependencias
📋 OWASP Top 10: Cubre las 10 vulnerabilidades más críticas según OWASP
✅ Sin descargas: No requiere base de datos externa (a diferencia de Dependency-Check)
🎯 Complementario: Usar junto con maven_vulnerability_scan para análisis completo

🔄 Herramientas de Migración (OpenRewrite)

6. `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:

{
  "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"
  }
}

7. `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:

{
  "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
  }
}

8. `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:

Backup automático: Copia el proyecto a backup-{timestamp}/
Ejecución OpenRewrite: Aplica recetas en modo run
Parsing de resultados: Extrae archivos modificados y estadísticas
Detección de issues: Identifica código que requiere migración manual
Generación de TODO: Crea MIGRATION-TODO.md con tareas pendientes
Comentarios en código: Inserta // MIGRATION TODO: en líneas problemáticas
Validación: Ejecuta mvn clean compile -DskipTests (5 min timeout)
Git commit (opcional): Crea commit con mensaje estructurado
Rollback automático: Restaura backup si falla

Ejemplo de salida (migración exitosa):

{
  "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:

# 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
│   │   ├── security_parser.ts    # Parser de vulnerabilidades OWASP
│   │   └── spotbugs_parser.ts    # Parser de reportes SpotBugs
│   ├── tools/                    # 9 herramientas MCP
│   │   ├── analyze.ts            # Herramienta: analizar calidad
│   │   ├── dependency_analyze.ts # Herramienta: analizar dependencias
│   │   ├── fix_style.ts          # Herramienta: corregir estilo
│   │   ├── security_scan.ts      # Herramienta: análisis de seguridad OWASP
│   │   ├── 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 9 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)

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

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:

Diagrama C4 - Contexto: Vista general del sistema
Diagrama C4 - Contenedores: Módulos y aplicaciones
Diagrama C4 - Componentes: Componentes internos
Diagramas de Secuencia: Flujos de ejecución de cada herramienta

👨‍💻 Desarrollo

Configurar Entorno de Desarrollo

# 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

# 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

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

Crear archivo en src/tools/:

// 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 };
}

Registrar en src/index.ts:

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);
  }
  // ...
});

Crear tests en tests/tools/:

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

# 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.54 |    83.94 |   93.07 |   91.97 |
 core               |   83.39 |    76.79 |   83.92 |   83.92 |
 parsers            |   95.85 |    85.81 |   98.36 |   96.74 |
 tools              |   96.12 |    88.46 |   97.22 |   96.31 |
 utils              |    90.9 |     87.3 |   96.15 |   90.37 |
--------------------|---------|----------|---------|---------|

✅ 572 tests pasando en 28 suites con 0 fallos

Tests por Componente

Parsers (9 suites): SpotBugs, Checkstyle, PMD, JaCoCo, Dependency, Security, 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 (9 suites): Setup Quality, Analyze, Fix Style, Dependency Analyze, Vulnerability Scan, Security 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:

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

npm install
npm run build

Error: "Permission denied" (Linux/macOS)

Problema: Permisos incorrectos

Solución:

chmod +x build/index.js

Tests Fallan Localmente

Problema: Entorno de test no configurado

Solución:

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

Verifica la ruta absoluta en la configuración
Compila el proyecto: npm run build
Verifica que el archivo dist/index.js existe
Lista los servidores: cell mcp list
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:

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

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

[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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Maven Quality MCP Server

📋 Tabla de Contenidos

🎯 ¿Qué es Maven Quality MCP?

✨ Características

Análisis de Calidad

Corrección Automática

Configuración Inteligente

📦 Requisitos

Requisitos del Sistema

Compatibilidad Java/JDK

JDK 17 - 25 (Recomendado)

JDK 11 - 16

JDK 8 - 10

Clientes MCP Compatibles

🚀 Instalación

Desde npm (Recomendado)

Desde Código Fuente

⚙️ Configuración

Configuración en Cell CLI (Instalación Global)

Configuración en Cell CLI (Instalación desde Código Fuente)

Variables de Entorno

Verificar Configuración

💡 Uso

Uso Básico con Cell CLI

Ejemplos de Comandos

Configurar Herramientas de Calidad

Analizar Código

Corregir Problemas de Estilo

Flujo de Trabajo Completo

🛠️ Herramientas Disponibles

1. maven_setup_quality

2. maven_analyze

3. maven_fix_style

4. maven_dependency_analyze

5. maven_security_scan

🔄 Herramientas de Migración (OpenRewrite)

6. maven_rewrite_discover

7. maven_rewrite_preview

8. maven_rewrite_apply

🏗️ Arquitectura del Proyecto

Estructura de Directorios

Diagrama de Arquitectura (C4 - Contexto)

Flujo de Datos Detallado

📐 Documentación Completa de Arquitectura

👨‍💻 Desarrollo

Configurar Entorno de Desarrollo

Scripts Disponibles

Estructura de un Test

Agregar Nueva Herramienta

🧪 Testing

Ejecutar Tests

Cobertura Actual

Tests por Componente

🔧 Solución de Problemas

Detección Automática de Errores

Error de Red

Error de Compilación

Perfil de Calidad Faltante

Dependencias Faltantes

Error: "Maven not found"

Error: "Cannot find module '@modelcontextprotocol/sdk'"

Error: "Permission denied" (Linux/macOS)

Tests Fallan Localmente

Cell CLI no ve el servidor

Logs para Debugging

1. `maven_setup_quality`

2. `maven_analyze`

3. `maven_fix_style`

4. `maven_dependency_analyze`

5. `maven_security_scan`

6. `maven_rewrite_discover`

7. `maven_rewrite_preview`

8. `maven_rewrite_apply`