JMX MCP Server

Proporciona capacidades de monitoreo y gestión JMX para asistentes de IA. Requiere Java 17+.

Documentación

Servidor MCP JMX

Un potente servidor de Protocolo de Contexto de Modelo (MCP) que proporciona capacidades integrales de monitoreo y gestión JMX para asistentes de IA como Claude Desktop. Monitoree aplicaciones Java, gestione MBeans y realice operaciones JMX mediante interacciones en lenguaje natural.

🎥 Video de Demostración

¡Vea el Servidor MCP JMX en acción! Observe cómo Claude Desktop puede monitorear y gestionar aplicaciones Java mediante lenguaje natural:

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

La demostración muestra monitoreo JMX en tiempo real, exploración de MBeans y gestión de aplicaciones Java impulsada por IA a través de Claude Desktop.

🚀 Características

🔍 Integración JMX Integral

Descubrimiento de MBeans en Tiempo Real: Descubre y cataloga automáticamente todos los MBeans disponibles
Gestión de Atributos: Lee y escribe atributos de MBeans con total seguridad de tipos
Ejecución de Operaciones: Ejecuta operaciones de MBeans con validación de parámetros
Exploración de Dominios: Navega y filtra MBeans por dominio

🤖 Monitoreo Impulsado por IA

Consultas en Lenguaje Natural: Haga preguntas como "¿Cuál es el uso actual de memoria heap?"
Análisis Inteligente: La IA puede correlacionar métricas e identificar problemas de rendimiento
Información Automatizada: Obtenga recomendaciones basadas en patrones de datos JMX

🛡️ Listo para Empresas

Validación de Seguridad: Controles de seguridad integrados y validación de acceso
Gestión de Conexiones: Manejo robusto de conexiones JMX locales y remotas
Manejo de Errores: Mecanismos integrales de manejo de errores y recuperación
Registro en Producción: Registro configurable para diferentes entornos

🔌 Cumplimiento del Protocolo MCP

Herramientas: 12 herramientas de gestión JMX para interacción con IA
Recursos: Todos los atributos JMX expuestos como recursos descubribles
Transporte STDIO: Optimizado para integración con Claude Desktop
JSON-RPC 2.0: Cumplimiento total del protocolo para comunicación confiable

📋 Requisitos Previos

Java 17+ (OpenJDK u Oracle JDK)
Maven 3.6+ para compilación
Claude Desktop o cualquier cliente de IA compatible con MCP

🛠️ Inicio Rápido

1. Clonar y Compilar

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

2. Probar el Servidor

# Test with comprehensive validation
python3 comprehensive-test.py

3. Configurar Claude Desktop

Agregue a su archivo de configuración MCP de Claude Desktop:

Ubicación:

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

Configuración:

{
  "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. Comience a Usar con Claude

Reinicie Claude Desktop y pruebe estas consultas:

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

🔧 Herramientas Disponibles (12 en Total)

Operaciones JMX Principales

Herramienta	Descripción	Ejemplo de Uso
`listMBeans`	Lista todos los MBeans descubiertos con filtrado opcional por dominio	"Muéstrame todos los MBeans relacionados con memoria"
`getMBeanInfo`	Obtiene información detallada sobre un MBean específico	"Cuéntame sobre el MBean de Runtime"
`getAttribute`	Lee el valor de un atributo de MBean	"¿Cuál es el uso actual de memoria heap?"
`setAttribute`	Establece el valor de un atributo de MBean escribible	"Establece el nivel de registro a DEBUG"
`listDomains`	Lista todos los dominios de MBeans disponibles	"¿Qué dominios están disponibles?"

Gestión de Conexiones

Herramienta	Descripción	Ejemplo de Uso
`listJmxConnections`	Lista todas las conexiones JMX configuradas	"Muéstrame todas las conexiones disponibles"
`addJmxConnection`	Agrega una nueva conexión JMX	"Conéctate al servidor de producción"
`removeJmxConnection`	Elimina una conexión JMX	"Elimina la conexión de prueba antigua"
`switchJmxConnection`	Cambia a una conexión JMX diferente	"Cambia al entorno de staging"
`getConnectionInfo`	Obtiene el estado actual de la conexión JMX y estadísticas	"¿Está saludable la conexión JMX?"

Descubrimiento de Servicios

Herramienta	Descripción	Ejemplo de Uso
`discoverJmxServices`	Descubre aplicaciones Java con JMX habilitado en el sistema	"Encuentra todas las aplicaciones Java con JMX habilitado"
`autoRegisterDiscoveredConnections`	Registra automáticamente los servicios JMX descubiertos	"Conéctate automáticamente a todas las aplicaciones Java descubiertas"

📊 Recursos Disponibles

El servidor expone automáticamente todos los atributos JMX como recursos MCP, haciéndolos descubribles y accesibles para asistentes de IA:

Métricas de Memoria: Uso de heap, uso de no-heap, grupos de memoria
Recolección de Basura: Estadísticas de GC, tiempos de recolección, conteos de recolección
Subprocesos: Conteos de subprocesos, detección de interbloqueos, estados de subprocesos
Información de Runtime: Tiempo de actividad de JVM, tiempo de inicio, propiedades del sistema
Carga de Clases: Clases cargadas, clases descargadas, ruta de clases
Sistema Operativo: Uso de CPU, carga del sistema, procesadores disponibles

Formato de URI de Recursos:

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

Ejemplos 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

💬 Ejemplos de Interacciones

Monitoreo de Memoria

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álisis de Rendimiento

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.

🏗️ Arquitectura

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   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 Principales

JMXConnectionManager: Gestiona conexiones JMX locales y remotas
MBeanDiscoveryService: Descubre y cataloga los MBeans disponibles
JmxService: Proporciona métodos anotados con @Tool para interacción con IA
JMXToMCPMapper: Mapea atributos JMX a recursos MCP
JmxSecurityValidator: Valida operaciones para cumplimiento de seguridad

⚙️ Perfiles de Configuración

Perfil Predeterminado

Configuración estándar con registro completo para desarrollo y depuración.

Perfil STDIO

Optimizado para integración con Claude Desktop:

Operación Silenciosa: Sin salida de consola para evitar interferencia JSON-RPC
Registro Mínimo: Registro solo de errores para prevenir problemas del sistema de archivos
Inicio Rápido: Inicialización optimizada para respuestas rápidas de IA

🧪 Pruebas

Suite de Pruebas Integral

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

Cobertura de Pruebas:

✅ Cumplimiento del protocolo MCP
✅ Comunicación JSON-RPC 2.0
✅ Registro y ejecución de las 12 herramientas
✅ Gestión de múltiples conexiones
✅ Descubrimiento de servicios y auto-registro
✅ Descubrimiento y acceso a recursos
✅ Manejo de errores y recuperación

Pruebas Unitarias

mvn test

🔒 Seguridad

Características de Seguridad Integradas

Validación de ObjectName: Previene el acceso a MBeans sensibles
Filtrado de Operaciones: Restringe operaciones peligrosas
Seguridad de Tipos: Valida tipos de atributos antes de las operaciones
Control de Acceso: Políticas de seguridad configurables

Configuración de Seguridad

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

🚀 Despliegue

Desarrollo Local

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

Despliegue en Producción

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

Despliegue con Docker

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

🤝 Contribuciones

¡Damos la bienvenida a contribuciones! Consulte nuestra Guía de Contribución para más detalles.

Configuración de Desarrollo

Haga un fork del repositorio
Cree una rama de características
Realice sus cambios
Agregue pruebas para la nueva funcionalidad
Asegúrese de que todas las pruebas pasen
Envíe una solicitud de extracción

Estilo de Código

Siga las convenciones de codificación de Java
Use nombres significativos para variables y métodos
Agregue comentarios JavaDoc integrales
Mantenga la cobertura de pruebas por encima del 80%

📚 Documentación

Documentación de API: Referencia detallada de API
Guía de Configuración: Opciones de configuración avanzadas
Solución de Problemas: Problemas comunes y soluciones
Ejemplos: Ejemplos de uso y tutoriales

🐛 Solución de Problemas

Problemas Comunes

El servidor no inicia con Claude Desktop:

Verifique que Java 17+ esté instalado
Compruebe la ruta del JAR en la configuración
Asegúrese de que el perfil STDIO esté activo

No se ven herramientas/recursos:

Reinicie Claude Desktop después de los cambios de configuración
Revise los registros del servidor para ver errores
Verifique el cumplimiento del protocolo MCP

Problemas de conexión:

Confirme que JMX esté habilitado en la aplicación objetivo
Verifique la conectividad de red para conexiones remotas
Valide la configuración de seguridad

🤝 Contribuciones

¡Damos la bienvenida a contribuciones! Consulte nuestra Guía de Contribución para más detalles.

Inicio Rápido para Contribuyentes

# 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

🐛 Reportar errores - Ayúdenos a identificar y corregir problemas
💡 Sugerir características - Comparta ideas para nueva funcionalidad
📝 Mejorar documentación - Ayude a otros a entender el proyecto
🔧 Enviar código - Corrija errores o implemente nuevas características
🧪 Escribir pruebas - Mejore la cobertura y confiabilidad de las pruebas
🎨 Mejoras de UI/UX - Mejore la experiencia del usuario

Comunidad

Discusiones de GitHub: Haga preguntas y comparta ideas
Issues: Reporte errores y solicite características
Solicitudes de Extracción: Contribuya con mejoras de código
Wiki: Documentación colaborativa

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulte el archivo LICENCIA para más detalles.

🙏 Agradecimientos

Equipo de Spring AI por el excelente marco MCP
Protocolo de Contexto de Modelo por el protocolo estandarizado de integración de IA
Anthropic por Claude Desktop y las capacidades de asistente de IA
Comunidad OpenJDK por la robusta plataforma Java

📞 Soporte

Issues: Issues de GitHub
Discusiones: Discusiones de GitHub
Documentación: Wiki

Hecho con ❤️ para las comunidades de IA y Java