JVM Source Lens

jvmsrc — Dê ao seu agente de codificação um IDE Java

O Problema

Você usa um IDE para escrever Java. Seu agente de codificação não tem um.

Quando seu agente encontra um tipo de biblioteca desconhecido — digamos, uma superclasse de uma biblioteca interna proprietária — ele gasta mais de 25 turnos percorrendo ~/.gradle/caches, abrindo JARs manualmente com jar tf, escolhendo um por tentativa e erro, e tentando responder a uma pergunta que seu IDE responderia com um único toque de tecla: essa superclasse tem um método utilitário público chamado X?

A Solução

jvmsrc consulta sua ferramenta de build (Gradle) pelo classpath resolvido deste projeto e então entrega ao seu agente código-fonte real, assinaturas reais e estrutura real — para a versão exata que seu build realmente usa.

• Como servidor MCP – Conecte-se ao Claude Code, Cursor, Windsurf ou qualquer outro host MCP e equipe seu agente com seis ferramentas de classpath feitas sob medida.
• Como CLI jvmsrc – Mesmo motor, scriptável, compatível com pipes e útil por conta própria quando você só quer ler uma classe.

Claude Code resolvendo assinaturas de HandlerInterceptor via jvmsrc — 3 chamadas, resposta correta, sem percorrer cache.

O que economiza, diariamente

Em projetos JVM com bibliotecas privadas e sem Javadocs públicos, jvmsrc é um multiplicador de força:

• ~50 mil tokens economizados por investigação de "o que há nessa classe externa" — aproximadamente 70% de redução de custo.
• Mais de 15 loops de pânico do agente evitados por dia — sem vasculhar caches do Gradle, abrir JARs errados ou desistir.
• Desbloqueie delegação para tarefas complexas que envolvem SDKs internos que antes você precisava fazer sozinho.

A Diferença em Ação

Sem jvmsrc (A busca cega de 25 turnos)

Usuário: Sobrescreva o hook de auditoria de AbstractTradingService — existe um método utilitário público nele que devemos reutilizar?

Agente:

1. Procura no workspace por AbstractTradingService.java ➔ 0 hits
2. Executa: find ~/.gradle -name "trading-core*"
3. Encontra 4 versões: 2.1.0, 2.3.0, 2.4.1, 3.0.0-SNAPSHOT
4. Adivinha: Escolhe trading-core-2.4.1.jar (o projeto na verdade usa 3.0.0-SNAPSHOT!)
5. Executa: jar tf e javap -p no JAR errado
6. [22 turnos depois] "Não vejo um método utilitário, você terá que implementar você mesmo."

Realidade: 3.0.0-SNAPSHOT adicionou maskSensitiveFields() como um helper protegido exatamente para este caso. O agente não alucinou — ele estava apenas cego.

Com jvmsrc (A resolução instantânea em 3 turnos)

Usuário: Sobrescreva o hook de auditoria de AbstractTradingService — existe um método utilitário público nele que devemos reutilizar?

Agente:

1. search_classes("AbstractTradingService") ➔ Encontra o FQN e a biblioteca resolvida exata.
2. get_class_structure(scope: "overview") ➔ Descobre maskSensitiveFields() em 3.0.0-SNAPSHOT.
3. get_method_signature("maskSensitiveFields") ➔ Obtém assinatura precisa e genéricos.

Resultado: Escreve a sobrescrita corretamente na primeira tentativa. Sem percorrer cache, sem adivinhação, sem versão errada.

Como Funciona

1. Consulta à Ferramenta de Build: jvmsrc consulta sua ferramenta de build ativa (ex.: Gradle) pela configuração exata do classpath resolvido.
2. Cache Inteligente: Ele armazena em cache o classpath resolvido, rastreando mudanças nos arquivos de build para se manter atualizado.
3. Ferramentas de IA de Precisão: Em vez de despejar código completo, ele expõe ferramentas precisas e de alta granularidade (assinaturas, estrutura, busca) para manter as janelas de contexto pequenas e o uso de tokens ultrabaixo.

Instalação e Início Rápido

1. Instale a CLI

npm install -g jvmsrc

Ou use diretamente via npx:

npx jvmsrc mcp

[!IMPORTANTE]
Requer Node ≥ 20 e Java no PATH (para o decompilador CFR + javap).

2. Adicione o servidor MCP

Cole isto na configuração do seu assistente de IA (Cursor, Claude Code, Windsurf, etc.) e reinicie o host:

{
  "mcpServers": {
    "jvmsrc": {
      "command": "jvmsrc",
      "args": ["mcp"]
    }
  }
}

Opcional: jvmsrc config (ou jvmsrc config --project /path/to/gradle-project) imprime um bloco pronto para colar, além de dicas de ambiente. A maioria dos usuários pode pular e copiar o trecho acima.

Referência do Servidor MCP

O servidor MCP roda via stdio usando jvmsrc mcp. A configuração padrão não precisa de variáveis de ambiente:

{
  "mcpServers": {
    "jvmsrc": {
      "command": "jvmsrc",
      "args": ["mcp"]
    }
  }
}

Credenciais de repositório privado (opcional)

Necessário apenas quando seu build Gradle exige variáveis de ambiente de credenciais para um repositório privado Maven/Artifactory/Nexus. Hosts MCP frequentemente não herdam seu shell interativo, então essas variáveis devem ser definidas no processo MCP do jvmsrc (e então reiniciar o servidor).

REPO_USER / REPO_PASS abaixo são apenas nomes de exemplo — não são exigidos pelo jvmsrc. Use os nomes de variáveis que os scripts Gradle do seu projeto documentarem:

{
  "mcpServers": {
    "jvmsrc": {
      "command": "jvmsrc",
      "args": ["mcp"],
      "env": {
        "REPO_USER": "your-username",
        "REPO_PASS": "your-password"
      }
    }
  }
}

Omita o bloco env completamente quando o projeto não precisar delas.

Ferramentas que seu agente recebe

[!DICA]
Toda resposta de fonte inclui sourceAvailable: true para fontes reais (Javadoc, nomes de parâmetros, genéricos), false para decompilação CFR (estrutura confiável, nomes podem ser sintéticos).

[!NOTA]
Multimódulo: omita modulePath e o jvmsrc escolhe automaticamente o módulo proprietário único; em caso de falha, ele lista modulePaths candidatos. Métodos: search_classes corresponde a nomes de métodos declarados quando o índice tem enriquecimento de fonte; para texto de corpo em um JAR conhecido, use search_in_artifact. get_class_source methodNames também percorre superclasses para nomes sem correspondência.

Comparação

Público-Alvo

Principalmente projetos Java + Spring Boot com Gradle. Outras linguagens JVM (Kotlin, Scala) e Android funcionam hoje na base do melhor esforço e estão no roadmap como alvos de primeira classe — veja ROADMAP.md.

Se você usa Maven ou Bazel, está planejado, mas ainda não disponível. Dê uma estrela no repositório ou abra uma issue e eu priorizarei de acordo.

Referência Detalhada

jvmsrc com.example.MyClass -p /path/to/gradle-project          # shorthand for get
jvmsrc get com.example.MyClass -p /path/to/project -q > MyClass.java
jvmsrc resolve -p /path/to/project --force-refresh
jvmsrc config jdk-roots add /path/to/jdks                      # one-time JDK roots setup
jvmsrc doctor java -p /path/to/project                         # check JDK requirement + selection
jvmsrc diagnostics last                                         # latest failure message
jvmsrc mcp                                                     # run as MCP server

Documentação do Projeto

Compilando a partir do código-fonte

git clone https://github.com/Sintexer/jvm-source-lens.git
cd jvm-source-lens
bun install && bun run setup:cfr && bun run build
node dist/cli.js --version

Fluxo de trabalho completo para contribuidores: CONTRIBUTING.md.

Eu construí o jvmsrc porque continuava batendo na mesma parede: agentes ótimos em escrever Java, mas cegos para o classpath real. Se isso poupar você dos mesmos 25 turnos de idas e vindas que poupou para mim, é exatamente para isso que isto existe. Encontrou um bug, tem uma ideia, ou só quer dizer que ajudou? Abra uma issue ou um PR — eu leio tudo.

Licença

MIT — veja LICENSE.