java_mat_suspects

Implementation Reference

• src/heap_seance_mcp/server.py:61-63 (registration)

  MCP tool registration for java_mat_suspects via @mcp.tool() decorator, delegating to tools.java_mat_suspects

  @mcp.tool()
  def java_mat_suspects(heap_dump_file: str) -> dict[str, Any]:
      return tools.java_mat_suspects(heap_dump_file=heap_dump_file)

• src/heap_seance_mcp/tools.py:269-341 (handler)

  Core handler implementation: runs Eclipse MAT CLI (ParseHeapDump.sh) with the 'suspects' report, parses output, collects report files, and returns evidence/metrics.

  def java_mat_suspects(heap_dump_file: str) -> dict[str, Any]:
      heap_path = Path(heap_dump_file)
      if not heap_path.exists():
          return error_result(
              f"Heap dump file not found: {heap_dump_file}",
              next_recommended_action="Run java_heap_dump first and pass its artifact path.",
          )
  
      try:
          mat_bin = os.environ.get("MAT_BIN")
          if mat_bin:
              mat_exec = mat_bin
          else:
              mat_exec = require_any_binary(
                  ["ParseHeapDump.sh", "ParseHeapDump.bat", "mat"],
                  "Install Eclipse MAT CLI and set MAT_BIN if binary is not in PATH.",
              )
  
          mat_env: dict[str, str] | None = None
          java_home = os.environ.get("JAVA_HOME")
          if java_home:
              path_sep = ";" if os.name == "nt" else ":"
              java_bin = os.path.join(java_home, "bin")
              mat_env = {
                  "JAVA_HOME": java_home,
                  "PATH": java_bin + path_sep + os.environ.get("PATH", ""),
              }
  
          result = run_command(
              [mat_exec, str(heap_path), "org.eclipse.mat.api:suspects"],
              timeout_s=1200,
              env=mat_env,
          )
  
          if result.returncode != 0:
              raise CommandExecutionError(
                  f"MAT suspects analysis failed with code {result.returncode}. stderr: {result.stderr.strip()[:1000]}"
              )
  
          parsed = parse_mat_suspects_output(result.stdout + "\n" + result.stderr)
      except ToolingMissingError as exc:
          return _missing_tool(str(exc))
      except Exception as exc:  # noqa: BLE001
          return _command_failed(exc)
  
      # MAT writes reports next to the heap dump — scan for them
      report_paths = list(parsed["report_paths"])
      heap_stem = heap_path.stem
      heap_dir = heap_path.parent
      for pattern in (f"{heap_stem}_Leak_Suspects.zip", f"{heap_stem}*Leak*.html"):
          for found in heap_dir.glob(pattern):
              path_str = str(found)
              if path_str not in report_paths:
                  report_paths.append(path_str)
  
      report_path = report_paths[0] if report_paths else None
      confidence = "high" if parsed["suspect_lines"] or report_paths else "medium"
  
      evidence = [f"MAT suspects analysis completed for {heap_path}."]
      evidence.extend(parsed["suspect_lines"][:5])
      if report_paths:
          evidence.append(f"Report(s): {', '.join(report_paths[:3])}")
  
      return ok_result(
          evidence=evidence,
          metrics={
              "suspect_line_count": len(parsed["suspect_lines"]),
              "report_paths": report_paths,
          },
          confidence=confidence,
          next_recommended_action="Correlate MAT dominators with class histogram and allocation profile.",
          raw_artifact_path=report_path,
      )

• src/heap_seance_mcp/workflow.py:27-27 (helper)

  Workflow imports java_mat_suspects from tools module for use in automated analysis pipeline

  java_mat_suspects,

• src/heap_seance_mcp/workflow.py:213-213 (helper)

  Workflow calls java_mat_suspects with the raw heap dump artifact path during automated analysis

  mat_result = java_mat_suspects(heap_result["raw_artifact_path"])

• src/heap_seance_mcp/tools.py:260-265 (helper)

  java_heap_dump tool recommends 'Run java_mat_suspects' as next action, showing the intended workflow linkage

  return ok_result(
      evidence=[f"Heap dump created for PID {pid}: {path}"],
      metrics={"pid": pid, "size_bytes": path.stat().st_size, "live_only": live_only},
      confidence="medium",
      next_recommended_action="Run java_mat_suspects on this heap dump.",
      raw_artifact_path=str(path),