使用说明

javaperf

MCP（模型上下文协议）服务器，用于通过JDK实用程序（jcmd、jfr、jps）分析Java应用程序

使AI助手能够诊断性能、分析线程和检查JFR记录，而无需手动使用CLI。

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

如何连接到克劳德桌面/IDE

将服务器添加到MCP配置中。示例 claude_desktop_config json:

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

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

对于 光标IDE：设置→ 特性→ 模型上下文协议→ 编辑Config，然后在内部添加相同的块 mcpServers。请参阅整合更多选项（本地开发、自定义 JAVA_HOME等等）。

需求

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

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

对于开发者

克隆存储库：

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

安装依赖项：

npm install

构建项目：

npm run build

用法

开发模式

npm run dev

生产模式

npm start

MCP检查员

使用MCP检查员进行调试和测试：

npx @modelcontextprotocol/inspector node dist/index.js

整合

光标IDE

打开光标设置→ 特性→ 模型上下文协议
点击“编辑配置”按钮
添加以下配置之一

选项1：通过npm（推荐）

从npm注册表自动安装：

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

选项2：通过npm链接（开发）

对于具有实时变化的本地开发：

{
  "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”，MCP服务器可能无法继承您的shell JAVA_HOME.添加 env 使用JDK根路径（例如。 /usr/lib/jvm/java-17 或 ~/.sdkman/candidates/java/current).

克劳德桌面版

编辑 ~/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`	Socket I/O摘要来自 `.jfr` (`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` --需要JVM `-XX:NativeMemoryTracking=summary` 或 `detail`.通行证 `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`	停止录制并保存到records/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路径到GC根。通过 `pid`。已保存到录音/heap_dump.hprof。
`heap_info`	堆摘要。通过 `pid`.
`vm_info`	JVM信息：正常运行时间、版本、标志。通过 `pid`.
`trace_method`	为.jfr.Pass中的方法构建调用树 `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`.

工作流示例

列出流程 → list_java_processes
开始录制 → start_profiling 随着 pid 和 duration （例如60）
等候 duration 秒（或让它运行）
检查录音 （可选）→ list_jfr_recordings 得到 recordingId
停止并保存 → stop_profiling 随着 pid 和 recordingId
分析 → 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 具有适当的预设或 .jfc 通过 settingsFile)

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

列出流程 → list_java_processes
寻找成长类 → heap_live_histogram_diff 随着 pid, intervalSeconds: 5
负载下的记录 → start_profiling → wait → stop_profiling
分配概况 → profile_memory 上 new_profile （检查 oldObjectSamplesByClass 对于可疑类别）
GC压力 → gc_efficiency 在同一 .jfr
确认保留 → heap_dump → Eclipse MAT→ GC根路径（不包括弱/软引用）
人工智能根据组合结果构建连贯的泄漏假设（没有专用工具）

远程JVM（stdio MCP）

javaperf使用stdio MCP，并通过本地连接到JVM jps/jcmd.那只管用 在运行MCP进程的操作系统帐户和主机上.

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

运行MCP服务器（IDE连接器、Cursor或Claude Desktop） 在那台机器上，例如SSH远程工作区、代码空间、服务器上的CI运行器签出，或与进程位于同一主机上的shell会话。
不要依靠管道 jcmd 除非您故意在另一台主机上运行MCP，否则可以通过普通SSH从该主机访问；跨主机连接不在此服务器的范围内。

以下列出的要求（同一用户，本地附件） 局限性 仍然适用。

局限性

采样：JFR样本~10ms；快速方法可能不会出现在ExecutionSample中
仅限本地：在启动MCP的机器上运行
权限：必须以与目标JVM相同的用户身份运行才能访问jcmd