企业官网建设流程全解析

Arthas MCP Server 实战指南：用 AI 工具调用驱动 Java 诊断

【免费下载链接】arthasAlibaba Java Diagnostic Tool Arthas/Alibaba Java诊断利器Arthas项目地址: https://gitcode.com/gh_mirrors/ar/arthas

Arthas MCP Server 是 Alibaba Java 诊断利器 Arthas 的实验性模块，它实现了基于 MCP（Model Context Protocol，版本 2025-03-26）协议的服务端，通过 HTTP/Netty 提供统一的 JSON-RPC 2.0 接口，让 AI 助手（如 Cherry Studio、Cline 等）能够以"工具调用"（tool calling）的方式直接执行 Arthas 诊断命令。读完本文，你将掌握 arthas-mcp-server 的架构原理、26 个诊断工具的完整清单、配置启动步骤，以及如何在 AI 客户端中接入并完成认证。

模块定位与架构概览

什么是 Arthas MCP Server

MCP（Model Context Protocol）是由 Anthropic 提出的标准化协议，用于连接 AI 助手与外部工具和数据源。arthas-mcp-server是 Arthas），它把 Arthas 的终端命令封装成 MCP 协议下的"工具"（Tool），AI 客户端通过标准的 JSON-RPC 2.0 请求即可触发诊断动作，从而实现"自然语言下指令 → AI 调用工具 → 返回诊断结果"的闭环。

从模块依赖看，arthas-mcp-server仅依赖arthas-model与 Netty（netty-buffer、netty-handler、netty-transport、netty-codec-http）、fastjson2、Jackson 2.18.1 与 slf4j，Java 编译级别为 8，说明它是一套轻量、独立的协议服务端实现，不耦合 Arthas 核心的 shell 层。

服务端分层与启动链路

MCP 服务端代码位于 arthas-mcp-server/src/main/java/com/taobao/arthas/mcp/server，主要分为四层：

• protocol/spec：MCP 协议规范层，定义了McpSchema、McpSession、McpTransport、McpServerTransportProvider、事件存储EventStore等抽象与规范类，对应 MCP 协议 2025-03-26 版本；
• protocol/server：Netty 服务端实现，包括McpNettyServer、McpStatelessNettyServer、HTTP 请求处理器（McpHttpRequestHandler、McpStreamableHttpRequestHandler、McpStatelessHttpRequestHandler）、传输层（NettyStreamableServerTransportProvider、NettyStatelessServerTransport）以及初始化握手McpInitRequestHandler；
• tool：工具抽象层，定义了Tool/ToolParam注解、ToolDefinition工具定义、ToolCallback回调以及基于 JSON Schema 的入参校验生成器JsonSchemaGenerator；
• task：任务管理扩展层，提供TaskManager、TaskStore、TaskMessageQueue以及InMemoryTaskStore等实现，支持长时间运行工具的异步任务化。

在 Arthas 核心模块中，ArthasMcpBootstrap（core/src/main/java/com/taobao/arthas/core/mcp/ArthasMcpBootstrap.java）负责接收配置并创建ArthasMcpServer，后者（core/src/main/java/com/taobao/arthas/core/mcp/ArthasMcpServer.java）完成实际的启动工作：

1. 注册 Arthas 特定的 JSON 过滤器（McpObjectVOFilter）；
2. 通过McpServerProperties.Builder构建服务端配置；
3. 扫描com.taobao.arthas.core.mcp.tool.function基础包下的全部工具并分类；
4. 按协议模式启动 Streamable 或 Stateless 服务器；
5. 在启动日志中打印MCP Endpoint与Transport mode。

其中命令的真正执行者是一个关键的CommandExecutor接口（arthas-mcp-server/src/main/java/com/taobao/arthas/mcp/server/CommandExecutor.java），它抽象了 Arthas 命令的同步/异步执行、session 生命周期管理、结果拉取、任务中断与认证注入等能力，是 MCP 工具层与 Arthas 核心命令引擎之间的桥梁。

两种传输协议模式

从McpServerProperties.ServerProtocol枚举（McpServerProperties.java）可以看出，服务端支持两种模式：

在源码中，协议值通过ServerProtocol.valueOf(protocol.toUpperCase())解析，非法值会被记录警告并回退到默认的STREAMABLE；Streamable 模式还会额外初始化ArthasCommandSessionManager会话管理器与固定大小的任务线程池（线程名为mcp-task-*，使用SynchronousQueue无缓冲队列 +AbortPolicy兜底拒绝策略），避免 I/O 密集任务污染公共 ForkJoinPool。

支持的 26 个诊断工具清单

Arthas MCP Server 将 Arthas 命令封装为 26 个工具（对应core模块 core/src/main/java/com/taobao/arthas/core/mcp/tool/function 下按basic1000、jvm300、klass100、monitor200等包分类的*Tool.java实现），按功能分为三大类：

JVM 相关工具（13 个）

Class/ClassLoader 相关工具（8 个）

监控诊断工具（5 个）

这些工具在服务启动时通过DefaultToolCallbackProvider扫描注册，并依据tool.taskSupport属性被分类为普通工具（FORBIDDEN）、可选任务工具（OPTIONAL）与必需任务工具（REQUIRED）。其中，watch、trace、monitor 等长时间运行工具在 Streamable 模式下可注册为任务感知工具（task-aware tool），配合内存版InMemoryTaskStore（任务 TTL 默认 30 分钟）与InMemoryTaskMessageQueue实现异步任务的创建、查询与取消（对应tasks/list、tasks/cancel、tools/call增强等能力），从源码结构看这是为长耗时诊断命令准备的异步化方案。

快速开始：从配置到 AI 客户端接入

1. 配置 MCP 服务

首先在arthas.properties中配置 MCP 服务的访问路径。该文件位于 core/src/main/java/arthas.properties，默认配置为：

# MCP (Model Context Protocol) configuration arthas.mcpEndpoint=/mcp

配置项由Configure类（core/src/main/java/com/taobao/arthas/core/config/Configure.java）承载，ArthasBootstrap在启动时会检测该配置并触发 MCP 服务初始化。arthas.properties还支持以下 MCP 相关配置项：

2. 启动应用

正常启动 Arthas 或带有 Arthas 的 Java 应用后，MCP 服务会在 HTTP 端口 8563 上对外暴露。可以先用 curl 验证服务是否就绪：

curl http://localhost:8563/mcp

如果返回 MCP 协议相关信息，说明服务已成功启动。服务端启动日志中也会打印MCP Endpoint与Transport mode两行信息，便于确认实际生效的端点与协议。

3. 在 AI 客户端中配置 MCP 服务器

在 Cherry Studio、Cline 等 AI 客户端的设置中添加 MCP 服务器：

{ "mcpServers": { "arthas-mcp": { "type": "streamableHttp", "url": "http://localhost:8563/mcp" } } }

配置完成后，AI 即可通过工具调用方式执行 Arthas 命令，例如"看一下这个 JVM 的线程状态""追踪 demo.MathGame 的 run 方法"等，AI 会选择合适的工具（thread、trace等）完成诊断。

开启认证：Bearer Token 鉴权

当在arthas.properties中设置了arthas.password时，MCP Server 会自动开启鉴权功能，AI 客户端需要在请求头中携带 Bearer Token，token 值就是配置的密码本身。

配置文件示例：

arthas.password=your-secure-password

AI 客户端配置示例：

{ "mcpServers": { "arthas-mcp-streamable-server": { "type": "streamableHttp", "url": "http://localhost:8563/mcp", "headers": { "Authorization": "Bearer your-secure-password" } } } }

注意：Authorizationheader 中的 token 必须与arthas.password配置的值完全一致，否则鉴权失败。

从源码看，认证支持由 core/src/main/java/com/taobao/arthas/core/mcp/util/McpAuthExtractor.java 与协议层的McpAuthExtractor（arthas-mcp-server/src/main/java/com/taobao/arthas/mcp/util/McpAuthExtractor.java）实现：认证主体（subject）会被挂载到 Netty Channel 的AttributeKey（arthas.auth.subject）上，供后续命令执行时注入 session；同时支持通过X-User-Id请求头携带用户 ID，用于命令执行的统计上报。BasicHttpAuthenticatorHandler（core/src/main/java/com/taobao/arthas/core/shell/term/impl/http/BasicHttpAuthenticatorHandler.java）也会对 MCP 端点做统一认证校验。

进阶：协议模式与配置要点

显式指定协议模式

默认情况下服务以STREAMABLE模式启动，如需切换为无状态的STATELESS模式，可在arthas.properties中显式配置：

arthas.mcpEndpoint=/mcp # 可选，默认为 STREAMABLE arthas.mcpProtocol=STREAMABLE

两种模式的取舍：Streamable 适合 watch、trace、monitor 等需要流式输出和会话状态的交互式诊断场景；Stateless 模式每个请求相互独立，适合一次性查询，且该模式不注册任务感知工具（源码中enableTasks = false），所有工具一律以普通工具方式注册。

服务端默认参数

从McpServerProperties.Builder（McpServerProperties.java）的默认值可以看出服务端的关键默认参数：

总结

Arthas MCP Server 打通了"AI 大模型 ↔ MCP 协议 ↔ Arthas 命令引擎"的链路，让 Java 应用的日常诊断从"人肉敲命令"演进为"自然语言对话式诊断"。它基于 Netty 与 JSON-RPC 2.0 实现了标准 MCP 服务端（支持 Streamable HTTP 与 Stateless 两种传输模式），内置 26 个覆盖 JVM 监控、Class/ClassLoader 诊断与方法级追踪的工具，并提供 Bearer Token 认证与异步任务扩展能力。如需深入了解，可继续阅读：

• 模块源码：arthas-mcp-server/src/main/java/com/taobao/arthas/mcp/server
• 核心装配与工具扫描：core/src/main/java/com/taobao/arthas/core/mcp
• 官方文档：site/docs/doc/mcp-server.md 与英文版 site/docs/en/doc/mcp-server.md

提示：Arthas MCP Server 目前属于实验性功能，接口与配置可能在后续版本中调整，请以当前仓库实际内容为准。

【免费下载链接】arthasAlibaba Java Diagnostic Tool Arthas/Alibaba Java诊断利器Arthas项目地址: https://gitcode.com/gh_mirrors/ar/arthas