# arthas-mcp-server

**Repository Path**: hatricks/arthas-mcp-server

## Basic Information

- **Project Name**: arthas-mcp-server
- **Description**: Arthas MCP Server - Java应用性能诊断工具的MCP服务端
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-09
- **Last Updated**: 2026-07-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Arthas MCP Server

[![English](https://img.shields.io/badge/lang-English-red.svg)](README.md) [![中文](https://img.shields.io/badge/lang-中文-blue.svg)](README.zh-CN.md) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

**多实例 MCP Bridge** — 通过 [Alibaba Arthas](https://arthas.aliyun.com/) 对 Java 应用进行运行时诊断，专为 LLM 集成设计。

## 项目概述

Arthas MCP Server 将 AI 助手（Cursor、Windsurf、Claude Code 等）与运行中的 Java 应用连接起来，基于 [Model Context Protocol](https://modelcontextprotocol.io) 协议。它动态发现 Arthas 工具、管理多实例路由，并提供高级诊断工作流 —— 全部通过 stdio 通信。

![示例](./usecase/case1.jpg)

## 核心特性

- **40+ 诊断工具** — 镜像所有 Arthas 命令（dashboard、thread、memory、trace、watch、ognl、profiler、heapdump 等）+ 自定义编排
- **多实例管理** — 路由命令到任意 Arthas 实例；热加载配置无需重启
- **智能韧性** — Session 自愈、智能重试（区分超时 vs Session 失效）、HTTP API 回退突破 30s 限制
- **JDBC 安全** — 自动注入 `setQueryTimeout` + `setNetworkTimeout`，防止慢 SQL 阻塞 Arthas
- **热部署** — OBS 加速上传 `.class` 文件（5-10 倍提速），OGNL 分块传输兜底
- **OBS 文件传输** — 通过预签名 URL 上传/下载诊断产物（heapdump、profiler 输出等）
- **MCP Resources** — 暴露实例状态、工具目录、配置信息供 LLM 被动查询
- **MCP Prompt** — `diagnose_oom`（K8s cgroup / Node OOM 编排；慢接口与泄漏请直接用 trace/watch 或 memory+vmtool）

## 快速开始

### 安装

```bash
uv sync
```

### 启动

```bash
python main.py
```

## MCP 能力

### 工具（~40 个）

| 分类 | 工具 |
|------|------|
| **实例管理** | `list_instances` |
| **诊断编排** | `full_diagnosis`、`hotswap` |
| **OBS 文件操作** | `obs_upload`、`obs_download`、`obs_list`、`obs_delete`、`obs_presigned_upload`、`obs_presigned_download`、`obs_bridge_status` |
| **Arthas 命令** | `dashboard`、`thread`、`memory`、`jvm`、`sc`、`sm`、`jad`、`dump`、`watch`、`trace`、`monitor`、`stack`、`tt`、`ognl`、`vmtool`、`getstatic`、`profiler`、`heapdump`、`classloader`、`mc`、`retransform`、`mbean`、`perfcounter`、`sysenv`、`sysprop`、`vmoption`、`options`、`stop`、`viewfile`（`redefine` 已排除，请用 `retransform` / `hotswap`） |

### Resources

| URI | 说明 |
|-----|------|
| `arthas://instances` | 所有实例及健康状态 |
| `arthas://tools` | 完整工具目录及参数说明 |
| `arthas://config` | Bridge 配置和运行时状态 |

### Prompts

| Prompt | 使用场景 |
|--------|---------|
| `diagnose_oom` | OOMKilled / 内存持续增长（cgroup v1/v2、Node OOM 研判） |

## 配置

### 推荐方式：配置文件 + [devops-toolkit](https://gitee.com/hatricks/devops-toolkit)

**实例信息通过 `.cache/instances.json` 配置文件加载，支持运行时热加载**——这是当前推荐的主路径，特别适合 K8s 环境下多 Pod 动态增减的场景。

**优点**：
- 实例增减不需重启 MCP server（变更 `instances.json` 后下次 tool call 自动热加载）
- MCP 客户端（Windsurf / Cursor）配置固定不变，避免 Windsurf 频繁重启子进程
- devops-toolkit 提供可视化 UI：K8s 隧道 / 直连、多环境多 Pod 管理、一键写入 mcp_config.json

#### 步骤 1：一次性添加到 Cursor / Windsurf / Claude Code

**macOS**: `~/.cursor/mcp.json` 或 `~/.codeium/windsurf/mcp_config.json`
**Windows**: `C:\Users\{用户名}\.cursor\mcp.json`

```json
{
  "mcpServers": {
    "arthas-bridge": {
      "command": "uv",
      "args": ["--directory", "/path/to/arthas-mcp-server", "run", "--frozen", "python", "main.py"]
    }
  }
}
```

> 注意：**不需要 `env` 字段**。实例信息从配置文件读取，避免实例变更触发客户端重启 MCP server。

#### 步骤 2：创建 `.cache/instances.json`

```json
[
  { "name": "order-service", "url": "http://10.0.1.10:8563" },
  { "name": "user-service", "url": "http://10.0.1.11:8563" }
]
```

修改后无需重启，下次调用任意实例工具时 Bridge 会自动重加载。推荐使用 [devops-toolkit](https://gitee.com/hatricks/devops-toolkit) 自动维护该文件。

> **实例列表仅支持配置文件**，不再通过 `ARTHAS_INSTANCES` / `ARTHAS_URL` 或默认 localhost 注入，避免 MCP 配置与实例列表双轨维护、以及静默连错端口。

### 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `ARTHAS_MAX_CONCURRENT` | `5` | 每实例最大并发调用数 |

实例列表**仅**读写 `{arthas-mcp-server 根}/.cache/instances.json`（与 devops-toolkit、`mcp.json` 中 `uv --directory` 指向的目录一致）。不支持 `ARTHAS_CONFIG_FILE` 等自定义路径。

### 启动 Arthas

Arthas 可通过 **attach 模式** 或 **agent 模式** 启动，两种方式最终都会在端口（默认 8563）上监听 HTTP 请求，本 Bridge 通过该端点通信。

## 项目结构

```
arthas-mcp-server/
├── main.py                    # 入口：配置解析、日志、异步初始化
├── src/
│   ├── bridge.py              # 核心：工具/资源/提示词注册、自定义诊断剧本
│   ├── instance_manager.py    # 多实例管理、健康检查、切换
│   ├── client_pool.py         # 智能重试、JDBC 安全、HTTP API 回退
│   ├── raw_mcp_client.py      # 底层 HTTP MCP 客户端（JSON-RPC over SSE）
│   ├── tool_mirror.py         # 动态工具转发（远端 → 本地 FastMCP）
│   ├── tool_cache.py          # Schema 缓存、增强、JDBC 检测
│   ├── obs_bridge_client.py   # OBS Bridge HTTP 客户端
│   ├── instance_config.py     # 配置文件管理、热加载
│   └── default_tools_schema.json  # 离线兜底工具 Schema
├── tests/                     # 13 个测试文件
├── pyproject.toml
└── README.md
```

## 开发

```bash
uv sync --extra dev
```

## 构建与发布（PyInstaller）

终端用户通过 [devops-toolkit](https://gitee.com/hatricks/devops-toolkit) 从 **华为云 OBS**（应用内当前 OBS 环境）下载安装。维护者请参阅 **[docs/BUILD_AND_RELEASE.md](docs/BUILD_AND_RELEASE.md)**（构建、`publish_obs` 上传 OBS、冒烟测试）。

## 许可证

[MIT](LICENSE)