Arthas MCP 프록시

MCP(Model Context Protocol) 기반의 Arthas 진단 프록시 서버로, Claude 대화 내에서 SSH를 통해 임의의 서버에 동적으로 연결하여 JVM 실시간 진단을 지원합니다.

기능 특징

대화 중 동적 연결: SSH 주소, 사용자 이름, 비밀번호/키를 직접 전달하여 대상 서버에 실시간 연결
다중 프로세스 병렬 진단: 각 JVM 프로세스별 독립적인 Arthas 에이전트, PID 전환 시 지연 시간 없음
연결 풀 자동 재사용: user@host:port 기준으로 SSH 연결을 캐싱하며, 5분간 유휴 상태 시 자동 회수
Arthas 자동 attach: 대상 PID 최초 사용 시 백그라운드에서 자동 attach, 이후 재사용
SSE 원격 배포: HTTP SSE 모드 상주 배포 지원, Claude가 URL을 통해 연결
오프라인 빌드 지원: 내부망 환경에서 사전 다운로드된 whl 패키지를 통해 Docker 빌드 완료

MCP 도구 목록

도구 이름	설명
`connect_ssh`	SSH 연결을 설정하고 session_id 반환
`list_java_processes`	대상 머신의 Java 프로세스 나열 (Arthas 부착 상태 표시)
`thread_dump`	스레드 스택 가져오기 (CPU 기준 상위 N개)
`heap_info`	메모리/대시보드 정보 확인
`watch_method`	메서드 입력 매개변수 및 반환값 모니터링
`exec_command`	임의의 Arthas 명령 실행
`disconnect_ssh`	SSH 연결을 끊고 리소스 해제

병렬 진단 모델

중요: Arthas는 각 JVM 프로세스마다 독립적인 에이전트 인스턴스가 필요합니다.

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

최초 사용: 백그라운드에서 자동 attach, Arthas가 자동으로 포트 할당 (약 5초 소요)
이후 전환: 기존 에이전트에 직접 연결, 지연 시간 제로
다중 프로세스 지원: 여러 에이전트를 동시에 실행 상태로 유지하며 자유롭게 전환 가능
리소스 점유: 에이전트당 약 20-30MB 메모리 사용, 동시 실행은 10개 이하 권장
해제: exec_command를 통해 stop을 실행하거나 SSH 연결을 끊을 때 자동 정리

기술 스택

구성 요소	선택
언어	Python 3.11+
MCP SDK	mcp >= 1.6.0
SSH 라이브러리	paramiko >= 3.4.0
HTTP 프레임워크	starlette + uvicorn

빠른 시작

1. 온라인 빌드 (네트워크 환경)

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

2. 오프라인 빌드 (내부망 네트워크 없음)

단계 1: 외부망 머신에서 의존성 사전 다운로드

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

단계 2: 패키징하여 내부망으로 전송

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

단계 3: 내부망 빌드

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

3. Claude 설정

SSE 모드 (원격 배포):

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

stdio 모드 (로컬 임베딩):

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

사용 예시

Claude 대화 내에서:

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

Claude가 자동으로 connect_ssh -> list_java_processes를 호출합니다.

그 다음:

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

Claude가 여러 PID 간에 진단을 자동으로 전환하며, 각 PID는 최초 사용 시 자동으로 attach되고 이후 재사용됩니다.

프로젝트 구조

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                # 本文档

대상 머신 요구 사항

Arthas 설치 완료 (/opt/arthas/as.sh 또는 사용자 정의 경로)
SSH 접근 가능, 실행 사용자가 대상 JVM에 attach할 권한 보유
jps 명령 사용 가능 (JDK 포함)

라이선스

MIT License

Arthas MCP Proxy