System Information MCP Server

Instructions

Implementation Reference

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

  MCP tool handler for get_process_list_tool, decorated with @app.tool() which registers the tool and defines input schema via type hints and docstring.

  @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:259-347 (helper)

  Core implementation logic for retrieving, filtering, sorting, and formatting the process list using psutil.

  @cache_result("process_list", ttl=2)
  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