[miguelnieto]

Summary

Adds a headless Model Context Protocol server, so that AI assistants (Claude Code and other MCP clients) can investigate heap dumps. They query with SQL, use MAT's per-object actions, and run analyses that return data rather than prose.

./MemoryAnalyzer -nosplash -application MatCalcitePlugin.mcp
claude mcp add mat-sql -- /path/to/mat/MemoryAnalyzer -nosplash -application MatCalcitePlugin.mcp

Stacked on #122 (SQL editor), which is stacked on #121 (MAT 1.17 / Java 21 / Calcite 1.42). Until those are merged, this PR also shows their commits. #129 (4/4, security updates) builds on this one. Review only 5f72e7d, or see just this PR's changes.

How it works

• The server speaks MCP on stdio, JSON-RPC one message per line, using the MAT install the plugin is in. It is a new Equinox application, MatCalcitePlugin.mcp, in plugin.xml.
• No new dependencies. JSON uses json-smart, which is already bundled.
• Dumps stay open between calls. The first open builds MAT's indexes; later opens reuse them.
• Requests run one at a time on a worker thread, since snapshots aren't shared between threads. Cancellation and ping are handled at once on the reading thread, so they work while a long query runs.
• Every request gets an answer, even when a tool throws, so a client never hangs.
• The code is in com.github.vlsi.mat.calcite.mcp. That package is exported only to the test bundle (x-friends). McpServer handles JSON-RPC without stdio, so the tests drive it directly.

Tools

Area	Tools
Dumps and schema	open_heap_dump, list_heap_dumps, close_heap_dump, list_tables, describe_table
SQL	sql_query (markdown, row limit), explain_sql, sql_reference, export_query (CSV, all rows)
Per object, as on MAT's context menu	object_info, list_references (incoming / outgoing), retained_set, path_to_gc_roots, immediate_dominators
Any other MAT command	mat_query, e.g. find_leaks, top_consumers, dominator_tree
Analyses	heap_overview, histogram, leak_suspects, compare_dumps, collection_contents, duplicate_strings, wasteful_collections
Control	cancel_query

Results show objects as class @ 0xaddress, and the object tools take those addresses, so an assistant can chain calls. For example, it can find the biggest maps with sql_query, then ask path_to_gc_roots why one is alive.

Some of the tools in more detail:

• leak_suspects returns MAT's leak suspects as data rather than report text:
  • the suspect's class loader;
  • the accumulation point, with the path from a GC root to it;
  • for a group, its biggest members;
  • for a thread, the stack frames whose locals hold memory.
• duplicate_strings counts string values by a 64-bit hash, not by keeping each text in memory.
• wasteful_collections counts 4 bytes per unused slot when the dump uses compressed pointers.

Cancellation

• MCP notifications/cancelled, the cancel_query tool, and timeout_seconds (default 300 s; opening a dump has no default limit).
• No Thread.interrupt(). MAT reads its index files through a FileChannel, which an interrupt closes for good, and that breaks the dump until it is reopened. Instead, each call sets a flag (QueryCancellation, from SQL editor: schema browser, Open in SQL Editor, cancel, date functions (2/4) #122) that the heap scan, the analysis loops and MAT's progress listener check.
• A call cancelled while it still waits in the queue never runs.
• A cancelled open_heap_dump deletes the index files it created, matching only MAT's index file names.

Security

The assistant reads heap contents. A heap can hold text written by outsiders, such as request bodies, messages or log lines, possibly written to steer an assistant. The server's instructions tell the assistant to treat heap text as data, never as instructions. Beyond that, the server limits what it can do:

• No general file writes. export_query writes only .csv files inside the export directory: MAT_MCP_EXPORT_DIR, or the dump's directory. It refuses other paths (../ and symlinks included), writes through a temporary file moved atomically, and adds a leading ' to cells and headers that a spreadsheet would run as formulas.
• mat_query refuses MAT commands that read or write files, open other dumps or run reports, judged by each argument's type and its Argument.Advice. Examples: export_hprof, delta_histogram -baseline, create_report. compare_dumps compares dumps that are already open.
• open_heap_dump accepts only regular files.
• SQL reaches only the heap schema: Calcite runs without extra function libraries or DDL, and the plugin's functions only read the heap.
• Runaway work stops.
  • Infinite recursive queries, huge cross joins and pathological histogram regexes (e.g. ^(.+)+\1!) stop at the timeout.
  • A query that exhausts memory returns an error, and the server keeps working.
  • Cells are capped at 200 characters and results at 5,000 rows.

Testing

• ./mvnw verify with JDK 21: 101 tests pass, 1 skipped (@Ignore on main too). McpServerTests covers:

  • the protocol;
  • every tool;
  • cancellation and timeouts, including a cancel that arrives before its call starts, and request-id reuse;
  • the security refusals, and the export rules;
  • cleanup after a failed open.

• Over stdio with Claude Code: investigations on the test dump and on a 1.5 GB dump with 24M objects. Timings on the large dump:

  Tool	Time
  duplicate_strings (4M strings)	13 s
  wasteful_collections	24 s
  heap_overview, leak_suspects	under 1 s

  Two servers can run on one MAT install at the same time.

Notes for reviewers

• Possible MAT bug found along the way. Before indexing app.hprof, MAT deletes old index files matching app + ([A-Za-z0-9]{1,20}\.)?index. That pattern also matches app.2.index, the index of a sibling dump app.2.hprof. The cleanup in this PR uses only MAT's exact index names, so it doesn't make this worse.
• Known limits:
  • duplicate_strings needs about 80 bytes per distinct value, which matters only for dumps with tens of millions of distinct strings;
  • a single regex match inside SQL (SIMILAR TO on a huge string) can't be interrupted;
  • export size is bounded by the timeout, not by a size limit.

🤖 Generated with Claude Code