Dependency Doctor

dependency-doc

Un servidor MCP que explica la resolución de dependencias de Maven. Pregunta a tu asistente de IA por qué una versión está en tu classpath — y obtén la respuesta real: qué regla decidió, quién solicitó qué, y la ruta completa de la dependencia que la arrastró.

Tú: ¿por qué tengo commons-lang3 3.9 en mi proyecto?

Claude (vía dependency-doc): La cadena es spring-boot-testcontainers → testcontainers 2.0.5 → commons-compress 1.28.0 → commons-lang3 3.20.0 (alcance test) — pero Maven resolvió a 3.9 de todos modos. Maven no elige la versión más nueva, elige la declaración más cercana en el árbol, y tu pom declara 3.9 directamente. Tu declaración de una línea degradó silenciosamente todo el proyecto en once versiones.

Por qué existe esto

mvn dependency:tree -Dverbose te muestra que una versión fue omitida. Nunca explica por qué — y el porqué involucra reglas que la mayoría de los desarrolladores nunca han aprendido: mediación de gana-el-más-cercano, fijaciones de dependencyManagement, importaciones de BOM, sombreado por exclusiones. Un proyecto típico de Spring Boot hereda más de 1,900 versiones gestionadas que nunca escribió. Cuando una actualización misteriosamente no surte efecto, la respuesta está enterrada en esa maquinaria.

dependency-doc ejecuta la propia maquinaria de resolución de Maven (Maven Resolver + Model Builder) contra tu pom.xml real y expone los resultados como herramientas MCP, para que un asistente de IA pueda responder preguntas sobre dependencias con evidencia en lugar de conjeturas.

Herramientas

analyzeDependencies(pomPath) — verificación de salud del árbol completo: conteos de nodos, dependencias directas, y cada conflicto de versión con su explicación completa.

explainVersion(pomPath, groupArtifact) — la funcionalidad principal. Para una biblioteca: la versión resuelta, la regla que la decidió (declaración directa / dependencyManagement / gana-el-más-cercano), y cada solicitud con su ruta y resultado.

findDependencyPaths(pomPath, groupArtifact) — cada cadena por la cual una biblioteca entra en tu build. Útil para planificar exclusiones.

Configuración

Requiere Java 21+.

git clone https://github.com/sindhunaydu/dependency-doc.git
cd dependency-doc
./gradlew bootJar

Añade a la configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

{
  "mcpServers": {
    "dependency-doc": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/dependency-doc/build/libs/dependency-doc-0.0.1-SNAPSHOT.jar"]
    }
  }
}

Reinicia Claude Desktop por completo, luego pregúntale algo como: "Analiza las dependencias de /path/to/my-project/pom.xml — ¿por qué jackson-databind está en la versión en la que está?"

Cómo funciona

dependency-doc incorpora las mismas bibliotecas sobre las que está construido Maven. El Model Builder convierte tu pom.xml en el modelo efectivo — padres heredados, BOMs importados, propiedades interpoladas. Maven Resolver luego recopila el grafo completo de dependencias con la preservación de perdedores de conflictos habilitada, de modo que las solicitudes superadas permanezcan en el grafo, marcadas con lo que las venció. La capa de análisis recorre ese grafo y convierte las marcas en explicaciones.

El análisis difiere de un build en un aspecto importante: las dependencias de test y provided de tu propio proyecto son parte de la verdad (un selector de alcance personalizado codifica la semántica exacta de Maven — dependencias de test directas incluidas, universos de test de otras bibliotecas excluidos).

Una nota sobre el modo estricto (una saga de depuración)

Esta herramienta se niega a omitir ramas silenciosamente. Durante el desarrollo, una pila de valores predeterminados silenciosos — una política indulgente de descriptores de artefactos más una lista de excepciones de aspecto vacío — produjo un confiado "Conflictos: 0" en un proyecto que verificablemente tenía conflictos. La causa: los poms padre con perfiles activados por JDK fallaban al construirse cuando la sesión del resolver carecía de propiedades del sistema, y la política indulgente se tragaba cada fallo, dejando nodos sin hijos y un informe de aspecto limpio.

Por lo tanto, dependency-doc se ejecuta con una política estricta de descriptores y expone cada problema de recopilación en sus respuestas. Un análisis que falla ruidosamente es útil; uno que miente con confianza es peor que ninguno. Si una respuesta incluye una sección "⚠ Análisis incompleto", créela.

Limitaciones y hoja de ruta

• Solo Maven, por ahora. La resolución de Gradle usa un modelo genuinamente diferente (gana-el-más-alto, restricciones, reglas de resolución) y está planificada como v2 mediante la Gradle Tooling API.
• Proyectos de módulo único; el soporte de reactor multimódulo está planificado.
• El diffing de árboles (what changes if I bump X?) está en la hoja de ruta.

Se aceptan issues y PRs.

Licencia

Apache 2.0