mcp-mat

mcp-mat

用于 Eclipse MAT 的无头 MCP 服务，通过直接执行 java -jar org.eclipse.equinox.launcher_*.jar 运行。

功能

• mat_healthcheck — 验证 MAT 启动器和 Java 运行时的可用性
• mat_parse_report — 运行预定义的 MAT 报告（泄漏嫌疑、系统概览等）
• mat_oql_query — 执行 OQL 查询并返回内联结果
• mat_run_command — 执行 56 个内置 MAT 分析命令（histogram、dominator_tree、path2gc、thread_overview 等）
• mat_index_status — 检查堆转储是否存在 MAT 索引产物
• mat_oql_spec — 返回 OQL 解析器指南和支持的模式

支持的命令（mat_run_command）

支配树分析

dominator_tree、show_dominator_tree、immediate_dominators、big_drops_in_dominator_tree

GC 根路径

path2gc、merge_shortest_paths、gc_roots

直方图与对象列表

histogram、delta_histogram*、list_objects、group_by_value、duplicate_classes

泄漏检测

leakhunter、leakhunter2、find_leaks、find_leaks2、reference_leak

线程分析

thread_overview、thread_details、thread_stack

集合分析

collection_fill_ratio、collections_grouped_by_size、array_fill_ratio、arrays_grouped_by_size、hash_entries、map_collision_ratio、extract_list_values、hash_set_values、primitive_arrays_with_a_constant_value

引用分析

references_statistics、weak_references_statistics、soft_references_statistics、phantom_references_statistics、finalizer_references_statistics

Finalizer 分析

finalizer_overview、finalizer_thread、finalizer_queue、finalizer_in_processing、finalizer_thread_locals

保留集

show_retained_set、customized_retained_set

组件与最大占用者

component_report、component_report_top、top_consumers、top_consumers_html、pie_biggest_objects

字符串与内存浪费

find_strings、waste_in_char_arrays

堆信息与杂项

heap_dump_overview、unreachable_objects、system_properties、class_references、comparison_report*

Eclipse/OSGi 专用

bundle_registry、leaking_bundles

导出

export_hprof

* 需要 baseline 堆转储（第二个 .hprof 文件）。

OQL 模式说明

• 本服务会规范化客户端 OQL 输入，并将其包装以供 MAT parse-app 命令模式使用。
• 你可以带或不带外层引号发送 OQL。
• 对于类排名和最大占用者，优先使用 mat_parse_report 搭配 org.eclipse.mat.api:overview，并解析 Class_Histogram*.txt。
• 对于对象检查，使用简单的字段级 OQL 模式（INSTANCEOF、OBJECTS 0x...）。

环境

所有环境变量均为可选：

• MAT_HOME
• MAT_LAUNCHER
• JAVA_PATH（默认 java）
• MAT_XMX_MB（默认 4096）
• MAT_TIMEOUT_SEC（默认 1800）
• MAT_CONFIG_DIR（默认 /tmp/mat-config）
• MAT_DATA_DIR（默认 /tmp/mat-workspace）
• MAT_DEBUG（默认 false）
• MAT_DEBUG_LOG_DIR（默认 /tmp/mcp-mat-logs）
• MAT_PRIVACY_MODE（默认 false）
• MAT_OQL_MAX_BYTES（默认 16384）
• MAT_RESULT_PREVIEW_LINES（默认 20）
• MAT_STDIO_TAIL_CHARS（默认 4000）

运行

npm install
npm run build
MAT_HOME=/path/to/mat node dist/src/server.js

测试

npm test

通过 npx 安装

无需构建步骤。直接从 npm 安装：

Claude Code

添加到 ~/.claude/settings.json 或项目 .claude/settings.json：

{
  "mcpServers": {
    "mat": {
      "command": "npx",
      "args": ["-y", "mcp-mat"],
      "env": {
        "MAT_HOME": "/Applications/MemoryAnalyzer.app/Contents/Eclipse"
      }
    }
  }
}

Codex

codex mcp add \
  --env MAT_HOME=/Applications/MemoryAnalyzer.app/Contents/Eclipse \
  mat \
  npx -y mcp-mat

在 Claude Code 中安装（从源码）

将 MCP 服务添加到 Claude Code 设置（~/.claude/settings.json 或项目 .claude/settings.json）：

{
  "mcpServers": {
    "mat": {
      "command": "node",
      "args": ["/path/to/mcp-mat/dist/src/server.js"],
      "env": {
        "MAT_HOME": "/Applications/MemoryAnalyzer.app/Contents/Eclipse"
      }
    }
  }
}

在 Codex 中安装（从源码）

先构建：

cd /path/to/mcp-mat
npm install
npm run build

将 MCP 服务添加到 Codex：

codex mcp add \
  --env MAT_HOME=/Applications/MemoryAnalyzer.app/Contents/Eclipse \
  mat \
  node /path/to/mcp-mat/dist/src/server.js

验证：

codex mcp list
codex mcp get mat --json

如果需要更新条目：

codex mcp remove mat
# then run codex mcp add ... again

等效的 ~/.codex/config.toml 条目：

[mcp_servers.mat]
command = "node"
args = ["/path/to/mcp-mat/dist/src/server.js"]

[mcp_servers.mat.env]
MAT_HOME = "/Applications/MemoryAnalyzer.app/Contents/Eclipse"