Dependency Doctor

dependency-doc

Um servidor MCP que explica a resolução de dependências do Maven. Pergunte ao seu assistente de IA por que uma versão está no seu classpath — e obtenha a resposta real: qual regra decidiu, quem solicitou o quê, e o caminho completo da dependência que a trouxe.

Você: por que tenho commons-lang3 3.9 no meu projeto?

Claude (via dependency-doc): A cadeia é spring-boot-testcontainers → testcontainers 2.0.5 → commons-compress 1.28.0 → commons-lang3 3.20.0 (escopo de teste) — mas o Maven resolveu para 3.9 mesmo assim. O Maven não escolhe a versão mais nova, ele escolhe a declaração mais próxima na árvore, e o seu pom declara 3.9 diretamente. Sua declaração de uma linha silenciosamente rebaixou todo o projeto em onze versões.

Por que isso existe

mvn dependency:tree -Dverbose mostra que uma versão foi omitida. Nunca explica por que — e o porquê envolve regras que a maioria dos desenvolvedores nunca aprendeu: mediação nearest-wins, pins de dependencyManagement, imports de BOM, sombreamento de exclusões. Um projeto Spring Boot típico herda mais de 1.900 versões gerenciadas que nunca escreveu. Quando um upgrade misteriosamente não tem efeito, a resposta está enterrada nessa maquinaria.

dependency-doc executa a própria maquinaria de resolução do Maven (Maven Resolver + Model Builder) contra o seu pom.xml real e expõe os resultados como ferramentas MCP, para que um assistente de IA possa responder perguntas sobre dependências com evidências em vez de suposições.

Ferramentas

analyzeDependencies(pomPath) — verificação de saúde da árvore completa: contagem de nós, dependências diretas e cada conflito de versão com sua explicação completa.

explainVersion(pomPath, groupArtifact) — o recurso principal. Para uma biblioteca: a versão resolvida, a regra que a decidiu (declaração direta / dependencyManagement / nearest-wins), e cada solicitação com seu caminho e resultado.

findDependencyPaths(pomPath, groupArtifact) — todas as cadeias pelas quais uma biblioteca entra no seu build. Útil para planejar exclusões.

Configuração

Requer Java 21+.

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

Adicione à configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

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

Reinicie o Claude Desktop completamente e então pergunte algo como: "Analise as dependências de /path/to/my-project/pom.xml — por que o jackson-databind está na versão em que está?"

Como funciona

dependency-doc incorpora as mesmas bibliotecas sobre as quais o Maven é construído. O Model Builder transforma seu pom.xml no modelo efetivo — pais herdados, BOMs importados, propriedades interpoladas. O Maven Resolver então coleta o grafo completo de dependências com a preservação de perdedores de conflito habilitada, para que solicitações superadas permaneçam no grafo, marcadas com o que as venceu. A camada de análise percorre esse grafo e transforma as marcações em explicações.

A análise difere de um build de uma maneira importante: as dependências de teste e provided do seu próprio projeto fazem parte da verdade (um seletor de escopo personalizado codifica a semântica exata do Maven — dependências de teste diretas incluídas, universos de teste de outras bibliotecas excluídos).

Uma nota sobre o modo estrito (uma saga de depuração)

Esta ferramenta se recusa a omitir ramos silenciosamente. Durante o desenvolvimento, uma pilha de padrões silenciosos — uma política permissiva de descritor de artefato mais uma lista de exceções aparentemente vazia — produziu um confiante "Conflicts: 0" em um projeto que comprovadamente tinha conflitos. A causa: poms pais com perfis ativados por JDK falhavam ao construir quando a sessão do resolver não tinha propriedades de sistema, e a política permissiva engolia todas as falhas, deixando nós sem filhos e um relatório de aparência limpa.

dependency-doc, portanto, executa com uma política estrita de descritor e expõe todos os problemas de coleta em suas respostas. Uma análise que falha ruidosamente é útil; uma que mente com confiança é pior do que nenhuma. Se uma resposta incluir uma seção "⚠ Análise incompleta", acredite nela.

Limitações e roteiro

• Somente Maven, por enquanto. A resolução do Gradle usa um modelo genuinamente diferente (highest-wins, constraints, regras de resolução) e está planejada como v2 via Gradle Tooling API.
• Projetos de módulo único; suporte a reator multi-módulo está planejado.
• Diff de árvore (what changes if I bump X?) está no roteiro.

Issues e PRs são bem-vindos.

Licença

Apache 2.0