feat: add proactive monitoring, resources, and prompts

Transform SysMetrics MCP from a pull-based query tool into a proactive
monitoring agent.

- Add internal/monitor package: delta-based sampler (CPU/net/disk rates),
  snapshot history ring, and threshold evaluation producing alerts.
- Add 7 monitoring tools: start_monitoring, stop_monitoring,
  get_monitoring_status, get_metrics_history, get_alerts,
  get_network_throughput, get_disk_throughput.
- Add subscribable sys://metrics/* MCP resources plus a processes resource
  template.
- Add analyze_system_health and diagnose_performance_issue MCP prompts.
- Enable MCP sampling capability for proactive alert push.
- Refactor get_system_health to share threshold logic with the monitor.
- Add --monitor-interval CLI flag and unit tests.

Author: raythurman2386

README.md

@@ -4,7 +4,11 @@ A lightweight MCP (Model Context Protocol) server that exposes Linux system metr
 
 ## Features
 
-- **12 MCP Tools**: System info, CPU, memory, disk, disk I/O, network, network connections, processes, thermal, Docker, system health, and service status
+- **19 MCP Tools**: System info, CPU, memory, disk, disk I/O, network, network connections, processes, thermal, Docker, system health, service status, plus monitoring and alerting tools
+- **MCP Resources**: Subscribable `sys://metrics/*` resources for proactive state reads
+- **MCP Prompts**: `analyze_system_health` and `diagnose_performance_issue` prompt templates
+- **Streaming Metrics**: Delta-based throughput sampling (network bytes/s, disk IOPS/bytes/s) and history
+- **Threshold Alerting**: Background monitoring that generates warning/critical alerts on resource saturation
 - **Configurable**: CLI arguments for temperature units, process limits, mount points, and interfaces
 - **Cross-Platform**: Works on any Linux system (enhanced metrics for Raspberry Pi)
 - **AI-Ready**: Designed for integration with Claude Desktop, Cursor, or any MCP client
@@ -74,6 +78,7 @@ Add to your agent's configuration file:
 | `--mount-points` | `""` | Comma-separated mount points (empty = all) |
 | `--interfaces` | `""` | Comma-separated interfaces (empty = all, excludes `lo`) |
 | `--enable-gpu` | `true` | Attempt to read GPU metrics (Raspberry Pi only) |
+| `--monitor-interval` | `5` | Default sampling interval in seconds for monitoring (1-60) |
 
 ## MCP Tools
 
@@ -143,6 +148,54 @@ Returns systemd service health information via `systemctl show`.
 **Required Arguments:**
 - `services`: Comma-separated list of service names to check
 
+### `start_monitoring`
+Starts background sampling of system metrics. Once running, the server retains a history buffer and evaluates resource thresholds to generate alerts.
+
+**Optional Arguments:**
+- `interval`: Sampling interval in seconds (defaults to `--monitor-interval`)
+
+### `stop_monitoring`
+Stops background sampling.
+
+### `get_monitoring_status`
+Returns whether monitoring is running, the aggregate health status, and the latest snapshot.
+
+### `get_metrics_history`
+Returns recent metric snapshots captured by the monitor.
+
+**Optional Arguments:**
+- `seconds`: Only return snapshots captured within the last N seconds
+
+### `get_alerts`
+Returns threshold alerts generated since the last read (read-then-drain).
+
+**Optional Arguments:**
+- `severity`: Filter by `warning` or `critical`
+
+### `get_network_throughput`
+Returns per-interface network throughput rates (bytes/sec) since the last sample.
+
+### `get_disk_throughput`
+Returns per-device disk I/O throughput rates (bytes/sec and IOPS) since the last sample.
+
+## MCP Resources
+
+The server exposes subscribable resources under the `sys://metrics/*` namespace so clients can read current state without issuing a tool call:
+
+| URI | Description |
+|-----|-------------|
+| `sys://metrics/overview` | Aggregated health dashboard |
+| `sys://metrics/cpu` | CPU model, cores, temperature |
+| `sys://metrics/memory` | RAM usage |
+| `sys://metrics/disk` | Disk usage across mount points |
+| `sys://metrics/network` | Network interface throughput |
+| `sys://metrics/processes/top` | Template: top N processes (e.g. `sys://metrics/processes/top?limit=10`) |
+
+## MCP Prompts
+
+- **`analyze_system_health`** — gathers and summarizes overall system health.
+- **`diagnose_performance_issue`** — diagnoses a reported performance problem by checking CPU, memory, disk, network, and top processes.
+
 ## Example Usage
 
 Once configured, you can ask your AI assistant:
@@ -157,6 +210,9 @@ Once configured, you can ask your AI assistant:
 - "Check if the SSH and Docker services are running"
 - "What are the disk I/O stats for my drives?"
 - "How much CPU and memory are my Docker containers using?"
+- "Start monitoring every 2 seconds and alert me if CPU is high"
+- "Show me disk throughput over the last minute"
+- "Are there any recent resource warnings?"
 
 ## Raspberry Pi Enhancements
 

cmd/sysmetrics-mcp/main.go

@@ -21,6 +21,7 @@ func main() {
 	flag.StringVar(&cfg.MountPointsStr, "mount-points", "", "Comma-separated mount points to monitor (empty = all)")
 	flag.StringVar(&cfg.InterfacesStr, "interfaces", "", "Comma-separated interfaces to monitor (empty = all)")
 	flag.BoolVar(&cfg.EnableGPU, "enable-gpu", true, "Attempt to read GPU metrics if available")
+	flag.IntVar(&cfg.MonitorInterval, "monitor-interval", config.DefaultMonitorInterval, "Default sampling interval in seconds for monitoring")
 	flag.Parse()
 
 	// Validate and parse comma-separated lists
@@ -35,9 +36,16 @@ func main() {
 		"1.0.0",
 	)
 
-	// Create handler manager and register tools
+	// Enable sampling so the server can proactively push alerts to clients
+	// that declare sampling support.
+	s.EnableSampling()
+
+	// Create handler manager and register tools, resources, and prompts
 	hm := handlers.NewHandlerManager(&cfg)
 	hm.RegisterTools(s)
+	hm.RegisterMonitoringTools(s)
+	hm.RegisterResources(s)
+	hm.RegisterPrompts(s)
 
 	// Start server via stdio
 	if err := server.ServeStdio(s); err != nil {

internal/config/config.go

@@ -17,15 +17,25 @@ const (
 	UnitKelvin     = "kelvin"
 )
 
+// DefaultMonitorInterval is the default sampling interval in seconds.
+const DefaultMonitorInterval = 5
+
+// MaxMonitorInterval and MinMonitorInterval bound the monitor interval.
+const (
+	MaxMonitorInterval = 60
+	MinMonitorInterval = 1
+)
+
 // Config holds the server configuration from CLI args
 type Config struct {
-	TempUnit       string
-	MaxProcesses   int
-	MountPoints    []string
-	Interfaces     []string
-	EnableGPU      bool
-	MountPointsStr string
-	InterfacesStr  string
+	TempUnit        string
+	MaxProcesses    int
+	MountPoints     []string
+	Interfaces      []string
+	EnableGPU       bool
+	MountPointsStr  string
+	InterfacesStr   string
+	MonitorInterval int
 }
 
 // Validate checks the configuration and parses string lists
@@ -54,6 +64,14 @@ func (c *Config) Validate() error {
 		c.Interfaces = SplitAndTrim(c.InterfacesStr)
 	}
 
+	// Validate monitor interval
+	if c.MonitorInterval < MinMonitorInterval {
+		c.MonitorInterval = DefaultMonitorInterval
+	}
+	if c.MonitorInterval > MaxMonitorInterval {
+		c.MonitorInterval = MaxMonitorInterval
+	}
+
 	return nil
 }
 

internal/handlers/handlers.go

@@ -12,6 +12,7 @@ import (
 	"time"
 
 	"sysmetrics-mcp/internal/config"
+	"sysmetrics-mcp/internal/monitor"
 
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
@@ -24,13 +25,6 @@ import (
 	"github.com/shirou/gopsutil/v3/process"
 )
 
-// Health status constants.
-const (
-	statusHealthy  = "healthy"
-	statusCritical = "critical"
-	statusWarning  = "warning"
-)
-
 // Network kind constants.
 const (
 	kindTCP = "tcp"
@@ -40,12 +34,16 @@ const (
 
 // HandlerManager manages the MCP tool handlers
 type HandlerManager struct {
-	cfg *config.Config
+	cfg     *config.Config
+	monitor *monitor.Monitor
 }
 
 // NewHandlerManager creates a new HandlerManager
 func NewHandlerManager(cfg *config.Config) *HandlerManager {
-	return &HandlerManager{cfg: cfg}
+	return &HandlerManager{
+		cfg:     cfg,
+		monitor: monitor.NewMonitor(monitor.DefaultThresholds(), 60),
+	}
 }
 
 // RegisterTools registers all available tools with the MCP server
@@ -642,38 +640,19 @@ func (h *HandlerManager) HandleGetSystemHealth(ctx context.Context, request mcp.
 	//nolint:gosec // G115: integer overflow conversion safe for reasonable uptimes
 	uptime := time.Duration(info.Uptime) * time.Second
 
-	// Determine overall status
-	status := statusHealthy
-	var warnings []string
-
-	if cpuUsage > 95 {
-		status = statusCritical
-		warnings = append(warnings, "CPU usage is critical (>95%)")
-	} else if cpuUsage > 80 {
-		if status != statusCritical {
-			status = statusWarning
-		}
-		warnings = append(warnings, "CPU usage is high (>80%)")
-	}
-
-	if memInfo.UsedPercent > 95 {
-		status = statusCritical
-		warnings = append(warnings, "Memory usage is critical (>95%)")
-	} else if memInfo.UsedPercent > 85 {
-		if status != statusCritical {
-			status = statusWarning
-		}
-		warnings = append(warnings, "Memory usage is high (>85%)")
-	}
-
-	if rootDisk.UsedPercent > 95 {
-		status = statusCritical
-		warnings = append(warnings, "Disk usage is critical (>95%)")
-	} else if rootDisk.UsedPercent > 85 {
-		if status != statusCritical {
-			status = statusWarning
-		}
-		warnings = append(warnings, "Disk usage is high (>85%)")
+	// Determine overall status via shared threshold evaluation
+	status, alerts := monitor.EvaluateHealth(
+		monitor.DefaultThresholds(),
+		cpuUsage,
+		memInfo.UsedPercent,
+		rootDisk.UsedPercent,
+		[]monitor.NetStat{},
+	)
+
+	// Keep warnings as human-readable strings
+	warnings := make([]string, 0, len(alerts))
+	for _, a := range alerts {
+		warnings = append(warnings, a.Message)
 	}
 
 	result := map[string]interface{}{

internal/handlers/handlers_test.go

@@ -266,3 +266,93 @@ func TestHandleGetServiceStatusMissing(t *testing.T) {
 		t.Error("Expected error result when services parameter is missing")
 	}
 }
+
+func TestHandleStartStopMonitoring(t *testing.T) {
+	h := NewHandlerManager(&config.Config{MonitorInterval: 5})
+	req := mcp.CallToolRequest{
+		Params: mcp.CallToolParams{
+			Arguments: map[string]interface{}{
+				"interval": 1,
+			},
+		},
+	}
+
+	// Start monitoring
+	res, err := h.HandleStartMonitoring(context.Background(), req)
+	checkToolResult(t, res, err, []string{"started", "interval_seconds"})
+
+	// Stop monitoring
+	stopReq := mcp.CallToolRequest{}
+	res, err = h.HandleStopMonitoring(context.Background(), stopReq)
+	checkToolResult(t, res, err, []string{"was_running", "is_running"})
+}
+
+func TestHandleGetMonitoringStatus(t *testing.T) {
+	h := NewHandlerManager(&config.Config{MonitorInterval: 5})
+	req := mcp.CallToolRequest{}
+	res, err := h.HandleGetMonitoringStatus(context.Background(), req)
+	checkToolResult(t, res, err, []string{"running", "status", "has_snapshot"})
+}
+
+func TestHandleGetAlerts(t *testing.T) {
+	h := NewHandlerManager(&config.Config{})
+	req := mcp.CallToolRequest{
+		Params: mcp.CallToolParams{
+			Arguments: map[string]interface{}{},
+		},
+	}
+	res, err := h.HandleGetAlerts(context.Background(), req)
+	checkToolResult(t, res, err, []string{"count", "alerts"})
+}
+
+func TestHandleGetMetricsHistory(t *testing.T) {
+	h := NewHandlerManager(&config.Config{})
+	req := mcp.CallToolRequest{
+		Params: mcp.CallToolParams{
+			Arguments: map[string]interface{}{},
+		},
+	}
+	res, err := h.HandleGetMetricsHistory(context.Background(), req)
+	checkToolResult(t, res, err, []string{"count", "samples", "running"})
+}
+
+func TestHandleGetNetworkThroughput(t *testing.T) {
+	h := NewHandlerManager(&config.Config{})
+	req := mcp.CallToolRequest{}
+	res, err := h.HandleGetNetworkThroughput(context.Background(), req)
+	checkToolResult(t, res, err, []string{"timestamp", "interfaces"})
+}
+
+func TestHandleGetDiskThroughput(t *testing.T) {
+	h := NewHandlerManager(&config.Config{})
+	req := mcp.CallToolRequest{}
+	res, err := h.HandleGetDiskThroughput(context.Background(), req)
+	checkToolResult(t, res, err, []string{"timestamp", "devices"})
+}
+
+func TestPrompts(t *testing.T) {
+	h := NewHandlerManager(&config.Config{})
+
+	res, err := h.promptAnalyzeHealth(context.Background(), mcp.GetPromptRequest{})
+	if err != nil {
+		t.Fatalf("promptAnalyzeHealth error: %v", err)
+	}
+	if res.Description == "" {
+		t.Error("prompt result missing description")
+	}
+	if len(res.Messages) == 0 {
+		t.Error("prompt result missing messages")
+	}
+
+	res, err = h.promptDiagnosePerformance(context.Background(), mcp.GetPromptRequest{
+		Params: mcp.GetPromptParams{
+			Arguments: map[string]string{"symptom": "slow"},
+		},
+	})
+	if err != nil {
+		t.Fatalf("promptDiagnosePerformance error: %v", err)
+	}
+	if len(res.Messages) == 0 {
+		t.Error("prompt result missing messages")
+	}
+}