pcp-mcp 0.1.0__py3-none-any.whl

pcp_mcp/server.py

@@ -0,0 +1,124 @@
+"""FastMCP server setup and lifespan management."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any
+
+from fastmcp import FastMCP
+
+from pcp_mcp.client import PCPClient
+from pcp_mcp.config import PCPMCPSettings
+
+
+@asynccontextmanager
+async def lifespan(mcp: FastMCP) -> AsyncIterator[dict[str, Any]]:
+    """Manage PCPClient lifecycle.
+
+    Creates a PCPClient for the duration of the server's lifetime,
+    making it available to all tools and resources via the context.
+
+    Args:
+        mcp: The FastMCP server instance.
+
+    Yields:
+        Context dict with client and settings.
+    """
+    settings = PCPMCPSettings()
+
+    async with PCPClient(
+        base_url=settings.base_url,
+        target_host=settings.target_host,
+        auth=settings.auth,
+        timeout=settings.timeout,
+    ) as client:
+        yield {
+            "client": client,
+            "settings": settings,
+        }
+
+
+def create_server() -> FastMCP:
+    """Create and configure the MCP server.
+
+    Returns:
+        Configured FastMCP server instance.
+    """
+    settings = PCPMCPSettings()
+
+    mcp = FastMCP(
+        name="pcp",
+        instructions=f"""PCP MCP Server - Performance Co-Pilot Metrics
+
+Monitoring target: {settings.target_host}
+pmproxy endpoint: {settings.base_url}
+
+🎯 QUICK START GUIDE FOR LLMs
+
+Common troubleshooting workflows:
+- "System is slow" → get_system_snapshot(categories=["cpu", "load", "memory"])
+- "High CPU usage" → get_process_top(sort_by="cpu") + query_metrics(["kernel.all.cpu.*"])
+- "Memory pressure" → get_system_snapshot(categories=["memory"]) + search_metrics("mem.util")
+- "Disk I/O issues" → get_system_snapshot(categories=["disk"]) + search_metrics("disk.dev")
+- "Network saturation" → get_system_snapshot(categories=["network"]) +
+  search_metrics("network.interface")
+
+📊 METRIC NAMESPACE GUIDE
+
+Key prefixes and what they measure:
+- kernel.all.*    → System-wide aggregates (load, CPU totals, interrupts)
+- mem.*           → Memory utilization (physmem, swap, buffers, cache)
+- disk.*          → Disk I/O (disk.all.* for totals, disk.dev.* per-device)
+- network.*       → Network I/O (network.interface.* per-interface)
+- proc.*          → Per-process metrics (use get_process_top instead of raw queries)
+- hinv.*          → Hardware inventory (ncpu, physmem, machine type)
+- pmcd.*          → PCP daemon health (agent status, timeouts)
+- cgroup.*        → Container/cgroup metrics (requires cgroups PMDA)
+
+⚠️ COUNTER METRICS WARNING
+
+These metrics are CUMULATIVE (values since boot):
+- kernel.all.cpu.*
+- disk.all.read_bytes, disk.all.write_bytes
+- network.interface.in.bytes, network.interface.out.bytes
+- proc.psinfo.utime, proc.psinfo.stime
+- proc.io.read_bytes, proc.io.write_bytes
+
+For meaningful rates, use:
+- get_system_snapshot (handles rate calculation automatically)
+- get_process_top (handles rate calculation automatically)
+
+DO NOT query these directly with query_metrics expecting per-second rates!
+
+🔍 DISCOVERY WORKFLOW
+
+1. Start broad: get_system_snapshot() or get_process_top()
+2. Drill down: search_metrics("prefix") to find specific metrics
+3. Investigate: describe_metric("full.metric.name") for units/semantics
+4. Query: query_metrics(["name1", "name2"]) for raw values (non-counters only)
+
+Tools:
+- query_metrics: Fetch specific metrics by name (use for instant/gauge metrics)
+- search_metrics: Find metrics matching a pattern (e.g., 'kernel.all', 'mem')
+- describe_metric: Get metadata for a metric (type, units, help text)
+- get_system_snapshot: System overview (CPU, memory, disk, network) - USE THIS FIRST
+- get_process_top: Top processes by resource consumption
+
+Resources:
+- pcp://health - Quick system health summary
+- pcp://metrics/common - Catalog of commonly used metrics
+- pcp://namespaces - Dynamically discovered metric namespaces
+""",
+        lifespan=lifespan,
+    )
+
+    from pcp_mcp.prompts import register_prompts
+    from pcp_mcp.resources import register_resources
+    from pcp_mcp.tools import register_tools
+
+    register_tools(mcp)
+    register_resources(mcp)
+    register_prompts(mcp)
+
+    return mcp

pcp_mcp/tools/__init__.py

@@ -0,0 +1,21 @@
+"""Tool registration for the PCP MCP server."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+
+
+def register_tools(mcp: FastMCP) -> None:
+    """Register all tools with the MCP server.
+
+    Args:
+        mcp: The FastMCP server instance.
+    """
+    from pcp_mcp.tools.metrics import register_metrics_tools
+    from pcp_mcp.tools.system import register_system_tools
+
+    register_metrics_tools(mcp)
+    register_system_tools(mcp)

pcp_mcp/tools/metrics.py

@@ -0,0 +1,148 @@
+"""Core metric tools for querying PCP metrics."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Annotated
+
+from fastmcp import Context
+from pydantic import Field
+
+from pcp_mcp.context import get_client
+from pcp_mcp.models import MetricInfo, MetricSearchResult, MetricValue
+from pcp_mcp.utils.extractors import extract_help_text
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+
+
+def register_metrics_tools(mcp: FastMCP) -> None:
+    """Register core metric tools with the MCP server."""
+
+    @mcp.tool()
+    async def query_metrics(
+        ctx: Context,
+        names: Annotated[
+            list[str],
+            Field(description="List of PCP metric names to fetch (e.g., ['kernel.all.load'])"),
+        ],
+    ) -> list[MetricValue]:
+        """Fetch current values for specific PCP metrics.
+
+        Returns the current value for each requested metric. For metrics with
+        instances (e.g., per-CPU, per-disk), returns one MetricValue per instance.
+        """
+        from pcp_mcp.errors import handle_pcp_error
+
+        client = get_client(ctx)
+
+        try:
+            response = await client.fetch(names)
+        except Exception as e:
+            raise handle_pcp_error(e, "fetching metrics") from e
+
+        results: list[MetricValue] = []
+        for metric in response.get("values", []):
+            metric_name = metric.get("name", "")
+            instances = metric.get("instances", [])
+
+            for inst in instances:
+                instance_id = inst.get("instance")
+                value = inst.get("value")
+
+                instance_name = None
+                if instance_id is not None and instance_id != -1:
+                    instance_name = str(instance_id)
+
+                results.append(
+                    MetricValue(
+                        name=metric_name,
+                        value=value,
+                        instance=instance_name,
+                    )
+                )
+
+        return results
+
+    @mcp.tool()
+    async def search_metrics(
+        ctx: Context,
+        pattern: Annotated[
+            str,
+            Field(description="Metric name prefix to search for (e.g., 'kernel.all', 'mem')"),
+        ],
+    ) -> list[MetricSearchResult]:
+        """Find PCP metrics matching a name pattern.
+
+        Use this to discover available metrics before querying them.
+        Returns metric names and brief descriptions.
+        """
+        from pcp_mcp.errors import handle_pcp_error
+
+        client = get_client(ctx)
+
+        try:
+            metrics = await client.search(pattern)
+        except Exception as e:
+            raise handle_pcp_error(e, "searching metrics") from e
+
+        return [
+            MetricSearchResult(
+                name=m.get("name", ""),
+                help_text=extract_help_text(m),
+            )
+            for m in metrics
+        ]
+
+    @mcp.tool()
+    async def describe_metric(
+        ctx: Context,
+        name: Annotated[
+            str,
+            Field(description="Full PCP metric name (e.g., 'kernel.all.cpu.user')"),
+        ],
+    ) -> MetricInfo:
+        """Get detailed metadata about a PCP metric.
+
+        Returns type, semantics, units, and help text for the metric.
+        Use this to understand what a metric measures and how to interpret it.
+        """
+        from fastmcp.exceptions import ToolError
+
+        from pcp_mcp.errors import handle_pcp_error
+
+        client = get_client(ctx)
+
+        try:
+            info = await client.describe(name)
+        except Exception as e:
+            raise handle_pcp_error(e, "describing metric") from e
+
+        if not info:
+            raise ToolError(f"Metric not found: {name}")
+
+        return MetricInfo(
+            name=info.get("name", name),
+            type=info.get("type", "unknown"),
+            semantics=info.get("sem", "unknown"),
+            units=_format_units(info),
+            help_text=extract_help_text(info),
+            indom=info.get("indom"),
+        )
+
+
+def _format_units(info: dict) -> str:
+    """Format PCP units into a human-readable string."""
+    units = info.get("units", "")
+    if units:
+        return units
+
+    # Fallback: build from components if available
+    parts = []
+    if info.get("units-space"):
+        parts.append(info["units-space"])
+    if info.get("units-time"):
+        parts.append(info["units-time"])
+    if info.get("units-count"):
+        parts.append(info["units-count"])
+
+    return " / ".join(parts) if parts else "none"

pcp_mcp/tools/system.py

@@ -0,0 +1,229 @@
+"""System health tools for clumped metric queries."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Annotated, Literal
+
+from fastmcp import Context
+from pydantic import Field
+
+from pcp_mcp.context import get_client
+from pcp_mcp.models import ProcessTopResult, SystemSnapshot
+from pcp_mcp.utils.builders import (
+    assess_processes,
+    build_cpu_metrics,
+    build_disk_metrics,
+    build_load_metrics,
+    build_memory_metrics,
+    build_network_metrics,
+    build_process_list,
+    get_sort_key,
+)
+from pcp_mcp.utils.extractors import get_scalar_value
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+
+SNAPSHOT_METRICS = {
+    "cpu": [
+        "kernel.all.cpu.user",
+        "kernel.all.cpu.sys",
+        "kernel.all.cpu.idle",
+        "kernel.all.cpu.wait.total",
+        "hinv.ncpu",
+    ],
+    "memory": [
+        "mem.physmem",
+        "mem.util.used",
+        "mem.util.free",
+        "mem.util.available",
+        "mem.util.cached",
+        "mem.util.bufmem",
+        "mem.util.swapTotal",
+        "mem.util.swapFree",
+    ],
+    "load": [
+        "kernel.all.load",
+        "kernel.all.runnable",
+        "kernel.all.nprocs",
+        "hinv.ncpu",
+    ],
+    "disk": [
+        "disk.all.read_bytes",
+        "disk.all.write_bytes",
+        "disk.all.read",
+        "disk.all.write",
+    ],
+    "network": [
+        "network.interface.in.bytes",
+        "network.interface.out.bytes",
+        "network.interface.in.packets",
+        "network.interface.out.packets",
+    ],
+}
+
+COUNTER_METRICS = {
+    "kernel.all.cpu.user",
+    "kernel.all.cpu.sys",
+    "kernel.all.cpu.idle",
+    "kernel.all.cpu.wait.total",
+    "disk.all.read_bytes",
+    "disk.all.write_bytes",
+    "disk.all.read",
+    "disk.all.write",
+    "network.interface.in.bytes",
+    "network.interface.out.bytes",
+    "network.interface.in.packets",
+    "network.interface.out.packets",
+}
+
+PROCESS_METRICS = {
+    "cpu": ["proc.psinfo.utime", "proc.psinfo.stime"],
+    "memory": ["proc.memory.rss"],
+    "io": ["proc.io.read_bytes", "proc.io.write_bytes"],
+    "info": ["proc.psinfo.pid", "proc.psinfo.cmd", "proc.psinfo.psargs"],
+}
+
+
+def register_system_tools(mcp: FastMCP) -> None:
+    """Register system health tools with the MCP server."""
+
+    @mcp.tool()
+    async def get_system_snapshot(
+        ctx: Context,
+        categories: Annotated[
+            list[str] | None,
+            Field(
+                default=None,
+                description="Categories to include: cpu, memory, disk, network, load",
+            ),
+        ] = None,
+        sample_interval: Annotated[
+            float,
+            Field(
+                default=1.0,
+                ge=0.1,
+                le=10.0,
+                description="Seconds between samples for rate calculation",
+            ),
+        ] = 1.0,
+    ) -> SystemSnapshot:
+        """Get a point-in-time system health overview.
+
+        Returns CPU, memory, disk I/O, network I/O, and load metrics in a single
+        call. For rate metrics (CPU %, disk I/O, network throughput), takes two
+        samples to calculate per-second rates.
+        """
+        from pcp_mcp.errors import handle_pcp_error
+
+        client = get_client(ctx)
+
+        if categories is None:
+            categories = ["cpu", "memory", "disk", "network", "load"]
+
+        all_metrics: list[str] = []
+        for cat in categories:
+            if cat in SNAPSHOT_METRICS:
+                all_metrics.extend(SNAPSHOT_METRICS[cat])
+
+        try:
+            data = await client.fetch_with_rates(
+                all_metrics,
+                COUNTER_METRICS,
+                sample_interval,
+            )
+        except Exception as e:
+            raise handle_pcp_error(e, "fetching system snapshot") from e
+
+        snapshot = SystemSnapshot(
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            hostname=client.target_host,
+        )
+
+        if "cpu" in categories:
+            snapshot.cpu = build_cpu_metrics(data)
+        if "memory" in categories:
+            snapshot.memory = build_memory_metrics(data)
+        if "load" in categories:
+            snapshot.load = build_load_metrics(data)
+        if "disk" in categories:
+            snapshot.disk = build_disk_metrics(data)
+        if "network" in categories:
+            snapshot.network = build_network_metrics(data)
+
+        return snapshot
+
+    @mcp.tool()
+    async def get_process_top(
+        ctx: Context,
+        sort_by: Annotated[
+            Literal["cpu", "memory", "io"],
+            Field(description="Resource to sort by"),
+        ] = "cpu",
+        limit: Annotated[
+            int,
+            Field(default=10, ge=1, le=50, description="Number of processes to return"),
+        ] = 10,
+        sample_interval: Annotated[
+            float,
+            Field(
+                default=1.0,
+                ge=0.5,
+                le=5.0,
+                description="Seconds to sample for CPU/IO rates",
+            ),
+        ] = 1.0,
+    ) -> ProcessTopResult:
+        """Get top processes by resource consumption.
+
+        For CPU and I/O, takes two samples to calculate rates. Memory is instantaneous.
+        Returns the top N processes sorted by the requested resource.
+        """
+        client = get_client(ctx)
+
+        all_metrics = (
+            PROCESS_METRICS["info"] + PROCESS_METRICS["memory"] + PROCESS_METRICS.get(sort_by, [])
+        )
+        if sort_by == "cpu":
+            all_metrics.extend(PROCESS_METRICS["cpu"])
+        elif sort_by == "io":
+            all_metrics.extend(PROCESS_METRICS["io"])
+
+        all_metrics = list(set(all_metrics))
+        system_metrics = ["hinv.ncpu", "mem.physmem"]
+
+        counter_metrics = {
+            "proc.psinfo.utime",
+            "proc.psinfo.stime",
+            "proc.io.read_bytes",
+            "proc.io.write_bytes",
+        }
+
+        from pcp_mcp.errors import handle_pcp_error
+
+        try:
+            proc_data = await client.fetch_with_rates(all_metrics, counter_metrics, sample_interval)
+            sys_data = await client.fetch(system_metrics)
+        except Exception as e:
+            raise handle_pcp_error(e, "fetching process data") from e
+
+        ncpu = get_scalar_value(sys_data, "hinv.ncpu", 1)
+        total_mem = get_scalar_value(sys_data, "mem.physmem", 1) * 1024
+
+        processes = build_process_list(proc_data, sort_by, total_mem, ncpu)
+        processes.sort(key=lambda p: get_sort_key(p, sort_by), reverse=True)
+        processes = processes[:limit]
+
+        assessment = assess_processes(processes, sort_by, ncpu)
+
+        return ProcessTopResult(
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            hostname=client.target_host,
+            sort_by=sort_by,
+            sample_interval=sample_interval,
+            processes=processes,
+            total_memory_bytes=int(total_mem),
+            ncpu=ncpu,
+            assessment=assessment,
+        )

pcp_mcp/utils/__init__.py

@@ -0,0 +1,42 @@
+"""Shared utility modules for PCP-MCP.
+
+This package contains reusable utilities extracted to follow DRY principles:
+- extractors: Metric data extraction helpers
+- decorators: Error handling and other decorators
+- builders: Metric transformation and builder functions
+"""
+
+from pcp_mcp.utils.builders import (
+    build_cpu_metrics,
+    build_disk_metrics,
+    build_load_metrics,
+    build_memory_metrics,
+    build_network_metrics,
+    build_process_list,
+)
+from pcp_mcp.utils.decorators import handle_pcp_errors
+from pcp_mcp.utils.extractors import (
+    extract_help_text,
+    extract_timestamp,
+    get_first_value,
+    get_scalar_value,
+    sum_instances,
+)
+
+__all__ = [
+    # Extractors
+    "get_first_value",
+    "get_scalar_value",
+    "sum_instances",
+    "extract_help_text",
+    "extract_timestamp",
+    # Decorators
+    "handle_pcp_errors",
+    # Builders
+    "build_cpu_metrics",
+    "build_memory_metrics",
+    "build_load_metrics",
+    "build_disk_metrics",
+    "build_network_metrics",
+    "build_process_list",
+]