maven-indexer-mcp

Um servidor Model Context Protocol (MCP) que indexa seu repositório Maven local (~/.m2/repository) e cache Gradle (~/.gradle/caches/modules-2/files-2.1) para fornecer ferramentas a agentes de IA para pesquisar classes Java, assinaturas de métodos e código-fonte.

GitHub
22
Experimente este MCPPatrocinado

Documentação

Servidor MCP do Maven Indexer

npm version Tests

Um servidor Model Context Protocol (MCP) que indexa seu repositório Maven local (~/.m2/repository) e cache do Gradle ( ~/.gradle/caches/modules-2/files-2.1) para fornecer ferramentas a agentes de IA para buscar classes Java, assinaturas de métodos e código-fonte.

Caso de Uso Principal: Embora modelos de IA sejam bem versados em bibliotecas públicas populares (como Spring, Apache Commons, Guava), eles frequentemente têm dificuldade com:

  1. Pacotes Internos da Empresa: Bibliotecas privadas que não são públicas.
  2. Pacotes Públicos Pouco Conhecidos: Bibliotecas de código aberto de nicho ou menos populares.

Este servidor preenche essa lacuna permitindo que a IA "leia" suas dependências locais, efetivamente dando a ela conhecimento de suas bibliotecas privadas e obscuras.

Recursos

  • Busca Semântica de Classes: Busque classes por nome ou finalidade.
  • Busca por Herança: Encontre todas as implementações de uma interface ou subclasses de uma classe.
  • Análise Sob Demanda: Extrai assinaturas de métodos e Javadocs diretamente de JARs.
  • Recuperação de Código-Fonte: Fornece o código-fonte completo, se disponível.
  • Monitoramento em Tempo Real: Atualiza automaticamente o índice quando os repositórios mudam.

Maven Indexer MCP vs Maven Indexer CLI

Este pacote fornece uma interface MCP para o índice Maven/Gradle. Se você está usando um agente de codificação no terminal, você pode se beneficiar do uso do CLI + SKILL em vez disso.

  • CLI: Agentes de codificação modernos cada vez mais preferem fluxos de trabalho baseados em CLI expostos como SKILLs em vez de MCP porque invocações de CLI são mais eficientes em tokens: elas evitam carregar grandes esquemas de ferramentas no contexto do modelo, permitindo que agentes atuem por meio de comandos concisos e específicos. Isso torna CLI + SKILLs mais adequados para agentes de codificação de alto rendimento que devem equilibrar consultas de dependências com grandes bases de código e raciocínio dentro de janelas de contexto limitadas.
    Saiba mais sobre Maven Indexer CLI com SKILLS.

  • MCP: MCP continua sendo a melhor escolha para agentes integrados a IDEs (Cursor, Kiro, Windsurf, etc.) que se beneficiam de indexação persistente em segundo plano, monitoramento automático de repositórios e invocação de ferramentas sem necessidade de configuração de CLI. O servidor MCP indexa seu repositório em segundo plano e mantém o índice atualizado automaticamente.

Primeiros Passos

Adicione a seguinte configuração ao seu cliente MCP:

{
  "mcpServers": {
    "maven-indexer": {
      "command": "npx",
      "args": [
        "-y",
        "maven-indexer-mcp@latest"
      ]
    }
  }
}

Isso baixará e executará automaticamente a versão mais recente do servidor. Ele detectará automaticamente a localização do seu repositório Maven (geralmente ~/.m2/repository) e o cache do Gradle.

Configuração do Cliente MCP

Cline

Siga o guia MCP do Cline e use a configuração fornecida acima.

Codex

Siga o guia de configuração do MCP usando a configuração padrão acima.

Cursor

Clique no botão para instalar:

Cursor

Ou instale manualmente:

Vá para Cursor Settings -> MCP -> New MCP Server. Use a configuração fornecida acima.

JetBrains AI Assistant & Junie

Vá para Settings | Tools | AI Assistant | Model Context Protocol (MCP) -> Add. Use a configuração fornecida acima. Da mesma forma, maven-indexer pode ser configurado para JetBrains Junie em Settings | Tools | Junie | MCP Settings ->Add. Use a configuração fornecida acima.

Kiro

Em Configurações do Kiro, vá para Configure MCP > Open Workspace or User MCP Config > Use o trecho de configuração fornecido acima.

Ou, a partir da Barra de Atividades da IDE > Kiro > MCP Servers > Click Open MCP Config. Use o trecho de configuração fornecido acima.

Qoder

Em Configurações do Qoder, vá para MCP Server > + Add > Use o trecho de configuração fornecido acima.

Alternativamente, siga o guia MCP e use a configuração padrão acima.

Trae

Vá para Settings -> MCP -> + Add -> Add Manually para adicionar um Servidor MCP. Use a configuração fornecida acima.

Windsurf

Siga o guia de configuração do MCP usando a configuração padrão acima.

Seu primeiro prompt

Digite o seguinte prompt no seu Cliente MCP para verificar se tudo está funcionando:

Find the class `StringUtils` in my local maven repository and show me its methods.

Seu cliente MCP deve ler a classe StringUtils do seu repositório Maven local e mostrar seus métodos.

Configuração (Opcional)

Se a detecção automática falhar, ou se você quiser filtrar quais pacotes são indexados, você pode adicionar variáveis de ambiente à configuração:

  • MAVEN_REPO: Caminho absoluto para seu repositório Maven local (ex.: /Users/yourname/.m2/repository). Use isso se seu repositório estiver em um local não padrão.
  • GRADLE_REPO_PATH: Caminho absoluto para seu cache do Gradle (ex.: /Users/yourname/.gradle/caches/modules-2/files-2.1).
  • INCLUDED_PACKAGES: Lista separada por vírgulas de padrões de pacotes para indexar (ex.: com.mycompany.*,org.example.*). O padrão é * (indexar tudo).
  • MAVEN_INDEXER_CFR_PATH: (Opcional) Caminho absoluto para um JAR específico do decompilador CFR. Se não for fornecido, o servidor tentará usar sua versão CFR integrada.
  • VERSION_RESOLUTION_STRATEGY: (Opcional) Estratégia para escolher a versão quando múltiplas versões de um artefato são encontradas e nenhuma coordenada específica é fornecida.
    • semver: (Padrão) Prefira a versão semântica mais alta (ex.: 1.2.0 > 1.1.9).
    • latest-published: Prefira a versão com o horário de publicação mais recente (verifica *.pom.lastUpdated primeiro, depois o horário de modificação do arquivo).
    • latest-used: Prefira a versão mais recentemente importada/usada pelo usuário (com base no horário de criação do arquivo).

Exemplo com configuração opcional:

{
  "mcpServers": {
    "maven-indexer": {
      "command": "npx",
      "args": [
        "-y",
        "maven-indexer-mcp@latest"
      ],
      "env": {
        "MAVEN_REPO": "/Users/yourname/.m2/repository",
        "GRADLE_REPO_PATH": "/Users/yourname/.gradle/caches/modules-2/files-2.1",
        "INCLUDED_PACKAGES": "com.mycompany.*",
        "MAVEN_INDEXER_CFR_PATH": "/path/to/cfr-0.152.jar",
        "VERSION_RESOLUTION_STRATEGY": "semver"
      }
    }
  }
}

Desenvolvimento Local

Se você preferir executar a partir do código-fonte:

  1. Clone o repositório:

    git clone https://github.com/tangcent/maven-indexer-mcp.git
cd maven-indexer-mcp

  2. Instale as dependências e compile:

    npm install
npm run build

  3. Use o caminho absoluto na sua configuração:

    {
  "mcpServers": {
    "maven-indexer": {
      "command": "node",
      "args": ["/absolute/path/to/maven-indexer-mcp/build/index.js"]
    }
  }
}

Ferramentas Disponíveis

  • search_classes: Busque classes Java no repositório Maven local e caches do Gradle.

    • QUANDO USAR: 1. Código Interno/Privado: Você precisa encontrar uma classe de uma biblioteca interna da empresa. 2. Bibliotecas Obscuras: Você está usando uma biblioteca pública menos comum que a IA não conhece bem. 3. Verificação de Versão: Você precisa verificar exatamente qual versão de uma classe está presente localmente.

      • Nota: Para bibliotecas bem conhecidas (ex.: bibliotecas Java padrão, Spring), a IA provavelmente já conhece a estrutura da classe, então esta ferramenta é menos crítica.

    • Exemplos: "Mostre-me o código-fonte de StringUtils", "Quais métodos estão disponíveis em DateTimeUtils?", "De onde esta classe é importada?".

    • Entrada: className (ex.: "StringUtils", "Parser Json")

    • Saída: Lista de classes correspondentes com seus artefatos.

  • get_class_details: Descompile e leia o código-fonte de bibliotecas/dependências externas. Use isso em vez de 'SearchCodebase' para classes que são importadas, mas definidas em arquivos JAR.
    • Valor Principal: "Não adivinhe o que a biblioteca interna faz—leia o código."
    • Dica: Essencial para código interno/proprietário onde a documentação é escassa ou inexistente.
    • Entrada: className (obrigatório), artifactId (opcional), type ("signatures", "docs", "source")
    • Saída: Assinaturas de métodos, Javadocs ou código-fonte completo.
    • Nota: Se artifactId for omitido, a ferramenta seleciona automaticamente o melhor artefato disponível (preferindo aqueles com código-fonte anexado).
  • search_artifacts: Busque artefatos nos caches Maven/Gradle por coordenada (groupId, artifactId).
  • search_implementations: Busque classes que implementam uma interface específica ou estendem uma classe específica. Útil para encontrar implementações de SPI em bibliotecas externas.
    • Entrada: className (ex.: "java.util.List")
    • Saída: Lista de nomes de implementações/subclasses e seus artefatos.
  • refresh_index: Acione uma nova varredura do repositório Maven.

Desenvolvimento

  • Executar testes: npm test
  • Modo de observação: npm run watch

Licença

ISC