Skip to content

Commit f6ff06b

Browse files
YeauryYeaury
authored
docs: add official documentation for MCP Server (#3073)
1 parent 0c38eee commit f6ff06b

File tree

5 files changed

+306
-1
lines changed

5 files changed

+306
-1
lines changed

‎labs/arthas-mcp-server/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
## 项目简介
44

5-
`arthas-mcp-server` 是 [Arthas](https://github.com/alibaba/arthas) 的实验模块，实现了基于 MCP（Model Context Protocol）协议的服务端。该模块通过 HTTP/Netty 提供统一的 JSON-RPC 2.0 接口，支持 AI 使用工具调用的方式执行 arthas 的命令。
5+
`arthas-mcp-server` 是 [Arthas](https://github.com/alibaba/arthas) 的实验模块，实现了基于 MCP（Model Context Protocol）协议（版本 2025-03-26）的服务端。该模块通过 HTTP/Netty 提供统一的 JSON-RPC 2.0 接口，支持 AI 使用工具调用的方式执行 arthas 的命令。
66

77
Arthas MCP 服务集成了 26 个核心诊断工具，按功能分类如下：
88

‎site/docs/.vuepress/configs/sidebar/en.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ export const sidebarEN = {
7676
"/en/doc/agent.html",
7777
"/en/doc/spring-boot-starter.md",
7878
"/en/doc/http-api.md",
79+
"/en/doc/mcp-server.md",
7980
"/en/doc/batch-support.md",
8081
],
8182
},

‎site/docs/.vuepress/configs/sidebar/zh.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ export const sidebarZH = {
7676
"/doc/agent.html",
7777
"/doc/spring-boot-starter.md",
7878
"/doc/http-api.md",
79+
"/doc/mcp-server.md",
7980
"/doc/batch-support.md",
8081
],
8182
},

‎site/docs/doc/mcp-server.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# Arthas MCP Server
2+
3+
## 概览
4+
5+
Arthas MCP Server 是 Arthas 的实验性模块，实现了基于 [MCP（Model Context Protocol）](https://modelcontextprotocol.io/) 协议的服务端。该模块通过 HTTP/Netty 提供统一的 JSON-RPC 2.0 接口，使 AI 助手能够通过工具调用的方式执行 Arthas 诊断命令。
6+
7+
MCP（Model Context Protocol）是由 Anthropic 提出的一种标准化协议，用于连接 AI 助手与各种工具和数据源。通过 Arthas MCP Server，AI 助手可以自然地执行 Java 应用诊断任务，大幅提升开发和运维效率。
8+
9+
### 主要特性
10+
11+
- **AI 原生集成**：支持主流 AI 客户端（Claude Desktop、Cherry Studio、Cline 等）
12+
- **标准化协议**：完整实现 MCP 协议规范（版本 2025-03-26），支持 Streamable Http 传输
13+
- **26 个诊断工具**：涵盖 JVM 监控、类加载、方法追踪等核心功能
14+
- **安全认证**：支持 Bearer Token 认证机制
15+
16+
## 支持的诊断工具
17+
18+
Arthas MCP Server 集成了 26 个核心诊断工具，按功能分类如下：
19+
20+
### JVM 相关工具（12 个）
21+
22+
| 工具 | 功能描述 |
23+
| ------ | ----------------------------------------------------- |
24+
| **dashboard** | 实时展示 JVM/应用面板，支持自定义刷新间隔和次数控制 |
25+
| **heapdump** | 生成 JVM heap dump 文件，支持 `--live` 选项只导出存活对象 |
26+
| **jvm** | 查看当前 JVM 的详细信息 |
27+
| **mbean** | 查看或监控 MBean 属性信息，支持实时刷新和模式匹配 |
28+
| **memory** | 查看 JVM 的内存信息 |
29+
| **thread** | 查看线程信息及堆栈，支持查找阻塞线程和最忙线程 |
30+
| **sysprop** | 查看或修改系统属性，支持动态修改 JVM 系统属性 |
31+
| **sysenv** | 查看系统环境变量 |
32+
| **vmoption** | 查看或更新 VM 选项，支持动态调整 JVM 参数 |
33+
| **perfcounter** | 查看 Perf Counter 信息，显示 JVM 性能计数器 |
34+
| **vmtool** | 虚拟机工具集合，支持强制 GC、获取实例、线程中断等 |
35+
| **getstatic** | 查看类的静态字段值 |
36+
| **ognl** | 执行 OGNL 表达式，动态调用方法和访问字段 |
37+
38+
### Class/ClassLoader 相关工具（8 个）
39+
40+
| 工具 | 功能描述 |
41+
| ------ | ------------------------------------------------------ |
42+
| **sc** | 查看 JVM 已加载的类信息，支持详细信息和统计 |
43+
| **sm** | 查看已加载类的方法信息，显示方法签名和修饰符 |
44+
| **jad** | 反编译指定已加载类的源码，将字节码反编译为 Java 代码 |
45+
| **classloader** | ClassLoader 诊断工具，查看类加载器统计、继承树、URLs |
46+
| **mc** | 内存编译器，将 Java 源码编译为字节码文件 |
47+
| **redefine** | 重定义类，加载外部 class 文件重新定义 JVM 中的类 |
48+
| **retransform** | 重新转换类，触发类的重新转换和字节码增强 |
49+
| **dump** | 将 JVM 中实际运行的 class 字节码导出到指定目录 |
50+
51+
### 监控诊断工具（6 个）
52+
53+
| 工具 | 功能描述 |
54+
| ------ | ---------------------------------------------------------------- |
55+
| **monitor** | 实时监控指定类的指定方法的调用情况 |
56+
| **stack** | 输出当前方法被调用的调用路径，帮助分析方法的调用链路 |
57+
| **trace** | 追踪方法内部调用路径，输出每个节点的耗时信息 |
58+
| **tt** | 方法执行数据的时空隧道，记录下指定方法每次调用的入参和返回信息 |
59+
| **watch** | 观察指定方法的调用情况，包含入参、返回值和抛出异常等信息 |
60+
61+
## 快速开始
62+
63+
### 1. 配置 MCP 服务
64+
65+
在 `arthas.properties` 配置文件中启用 MCP 服务：
66+
67+
```properties
68+
# MCP (Model Context Protocol) configuration
69+
arthas.mcpEndpoint=/mcp
70+
```
71+
72+
### 2. 启动应用
73+
74+
正常启动 Arthas 或带有 Arthas 的 Java 应用。默认情况下，MCP 服务会在 HTTP 端口 8563 上暴露。
75+
76+
验证 MCP 服务是否启动：
77+
78+
```bash
79+
curl http://localhost:8563/mcp
80+
```
81+
82+
如果返回 MCP 协议信息，说明服务已成功启动。
83+
84+
### 3. 配置 AI 客户端
85+
86+
以下是几种主流 AI 客户端的配置方式：
87+
88+
#### Cherry Studio / Cline
89+
90+
在设置中添加 MCP 服务器配置：
91+
92+
```json
93+
{
94+
"mcpServers": {
95+
"arthas-mcp": {
96+
"type": "streamableHttp",
97+
"url": "http://localhost:8563/mcp"
98+
}
99+
}
100+
}
101+
```
102+
103+
104+
## 配置说明
105+
106+
### Arthas 配置项
107+
108+
| 配置项 | 说明 | 默认值 |
109+
| -------- | ---------------------------- | -------------------- |
110+
| `arthas.mcpEndpoint` | MCP 服务的访问路径 | 无（需要手动配置） |
111+
| `arthas.httpPort` | HTTP 服务端口 | 8563 |
112+
| `arthas.password` | 认证密码（开启认证时使用） | 无 |
113+
114+
### 认证配置
115+
116+
当在配置文件中设置了 `arthas.password` 时，MCP Server 会自动开启鉴权功能。此时需要在 AI 客户端配置中添加认证头，携带的 Bearer Token 就是配置的密码值。
117+
118+
配置文件示例（`arthas.properties`）：
119+
120+
```properties
121+
arthas.password=your-secure-password
122+
```
123+
124+
AI 客户端配置示例：
125+
126+
```json
127+
{
128+
"mcpServers": {
129+
"arthas-mcp": {
130+
"type": "streamableHttp",
131+
"url": "http://localhost:8563/mcp",
132+
"headers": {
133+
"Authorization": "Bearer your-secure-password"
134+
}
135+
}
136+
}
137+
}
138+
```
139+
140+
::: warning
141+
**注意**：Authorization header 中的 token 必须与 `arthas.password` 配置的值完全一致。
142+
:::
143+
144+
## 反馈与贡献
145+
146+
::: tip
147+
Arthas MCP Server 是实验性功能，欢迎提供反馈和建议！
148+
:::
149+
150+
- **问题反馈**：[GitHub Issues](https://github.com/alibaba/arthas/issues)
151+
- **功能建议**：[GitHub Discussions](https://github.com/alibaba/arthas/discussions)
152+
- **参与贡献**：[贡献指南](https://github.com/alibaba/arthas/blob/master/CONTRIBUTING.md)

‎site/docs/en/doc/mcp-server.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Arthas MCP Server
2+
3+
## Overview
4+
5+
Arthas MCP Server is an experimental module of Arthas that implements a server based on the [MCP (Model Context Protocol)](https://modelcontextprotocol.io/). This module provides a unified JSON-RPC 2.0 interface through HTTP/Netty, enabling AI assistants to execute Arthas diagnostic commands via tool calls.
6+
7+
MCP (Model Context Protocol) is a standardized protocol proposed by Anthropic for connecting AI assistants with various tools and data sources. Through Arthas MCP Server, AI assistants can naturally execute Java application diagnostic tasks, significantly improving development and operations efficiency.
8+
9+
### Key Features
10+
11+
- **AI-Native Integration**: Supports mainstream AI clients (Claude Desktop, Cherry Studio, Cline, etc.)
12+
- **Standardized Protocol**: Full implementation of MCP protocol specification (version 2025-03-26), supporting Streamable Http transport
13+
- **26 Diagnostic Tools**: Covers core functionalities including JVM monitoring, class loading, method tracing, etc.
14+
- **Security Authentication**: Supports Bearer Token authentication mechanism
15+
16+
## Supported Diagnostic Tools
17+
18+
Arthas MCP Server integrates 26 core diagnostic tools, categorized by functionality:
19+
20+
### JVM-Related Tools (12)
21+
22+
| Tool | Description |
23+
|------|-------------|
24+
| **dashboard** | Real-time JVM/application dashboard with customizable refresh interval and count control |
25+
| **heapdump** | Generate JVM heap dump file, supports `--live` option to export only live objects |
26+
| **jvm** | View current JVM detailed information |
27+
| **mbean** | View or monitor MBean attributes, supports real-time refresh and pattern matching |
28+
| **memory** | View JVM memory information |
29+
| **thread** | View thread information and stack traces, supports finding blocked and busiest threads |
30+
| **sysprop** | View or modify system properties, supports dynamic JVM system property modification |
31+
| **sysenv** | View system environment variables |
32+
| **vmoption** | View or update VM options, supports dynamic JVM parameter adjustment |
33+
| **perfcounter** | View Perf Counter information, displays JVM performance counters |
34+
| **vmtool** | VM tool collection, supports forced GC, instance retrieval, thread interruption, etc. |
35+
| **getstatic** | View static field values of a class |
36+
| **ognl** | Execute OGNL expressions, dynamically invoke methods and access fields |
37+
38+
### Class/ClassLoader Tools (8)
39+
40+
| Tool | Description |
41+
|------|-------------|
42+
| **sc** | View loaded class information in JVM, supports detailed info and statistics |
43+
| **sm** | View method information of loaded classes, displays method signatures and modifiers |
44+
| **jad** | Decompile loaded class source code, converts bytecode to Java code |
45+
| **classloader** | ClassLoader diagnostic tool, view classloader statistics, hierarchy tree, URLs |
46+
| **mc** | Memory compiler, compiles Java source code to bytecode files |
47+
| **redefine** | Redefine classes, load external class files to redefine classes in JVM |
48+
| **retransform** | Retransform classes, triggers class retransformation and bytecode enhancement |
49+
| **dump** | Dump actual running class bytecode from JVM to specified directory |
50+
51+
### Monitoring and Diagnostic Tools (6)
52+
53+
| Tool | Description |
54+
|------|-------------|
55+
| **monitor** | Monitor invocation of specified methods in real-time |
56+
| **stack** | Output call path of current method, helps analyze method call chains |
57+
| **trace** | Trace internal method call paths, output time cost for each node |
58+
| **tt** | Time tunnel for method execution data, records parameters and return values for each invocation |
59+
| **watch** | Observe method invocations including parameters, return values, and exceptions |
60+
61+
## Quick Start
62+
63+
### 1. Configure MCP Service
64+
65+
Enable MCP service in `arthas.properties` configuration file:
66+
67+
```properties
68+
# MCP (Model Context Protocol) configuration
69+
arthas.mcpEndpoint=/mcp
70+
```
71+
72+
### 2. Start Application
73+
74+
Start Arthas or Java application with Arthas normally. By default, MCP service will be exposed on HTTP port 8563.
75+
76+
Verify MCP service is running:
77+
78+
```bash
79+
curl http://localhost:8563/mcp
80+
```
81+
82+
If MCP protocol information is returned, the service has started successfully.
83+
84+
### 3. Configure AI Client
85+
86+
Configuration examples for mainstream AI clients:
87+
88+
#### Cherry Studio / Cline
89+
90+
Add MCP server configuration in settings:
91+
92+
```json
93+
{
94+
"mcpServers": {
95+
"arthas-mcp": {
96+
"type": "streamableHttp",
97+
"url": "http://localhost:8563/mcp"
98+
}
99+
}
100+
}
101+
```
102+
103+
## Configuration
104+
105+
### Arthas Configuration
106+
107+
| Property | Description | Default |
108+
|----------|-------------|---------|
109+
| `arthas.mcpEndpoint` | MCP service access path | None (requires manual configuration) |
110+
| `arthas.httpPort` | HTTP service port | 8563 |
111+
| `arthas.password` | Authentication password (when authentication enabled) | None |
112+
113+
### Authentication Configuration
114+
115+
When `arthas.password` is configured in the configuration file, MCP Server will automatically enable authentication. In this case, you need to add an authentication header in the AI client configuration, with the Bearer Token set to the configured password value.
116+
117+
Configuration file example (`arthas.properties`):
118+
119+
```properties
120+
arthas.password=your-secure-password
121+
```
122+
123+
AI client configuration example:
124+
125+
```json
126+
{
127+
"mcpServers": {
128+
"arthas-mcp": {
129+
"type": "streamableHttp",
130+
"url": "http://localhost:8563/mcp",
131+
"headers": {
132+
"Authorization": "Bearer your-secure-password"
133+
}
134+
}
135+
}
136+
}
137+
```
138+
139+
::: warning
140+
**Note**: The token in the Authorization header must exactly match the value configured in `arthas.password`.
141+
:::
142+
143+
## Feedback & Contribution
144+
145+
::: tip
146+
Arthas MCP Server is an experimental feature. Feedback and suggestions are welcome!
147+
:::
148+
149+
- **Issue Report**: [GitHub Issues](https://github.com/alibaba/arthas/issues)
150+
- **Feature Request**: [GitHub Discussions](https://github.com/alibaba/arthas/discussions)
151+
- **Contribute**: [Contributing Guide](https://github.com/alibaba/arthas/blob/master/CONTRIBUTING.md)

0 commit comments

Comments
 (0)