java_list_processes

Implementation Reference

• src/heap_seance_mcp/tools.py:60-85 (handler)

  The actual implementation of java_list_processes. It requires the 'jcmd' binary, runs 'jcmd -l', parses the output via parse_jcmd_processes, filters out the jcmd process itself, and returns an ok_result with process info.

  def java_list_processes() -> dict[str, Any]:
      try:
          require_binary("jcmd", "Install OpenJDK 17+ so jcmd is available.")
          output = ensure_success(run_command(["jcmd", "-l"])).stdout
      except Exception as exc:  # noqa: BLE001
          return _command_failed(exc)
  
      all_processes = parse_jcmd_processes(output)
      processes = [
          process
          for process in all_processes
          if "sun.tools.jcmd.JCmd" not in process["main_class"]
      ]
      if not processes:
          processes = all_processes
      evidence = [f"Discovered {len(processes)} JVM process(es) via jcmd -l."]
      if processes:
          sample = ", ".join(str(proc["pid"]) for proc in processes[:5])
          evidence.append(f"Sample PIDs: {sample}")
  
      return ok_result(
          evidence=evidence,
          metrics={"process_count": len(processes), "processes": processes},
          confidence="low",
          next_recommended_action="Choose a target PID and run java_class_histogram + java_gc_snapshot.",
      )

• src/heap_seance_mcp/server.py:27-29 (registration)

  The MCP tool registration using @mcp.tool() decorator in build_server(), which delegates to tools.java_list_processes().

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

• src/heap_seance_mcp/parsers.py:11-28 (helper)

  The parse_jcmd_processes helper function that parses the output of 'jcmd -l' into a list of process dicts with pid, main_class, args, and display fields.

  def parse_jcmd_processes(text: str) -> list[dict[str, Any]]:
      processes: list[dict[str, Any]] = []
      for line in text.splitlines():
          match = PROCESS_LINE.match(line)
          if not match:
              continue
          pid = int(match.group(1))
          main_class = match.group(2)
          args = (match.group(3) or "").strip()
          processes.append(
              {
                  "pid": pid,
                  "main_class": main_class,
                  "args": args,
                  "display": f"{pid} {main_class} {args}".strip(),
              }
          )
      return processes

• src/heap_seance_mcp/tools.py:26-34 (helper)

  The _artifact_dir() helper used by tools for output paths (not directly used by java_list_processes but defined in the same file).

  def _artifact_dir() -> Path:
      import tempfile
  
      default = str(Path(tempfile.gettempdir()) / "heap-seance")
      target = Path(os.environ.get("HEAP_SEANCE_ARTIFACT_DIR", default))
      target.mkdir(parents=True, exist_ok=True)
      return target

• src/heap_seance_mcp/workflow.py:19-28 (registration)

  Import of java_list_processes in workflow.py for use in the _pick_pid function and elsewhere.

  from .tools import (
      java_async_alloc_profile,
      java_class_histogram,
      java_gc_snapshot,
      java_heap_dump,
      java_jfr_start,
      java_jfr_summary,
      java_list_processes,
      java_mat_suspects,
  )