Proxy MCP de Arthas

Servidor proxy de diagnóstico de Arthas basado en MCP (Model Context Protocol), que permite la conexión dinámica a cualquier servidor a través de SSH dentro de las conversaciones de Claude para realizar diagnósticos de JVM en tiempo real.

Características

Conexión dinámica en la conversación: Pase directamente la dirección SSH, el nombre de usuario y la contraseña/clave para conectarse al servidor de destino en tiempo real.
Diagnóstico paralelo de múltiples procesos: Cada proceso de JVM tiene un agente de Arthas independiente, lo que permite cambiar de PID sin latencia.
Reutilización automática del pool de conexiones: Almacena en caché las conexiones SSH por user@host:port y las libera automáticamente tras 5 minutos de inactividad.
Attach automático de Arthas: Se conecta automáticamente en segundo plano al PID de destino la primera vez que se utiliza, reutilizándolo posteriormente.
Despliegue remoto SSE: Admite despliegue residente en modo HTTP SSE, permitiendo que Claude se conecte a través de una URL.
Soporte para construcción offline: Permite la construcción de Docker en entornos de red interna sin acceso a internet mediante la descarga previa de paquetes whl.

Lista de herramientas MCP

Nombre de la herramienta	Descripción
`connect_ssh`	Establece una conexión SSH y devuelve un session_id
`list_java_processes`	Lista los procesos Java en la máquina de destino (muestra el estado de adjunto de Arthas)
`thread_dump`	Obtiene la pila de hilos (top N por CPU)
`heap_info`	Consulta información de memoria/Dashboard
`watch_method`	Monitorea los parámetros de entrada y valores de retorno de un método
`exec_command`	Ejecuta cualquier comando de Arthas
`disconnect_ssh`	Cierra la conexión SSH y libera recursos

Modelo de diagnóstico concurrente

Importante: Cada proceso de JVM de Arthas requiere una instancia de agente independiente

PID 1234 (web)    <---> Arthas agent (port 3658)
PID 5678 (cpu)    <---> Arthas agent (port 3660)  
PID 9012 (memory) <---> Arthas agent (port 3661)

Primer uso: Se conecta automáticamente en segundo plano, Arthas asigna un puerto automáticamente (aprox. 5 segundos).
Cambios posteriores: Conexión directa al agente existente, latencia cero.
Soporte multiproceso: Puede mantener múltiples agentes ejecutándose simultáneamente y cambiar entre ellos a voluntad.
Consumo de recursos: Cada agente consume aproximadamente 20-30 MB de memoria; se recomienda un máximo de 10 simultáneos.
Liberación: Se limpia automáticamente al ejecutar stop mediante exec_command o al cerrar la conexión SSH.

Stack tecnológico

Componente	Selección
Lenguaje	Python 3.11+
MCP SDK	mcp >= 1.6.0
Librería SSH	paramiko >= 3.4.0
Framework HTTP	starlette + uvicorn

Inicio rápido

1. Construcción online (entorno con red)

docker build -t arthas-mcp-proxy .
# 或
docker-compose up -d

2. Construcción offline (entorno de red interna sin internet)

Paso 1: Descarga previa de dependencias en una máquina con acceso a internet

bash download-packages.sh
# 完成后 packages/ 目录包含所有 .whl 文件

Paso 2: Empaquetar y transferir a la red interna

zip -r arthas-mcp-proxy.zip arthas-mcp-proxy/
# 通过 U 盘/SCP 传入内网服务器

Paso 3: Construcción en la red interna

cd arthas-mcp-proxy
docker build --build-arg PIP_SOURCE=offline -t arthas-mcp-proxy .
# 或
PIP_SOURCE=offline docker-compose up -d --build

3. Configuración de Claude

Modo SSE (despliegue remoto):

{
  "mcpServers": {
    "arthas": {
      "type": "sse",
      "url": "http://your-server-ip:8000/sse"
    }
  }
}

Modo stdio (integración local):

{
  "mcpServers": {
    "arthas": {
      "command": "python",
      "args": ["/path/to/main.py", "--transport", "stdio"]
    }
  }
}

Ejemplo de uso

En la conversación de Claude:

连接到 192.168.1.100，用户 root，密码 xxx，查看上面的 Java 进程。

Claude llamará automáticamente a connect_ssh -> list_java_processes.

Luego:

查看 PID 1234 的线程栈 top 10，然后查看 PID 5678 的内存情况。

Claude cambiará automáticamente el diagnóstico entre múltiples PIDs, realizando el attach automáticamente la primera vez que se usa cada PID y reutilizándolo después.

Estructura del proyecto

arthas-mcp-proxy/
├── main.py                  # MCP Server 入口（SSE + stdio 双模式）
├── ssh_pool.py              # SSH 连接池（动态连接 + session 复用）
├── arthas_client.py         # Arthas 命令封装（多 PID 并行支持）
├── requirements.txt         # Python 依赖
├── Dockerfile               # 双模式构建 Dockerfile
├── docker-compose.yml       # Docker Compose 配置
├── download-packages.sh     # 外网预下载脚本
├── packages/                # 离线 whl 包目录
└── README.md                # 本文档

Requisitos de la máquina de destino

Arthas instalado (/opt/arthas/as.sh o ruta personalizada).
SSH accesible, el usuario que ejecuta tiene permisos para hacer attach a la JVM de destino.
Comando jps disponible (incluido con el JDK).

Licencia

Licencia MIT

Arthas MCP Proxy