Maven Decoder MCP

Servidor MCP para inspecionar, pesquisar e descompilar JARs do Maven .m2 para agentes de codificação Java com IA.

Documentação

Servidor Maven Decoder MCP

Seu agente adivinha APIs de bibliotecas que nunca leu. Isso faz com que ele as leia.

Permite que agentes de IA leiam o código-fonte real de qualquer dependência Maven — descompila jars do ~/.m2 ou Maven Central, e compara versões para detectar mudanças que quebram código.

Demo: comparing jsoup 1.17.2 with 1.23.2

Pergunte a um agente "Estou atualizando o org.jsoup:jsoup de 1.17.2 para 1.23.2 — o que quebra?" e sem uma forma de ler os jars, ele responderá de memória. Com este servidor, compare_versions lê ambos os jars e relata o que realmente mudou:

	1.17.2 → 1.23.2
Mudanças que quebram	45
Membros removidos	31
Membros adicionados	150
Classes com mudanças de API	47 de 115 comparadas

Os membros são comparados como declarados, então um que foi movido para uma superclasse é relatado como removido, mesmo que ainda possa ser chamável. A ferramenta declara isso em sua própria saída.

Funciona também em artefatos que não possuem jar de fontes: extract_class_info usa como fallback o javap e retorna campos, métodos e versão do bytecode analisados — que é exatamente o caso dos artefatos internos em um Nexus corporativo.

Experimente em um único comando

npx skills add https://github.com/salitaba/maven-decoder-mcp --skill maven-code-search

Isso instala a habilidade de agente maven-code-search, que informa ao seu agente quando usar essas ferramentas. Para uma configuração de servidor MCP pura, veja Instalação.

🚀 Recursos

Funcionalidade Principal

Análise de Arquivos Jar: Inspeção profunda de arquivos jar, incluindo metadados, manifests e estrutura
Resolução de Dependências: Análise completa da árvore de dependências com dependências transitivas
Extração de Código-Fonte: Extrai código-fonte de jars de fontes ou descompila bytecode
Informações de Classes: Assinaturas detalhadas de classes, métodos, campos e anotações
Capacidades de Busca: Encontra classes, métodos e dependências em todos os artefatos
Gerenciamento de Versões: Compara versões, encontra dependentes e rastreia conflitos de versão

Suporte Online ao Maven

Busca no Maven Central: Encontra artefatos e classes que não estão instalados localmente
Listagem Remota de Versões: Veja todas as versões publicadas, não apenas as que você possui
Download Sob Demanda: Busca qualquer artefato (jar, fontes, POM) em um cache local
Fallback Transparente: Cada ferramenta de análise baixa automaticamente um artefato ausente, então descompilar uma dependência que você nunca instalou simplesmente funciona
Compatível com Mirrors: Aponte para um Nexus/Artifactory corporativo, com credenciais opcionais
Modo Offline: Uma única variável de ambiente restaura o comportamento totalmente local, sem rede

Recursos Avançados

Suporte a Descompilação: Suporte integrado para múltiplos descompiladores Java (CFR, Fernflower, Procyon)
Análise de Conflitos: Detecta e analisa conflitos de versão de dependências
Navegação no Repositório: Navegue e explore a estrutura do repositório Maven local
Análise de Metadados: Extrai e analisa arquivos POM e metadados do Maven
Descoberta de Serviços: Encontra e analisa serviços Java e implementações SPI
Gerenciamento de Respostas: Paginação inteligente e resumo para respostas grandes
Extração de Métodos: Extrai métodos específicos de classes Java grandes
Verificação de Integridade: Downloads são verificados contra as somas de verificação SHA-1 do repositório

📦 Instalação

Pré-requisitos

Java 8+ (para recursos de descompilação)
Repositório local Maven (~/.m2/repository)
Um dos: Python 3.8+, Node.js 14+, ou Docker

🚀 Instalação Rápida

Instalação em Uma Linha (Recomendado)

curl -fsSL https://raw.githubusercontent.com/salitaba/maven-decoder-mcp/main/install.sh | bash

📋 Métodos de Instalação

Método 1: uvx (Recomendado)

# Install uv (if not installed)
curl -Ls https://astral.sh/uv/install.sh | sh
# Ensure your shell PATH is updated (restart shell or eval as printed by installer)

# Run the server via uvx (isolated, fast, no venv needed)
uvx maven-decoder-mcp

# Optional: pick a specific Python
# uvx --python 3.12 maven-decoder-mcp

Método 2: Node.js/npm

# Install globally
npm install -g maven-decoder-mcp

# Or install locally
npm install maven-decoder-mcp

# Run the server
maven-decoder-mcp
# or if installed locally: npx maven-decoder-mcp

Método 3: Docker

# Pull and run
docker run --rm -it \
  -v ~/.m2:/home/mcpuser/.m2 \
  -v $(pwd):/workspace \
  ali79taba/maven-decoder-mcp:latest

Método 4: A partir do Código-Fonte (Desenvolvimento)

# Clone repository
git clone https://github.com/salitaba/maven-decoder-mcp.git
cd maven-decoder-mcp

# Option A: Using Virtual Environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install "git+https://github.com/modelcontextprotocol/python-sdk.git"
./setup_decompilers.sh

# Option B: System-wide Installation (not recommended)
./setup_decompilers.sh

Windows

Para um checkout do código-fonte, use Python 3.10 ou mais recente e um JDK no PATH. A partir da raiz do repositório, crie e ative um ambiente virtual no PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

# Point to your existing local Maven repository (drive-letter paths are supported)
$env:MAVEN_REPOSITORY = 'F:\data\repository'
maven-decoder-mcp

No Prompt de Comando (cmd.exe), ative com .venv\Scripts\activate.bat e defina o repositório com set "MAVEN_REPOSITORY=F:\data\repository" em vez disso. Essas configurações de ambiente se aplicam a programas iniciados a partir desse terminal; defina-as no ambiente do seu cliente MCP quando ele iniciar o servidor separadamente.

Downloads remotos usam um cache separado, resolvido nesta ordem (valores vazios são ignorados):

MAVEN_DECODER_CACHE_DIR: o diretório de cache completo; nenhum subdiretório é anexado.
XDG_CACHE_HOME: anexa maven-decoder-mcp\repository.
LOCALAPPDATA: anexa maven-decoder-mcp\repository.
Caso contrário, ~/.cache/maven-decoder-mcp/repository no diretório inicial do usuário.

No Windows, isso geralmente significa %LOCALAPPDATA%\maven-decoder-mcp\repository; XDG_CACHE_HOME ainda tem precedência se definido. O cache usa o layout de diretórios do Maven, mas permanece separado do repositório local real, para que os downloads não interfiram nas builds do Maven. Definir MAVEN_REPOSITORY não altera o local do cache.

🔧 Configuração

Para o IDE Cursor

Adicione ao seu ~/.cursor/mcp_servers.json:

{
  "maven-decoder": {
    "command": "uvx",
    "args": ["maven-decoder-mcp"]
  }
}

Para Outros Clientes MCP

O servidor funciona como um servidor MCP padrão e pode ser integrado a qualquer cliente compatível com MCP.

🧠 Habilidade de Agente de IA

Este repositório inclui uma habilidade de agente maven-code-search que informa aos agentes de codificação de IA quando e como usar este MCP para pesquisar código de pacotes Maven instalados.

npx skills add https://github.com/salitaba/maven-decoder-mcp --skill maven-code-search

A habilidade está localizada em skills/maven-code-search e está pronta para indexação pelo skills.sh após o repositório ser enviado.

🛠️ Ferramentas Disponíveis

Análise Local

Ferramenta	Descrição
`list_artifacts`	Lista artefatos no repositório Maven com filtragem
`analyze_jar`	Analisa a estrutura e o conteúdo de arquivos jar
`extract_class_info`	Obtém informações detalhadas sobre classes Java
`get_dependencies`	Recupera dependências Maven de arquivos POM
`search_classes`	Busca classes em todos os jars, opcionalmente filtradas por anotação
`extract_source_code`	Descompila e extrai código-fonte Java
`extract_jar_resource`	Extrai recursos de texto, como arquivos `.proto`, serviços e metadados
`compare_versions`	Compara duas versões, incluindo diff de API pública e mudanças que quebram
`find_usage_examples`	Encontra classes que referenciam uma determinada classe ou método
`get_dependency_tree`	Obtém a árvore de dependências completa
`find_dependents`	Encontra artefatos que dependem de um artefato específico
`get_version_info`	Obtém versões instaladas de um artefato (defina `include_remote` para adicionar as publicadas)
`analyze_jar_structure`	Analisa a estrutura geral e os metadados do jar
`extract_method_info`	Extrai informações de métodos específicos de classes Java

Online (Maven Central)

Ferramenta	Descrição
`search_maven_central`	Busca no Maven Central por artefatos por nome, coordenadas ou classe contida
`get_remote_versions`	Lista todas as versões publicadas remotamente, marcando quais estão instaladas
`download_artifact`	Baixa um artefato (jar/fontes/POM) para o cache local; aceita `latest`

Parâmetros das ferramentas

Ferramenta	Parâmetro	Tipo	Padrão	Descrição
`list_artifacts`	`group_id`	string	—	Filtrar por ID do grupo (ex.: 'org.springframework')
`list_artifacts`	`artifact_id`	string	—	Filtrar por ID do artefato (ex.: 'spring-core')
`list_artifacts`	`version`	string	—	Filtrar por versão (ex.: '5.3.21')
`list_artifacts`	`sort_by`	string	name	Ordenar resultados por: 'name' (grupo/artefato/versão em ordem crescente, padrão), 'size' (maiores jars primeiro) ou 'modified' (modificados mais recentemente primeiro). Valores desconhecidos voltam para 'name'.
`list_artifacts`	`limit`	integer	50	Número máximo de artefatos a retornar
`list_artifacts`	`page`	integer	1	Número da página para paginação
`list_artifacts`	`items_per_page`	integer	20	Itens por página
`analyze_jar`	`group_id`*	string	—	ID do grupo Maven
`analyze_jar`	`artifact_id`*	string	—	ID do artefato Maven
`analyze_jar`	`version`*	string	—	Versão Maven
`analyze_jar`	`include_bytecode`	boolean	False	Incluir análise de bytecode
`analyze_jar`	`include_manifest`	boolean	True	Incluir manifesto do JAR
`analyze_jar`	`summarize_large_content`	boolean	True	Resumir conteúdo grande automaticamente
`extract_class_info`	`group_id`*	string	—	ID do grupo Maven
`extract_class_info`	`artifact_id`*	string	—	ID do artefato Maven
`extract_class_info`	`version`*	string	—	Versão Maven
`extract_class_info`	`class_pattern`	string	—	Padrão para corresponder nomes de classes (regex suportado)
`extract_class_info`	`include_methods`	boolean	True	Incluir assinaturas de métodos
`extract_class_info`	`include_fields`	boolean	True	Incluir informações de campos
`extract_class_info`	`include_bytecode`	boolean	False	Incluir saída detalhada de bytecode javap para classes correspondentes
`extract_class_info`	`page`	integer	1	Número da página para paginação
`extract_class_info`	`items_per_page`	integer	20	Itens por página
`extract_class_info`	`summarize_large_content`	boolean	True	Resumir conteúdo grande automaticamente
`get_dependencies`	`group_id`*	string	—	ID do grupo Maven
`get_dependencies`	`artifact_id`*	string	—	ID do artefato Maven
`get_dependencies`	`version`*	string	—	Versão Maven
`get_dependencies`	`include_transitive`	boolean	False	Incluir dependências transitivas
`get_dependencies`	`page`	integer	1	Número da página para paginação
`get_dependencies`	`items_per_page`	integer	20	Itens por página
`search_classes`	`class_name`	string	—	Nome da classe a pesquisar (suporta curingas)
`search_classes`	`package_pattern`	string	—	Padrão de pacote para filtrar
`search_classes`	`annotation`	string	—	Pesquisar classes com anotação específica
`search_classes`	`case_sensitive`	boolean	True	Corresponder class_name e package_pattern diferenciando maiúsculas de minúsculas. Defina como false para uma pesquisa sem diferenciar maiúsculas de minúsculas (ex.: 'arraylist' corresponde a 'ArrayList').
`search_classes`	`limit`	integer	100	Máximo de resultados a retornar
`search_classes`	`page`	integer	1	Número da página para paginação
`search_classes`	`items_per_page`	integer	20	Itens por página
`extract_source_code`	`group_id`*	string	—	ID do grupo Maven
`extract_source_code`	`artifact_id`*	string	—	ID do artefato Maven
`extract_source_code`	`version`*	string	—	Versão Maven
`extract_source_code`	`class_name`*	string	—	Nome totalmente qualificado da classe
`extract_source_code`	`prefer_sources`	boolean	True	Preferir jar de código-fonte em vez de descompilação
`extract_source_code`	`summarize_large_content`	boolean	True	Resumir conteúdo grande automaticamente
`extract_source_code`	`max_lines`	integer	500	Máximo de linhas a retornar (0 para todas)
`extract_jar_resource`	`group_id`*	string	—	ID do grupo Maven
`extract_jar_resource`	`artifact_id`*	string	—	ID do artefato Maven
`extract_jar_resource`	`version`*	string	—	Versão Maven
`extract_jar_resource`	`resource_path`	string	—	Caminho exato do recurso dentro do jar
`extract_jar_resource`	`resource_pattern`	string	—	Padrão regex para corresponder caminhos de recursos
`extract_jar_resource`	`max_bytes`	integer	65536	Máximo de bytes a ler por recurso
`extract_jar_resource`	`limit`	integer	20	Máximo de recursos correspondentes a retornar
`compare_versions`	`group_id`*	string	—	ID do grupo Maven
`compare_versions`	`artifact_id`*	string	—	ID do artefato Maven
`compare_versions`	`version1`*	string	—	Primeira versão (mais antiga) a comparar
`compare_versions`	`version2`*	string	—	Segunda versão (mais nova) a comparar
`compare_versions`	`compare_api`	boolean	True	Comparar a API pública: métodos e campos públicos e protegidos adicionados/removidos, e mudanças que quebram compatibilidade
`compare_versions`	`resolve_inherited`	boolean	False	Reclassificar membros que desapareceram de uma classe, mas ainda são declarados em um supertipo dentro do novo jar, em um grupo 'movido para supertipo' em vez de contá-los como remoções que quebram compatibilidade. O padrão é false (byte-idêntico à comparação como declarado).
`compare_versions`	`summarize_large_content`	boolean	True	Resumir conteúdo grande automaticamente
`find_usage_examples`	`class_name`*	string	—	Nome da classe para encontrar uso
`find_usage_examples`	`method_name`	string	—	Nome do método para encontrar uso
`find_usage_examples`	`search_tests`	boolean	True	Pesquisar em jars de teste
`find_usage_examples`	`limit`	integer	50	Máximo de resultados a retornar
`find_usage_examples`	`page`	integer	1	Número da página para paginação
`find_usage_examples`	`items_per_page`	integer	20	Itens por página
`get_dependency_tree`	`group_id`*	string	—	ID do grupo Maven
`get_dependency_tree`	`artifact_id`*	string	—	ID do artefato Maven
`get_dependency_tree`	`version`*	string	—	Versão Maven
`get_dependency_tree`	`max_depth`	integer	3	Profundidade máxima a exibir
`get_dependency_tree`	`summarize_large_content`	boolean	True	Resumir conteúdo grande automaticamente
`find_dependents`	`group_id`*	string	—	ID do grupo de destino
`find_dependents`	`artifact_id`*	string	—	ID do artefato de destino
`find_dependents`	`version`	string	—	Versão específica a pesquisar (opcional)
`find_dependents`	`limit`	integer	100	Máximo de resultados a retornar
`find_dependents`	`page`	integer	1	Número da página para paginação
`find_dependents`	`items_per_page`	integer	20	Itens por página
`get_version_info`	`group_id`*	string	—	ID do grupo Maven
`get_version_info`	`artifact_id`*	string	—	ID do artefato Maven
`get_version_info`	`include_remote`	boolean	False	Listar também versões publicadas no repositório remoto (não apenas as instaladas)
`get_version_info`	`limit`	integer	50	Máximo de versões a retornar
`get_version_info`	`page`	integer	1	Número da página para paginação
`get_version_info`	`items_per_page`	integer	20	Itens por página
`analyze_jar_structure`	`group_id`*	string	—	ID do grupo Maven
`analyze_jar_structure`	`artifact_id`*	string	—	ID do artefato Maven
`analyze_jar_structure`	`version`*	string	—	Versão Maven
`analyze_jar_structure`	`summarize_large_content`	boolean	True	Resumir conteúdo grande automaticamente
`extract_method_info`	`group_id`*	string	—	ID do grupo Maven
`extract_method_info`	`artifact_id`*	string	—	ID do artefato Maven
`extract_method_info`	`version`*	string	—	Versão Maven
`extract_method_info`	`class_name`*	string	—	Nome totalmente qualificado da classe
`extract_method_info`	`method_pattern`	string	—	Padrão para corresponder nomes de métodos (regex suportado)
`extract_method_info`	`include_bytecode`	boolean	False	Incluir análise de bytecode
`extract_method_info`	`max_methods`	integer	10	Número máximo de métodos a retornar
`search_maven_central`	`query`	string	—	Termo de pesquisa de texto livre (ex.: 'jackson databind')
`search_maven_central`	`group_id`	string	—	Filtro exato de ID do grupo (ex.: 'org.springframework')
`search_maven_central`	`artifact_id`	string	—	Filtro exato de ID do artefato (ex.: 'spring-core')
`search_maven_central`	`class_name`	string	—	Nome simples da classe para encontrar o artefato que a contém (ex.: 'ObjectMapper')
`search_maven_central`	`fully_qualified_class`	string	—	Nome totalmente qualificado da classe (ex.: 'com.fasterxml.jackson.databind.ObjectMapper')
`search_maven_central`	`packaging`	string	—	Filtro de empacotamento (ex.: 'jar', 'pom')
`search_maven_central`	`all_versions`	boolean	False	Retornar todas as versões publicadas em vez de apenas a mais recente por artefato
`search_maven_central`	`limit`	integer	20	Máximo de resultados a retornar (máx. 200)
`search_maven_central`	`page`	integer	1	Número da página para paginação
`get_remote_versions`	`group_id`*	string	—	ID do grupo Maven
`get_remote_versions`	`artifact_id`*	string	—	ID do artefato Maven
`get_remote_versions`	`include_snapshots`	boolean	True	Incluir versões -SNAPSHOT. Defina como false para listar apenas versões lançadas.
`get_remote_versions`	`limit`	integer	100	Máximo de versões a retornar
`download_artifact`	`group_id`*	string	—	ID do grupo Maven
`download_artifact`	`artifact_id`*	string	—	ID do artefato Maven
`download_artifact`	`version`*	string	—	Versão para baixar, ou 'latest' para o lançamento mais recente
`download_artifact`	`include_sources`	boolean	True	Baixar também o jar de fontes quando publicado
`download_artifact`	`include_javadoc`	boolean	False	Baixar também o jar de javadoc quando publicado
`download_artifact`	`classifier`	string	—	Baixar um jar classificado específico em vez do principal
`download_artifact`	`force`	boolean	False	Baixar novamente mesmo quando o arquivo já está em cache

* Obrigatório — o parâmetro aparece no array inputSchema required da ferramenta. Parâmetros sem * são opcionais e podem ser omitidos.

💡 Exemplos de Uso

Encontrando Dependências

"Show me all dependencies of org.springframework:spring-core:5.3.21"

Descompilando Classes

"Decompile the class com.example.MyService from my Maven repository"

Analisando Conflitos

"Find all version conflicts in my Maven repository"

Verificando uma Atualização para Mudanças que Quebram Compatibilidade

"Compare org.jsoup:jsoup 1.17.2 with 1.23.2 and tell me what would break"

compare_versions compara os membros públicos e protegidos de cada classe que as duas versões compartilham e relata remoções separadamente das adições. Membros removidos e classes removidas são contados como mudanças que quebram compatibilidade. Os membros são comparados como declarados, então um que foi movido para um supertipo é relatado como removido, mesmo que ainda possa ser chamável.

Explorando APIs

"Show me all public methods in the Jackson ObjectMapper class"

Encontrando Chamadores Reais

"Find classes that call ObjectMapper.readValue, including examples from test jars"

find_usage_examples examina os pools de constantes de classes compiladas, então encontra chamadores reais em vez de simples correspondências de nome. Passe method_name (como readValue) para restringir os resultados a chamadores de um método específico. Jars de teste são incluídos por padrão e classificados primeiro porque geralmente contêm os exemplos mais claros; defina search_tests como false para excluí-los. A varredura para após MCP_USAGE_SCAN_LIMIT classes (padrão: 200000) para permanecer responsiva em repositórios grandes.

Inspecionando Artefatos Apenas Compilados

"The sources jar is missing. Use extract_class_info for bytecode-backed fields and methods."
"Find and read .proto resources from com.example:protobuf-lib:1.0.0"

Quando uma dependência não possui um jar de fontes, o extract_class_info usa o javap internamente e retorna campos analisados, métodos, versão do bytecode e saída opcional detalhada do bytecode. Os agentes devem usar analyze_jar, extract_class_info, extract_source_code e extract_jar_resource por meio deste MCP em vez de executar jar ou javap diretamente.

Trabalhando com Respostas Grandes

"List all Spring classes with pagination (page 2, 10 items per page)"
"Extract source code for a large class with summarization"
"Get method information for specific patterns in a class"

Pesquisando no Maven Central (Online)

"Which Maven artifact contains the class HikariDataSource?"
"Search Maven Central for retrofit"
"What is the newest published version of org.apache.commons:commons-lang3?"
"Download com.google.code.gson:gson:latest and show me the JsonParser class"

🌐 Suporte Online ao Maven

O servidor funciona com o repositório local e repositórios remotos. O acesso online está habilitado por padrão.

Como funciona

Cada ferramenta primeiro procura no seu repositório local (~/.m2/repository).
Em caso de ausência, o artefato é baixado do Maven Central para um cache (~/.cache/maven-decoder-mcp/repository) que usa o layout padrão do Maven.
Toda a análise existente (decompilação, informações de classe, dependências) é então executada no artefato em cache exatamente como seria em um instalado.

O cache é deliberadamente separado do ~/.m2 para que os downloads nunca interfiram com suas builds do Maven ou Gradle. As respostas incluem um campo origin (local-repository ou remote-cache) para que você sempre saiba de onde veio um resultado.

Ficando offline

MAVEN_OFFLINE=true   # no network access at all; original local-only behavior
MAVEN_AUTO_DOWNLOAD=false   # keep online search, but never auto-download

Usando um espelho privado

MAVEN_REMOTE_REPOS="https://nexus.corp/repository/maven-public"
MAVEN_REMOTE_USERNAME=builder
MAVEN_REMOTE_PASSWORD=secret

Uma nota sobre o índice de pesquisa

Os downloads de artefatos usam repo1.maven.org, que é rápido e confiável. A pesquisa de artefatos usa search.maven.org, o único índice público que responde corretamente a consultas de nível de classe (c: / fc:). Esse índice limita rajadas de requisições, então as solicitações são repetidas com backoff; um período de alta demanda ainda pode resultar em timeout. Downloads e listagem de versões não são afetados, pois leem maven-metadata.xml diretamente do repositório.

🔄 Gerenciamento de Respostas

Suporte a Paginação

O servidor gerencia automaticamente respostas grandes por meio de paginação inteligente:

Detecção Automática: Respostas que excedem 50KB são paginadas automaticamente
Tamanho de Página Configurável: Padrão de 20 itens por página, personalizável por solicitação
Metadados de Paginação: Cada resposta inclui informações de paginação
Ferramentas Suportadas: list_artifacts, extract_class_info, search_classes, get_dependencies, find_dependents, get_version_info

Recursos de Resumo

Conteúdo de texto grande é resumido automaticamente para melhorar a legibilidade:

Resumo Inteligente: Preserva partes importantes (declarações de pacote, assinaturas de métodos, chaves de fechamento)
Limites Configuráveis: Padrão de limite de texto de 10KB, personalizável
Específico para Java: Otimizado para a estrutura de código-fonte Java
Preservação de Metadados: A estrutura original e os metadados são mantidos

Extração de Métodos

Nova ferramenta para acesso direcionado a métodos específicos:

Correspondência de Padrões: Use padrões regex para encontrar métodos específicos
Resultados Limitados: Controle o número de métodos retornados
Contexto Completo: Inclui assinaturas de métodos, corpos e números de linha
Processamento Eficiente: Extrai apenas os métodos solicitados, não classes inteiras

🏗️ Arquitetura

O servidor é construído com uma arquitetura modular:

MavenDecoderServer: Implementação principal do servidor MCP
ResponseManager: Gerencia paginação e resumo
JavaDecompiler: Gerencia múltiplas estratégias de decompilação
MavenDependencyAnalyzer: Analisa dependências e metadados do Maven
MavenCentralClient: Pesquisa remota, listagem de versões e downloads de artefatos
Decompiladores: Integração com CFR, Procyon, Fernflower e javap

🧪 Desenvolvimento

Executando Testes

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run specific test
python test_startup.py

Compilando o Pacote

# Build distribution
python setup.py sdist bdist_wheel

# Install locally
pip install dist/maven_decoder_mcp-*.whl

Desenvolvimento com Docker

# Build Docker image
docker build -t maven-decoder-mcp .

# Run container
docker run --rm -it maven-decoder-mcp

📝 Opções de Configuração

Variáveis de Ambiente

Repositório local

MAVEN_REPOSITORY / MAVEN_REPO: caminho direto para o repositório Maven local (ex.: F:\data\repository). Maior precedência.
MAVEN_HOME / M2_HOME: diretório de instalação do Maven ou diretório do repositório. Um subdiretório repository/ aninhado tem prioridade quando existe; conf/settings.xml <localRepository> são respeitados.
~/.m2/settings.xml <localRepository> são respeitados quando nenhuma variável de ambiente é definida. Fallback: ~/.m2/repository.

Acesso online

MAVEN_OFFLINE: defina como true para desabilitar todo o acesso à rede (padrão: false)
MAVEN_AUTO_DOWNLOAD: busca automática de artefatos ausentes localmente (padrão: true)
MAVEN_REMOTE_REPOS / MAVEN_REMOTE_REPO: URLs base do repositório separadas por vírgula/espaço (padrão: https://repo1.maven.org/maven2)
MAVEN_SEARCH_URL: endpoints de pesquisa Solr separados por vírgula/espaço (padrão: https://search.maven.org/solrsearch/select)
MAVEN_DECODER_CACHE_DIR: onde os artefatos baixados são armazenados em cache (padrão: ~/.cache/maven-decoder-mcp/repository)
MAVEN_REMOTE_USERNAME / MAVEN_REMOTE_PASSWORD: credenciais de autenticação básica para um espelho privado
MAVEN_HTTP_TIMEOUT: timeout por solicitação em segundos (padrão: 30)
MAVEN_HTTP_RETRIES: tentativas para falhas de rede transitórias (padrão: 3)
MAVEN_MAX_DOWNLOAD_SIZE: tamanho máximo de download em bytes (padrão: 104857600)
MAVEN_VERIFY_CHECKSUM: verifica downloads contra o SHA-1 publicado (padrão: true)

Respostas

MCP_LOG_LEVEL: Nível de registro (DEBUG, INFO, WARNING, ERROR)
MCP_MAX_RESPONSE_SIZE: Tamanho máximo da resposta em bytes (padrão: 50000)
MCP_MAX_ITEMS_PER_PAGE: Itens padrão por página (padrão: 20)
MCP_MAX_TEXT_LENGTH: Comprimento máximo de texto antes do resumo (padrão: 10000)
MCP_MAX_LINES: Número máximo de linhas antes do resumo (padrão: 500)
MCP_USAGE_SCAN_LIMIT: Máximo de classes analisadas por find_usage_examples (padrão: 200000)
MCP_API_DIFF_LIMIT: Máximo de classes comparadas por compare_versions (padrão: 2000)
MAVEN_DECODER_DECOMPILER_DIR: Diretório que contém cfr.jar / procyon-decompiler.jar

Configuração Avançada

O servidor detecta e configura automaticamente:

Localização do repositório Maven
Decompiladores Java disponíveis
Capacidades do sistema

🔍 Solução de Problemas

Problemas Comuns

O servidor não inicia

# Check Python installation
python --version

# Check Maven repository
ls ~/.m2/repository

# Check logs
maven-decoder-mcp --debug

A decompilação falha

# Check the environment: Java, repository, cache and available decompilers
maven-decoder-setup status

# Install the optional CFR and Procyon decompilers
maven-decoder-setup decompilers

A partir de um checkout do código-fonte, você pode executar ./setup_decompilers.sh, que baixa CFR e Procyon em um diretório decompilers/ ao lado do script, como decompilers/cfr.jar e decompilers/procyon-decompiler.jar.

Se maven-decoder-setup status informa que não há decompiladores mesmo tendo os jars, eles estão em algum lugar que o servidor não procura. Ele pesquisa estas raízes em ordem, usando a primeira correspondência:

$MAVEN_DECODER_DECOMPILER_DIR, se definido
decompilers/ dentro do pacote instalado
decompilers/ ao lado do pacote — o layout do checkout do código-fonte
~/.cache/maven-decoder-mcp/decompilers
decompilers/ no diretório de trabalho atual
o próprio diretório de trabalho atual

Seu cliente MCP inicia o servidor a partir de um diretório de trabalho arbitrário, então os dois últimos não são confiáveis na prática. Se seus jars estiverem em qualquer outro lugar, aponte explicitamente para eles:

export MAVEN_DECODER_DECOMPILER_DIR=~/tools/decompilers

O diretório deve conter os jars com os nomes exatos cfr.jar e procyon-decompiler.jar. O valor expande ~ e variáveis de ambiente.

Sem CFR ou Procyon, o servidor ainda funciona, usando javap do JDK como fallback para assinaturas, campos e métodos.

Nenhum artefato encontrado

# Verify Maven repository location
ls ~/.m2/repository

# Run a Maven build to populate repository
mvn dependency:resolve

A pesquisa no Maven Central expira

O índice de pesquisa público limita rajadas de solicitações. Tentativas com backoff são incorporadas, mas durante limitação intensa, uma pesquisa ainda pode falhar. Soluções alternativas:

# Wait a moment and retry, or raise the retry budget
MAVEN_HTTP_RETRIES=5

# Downloads and version listing do not use the search index, so these keep
# working even while search is throttled:
#   get_remote_versions, download_artifact

Downloads falham atrás de um proxy ou firewall

# requests honors the standard proxy variables
export HTTPS_PROXY=http://proxy.corp:8080

# Or point at an internal mirror
export MAVEN_REMOTE_REPOS="https://nexus.corp/repository/maven-public"

# Or turn the network off entirely
export MAVEN_OFFLINE=true

🤝 Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add amazing feature')
Envie para o branch (git push origin feature/amazing-feature)
Abra um Pull Request

📄 Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

🙏 Agradecimentos

Model Context Protocol - O protocolo que alimenta este servidor
CFR - Decompilador Java
Procyon - Decompilador Java
Maven - Gerenciamento de dependências

📊 Estatísticas

GitHub Stars GitHub Forks PyPI Downloads npm Downloads Docker Pulls

Feito com ❤️ para a comunidade de desenvolvimento Java