--- date: 2026-10-17 18:01 created: 2026-10-17 18:01 updated: 2026-10-17 18:01 categories: tags: --- # 1. 工作原理 先理解一个关键点：**arthas-mcp-server 不是一个独立进程**。 ``` ┌─────────────┐ MCP (streamableHttp) ┌──────────────────────────┐ │ AI 客户端 │ ───────────────────────▶ │ 目标 JVM (如 math-game) │ │ (WorkBuddy │ http://localhost:8563 │ ┌────────────────────┐ │ │ 等) │ │ │ arthas agent │ │ └─────────────┘ │ │ (attach 时注入) │ │ │ │ - telnet :3658 │ │ │ │ - http :8563/mcp │ │ │ └────────────────────┘ │ │ ┌────────────────────┐ │ │ │ 你的业务代码 │ │ │ └────────────────────┘ │ └──────────────────────────┘ ``` - Arthas 以 **agent 形式 attach 到目标 Java 进程**，之后在目标进程内部启动 HTTP 服务，默认端口 **8563**，MCP 路径为 `/mcp`（由 `arthas.properties` 中 `arthas.mcpEndpoint=/mcp` 控制）。 - 所以「启动 MCP server」= 「找一个目标 JVM + 把 arthas attach 上去」。 - 目标 JVM 停止（或调用 `stop` 工具），MCP 服务随之消失。 --- # 2. 环境准备 | 依赖 | 要求 | 检查命令 | | ------ | --------------------------------- | ------------------- | | Java | JDK 8+（目标进程和 attach 方都需要） | `java -version` | | curl | 用于下载和探活 | `curl --version` | | unzip | 解压安装包 | `unzip -v` | | telnet | 仅 as.sh 启动脚本检查用（macOS 通常没有，见 FAQ） | `command -v telnet` | > JDK 17+ 才会构建/启用 MCP 相关集成测试模块，但**运行时 JDK 8+ 即可**。 --- # 3. 下载与安装 ## 3.1. 下载发行包 从 GitHub Release 下载（不要本地编译，全量构建很慢）： ```bash # 下载（可换成其他版本号，见 https://github.com/alibaba/arthas/releases） curl -sSL -o /tmp/arthas-bin.zip \ https://github.com/alibaba/arthas/releases/download/arthas-all-4.3.5/arthas-bin.zip ``` 包大小约 16 MB，包含：`arthas-core.jar`、`arthas-agent.jar`、`arthas-boot.jar`、`arthas-client.jar`、`arthas-spy.jar`、`math-game.jar`（演示用）、`as.sh`、`arthas.properties`、`lib/`（vmtool native 库）、`async-profiler/` 等。 ## 3.2. 安装到本地 Arthas 的启动脚本默认在 `~/.arthas/lib/<版本>/arthas/` 下寻找安装： ```bash # 解压 unzip -q /tmp/arthas-bin.zip -d /tmp/arthas-dl # 安装 ARTHAS_HOME=~/.arthas/lib/4.3.5/arthas mkdir -p "$ARTHAS_HOME" cp /tmp/arthas-dl/*.jar "$ARTHAS_HOME"/ cp /tmp/arthas-dl/arthas.properties /tmp/arthas-dl/logback.xml "$ARTHAS_HOME"/ cp -r /tmp/arthas-dl/lib /tmp/arthas-dl/async-profiler "$ARTHAS_HOME"/ cp /tmp/arthas-dl/as.sh "$ARTHAS_HOME"/ chmod +x "$ARTHAS_HOME"/as.sh ``` > **注意**：包内自带的 `install-local.sh` 只拷贝 jar，不拷贝 `as.sh`，需要手动补（上面最后两行）。 ## 3.3. 确认 MCP 配置已开启 检查 `~/.arthas/lib/4.3.5/arthas/arthas.properties`，4.3.5 默认已开启，无需修改： ```properties arthas.mcpEndpoint=/mcp # MCP 服务路径；不配置则不启用 arthas.mcpProtocol=STREAMABLE # STREAMABLE(有状态,默认) / STATELESS(无状态) arthas.httpPort=8563 # HTTP 端口 ``` --- # 4. 启动服务 ## 4.1. 准备目标 JVM MCP 是 attach 模式，先要有一个运行中的 Java 进程。没有现成应用时，用自带的演示程序： ```bash # 演示程序 math-game：死循环做质因数分解，每秒一次 java -jar ~/.arthas/lib/4.3.5/arthas/math-game.jar ``` 有真实应用就直接用它（Spring Boot fat jar、tomcat 进程均可）。 ## 4.2. Attach Arthas 另开一个终端： ```bash # 查找目标进程 PID jps -l # attach（--attach-only 表示只注入 agent，不进入交互式 telnet） bash ~/.arthas/lib/4.3.5/arthas/as.sh --attach-only ``` 成功标志： ``` Attaching to using version /Users/xxx/.arthas/lib/4.3.5/arthas... Attach success. ``` **macOS 用户注意**：`as.sh` 启动时会硬性检查 `telnet` 命令是否存在，macOS 默认没有。用一个空壳脚本绕过： ```bash mkdir -p /tmp/arthas-dl/bin printf '#!/bin/bash\nexit 0\n' > /tmp/arthas-dl/bin/telnet chmod +x /tmp/arthas-dl/bin/telnet # 之后所有 as.sh 调用都带上 PATH 前缀 PATH=/tmp/arthas-dl/bin:$PATH bash ~/.arthas/lib/4.3.5/arthas/as.sh --attach-only ``` ## 4.3. 验证服务 ```bash # 1) 端口在监听 lsof -iTCP:8563 -sTCP:LISTEN # 2) MCP 握手（应返回 serverInfo: arthas-mcp-server） curl -s -X POST http://localhost:8563/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"probe","version":"0.0.1"}}}' ``` 正确响应（节选）： ```json {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-03-26","serverInfo":{"name":"arthas-mcp-server","version":"4.3.5"}, ...}} ``` --- # 5. 配置 AI 客户端 ## 5.1. WorkBuddy 编辑 `~/.workbuddy/mcp.json`（没有则新建）： ```json { "mcpServers": { "arthas-mcp": { "type": "streamableHttp", "url": "http://localhost:8563/mcp", "timeout": 30000 } } } ``` 然后在 WorkBuddy 中启用：左侧栏 **专家・技能・连接器 → 连接器 → 右上角自定义连接器 → 配置 MCP**，将 `arthas-mcp` 切到**信任/启用**状态。 验证：在对话里问「列出 arthas-mcp 提供的工具」或「查看当前 JVM 信息」。 ## 5.2. Cherry Studio / Cline 等其他客户端 设置中添加 MCP 服务器： ```json { "mcpServers": { "arthas-mcp": { "type": "streamableHttp", "url": "http://localhost:8563/mcp" } } } ``` --- # 6. 工具总览 共 **32 个工具**，与 Arthas 命令一一对应。 ### 6.1.1. JVM 诊断（13 个） | 工具 | 对应命令 | 说明 | | ------------- | ----------- | ------------------------------------------- | | `dashboard` | dashboard | 实时 JVM/应用面板，可控制刷新间隔与次数 | | `jvm` | jvm | JVM 运行时完整信息 | | `memory` | memory | 内存使用情况（heap/nonheap/buffer 分区明细） | | `thread` | thread | 线程信息与堆栈；`blocking=true` 找阻塞源，`topN=N` 找最忙线程 | | `heapdump` | heapdump | 导出堆转储，`live=true` 只含存活对象 | | `vmtool` | vmtool | 强制 GC、获取类实例、中断线程 | | `vmoption` | vmoption | 查看/动态修改 VM 参数 | | `sysprop` | sysprop | 查看/修改系统属性 | | `sysenv` | sysenv | 查看环境变量 | | `perfcounter` | perfcounter | JVM 性能计数器 | | `mbean` | mbean | 查看/监控 MBean 属性 | | `getstatic` | getstatic | 查看类静态字段，支持 OGNL 后处理 | | `ognl` | ognl | 执行任意 OGNL 表达式 | ### 6.1.2. Class / ClassLoader（8 个） | 工具 | 对应命令 | 说明 | | ------------- | ----------- | --------------------------------------------- | | `sc` | sc | 搜索已加载类（详情含类加载器、注解、字段） | | `sm` | sm | 搜索类的方法（签名、参数、注解） | | `jad` | jad | 反编译指定类 | | `classloader` | classloader | 类加载器统计/继承树/URL（mode=stats/tree/url-classes 等） | | `mc` | mc | 内存编译器，.java → .class | | `redefine` | redefine | 热更新类字节码 | | `retransform` | retransform | 触发类重新转换 | | `dump` | dump | 导出运行中的 class 字节码 | ### 6.1.3. 监控诊断（6 个，长耗时流式工具） | 工具 | 对应命令 | 说明 | | ---------- | -------- | --------------------------- | | `watch` | watch | 观察方法入参/返回值/异常 | | `trace` | trace | 方法内部调用链路耗时 | | `stack` | stack | 方法被调用的调用路径 | | `monitor` | monitor | 方法调用统计（次数/成功率/RT） | | `tt` | tt | 时空隧道：记录、搜索、回放方法调用 | | `profiler` | profiler | async-profiler 采样，输出火焰图/JFR | ### 6.1.4. 辅助工具（5 个） | 工具 | 说明 | | ------------- | ------------------------------------------------------------ | | `viewfile` | 查看白名单目录内文件，支持 cursor 分段读取 | | `upload_file` | 上传 .class/.java/.jfc 到目标 JVM（Base64），配合 mc/redefine/profiler | | `options` | 查看/修改 Arthas 全局开关（unsafe、json-format、strict 等） | | `version` | 查看 Arthas 版本 | | `stop` | **彻底停止 Arthas**（停完全部工具失效，慎用） | --- # 7. 常用场景示例 以下均为对 AI 说自然语言即可完成的事情（AI 会翻译成对应 tool 调用）： **基础巡检** - 「看下当前 JVM 内存占用和线程数」→ `memory` + `thread` - 「哪个线程 CPU 最高？打印它的堆栈」→ `thread` (topN=1) - 「当前 JVM 加载了多少个类？」→ `classloader` (mode=stats) **问题定位** - 「demo.MathGame.primeFactors 每次调用的入参和返回值是什么」→ `watch` - 「primeFactors 内部每一步耗时多少，哪一步最慢」→ `trace` - 「谁在调用 primeFactors？」→ `stack` - 「监控 primeFactors 一分钟的调用次数和成功率」→ `monitor` - 「把刚才那次失败的调用重放一下」→ `tt` (replay) **代码诊断** - 「反编译 demo.MathGame 看看运行中的真实代码」→ `jad` - 「搜一下 JVM 里所有加载的 StringUtils 类」→ `sc *StringUtils` - 「动态执行 @System@getProperty("user.dir")」→ `ognl` **热修复** - 「我把修复后的类编译好上传进去热更新」→ `upload_file` + `redefine` **性能分析** - 「对当前进程做 60 秒 CPU 采样，输出火焰图」→ `profiler` (action=start, duration=60, format=flamegraph) > 提示：`watch/trace/stack/monitor/tt` 属于长耗时工具，都支持 `numberOfExecutions`（次数）和 `timeout`（秒）参数控制自动停止，默认超时 30 秒。 --- # 8. 可选：开启认证 默认本地无认证。如需开启，在 `arthas.properties` 中配置： ```properties arthas.password=your-secure-password ``` 然后 AI 客户端配置加上 headers（token 与密码完全一致）： ```json { "mcpServers": { "arthas-mcp": { "type": "streamableHttp", "url": "http://localhost:8563/mcp", "headers": { "Authorization": "Bearer your-secure-password" } } } } ``` --- # 9. 常见问题（FAQ） **Q1：curl 8563 返回 Connection refused？** MCP 服务随目标 JVM 存活。检查目标进程是否还在（`jps -l`），不在则重启应用并重新 attach。 **Q2：macOS 报 `Error: telnet is not installed`？** 见 4.2 节——放一个空壳 telnet 脚本到 PATH 里绕过 as.sh 的检查。 **Q3：MCP 客户端报 session 失效 / 旧请求 404？** 目标 JVM 重启过（或 arthas 重新 attach 过）会生成新进程、旧 session 全部失效。客户端重新 initialize 即可（WorkBuddy 会自动处理）。 **Q4：想彻底停掉 Arthas？** - 优雅方式：调用 MCP 的 `stop` 工具（它会先返回结果再延迟执行）； - 或者直接杀目标 JVM（`kill `），agent 随进程消亡。 **Q5：viewfile 提示目录不在白名单？** 默认只允许 `./arthas-output/` 和 `~/logs/`。扩展方式： ```bash export ARTHAS_MCP_VIEWFILE_ALLOWED_DIRS=/path/a,/path/b ``` **Q6：怎么换成诊断我自己的应用？** 对你的应用进程重复 4.2 节的 attach 即可。一个目标 JVM 一个 arthas 实例；换目标后 8563 指向新进程。 **Q7：STATELESS 和 STREAMABLE 怎么选？** - `STREAMABLE`（默认）：有状态，支持 watch/trace 等流式长命令和进度通知，交互式诊断用这个； - `STATELESS`：每请求独立，适合简单一次性查询，改 `arthas.mcpProtocol=STATELESS`。 --- ## 9.1. 快速命令速查 ```bash # === 安装（一次性） === curl -sSL -o /tmp/arthas-bin.zip \ https://github.com/alibaba/arthas/releases/download/arthas-all-4.3.5/arthas-bin.zip unzip -q /tmp/arthas-bin.zip -d /tmp/arthas-dl ARTHAS_HOME=~/.arthas/lib/4.3.5/arthas mkdir -p "$ARTHAS_HOME" && cp /tmp/arthas-dl/*.jar "$ARTHAS_HOME"/ \ && cp /tmp/arthas-dl/arthas.properties /tmp/arthas-dl/logback.xml "$ARTHAS_HOME"/ \ && cp -r /tmp/arthas-dl/lib /tmp/arthas-dl/async-profiler "$ARTHAS_HOME"/ \ && cp /tmp/arthas-dl/as.sh "$ARTHAS_HOME"/ && chmod +x "$ARTHAS_HOME"/as.sh # telnet 空壳（macOS） mkdir -p /tmp/arthas-dl/bin && printf '#!/bin/bash\nexit 0\n' \ > /tmp/arthas-dl/bin/telnet && chmod +x /tmp/arthas-dl/bin/telnet # === 每次启动 === java -jar ~/.arthas/lib/4.3.5/arthas/math-game.jar & # 目标 JVM（或你自己的应用） jps -l # 找 PID PATH=/tmp/arthas-dl/bin:$PATH bash ~/.arthas/lib/4.3.5/arthas/as.sh --attach-only # === 验证 === curl -s -X POST http://localhost:8563/mcp \ -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"probe","version":"0.0.1"}}}' ``` ```