JMX MCP Server

Servidor MCP JMX

Um poderoso servidor Model Context Protocol (MCP) que fornece recursos abrangentes de monitoramento e gerenciamento JMX para assistentes de IA como o Claude Desktop. Monitore aplicações Java, gerencie MBeans e execute operações JMX por meio de interações em linguagem natural.

🎥 Vídeo de Demonstração

Assista ao servidor MCP JMX em ação! Veja como o Claude Desktop pode monitorar e gerenciar aplicações Java por meio de linguagem natural:

https://github.com/user-attachments/assets/722e1885-5aeb-4584-8116-b93324e0abc1

A demonstração mostra monitoramento JMX em tempo real, exploração de MBeans e gerenciamento de aplicações Java com IA por meio do Claude Desktop.

🚀 Recursos

🔍 Integração JMX Abrangente

• Descoberta de MBeans em Tempo Real: Descobre e cataloga automaticamente todos os MBeans disponíveis
• Gerenciamento de Atributos: Leia e escreva atributos de MBeans com segurança total de tipos
• Execução de Operações: Execute operações de MBeans com validação de parâmetros
• Exploração de Domínios: Navegue e filtre MBeans por domínio

🤖 Monitoramento com IA

• Consultas em Linguagem Natural: Faça perguntas como "Qual é o uso atual da memória heap?"
• Análise Inteligente: A IA pode correlacionar métricas e identificar problemas de desempenho
• Insights Automatizados: Obtenha recomendações com base em padrões de dados JMX

🛡️ Pronto para Empresas

• Validação de Segurança: Controles de segurança integrados e validação de acesso
• Gerenciamento de Conexões: Tratamento robusto de conexões JMX locais e remotas
• Tratamento de Erros: Mecanismos abrangentes de tratamento e recuperação de erros
• Registro em Produção: Registro configurável para diferentes ambientes

🔌 Conformidade com o Protocolo MCP

• Ferramentas: 12 ferramentas de gerenciamento JMX para interação com IA
• Recursos: Todos os atributos JMX expostos como recursos descobríveis
• Transporte STDIO: Otimizado para integração com o Claude Desktop
• JSON-RPC 2.0: Conformidade total com o protocolo para comunicação confiável

📋 Pré-requisitos

• Java 17+ (OpenJDK ou Oracle JDK)
• Maven 3.6+ para compilação
• Claude Desktop ou qualquer cliente de IA compatível com MCP

🛠️ Início Rápido

1. Clone e Compile

git clone https://github.com/itz4blitz/JMX-MCP.git
cd JMX-MCP
mvn clean package

2. Teste o Servidor

# Test with comprehensive validation
python3 comprehensive-test.py

3. Configure o Claude Desktop

Adicione ao seu arquivo de configuração MCP do Claude Desktop:

Localização:

• macOS: ~/.config/claude/mcp_servers.json
• Windows: %APPDATA%\Claude\mcp_servers.json

Configuração:

{
  "mcpServers": {
    "jmx-mcp-server": {
      "command": "java",
      "args": [
        "-Xmx512m",
        "-Xms256m",
        "-Dspring.profiles.active=stdio",
        "-Dspring.main.banner-mode=off",
        "-Dlogging.level.root=OFF",
        "-Dspring.main.log-startup-info=false",
        "-jar",
        "/path/to/your/jmx-mcp-server-1.0.0.jar"
      ],
      "env": {
        "JAVA_OPTS": "-Djava.awt.headless=true"
      }
    }
  }
}

4. Comece a Usar com o Claude

Reinicie o Claude Desktop e tente estas consultas:

"What JMX tools are available?"
"Show me the current heap memory usage"
"List all MBean domains"
"What's the garbage collection performance?"

🔧 Ferramentas Disponíveis (12 no Total)

Operações JMX Principais

Ferramenta	Descrição	Exemplo de Uso
listMBeans	Lista todos os MBeans descobertos com filtragem opcional por domínio	"Mostre-me todos os MBeans relacionados à memória"
getMBeanInfo	Obtém informações detalhadas sobre um MBean específico	"Fale-me sobre o MBean Runtime"
getAttribute	Lê o valor de um atributo de MBean	"Qual é o uso atual da memória heap?"
setAttribute	Define o valor de um atributo de MBean gravável	"Defina o nível de log para DEBUG"
listDomains	Lista todos os domínios de MBeans disponíveis	"Quais domínios estão disponíveis?"

Gerenciamento de Conexões

Ferramenta	Descrição	Exemplo de Uso
listJmxConnections	Lista todas as conexões JMX configuradas	"Mostre-me todas as conexões disponíveis"
addJmxConnection	Adiciona uma nova conexão JMX	"Conecte-se ao servidor de produção"
removeJmxConnection	Remove uma conexão JMX	"Remova a conexão de teste antiga"
switchJmxConnection	Alterna para uma conexão JMX diferente	"Alterne para o ambiente de staging"
getConnectionInfo	Obtém o status atual da conexão JMX e estatísticas	"A conexão JMX está saudável?"

Descoberta de Serviços

Ferramenta	Descrição	Exemplo de Uso
discoverJmxServices	Descobre aplicações Java habilitadas para JMX no sistema	"Encontre todos os aplicativos Java com JMX habilitado"
autoRegisterDiscoveredConnections	Registra automaticamente serviços JMX descobertos	"Conecte-se automaticamente a todos os aplicativos Java descobertos"

📊 Recursos Disponíveis

O servidor expõe automaticamente todos os atributos JMX como recursos MCP, tornando-os descobríveis e acessíveis aos assistentes de IA:

• Métricas de Memória: Uso de heap, uso de não-heap, pools de memória
• Coleta de Lixo: Estatísticas de GC, tempos de coleta, contagens de coleta
• Threads: Contagens de threads, detecção de deadlock, estados de threads
• Informações de Runtime: Tempo de atividade da JVM, tempo de início, propriedades do sistema
• Carregamento de Classes: Classes carregadas, classes descarregadas, caminho de classes
• Sistema Operacional: Uso de CPU, carga do sistema, processadores disponíveis

Formato do URI do Recurso:

jmx://domain:type=Type,name=Name/attributes/AttributeName

Exemplos de Recursos:

jmx://java.lang:type=Memory/attributes/HeapMemoryUsage
jmx://java.lang:type=Runtime/attributes/Uptime
jmx://java.lang:type=GarbageCollector,name=G1_Young_Generation/attributes/CollectionCount

💬 Exemplos de Interações

Monitoramento de Memória

User: "What's the current memory situation?"
Claude: I'll check the JMX memory metrics for you.

[Uses getAttribute tool to read HeapMemoryUsage]

The current heap memory usage is:
- Used: 245 MB
- Committed: 512 MB  
- Max: 2048 MB
- Usage: 12% of maximum heap

The application is running efficiently with low memory pressure.

Análise de Desempenho

User: "Are there any performance issues?"
Claude: Let me analyze the JMX performance metrics.

[Uses multiple tools to check GC, threads, and memory]

Performance analysis:
✅ Memory: Healthy (12% heap usage)
✅ GC: Efficient (avg 15ms collection time)
⚠️  Threads: High count (245 threads) - consider investigation
✅ CPU: Normal load

Recommendation: Monitor thread creation patterns.

🏗️ Arquitetura

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Claude AI     │◄──►│  JMX MCP Server  │◄──►│  Java App JMX   │
│                 │    │                  │    │                 │
│ Natural Language│    │ • Tools (12)     │    │ • MBeans        │
│ Queries         │    │ • Resources(224+)│    │ • Attributes    │
│                 │    │ • JSON-RPC 2.0   │    │ • Operations    │
│                 │    │ • Multi-Connect  │    │ • Discovery     │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Componentes Principais

• JMXConnectionManager: Gerencia conexões JMX locais e remotas
• MBeanDiscoveryService: Descobre e cataloga MBeans disponíveis
• JmxService: Fornece métodos anotados com @Tool para interação com IA
• JMXToMCPMapper: Mapeia atributos JMX para recursos MCP
• JmxSecurityValidator: Valida operações para conformidade de segurança

⚙️ Perfis de Configuração

Perfil Padrão

Configuração padrão com registro completo para desenvolvimento e depuração.

Perfil STDIO

Otimizado para integração com o Claude Desktop:

• Operação Silenciosa: Sem saída no console para evitar interferência JSON-RPC
• Registro Mínimo: Registro somente de erros para evitar problemas no sistema de arquivos
• Inicialização Rápida: Inicialização otimizada para respostas rápidas da IA

🧪 Testes

Suíte de Testes Abrangente

# Run the comprehensive integration test
python3 comprehensive-test.py

Cobertura de Testes:

• ✅ Conformidade com o protocolo MCP
• ✅ Comunicação JSON-RPC 2.0
• ✅ Registro e execução de todas as 12 ferramentas
• ✅ Gerenciamento de múltiplas conexões
• ✅ Descoberta de serviços e auto-registro
• ✅ Descoberta e acesso a recursos
• ✅ Tratamento de erros e recuperação

Testes Unitários

mvn test

🔒 Segurança

Recursos de Segurança Integrados

• Validação de ObjectName: Impede acesso a MBeans sensíveis
• Filtragem de Operações: Restringe operações perigosas
• Segurança de Tipos: Valida tipos de atributos antes das operações
• Controle de Acesso: Políticas de segurança configuráveis

Configuração de Segurança

jmx:
  security:
    enabled: true
    allowed-domains:
      - "java.lang"
      - "java.nio"
      - "com.myapp"
    blocked-operations:
      - "shutdown"
      - "restart"

🚀 Implantação

Desenvolvimento Local

java -jar target/jmx-mcp-server-1.0.0.jar

Implantação em Produção

java -Xmx1g -Xms512m \
     -Dspring.profiles.active=production \
     -jar jmx-mcp-server-1.0.0.jar

Implantação com Docker

FROM openjdk:17-jre-slim
COPY target/jmx-mcp-server-1.0.0.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar"]

🤝 Contribuições

Aceitamos contribuições! Consulte nosso Guia de Contribuição para obter detalhes.

Configuração de Desenvolvimento

1. Faça um fork do repositório
2. Crie um branch de funcionalidade
3. Faça suas alterações
4. Adicione testes para novas funcionalidades
5. Garanta que todos os testes passem
6. Envie um pull request

Estilo de Código

• Siga as convenções de codificação Java
• Use nomes significativos para variáveis e métodos
• Adicione comentários JavaDoc abrangentes
• Mantenha a cobertura de testes acima de 80%

📚 Documentação

• Documentação da API: Referência detalhada da API
• Guia de Configuração: Opções avançadas de configuração
• Solução de Problemas: Problemas comuns e soluções
• Exemplos: Exemplos de uso e tutoriais

🐛 Solução de Problemas

Problemas Comuns

O servidor não inicia com o Claude Desktop:

• Verifique se o Java 17+ está instalado
• Verifique o caminho do JAR na configuração
• Garanta que o perfil STDIO esteja ativo

Nenhuma ferramenta/recurso visível:

• Reinicie o Claude Desktop após alterações na configuração
• Verifique os logs do servidor para erros
• Verifique a conformidade com o protocolo MCP

Problemas de conexão:

• Confirme que o JMX está habilitado na aplicação de destino
• Verifique a conectividade de rede para conexões remotas
• Valide as configurações de segurança

🤝 Contribuições

Aceitamos contribuições! Consulte nosso Guia de Contribuição para obter detalhes.

Início Rápido para Contribuidores

# Fork the repository on GitHub
git clone https://github.com/YOUR_USERNAME/JMX-MCP.git
cd JMX-MCP

# Build and test
mvn clean compile
mvn test

# Run the application
mvn spring-boot:run

Formas de Contribuir

• 🐛 Relatar bugs - Ajude-nos a identificar e corrigir problemas
• 💡 Sugerir recursos - Compartilhe ideias para novas funcionalidades
• 📝 Melhorar a documentação - Ajude outros a entender o projeto
• 🔧 Enviar código - Corrija bugs ou implemente novos recursos
• 🧪 Escrever testes - Melhore a cobertura e a confiabilidade dos testes
• 🎨 Melhorias de UI/UX - Aprimore a experiência do usuário

Comunidade

• Discussões no GitHub: Faça perguntas e compartilhe ideias
• Issues: Relate bugs e solicite recursos
• Pull Requests: Contribua com melhorias de código
• Wiki: Documentação colaborativa

📄 Licença

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

🙏 Agradecimentos

• Equipe Spring AI pelo excelente framework MCP
• Model Context Protocol pelo protocolo padronizado de integração com IA
• Anthropic pelo Claude Desktop e recursos de assistente de IA
• Comunidade OpenJDK pela plataforma Java robusta

📞 Suporte

• Issues: GitHub Issues
• Discussões: GitHub Discussions
• Documentação: Wiki

---

Feito com ❤️ para as comunidades de IA e Java