get_process_list_tool

Instructions

Implementation Reference

• src/system_info_mcp/server.py:68-79 (handler)

  Tool handler (MCP registration) for get_process_list_tool. Uses @app.tool() decorator to register the tool with FastMCP, accepts limit, sort_by, and filter_name parameters, and delegates to get_process_list().

  @app.tool()
  def get_process_list_tool(
      limit: int = 50, sort_by: str = "cpu", filter_name: Optional[str] = None
  ) -> Dict[str, Any]:
      """Retrieve list of running processes.
  
      Args:
          limit: Maximum number of processes to return (default: 50)
          sort_by: Sort criteria - cpu, memory, name, pid (default: cpu)
          filter_name: Filter processes by name pattern
      """
      return get_process_list(limit=limit, sort_by=sort_by, filter_name=filter_name)

• src/system_info_mcp/tools.py:260-347 (helper)

  Core implementation of get_process_list(). Uses psutil to iterate over processes, supports filtering by name, sorting by cpu/memory/name/pid, and limiting results. Returns process details like pid, name, username, status, CPU/memory usage, memory RSS, creation time, and command line.

  def get_process_list(
      limit: int = 50, sort_by: str = "cpu", filter_name: Optional[str] = None
  ) -> Dict[str, Any]:
      """Retrieve list of running processes."""
      try:
          # Validate parameters
          if limit <= 0:
              raise ValueError("Limit must be a positive number")
  
          limit = min(limit, config.max_processes)
  
          valid_sort_keys = ["cpu", "memory", "name", "pid"]
          if sort_by not in valid_sort_keys:
              raise ValueError(f"sort_by must be one of: {valid_sort_keys}")
  
          processes = []
  
          # Get all processes
          for proc in psutil.process_iter(
              [
                  "pid",
                  "name",
                  "username",
                  "status",
                  "cpu_percent",
                  "memory_percent",
                  "memory_info",
                  "create_time",
                  "cmdline",
              ]
          ):
              try:
                  proc_info = proc.info
  
                  # Filter by name if specified
                  if filter_name and filter_name.lower() not in proc_info["name"].lower():
                      continue
  
                  # Get memory RSS
                  memory_rss = 0
                  if proc_info.get("memory_info"):
                      memory_rss = proc_info["memory_info"].rss
  
                  # Filter and format command line
                  cmdline = filter_sensitive_cmdline(proc_info.get("cmdline") or [])
  
                  process_data = {
                      "pid": proc_info["pid"],
                      "name": proc_info["name"] or "Unknown",
                      "username": proc_info.get("username", "Unknown"),
                      "status": proc_info.get("status", "unknown"),
                      "cpu_percent": round(
                          safe_float(proc_info.get("cpu_percent", 0)), 1
                      ),
                      "memory_percent": round(
                          safe_float(proc_info.get("memory_percent", 0)), 1
                      ),
                      "memory_rss": memory_rss,
                      "memory_rss_mb": bytes_to_mb(memory_rss),
                      "create_time": timestamp_to_iso(proc_info.get("create_time", 0)),
                      "cmdline": cmdline,
                  }
  
                  processes.append(process_data)
  
              except (psutil.NoSuchProcess, psutil.AccessDenied, psutil.ZombieProcess):
                  # Process may have terminated or we don't have permission
                  continue
  
          # Sort processes
          reverse_sort = True  # Most metrics should be sorted in descending order
          if sort_by == "cpu":
              processes.sort(key=lambda p: p["cpu_percent"], reverse=reverse_sort)
          elif sort_by == "memory":
              processes.sort(key=lambda p: p["memory_percent"], reverse=reverse_sort)
          elif sort_by == "name":
              processes.sort(key=lambda p: p["name"].lower(), reverse=False)
          elif sort_by == "pid":
              processes.sort(key=lambda p: p["pid"], reverse=False)
  
          # Apply limit
          limited_processes = processes[:limit]
  
          return {"processes": limited_processes, "total_processes": len(processes)}
  
      except Exception as e:
          logger.error(f"Error getting process list: {e}")
          raise

• src/system_info_mcp/config.py:10-27 (schema)

  ServerConfig dataclass defines max_processes (default 100, configurable via SYSINFO_MAX_PROCESSES env var) which acts as a hard limit on the number of processes returned by get_process_list.

  """Server configuration with environment variable support."""
  
  name: str = "system-info-server"
  version: str = "1.0.0"
  description: str = "System information MCP server"
  cache_ttl: int = int(os.getenv("SYSINFO_CACHE_TTL", "5"))
  max_processes: int = int(os.getenv("SYSINFO_MAX_PROCESSES", "100"))
  enable_temperatures: bool = (
      os.getenv("SYSINFO_ENABLE_TEMP", "true").lower() == "true"
  )
  log_level: str = os.getenv("SYSINFO_LOG_LEVEL", "INFO")
  
  # Transport configuration
  transport: Literal["stdio", "sse", "streamable-http"] = os.getenv("SYSINFO_TRANSPORT", "stdio")  # type: ignore
  port: int = int(os.getenv("SYSINFO_PORT", "8001"))
  host: str = os.getenv("SYSINFO_HOST", "localhost")
  mount_path: str = os.getenv("SYSINFO_MOUNT_PATH", "/mcp")

• src/system_info_mcp/server.py:9-15 (registration)

  Import of get_process_list from .tools module, which is the underlying function used by the registered tool handler.

  from .tools import (
      get_cpu_info,
      get_memory_info,
      get_disk_info,
      get_network_info,
      get_process_list,
      get_system_uptime,