Java Diag

Java Diag

面向 AI Agent 的 Java 线上排查 MCP

探针在业务机只读诊断；可选 Gateway 做集群路由。凡支持 MCP 的 AI Agent 均可接入。MIT 开源，Release 解压即用。

Java Diag is an open-source MCP server for read-only Java production diagnostics (probe + optional gateway). Open-source package/repo remains java-diag.

下载 Release GitHub 阅读文档

为何需要

线上 Java 卡住时，不必反复 SSH 上去敲 jcmd。把只读诊断交给 Agent：线程栈、GC、日志白名单，一次对话完成定位。

怎么工作

诊断在探针本机执行；Gateway 只做注册发现与 MCP 代理，自己不跑 jcmd、不读业务日志。

java-diag-probe

部署在业务机：进程发现、白名单日志、jcmd 等本机工具。

java-diag-gateway

可选集群入口：心跳注册表，按 target 把工具调用转到探针。

单机直连

Agent → http://host:8765/mcp → Probe

集群路由

Agent → Gateway :8787/mcp → 选中的 Probe

Java Diag Gateway Admin：MCP 配置与复制入口
Gateway Admin：查看探针并复制 MCP 配置

能力一览

通过 MCP 调用，分组如下（完整列表见仓库 README）。

Meta

  • diag.ping — 连通性
  • diag.list_processes — 进程列表
  • diag.resolve_java_pid — 解析 PID

Logs

  • diag.log_paths — 白名单路径
  • diag.tail_log — 尾部日志
  • diag.grep_log — 检索日志
  • diag.cluster_errors — 错误聚合

JVM

  • diag.thread_dump — 线程栈
  • diag.jstat / diag.gc_histo — GC
  • diag.heap_dump — 堆转储
  • diag.cpu_sample — CPU 采样

Quick Start（单机）

首轮推荐只启探针。需要 JDK 17+。细节与集群模式见 GitHub README。

  1. 下载 最新 Release 并解压（目录同仓库 deploy/）。
  2. 编辑 java-diag-probe.properties，设置 auth.token（必改）。
  3. 启动：cd java-diag-probe && ./start.sh start
  4. 在支持 MCP 的 Agent 中配置：URL http://127.0.0.1:8765/mcp，Bearer 填同一 token；验证 diag.ping。 
{
  "mcpServers": {
    "java-diag": {
      "url": "http://127.0.0.1:8765/mcp",
      "headers": { "Authorization": "Bearer YOUR_AUTH_TOKEN" }
    }
  }
}

多机集群：先 Gateway（8787）后 Probe，Agent 只连 Gateway /mcp。见 README 章节 B。

安全与开源

SECURITY.md

FAQ

Java Diag 是什么？

开源 MCP 服务，用于只读 Java 线上排查。组件： java-diag-probe（本机诊断）与可选 java-diag-gateway（集群路由）。开源仓库/包名仍为 java-diag。

和直接敲 jcmd 有什么区别？

本机仍用 jcmd / 日志白名单；通过 MCP 让任意兼容的 AI Agent 远程调用，减少反复登录机器。

应该用单机还是集群？

单机：探针 :8765/mcp。集群：Gateway :8787/mcp，探针注册后由网关选节点。

如何安装？

下载 GitHub Release 部署包 → 改 token → start 脚本 → Agent 配 MCP。需 JDK 17+。

是否安全、只读？

设计为只读可审计；强制 token。不要把诊断端口直接暴露到公网。