javaperf

javaperf

通过 JDK 实用工具（jcmd、jfr、jps）分析 Java 应用的 MCP（Model Context Protocol）服务

让 AI 助手无需手动使用命令行，即可诊断性能问题、分析线程并检查 JFR 记录。

📦 安装：npm install -g javaperf，或通过 npx 使用 🌐 npm：https://www.npmjs.com/package/javaperf

如何连接到 Claude Desktop / IDE

将服务添加到 MCP 配置中。claude_desktop_config.json 示例：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "javaperf": {
      "command": "npx",
      "args": ["-y", "javaperf"]
    }
  }
}

对于 Cursor IDE：依次选择 Settings → Features → Model Context Protocol → Edit Config，然后在 mcpServers 中添加相同的配置块。有关更多选项（本地开发、自定义 JAVA_HOME 等），请参阅集成部分。

要求

• Node.js v18+
• JDK 8u262+ 或支持 JFR 的 11+

JDK 工具（jps、jcmd、jfr）会通过 JAVA_HOME 或 which java 自动检测。如果未找到，请将 JAVA_HOME 设置为 JDK 根目录。

快速开始

面向用户（使用 npm 包）

# No installation needed - use directly in Cursor/Claude Desktop
# Just configure it as described in Integration section below

面向开发者

1. 克隆仓库：

git clone https://github.com/theSharque/mcp-jperf.git
cd mcp-jperf

2. 安装依赖：

npm install

3. 构建项目：

npm run build

用法

开发模式

npm run dev

生产模式

npm start

MCP Inspector

使用 MCP Inspector 调试和测试：

npx @modelcontextprotocol/inspector node dist/index.js

集成

Cursor IDE

1. 打开 Cursor Settings → Features → Model Context Protocol
2. 点击“Edit Config”按钮
3. 添加以下配置之一

选项 1：通过 npm（推荐）

自动从 npm 注册表安装：

{
  "mcpServers": {
    "javaperf": {
      "command": "npx",
      "args": ["-y", "javaperf"]
    }
  }
}

选项 2：通过 npm link（开发）

用于支持实时变更的本地开发：

{
  "mcpServers": {
    "javaperf": {
      "command": "javaperf"
    }
  }
}

需要执行：cd /path/to/mcp-jperf && npm link -g

选项 3：直接路径

{
  "mcpServers": {
    "javaperf": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "${workspaceFolder}",
      "env": {
        "JAVA_HOME": "/path/to/your/jdk"
      }
    }
  }
}

如果 list_java_processes 因“jps not found”而失败，MCP 服务可能无法继承 shell 的 JAVA_HOME。请添加上面的 env 块，并填写 JDK 根路径（例如 /usr/lib/jvm/java-17 或 ~/.sdkman/candidates/java/current）。

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "javaperf": {
      "command": "npx",
      "args": ["-y", "javaperf"]
    }
  }
}

Continue.dev

编辑 .continue/config.json：

{
  "mcpServers": {
    "javaperf": {
      "command": "npx",
      "args": ["-y", "javaperf"]
    }
  }
}

工具

工具	描述
list_java_processes	列出正在运行的 Java 进程（pid、mainClass、args）。使用 topN（默认值为 10）限制数量。
start_profiling	启动 JFR。传入 pid、duration（秒）。可选：preset（默认有效值：profile）、settingsFile（.jfc 文件路径，与 preset 互斥）、memorysize、stackdepth（默认值为 128）。
profile_jfr_network	汇总 .jfr 中的 Socket I/O（jdk.SocketRead、jdk.SocketWrite）。可选：filepath（默认值为 new_profile）、topN。
profile_jfr_file_io	汇总文件读写情况（jdk.FileRead、jdk.FileWrite）。可选：filepath、topN。
profile_jfr_locks	监视器争用（JavaMonitorBlocked）和 j.u.c 停放（ThreadPark）。可选：filepath、topN。实时等待情况：analyze_threads structured=true。
profile_jfr_native	原生方法 CPU 热点（jdk.NativeMethodSample）。可选：filepath、topN。
native_memory_summary	jcmd VM.native_memory summary — 需要使用 -XX:NativeMemoryTracking=summary 或 detail 启动的 JVM。传入 pid。
gc_class_stats	在可用时运行 jcmd GC.class_stats（通常为 JDK 21+）。传入 pid。
gc_finalizer_info	jcmd GC.finalizer_info。传入 pid。
compiler_codecache	jcmd Compiler.codecache。传入 pid。
compiler_queue	jcmd Compiler.queue。传入 pid。
list_jfr_recordings	列出某个进程的活动 JFR 录制。使用 stop_profiling 前运行，以获取 recordingId。
stop_profiling	停止录制并保存到 recordings/new_profile.jfr。需要 pid 和 recordingId。
check_deadlock	检查 Java 级别的死锁。返回包含线程、锁和循环的结构化 JSON。
analyze_threads	线程转储（jstack）及死锁摘要。传入 pid，可选 topN（默认值为 10）、structured（JSON 锁等待链）。实时快照；历史锁信息：profile_jfr_locks。
heap_histogram	类直方图（GC.class_histogram）。传入 pid，可选 topN（20）、all（触发完整 GC，可能导致应用暂停）。静态快照；要查看增长情况，请使用 heap_live_histogram_diff。
heap_live_histogram_diff	获取两个间隔为 intervalSeconds（默认值为 5）的直方图。按实例数或字节数增长列出排名靠前的类。内存泄漏工作流的第一步。传入 pid，可选 topN、all、minInstanceDelta。
heap_dump	为 MAT/VisualVM 创建 .hprof 文件。运行 heap_live_histogram_diff 后，使用 MAT Path to GC Roots。传入 pid。保存到 recordings/heap_dump.hprof。
heap_info	简要的堆摘要。传入 pid。
vm_info	JVM 信息：运行时间、版本、标志。传入 pid。
trace_method	根据 .jfr 为某个方法构建调用树。传入 className、methodName。可选：filepath（默认值为 new_profile）、topN。
parse_jfr_summary	将 .jfr 解析为摘要：排名靠前的方法、GC 统计数据、异常。可选：filepath（默认值为 new_profile）、events、topN。
profile_memory	内存分析：按字节数/次数列出排名靠前的分配者、分配栈，以及按类统计的 OldObjectSample。可选：filepath、topN、sortBy（bytes/count）。与 gc_efficiency、heap_live_histogram_diff 配合使用。
gc_efficiency	根据 .jfr 分析 GC 效率：按收集器统计暂停时间与释放字节数。可选：filepath、topN。在 stop_profiling 后运行。
profile_time	CPU 瓶颈分析（自底向上）。可选：filepath（默认值为 new_profile）、topN。
profile_frequency	调用频率分析（叶帧）。可选：filepath（默认值为 new_profile）、topN。

示例工作流

1. 列出进程 → list_java_processes
2. 开始录制 → 使用 pid 和 duration 调用 start_profiling（例如 60）
3. 等待 duration 秒（或让录制继续运行）
4. 检查录制（可选）→ 调用 list_jfr_recordings 获取 recordingId
5. 停止并保存 → 使用 pid 和 recordingId 调用 stop_profiling
6. 分析 → 使用 parse_jfr_summary、profile_memory、gc_efficiency、profile_time、profile_frequency、trace_method、profile_jfr_network、profile_jfr_file_io、profile_jfr_locks 或 profile_jfr_native（录制中必须存在相应事件 — 使用合适的预设调用 start_profiling，或通过 settingsFile 指定 .jfc）

示例工作流：内存泄漏假设

1. 列出进程 → list_java_processes
2. 查找持续增长的类 → 使用 pid 和 intervalSeconds: 5 调用 heap_live_histogram_diff
3. 在负载下录制 → start_profiling → 等待 → stop_profiling
4. 分配分析 → 对 new_profile 使用 profile_memory（检查 oldObjectSamplesByClass 中是否有可疑类）
5. GC 压力 → 对同一个 .jfr 使用 gc_efficiency
6. 确认对象保留情况 → heap_dump → Eclipse MAT → Path to GC Roots（排除弱引用／软引用）
7. AI 根据合并后的结果构建连贯的泄漏假设（没有专用工具）

远程 JVM（stdio MCP）

javaperf 使用 stdio MCP，并通过本地 jps／jcmd 附加到 JVM。这仅适用于运行 MCP 进程的操作系统账户和主机。

要诊断另一台机器上的 JVM：

• 在那台机器上运行 MCP 服务（你的 IDE 连接器、Cursor 或 Claude Desktop），例如使用 SSH 远程工作区、Codespaces、服务器上的 CI runner checkout，或与进程位于同一主机上的 shell 会话。
• 不要依赖从另一台主机通过普通 SSH 管道传递 jcmd，除非你有意在远程机器上运行 MCP；跨主机附加不在此服务的范围内。

Limitations 下列出的要求（同一用户、本地附加）仍然适用。

限制

• 采样：JFR 的采样间隔约为 10ms；执行时间很短的方法可能不会出现在 ExecutionSample 中
• 仅限本地：在启动 MCP 的机器上运行
• 权限：必须以与目标 JVM 相同的用户身份运行，才能访问 jcmd