pcp-mcp 0.1.0__py3-none-any.whl

pcp_mcp/prompts/__init__.py

@@ -0,0 +1,295 @@
+"""Diagnostic prompts for guided troubleshooting workflows."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+
+
+def register_prompts(mcp: FastMCP) -> None:
+    """Register diagnostic prompts with the MCP server.
+
+    Args:
+        mcp: The FastMCP server instance.
+    """
+
+    @mcp.prompt()
+    def diagnose_slow_system() -> str:
+        """Diagnose why a system is running slowly.
+
+        Returns a structured investigation workflow to identify performance
+        bottlenecks by examining CPU, memory, disk, and network metrics.
+        """
+        return """Investigate system slowness:
+
+1. Get baseline: get_system_snapshot(categories=["cpu", "memory", "load", "disk", "network"])
+
+2. Interpret the assessment fields:
+   - If cpu.assessment mentions "I/O wait": Disk bottleneck (skip to step 4)
+   - If cpu.assessment mentions "user/system": CPU bottleneck (go to step 3)
+   - If memory.assessment mentions "swap": Memory pressure (go to step 5)
+   - If load.assessment shows high load: Check load vs ncpu ratio
+
+3. Find CPU hogs:
+   - Run: get_process_top(sort_by="cpu", limit=10)
+   - Identify processes with high cpu_percent
+   - Note: cpu_percent > 100% means multi-threaded (e.g., 200% = 2 cores)
+
+4. Check disk I/O bottleneck:
+   - If disk.assessment shows high read/write rates
+   - Run: search_metrics("disk.dev") to see per-device metrics
+   - Run: get_process_top(sort_by="io", limit=10) to find I/O-heavy processes
+   - Cross-check: Does kernel.all.cpu.wait.total correlate with disk activity?
+
+5. Check memory pressure:
+   - If memory.assessment indicates swapping
+   - Run: get_process_top(sort_by="memory", limit=20)
+   - Look for large rss_bytes processes
+   - Check if swap usage is growing
+
+6. Check network saturation:
+   - If network.assessment shows high throughput
+   - Run: search_metrics("network.interface") for per-interface breakdown
+   - Look for interface errors or packet drops
+
+7. Report findings:
+   - Primary bottleneck (CPU/disk/memory/network)
+   - Specific culprits (process names, PIDs)
+   - Quantified impact (e.g., "process X using 45% CPU on 8-core system")
+   - Recommendations (kill process, add RAM, optimize queries, etc.)
+"""
+
+    @mcp.prompt()
+    def investigate_memory_usage() -> str:
+        """Investigate memory consumption and identify memory pressure.
+
+        Returns a workflow to analyze memory utilization, identify memory
+        hogs, and distinguish between normal cache usage and actual pressure.
+        """
+        return """Memory investigation workflow:
+
+1. Get memory overview:
+   - Run: get_system_snapshot(categories=["memory"])
+   - Read memory.assessment field for quick diagnosis
+
+2. Interpret memory metrics:
+   - mem.util.available is KEY metric (not "free"!)
+   - Large cache is NORMAL (Linux uses free RAM for cache)
+   - Swapping = BAD (indicates memory pressure)
+   - Check used_percent vs swap usage
+
+3. Assessment-based actions:
+   - "Memory pressure" → Go to step 4
+   - "Cache is large" → Normal, but check top consumers anyway (step 4)
+   - "Swapping actively" → CRITICAL, go to step 4 immediately
+
+4. Find memory consumers:
+   - Run: get_process_top(sort_by="memory", limit=20)
+   - Note processes with high rss_bytes
+   - Calculate: rss_percent shows memory impact
+   - Look for unexpected memory hogs (leaked memory, runaway processes)
+
+5. Detailed memory breakdown:
+   - Run: search_metrics("mem.util") for full breakdown
+   - Check: mem.util.slab (kernel memory)
+   - Check: mem.util.anonpages (process private memory)
+   - Check: mem.util.swapCached (pages swapped but still in RAM)
+
+6. NUMA systems (if applicable):
+   - Run: search_metrics("mem.numa") to check per-node allocation
+   - Look for imbalanced NUMA usage
+
+7. Report:
+   - Total memory: X GB
+   - Used: Y% (Z GB used, W GB available)
+   - Top 5 memory consumers with RSS sizes
+   - Swap status: active/inactive, growth rate if swapping
+   - Recommendation:
+     * No pressure + large cache = Normal
+     * High usage + no swap = Monitor but OK
+     * Active swapping = Add RAM or reduce load
+     * Single process consuming >50% = Investigate for memory leak
+"""
+
+    @mcp.prompt()
+    def find_io_bottleneck() -> str:
+        """Find disk I/O bottlenecks and identify processes causing high I/O.
+
+        Returns a workflow to diagnose disk performance issues, identify
+        hot devices, and find I/O-intensive processes.
+        """
+        return """Disk I/O investigation:
+
+1. Get system-wide I/O snapshot:
+   - Run: get_system_snapshot(categories=["disk", "cpu"])
+   - Check disk.assessment for read/write rates
+   - Check cpu.assessment for iowait_percent
+
+2. Interpret I/O metrics:
+   - High iowait_percent (>20%) = CPU waiting for disk
+   - Read vs write imbalance may indicate backup, logging, or database queries
+   - Sustained high I/O (>100 MB/s on HDD, >500 MB/s on SSD) = saturated
+
+3. Identify hot disks:
+   - Run: search_metrics("disk.dev")
+   - Run: query_metrics(["disk.dev.read_bytes", "disk.dev.write_bytes"])
+   - Note: These are COUNTERS, use get_system_snapshot for rates
+   - Look for specific devices with disproportionate activity
+
+4. Find I/O-heavy processes:
+   - Run: get_process_top(sort_by="io", limit=10, sample_interval=2.0)
+   - Note: Longer sample_interval (2-5s) gives more accurate I/O rates
+   - Identify processes with high io_read_bytes_sec or io_write_bytes_sec
+
+5. Correlate with CPU iowait:
+   - If cpu.iowait_percent is high AND disk I/O is high:
+     → Confirmed disk bottleneck
+   - If disk I/O is high BUT iowait is low:
+     → Fast storage keeping up (SSD/NVMe)
+   - If iowait is high BUT disk I/O is low:
+     → May be network storage (NFS) or storage controller issue
+
+6. Check for I/O patterns:
+   - Bursty I/O: Scheduled jobs, backups, log rotation
+   - Sustained I/O: Database, file server, streaming
+   - Random I/O: Database seeks (slow on HDD, fast on SSD)
+   - Sequential I/O: Backups, large file copies
+
+7. Advanced: Check per-partition I/O (if needed):
+   - Run: search_metrics("disk.partitions")
+   - Useful for systems with multiple partitions on same disk
+
+8. Report:
+   - Busiest disks by name (e.g., sda, nvme0n1)
+   - Read vs write breakdown (e.g., "80% reads, 20% writes")
+   - Top 3-5 processes causing I/O with rates
+   - I/O pattern: bursty vs sustained, random vs sequential
+   - Bottleneck severity: iowait % and queue depth
+   - Recommendations:
+     * High random I/O on HDD → Migrate to SSD
+     * Single process saturating disk → Optimize queries/access patterns
+     * Multiple processes fighting for I/O → I/O scheduler tuning or workload separation
+     * Backup/batch jobs during business hours → Reschedule
+"""
+
+    @mcp.prompt()
+    def analyze_cpu_usage() -> str:
+        """Analyze CPU utilization patterns and identify CPU-bound processes.
+
+        Returns a workflow to diagnose high CPU usage, distinguish between
+        user-space and kernel CPU time, and identify optimization opportunities.
+        """
+        return """CPU usage analysis workflow:
+
+1. Get CPU baseline:
+   - Run: get_system_snapshot(categories=["cpu", "load"])
+   - Read cpu.assessment for quick diagnosis
+   - Note: ncpu value (number of CPUs/cores)
+
+2. Interpret CPU metrics:
+   - user_percent: Application code execution
+   - system_percent: Kernel/syscall overhead
+   - idle_percent: Unused CPU capacity
+   - iowait_percent: CPU waiting for I/O (NOT CPU-bound if high)
+   - Load average: Runnable + waiting processes (compare to ncpu)
+
+3. CPU pattern classification:
+   - High user + low system = CPU-intensive application (normal)
+   - High system + low user = Kernel overhead (syscalls, context switches)
+   - High iowait = NOT a CPU problem, it's disk/storage (see find_io_bottleneck)
+   - Load > ncpu = More demand than capacity (may include I/O wait)
+
+4. Find CPU hogs:
+   - Run: get_process_top(sort_by="cpu", limit=15)
+   - Note: cpu_percent > 100% means multi-core usage (e.g., 400% = 4 cores)
+   - Identify unexpected high CPU consumers
+
+5. Per-CPU breakdown (if needed):
+   - Run: search_metrics("kernel.percpu.cpu")
+   - Useful for: Thread affinity issues, interrupt handling imbalance
+   - Look for: One CPU at 100% while others idle (poor parallelization)
+
+6. Check for CPU saturation indicators:
+   - Run: query_metrics(["kernel.all.runnable", "kernel.all.pswitch"])
+   - High runnable count: More threads than cores (contention)
+   - High pswitch (context switches): Thread thrashing
+
+7. Distinguish workload types:
+   - Compute-bound: High user%, low syscalls (scientific, encoding, crypto)
+   - I/O-bound: High iowait%, moderate user% (databases, file processing)
+   - System-bound: High system%, moderate user% (network servers, many syscalls)
+
+8. Report:
+   - CPU utilization breakdown: X% user, Y% system, Z% iowait, W% idle
+   - Load average: 1/5/15 min values vs ncpu (e.g., "load 8.5 on 8-core = 106%")
+   - Top 5 CPU consumers with cpu_percent and command names
+   - CPU pattern: compute-bound / I/O-bound / system-bound
+   - Saturation indicators: runnable queue, context switches
+   - Recommendations:
+     * Low idle + high load → Add CPU capacity or optimize hot processes
+     * High iowait → Disk bottleneck, not CPU (see I/O investigation)
+     * High system% → Profile syscalls, reduce I/O frequency, optimize locking
+     * Single-threaded bottleneck → Parallelize if possible
+     * Many small processes → Reduce process spawning overhead
+"""
+
+    @mcp.prompt()
+    def check_network_performance() -> str:
+        """Check network performance and identify bandwidth/error issues.
+
+        Returns a workflow to analyze network throughput, identify saturated
+        interfaces, and detect packet loss or errors.
+        """
+        return """Network performance investigation:
+
+1. Get network overview:
+   - Run: get_system_snapshot(categories=["network"])
+   - Read network.assessment for quick diagnosis
+   - Note: Rates are per-second (bytes/sec, packets/sec)
+
+2. Interpret network metrics:
+   - in_bytes_sec / out_bytes_sec: Throughput (compare to link speed)
+   - in_packets_sec / out_packets_sec: Packet rate
+   - Assessment field indicates saturation or errors
+
+3. Per-interface breakdown:
+   - Run: search_metrics("network.interface")
+   - Run: query_metrics(["network.interface.in.bytes", "network.interface.out.bytes"])
+   - Note: These are COUNTERS, use get_system_snapshot for rates
+   - Identify busy interfaces vs idle interfaces (e.g., eth0 busy, lo idle)
+
+4. Check for errors and drops:
+   - Run: query_metrics(["network.interface.in.errors", "network.interface.out.errors"])
+   - Run: query_metrics(["network.interface.in.drops", "network.interface.out.drops"])
+   - Non-zero errors = Hardware, driver, or cable issues
+   - Non-zero drops = Buffer overflow (traffic exceeds processing capacity)
+
+5. Calculate interface saturation:
+   - Compare throughput to link speed (e.g., 950 Mbps on 1 Gbps link = 95%)
+   - Sustained >80% = Approaching saturation
+   - Bursts >95% = Temporarily saturated
+
+6. Find network-heavy processes (indirect):
+   - PCP proc.* namespace doesn't have per-process network metrics
+   - Use system tools: netstat, ss, iftop (outside PCP)
+   - Or correlate: High network I/O often correlates with high CPU/disk I/O
+
+7. Check protocol-level stats (if needed):
+   - Run: search_metrics("network.tcp")
+   - Run: search_metrics("network.udp")
+   - Look for: Retransmissions, failed connections, buffer overflows
+
+8. Report:
+   - Per-interface throughput (e.g., "eth0: 850 Mbps in, 120 Mbps out")
+   - Link utilization % (if link speed known)
+   - Errors/drops: Count and affected interfaces
+   - Traffic pattern: Symmetric (similar in/out) vs asymmetric (download/upload heavy)
+   - Packet rate: Normal vs abnormal (tiny packets = inefficient, possible attack)
+   - Recommendations:
+     * High utilization + no errors → Upgrade link or load balance
+     * Errors/drops present → Check cables, NIC drivers, switch ports
+     * Asymmetric traffic → Normal for client (download heavy) or server (upload heavy)
+     * High packet rate + low byte rate → Small packets (check for SYN flood, fragmentation)
+"""

pcp_mcp/resources/__init__.py

@@ -0,0 +1,21 @@
+"""Resource registration for the PCP MCP server."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+
+
+def register_resources(mcp: FastMCP) -> None:
+    """Register all resources with the MCP server.
+
+    Args:
+        mcp: The FastMCP server instance.
+    """
+    from pcp_mcp.resources.catalog import register_catalog_resources
+    from pcp_mcp.resources.health import register_health_resources
+
+    register_health_resources(mcp)
+    register_catalog_resources(mcp)

pcp_mcp/resources/catalog.py

@@ -0,0 +1,233 @@
+"""Catalog resources for common metrics and namespaces."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fastmcp import Context
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+
+
+def register_catalog_resources(mcp: FastMCP) -> None:
+    """Register catalog resources with the MCP server.
+
+    Args:
+        mcp: The FastMCP server instance.
+    """
+
+    @mcp.resource("pcp://metrics/common")
+    def common_metrics_catalog() -> str:
+        """Catalog of commonly used metric groups.
+
+        Returns a structured guide to the most useful PCP metrics organized
+        by troubleshooting domain.
+        """
+        return """# Common PCP Metric Groups
+
+## CPU Performance
+- kernel.all.cpu.user       → User-space CPU time (counter) ⚠️
+- kernel.all.cpu.sys        → Kernel CPU time (counter) ⚠️
+- kernel.all.cpu.idle       → Idle CPU time (counter) ⚠️
+- kernel.all.cpu.wait.total → I/O wait time (counter) ⚠️ High = disk bottleneck
+- kernel.all.load           → Load average (1, 5, 15 min) [instances: 1, 5, 15]
+- kernel.all.runnable       → Runnable processes (instant)
+- kernel.all.nprocs         → Total processes (instant)
+- hinv.ncpu                 → Number of CPUs (instant)
+
+## Memory
+- mem.physmem               → Total physical memory in KB (instant)
+- mem.util.used             → Used memory in KB (instant)
+- mem.util.free             → Free memory in KB (instant)
+- mem.util.available        → Available for apps in KB (instant) ⭐ Use this, not "free"
+- mem.util.cached           → Cached data in KB (instant)
+- mem.util.bufmem           → Buffer memory in KB (instant)
+- mem.util.swapTotal        → Total swap in KB (instant)
+- mem.util.swapFree         → Free swap in KB (instant)
+- mem.util.slab             → Kernel slab allocator in KB (instant)
+
+## Disk I/O
+- disk.all.read_bytes       → Total bytes read (counter) ⚠️
+- disk.all.write_bytes      → Total bytes written (counter) ⚠️
+- disk.all.read             → Total read operations (counter) ⚠️
+- disk.all.write            → Total write operations (counter) ⚠️
+- disk.dev.read_bytes       → Per-disk reads in bytes [instances: sda, sdb, ...] (counter) ⚠️
+- disk.dev.write_bytes      → Per-disk writes in bytes [instances: sda, sdb, ...] (counter) ⚠️
+- disk.dev.avactive         → Average time disk was active (instant)
+
+## Network
+- network.interface.in.bytes  → Bytes received [instances: eth0, lo, ...] (counter) ⚠️
+- network.interface.out.bytes → Bytes sent [instances: eth0, lo, ...] (counter) ⚠️
+- network.interface.in.packets  → Packets received [instances] (counter) ⚠️
+- network.interface.out.packets → Packets sent [instances] (counter) ⚠️
+- network.interface.in.errors   → Receive errors [instances] (counter) ⚠️
+- network.interface.out.errors  → Transmit errors [instances] (counter) ⚠️
+
+## Process Metrics (⚠️ Use get_process_top instead of raw queries)
+- proc.psinfo.pid           → Process ID [instances: PIDs]
+- proc.psinfo.cmd           → Command name [instances: PIDs]
+- proc.psinfo.psargs        → Full command line [instances: PIDs]
+- proc.memory.rss           → Resident set size in KB [instances: PIDs] (instant)
+- proc.memory.vmsize        → Virtual memory size in KB [instances: PIDs] (instant)
+- proc.psinfo.utime         → User CPU time in ms [instances: PIDs] (counter) ⚠️
+- proc.psinfo.stime         → System CPU time in ms [instances: PIDs] (counter) ⚠️
+- proc.io.read_bytes        → Process I/O reads in bytes [instances: PIDs] (counter) ⚠️
+- proc.io.write_bytes       → Process I/O writes in bytes [instances: PIDs] (counter) ⚠️
+
+## System Health
+- kernel.all.uptime         → System uptime in seconds (instant)
+- kernel.all.nusers         → Logged-in users (instant)
+- pmcd.agent.status         → PMDA agent health [instances: agent names] (instant)
+- pmcd.pmlogger.host        → Active pmlogger hosts [instances] (instant)
+
+## Container Metrics (requires cgroups PMDA)
+- cgroup.cpuacct.usage      → CPU usage per cgroup [instances: cgroup paths] (counter) ⚠️
+- cgroup.memory.usage       → Memory usage per cgroup [instances: cgroup paths] (instant)
+- cgroup.blkio.io_service_bytes → I/O per cgroup [instances: cgroup paths] (counter) ⚠️
+
+---
+
+## Legend
+⚠️ = COUNTER METRIC - Use get_system_snapshot() or get_process_top() for rates
+⭐ = Recommended over alternatives
+[instances] = Returns multiple values (per-CPU, per-disk, per-process, etc.)
+(instant) = Instantaneous gauge value
+(counter) = Cumulative counter since boot
+"""
+
+    @mcp.resource("pcp://namespaces")
+    async def metric_namespaces(ctx: Context) -> str:
+        """List available PCP metric namespaces discovered from the live system.
+
+        Queries the connected PCP server to enumerate top-level namespaces
+        and active PMDAs, showing exactly what's available on this system.
+        """
+        from pcp_mcp.context import get_client
+        from pcp_mcp.errors import handle_pcp_error
+
+        client = get_client(ctx)
+
+        try:
+            all_metrics = await client.search("")
+            namespaces = sorted(
+                {m.get("name", "").split(".")[0] for m in all_metrics if m.get("name")}
+            )
+
+            pmda_status = await client.fetch(["pmcd.agent.status"])
+            active_pmdas = []
+            for metric in pmda_status.get("values", []):
+                for inst in metric.get("instances", []):
+                    instance_id = inst.get("instance")
+                    status = inst.get("value")
+                    if instance_id is not None and instance_id != -1 and status == 0:
+                        active_pmdas.append(str(instance_id))
+
+        except Exception as e:
+            raise handle_pcp_error(e, "discovering namespaces") from e
+
+        output = f"""# PCP Metric Namespaces (Live Discovery)
+
+Connected to: {client.target_host}
+Active PMDAs: {len(active_pmdas)}
+Top-level namespaces: {len(namespaces)}
+
+## Available Namespaces
+
+"""
+
+        namespace_docs = {
+            "kernel": "System-wide kernel statistics (CPU, load, interrupts, uptime)",
+            "mem": "Memory subsystem (physmem, swap, cache, buffers, NUMA)",
+            "disk": "Disk I/O (aggregates, per-device, partitions, device mapper)",
+            "network": "Network interfaces and protocols (TCP, UDP, IP)",
+            "proc": "Per-process metrics ⚠️ Use get_process_top instead of raw queries",
+            "hinv": "Hardware inventory (ncpu, physmem, architecture - static info)",
+            "pmcd": "PCP daemon health (agent status, clients, control)",
+            "pmproxy": "pmproxy daemon metrics (if pmproxy PMDA loaded)",
+            "cgroup": "Container/cgroup metrics (CPU, memory, I/O per cgroup)",
+            "containers": "Container metrics (Docker, Podman via PMDA)",
+            "filesys": "Filesystem metrics (capacity, used, free per mount point)",
+            "nfs": "NFS version-agnostic metrics",
+            "nfs3": "NFSv3 client and server metrics",
+            "nfs4": "NFSv4 client and server metrics",
+            "swap": "Swap device metrics (activity per swap device)",
+            "quota": "Filesystem quota metrics",
+            "xfs": "XFS filesystem-specific metrics",
+            "btrfs": "Btrfs filesystem-specific metrics",
+            "zfs": "ZFS filesystem-specific metrics",
+            "kvm": "KVM hypervisor metrics (guest VMs)",
+            "libvirt": "libvirt virtualization metrics",
+            "redis": "Redis server metrics (via redis PMDA)",
+            "postgresql": "PostgreSQL database metrics (via postgresql PMDA)",
+            "mysql": "MySQL database metrics (via mysql PMDA)",
+            "nginx": "nginx web server metrics",
+            "apache": "Apache web server metrics",
+            "haproxy": "HAProxy load balancer metrics",
+            "elasticsearch": "Elasticsearch metrics",
+            "mongodb": "MongoDB metrics",
+            "bcc": "eBPF-based advanced profiling (BPF PMDA - requires kernel 4.1+)",
+            "hotproc": "Hot process tracking (automatically tracks top resource consumers)",
+            "mmv": "Memory-mapped value metrics (custom app instrumentation)",
+            "sysfs": "Linux sysfs metrics",
+            "event": "System event tracing",
+            "ipc": "Inter-process communication metrics (SysV IPC)",
+            "jbd2": "JBD2 journal metrics (ext4 filesystem journaling)",
+            "rpc": "RPC statistics",
+            "acct": "Process accounting metrics",
+            "fchost": "Fibre Channel host metrics",
+            "tape": "Tape device metrics",
+            "hyperv": "Hyper-V guest metrics",
+        }
+
+        for ns in namespaces:
+            doc = namespace_docs.get(ns, "Namespace provided by PMDA (no built-in description)")
+            output += f"- **{ns}.***: {doc}\n"
+
+        output += f"""
+## Active PMDAs on This System
+
+{", ".join(active_pmdas) if active_pmdas else "Unable to enumerate PMDAs"}
+
+Status 0 = Running, non-zero = Error
+
+## Namespace Categories
+
+### Core System (always available)
+kernel, mem, disk, network, proc, hinv, pmcd
+
+### Filesystems
+filesys, xfs, btrfs, zfs, quota, swap
+
+### Virtualization
+kvm, libvirt, containers, cgroup, hyperv
+
+### Databases
+redis, postgresql, mysql, elasticsearch, mongodb
+
+### Web Servers
+nginx, apache, haproxy
+
+### Advanced
+bcc (eBPF), hotproc (auto-tracking), mmv (custom metrics), event (tracing)
+
+## Discovery Workflow
+
+1. **Explore a namespace**: search_metrics("{namespaces[0] if namespaces else "kernel"}")
+2. **Count metrics in namespace**: search_metrics("disk") to see all disk.* metrics
+3. **Get metric details**: describe_metric("full.metric.name")
+4. **Query specific metrics**: query_metrics(["name1", "name2"])
+
+## Navigation Strategy
+
+**Top-down** (recommended for troubleshooting):
+  1. Start with get_system_snapshot() → Identifies problem domain
+  2. Drill into relevant namespace (e.g., "disk" issue → search_metrics("disk.dev"))
+  3. Query specific metrics with query_metrics([...])
+
+**Bottom-up** (exploring new system):
+  1. Browse this pcp://namespaces resource → See what's available
+  2. search_metrics("interesting.namespace") → Explore subtree
+  3. describe_metric("full.name") → Understand semantics
+"""
+        return output

pcp_mcp/resources/health.py

@@ -0,0 +1,74 @@
+"""Health summary resource for quick system status."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+from fastmcp import Context
+
+from pcp_mcp.context import get_client
+from pcp_mcp.tools.system import COUNTER_METRICS, SNAPSHOT_METRICS
+from pcp_mcp.utils.builders import (
+    build_cpu_metrics,
+    build_load_metrics,
+    build_memory_metrics,
+)
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+
+
+def register_health_resources(mcp: FastMCP) -> None:
+    """Register health resources with the MCP server."""
+
+    @mcp.resource("pcp://health")
+    async def health_summary(ctx: Context) -> str:
+        """Quick system health summary.
+
+        Returns a text summary of CPU, memory, and load status suitable
+        for quick health checks. For detailed metrics, use the
+        get_system_snapshot tool instead.
+        """
+        client = get_client(ctx)
+
+        metrics = SNAPSHOT_METRICS["cpu"] + SNAPSHOT_METRICS["memory"] + SNAPSHOT_METRICS["load"]
+
+        try:
+            data = await client.fetch_with_rates(metrics, COUNTER_METRICS, sample_interval=1.0)
+        except Exception as e:
+            return f"Error fetching health data: {e}"
+
+        cpu = build_cpu_metrics(data)
+        memory = build_memory_metrics(data)
+        load = build_load_metrics(data)
+
+        timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
+
+        return f"""# System Health Summary
+Host: {client.target_host}
+Time: {timestamp}
+
+## CPU
+- User: {cpu.user_percent}%
+- System: {cpu.system_percent}%
+- Idle: {cpu.idle_percent}%
+- I/O Wait: {cpu.iowait_percent}%
+- CPUs: {cpu.ncpu}
+- Assessment: {cpu.assessment}
+
+## Memory
+- Used: {memory.used_percent}% ({memory.used_bytes / 1e9:.1f} / {memory.total_bytes / 1e9:.1f} GB)
+- Available: {memory.available_bytes / 1e9:.1f} GB
+- Cached: {memory.cached_bytes / 1e9:.1f} GB
+- Swap: {memory.swap_used_bytes / 1e9:.1f} GB / {memory.swap_total_bytes / 1e9:.1f} GB
+- Assessment: {memory.assessment}
+
+## Load
+- 1 min: {load.load_1m}
+- 5 min: {load.load_5m}
+- 15 min: {load.load_15m}
+- Runnable: {load.runnable}
+- Processes: {load.nprocs}
+- Assessment: {load.assessment}
+"""