1. 服务概述
一句话简介：基于MCP的Arthas诊断代理服务器，支持在Claude对话中通过SSH动态连接到任意服务器进行JVM实时诊断，实现多进程并行诊断和零延迟切换。
- 服务名称：Arthas MCP Proxy
- 版本号：1.0.0
- 开发者/提供方：narcissux
- 协议类型：MCP (Model Context Protocol)
2. 核心功能
该MCP服务提供七个核心诊断工具：
| 工具名称 | 功能描述 |
|---|---|
| connect_ssh | 建立SSH连接，返回session_id |
| list_java_processes | 列出目标机Java进程（显示Arthas附加状态） |
| thread_dump | 获取线程栈（top N by CPU） |
| heap_info | 查看内存/Dashboard信息 |
| watch_method | 监听方法入参和返回值 |
| exec_command | 执行任意Arthas命令 |
| disconnect_ssh | 断开SSH连接释放资源 |
3. 使用场景
该服务适合在以下情况下使用：
- JVM实时诊断和性能分析
- 线程栈分析和CPU热点定位
- 内存使用情况监控和分析
- 方法调用监听和参数追踪
- 多进程并行诊断和对比分析
- 生产环境问题快速定位和排查
4. 接入方式
4.1 服务端点
支持两种部署模式：
| 部署模式 | 端点说明 |
|---|---|
| SSE模式（远程部署） | http://your-server-ip:8000/sse |
| stdio模式（本地嵌入） | 本地Python进程，通过命令行启动 |
4.2 认证与权限
SSH认证方式：
- 用户名 + 密码认证
- 用户名 + SSH密钥认证
- 运行用户需要有权限attach目标JVM
- 目标机需要安装Arthas（/opt/arthas/as.sh或自定义路径）
4.3 数据格式
服务支持以下数据格式：
- 输入格式：JSON格式的请求参数（SSH连接信息、PID、命令参数等）
- 输出格式：JSON格式的诊断结果数据
- 通信协议：支持SSE（Server-Sent Events）和stdio两种传输方式
4.4 服务器配置
SSE模式配置：
{ "mcpServers": { "arthas": { "type": "sse", "url": "http://your-server-ip:8000/sse" } } }stdio模式配置：
{ "mcpServers": { "arthas": { "command": "python", "args": ["/path/to/main.py", "--transport", "stdio"] } } }5. 接口定义
5.1 connect_ssh 工具
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| host | string | 是 | 目标服务器IP地址 |
| port | number | 否 | SSH端口（默认22） |
| username | string | 是 | SSH用户名 |
| password | string | 否 | SSH密码（与key二选一） |
| key | string | 否 | SSH私钥（与password二选一） |
5.2 thread_dump 工具
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| session_id | string | 是 | SSH会话ID |
| pid | number | 是 | Java进程ID |
| top_n | number | 否 | 显示CPU占用最高的N个线程（默认10） |
5.3 watch_method 工具
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| session_id | string | 是 | SSH会话ID |
| pid | number | 是 | Java进程ID |
| class_pattern | string | 是 | 类名匹配模式 |
| method_pattern | string | 是 | 方法名匹配模式 |
6. 快速开始
6.1 环境要求
- Python 3.11或更高版本
- Docker（可选，用于容器化部署）
- 目标机已安装Arthas
- 目标机SSH可达
- 目标机jps命令可用（JDK自带）
6.2 示例代码
在线构建（有网络环境）：
docker build -t arthas-mcp-proxy . # 或 docker-compose up -d离线构建（内网无网络环境）：
# 步骤1：外网机器预下载依赖 bash download-packages.sh # 步骤2：打包传入内网 zip -r arthas-mcp-proxy.zip arthas-mcp-proxy/ # 步骤3：内网构建 cd arthas-mcp-proxy docker build --build-arg PIP_SOURCE=offline -t arthas-mcp-proxy .使用示例：
# 在Claude对话中： # 连接到 192.168.1.100，用户 root，密码 xxx，查看上面的 Java 进程。 # Claude会自动调用 connect_ssh -> list_java_processes # 查看 PID 1234 的线程栈 top 10，然后查看 PID 5678 的内存情况。 # Claude会自动在多个PID间切换诊断7. 注意事项
- 并发诊断模型：Arthas每个JVM进程需要独立的agent实例，首次使用自动后台attach（约5秒），后续切换零延迟
- 连接池管理：按user@host:port缓存SSH连接，空闲5分钟自动回收，支持连接复用
- 资源占用：每个agent约20-30MB内存，建议同时保持<=10个agent运行
- 多进程支持：可同时保持多个agent运行，任意切换PID进行诊断
- 离线构建支持：支持内网零网络环境下通过预下载whl包完成Docker构建
- 目标机要求：已安装Arthas、SSH可达、运行用户有权限attach目标JVM、jps命令可用
- 许可证：采用MIT License，可自由使用和修改
