pcp-mcp 0.1.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

pcp_mcp/resources/health.py

@@ -7,7 +7,10 @@ from typing import TYPE_CHECKING
 
 from fastmcp import Context
 
-from pcp_mcp.context import get_client
+from pcp_mcp.client import PCPClient
+from pcp_mcp.context import get_client, get_client_for_host, get_settings
+from pcp_mcp.icons import ICON_HEALTH, TAGS_HEALTH
+from pcp_mcp.models import CPUMetrics, LoadMetrics, MemoryMetrics
 from pcp_mcp.tools.system import COUNTER_METRICS, SNAPSHOT_METRICS
 from pcp_mcp.utils.builders import (
     build_cpu_metrics,
@@ -19,33 +22,16 @@ 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"]
+def _format_health_summary(
+    client: PCPClient,
+    cpu: CPUMetrics,
+    memory: MemoryMetrics,
+    load: LoadMetrics,
+) -> str:
+    """Format health metrics into a markdown summary."""
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
 
-        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
+    return f"""# System Health Summary
 Host: {client.target_host}
 Time: {timestamp}
 
@@ -72,3 +58,60 @@ Time: {timestamp}
 - Processes: {load.nprocs}
 - Assessment: {load.assessment}
 """
+
+
+async def _fetch_health_data(client: PCPClient) -> tuple[CPUMetrics, MemoryMetrics, LoadMetrics]:
+    """Fetch and build health metrics from a client."""
+    metrics = SNAPSHOT_METRICS["cpu"] + SNAPSHOT_METRICS["memory"] + SNAPSHOT_METRICS["load"]
+    data = await client.fetch_with_rates(metrics, COUNTER_METRICS, sample_interval=1.0)
+
+    return (
+        build_cpu_metrics(data),
+        build_memory_metrics(data),
+        build_load_metrics(data),
+    )
+
+
+def register_health_resources(mcp: FastMCP) -> None:
+    """Register health resources with the MCP server."""
+
+    @mcp.resource("pcp://health", icons=[ICON_HEALTH], tags=TAGS_HEALTH)
+    async def health_summary(ctx: Context) -> str:
+        """Quick system health summary for the default target host.
+
+        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)
+
+        try:
+            cpu, memory, load = await _fetch_health_data(client)
+        except Exception as e:
+            return f"Error fetching health data: {e}"
+
+        return _format_health_summary(client, cpu, memory, load)
+
+    @mcp.resource("pcp://host/{hostname}/health", icons=[ICON_HEALTH], tags=TAGS_HEALTH)
+    async def host_health_summary(ctx: Context, hostname: str) -> str:
+        """System health summary for a specific host.
+
+        Returns a text summary of CPU, memory, and load status for the
+        specified hostname. Requires PCP_ALLOWED_HOSTS to be configured
+        if querying hosts other than the default target.
+        """
+        settings = get_settings(ctx)
+
+        if not settings.is_host_allowed(hostname):
+            return (
+                f"Error: Host '{hostname}' is not allowed. "
+                f"Configure PCP_ALLOWED_HOSTS to permit additional hosts."
+            )
+
+        async with get_client_for_host(ctx, hostname) as client:
+            try:
+                cpu, memory, load = await _fetch_health_data(client)
+            except Exception as e:
+                return f"Error fetching health data from {hostname}: {e}"
+
+            return _format_health_summary(client, cpu, memory, load)

pcp_mcp/server.py

@@ -7,9 +7,11 @@ from contextlib import asynccontextmanager
 from typing import Any
 
 from fastmcp import FastMCP
+from fastmcp.server.middleware.logging import StructuredLoggingMiddleware
 
 from pcp_mcp.client import PCPClient
 from pcp_mcp.config import PCPMCPSettings
+from pcp_mcp.middleware import MetricCacheMiddleware
 
 
 @asynccontextmanager
@@ -32,6 +34,7 @@ async def lifespan(mcp: FastMCP) -> AsyncIterator[dict[str, Any]]:
         target_host=settings.target_host,
         auth=settings.auth,
         timeout=settings.timeout,
+        verify=settings.verify,
     ) as client:
         yield {
             "client": client,
@@ -107,12 +110,29 @@ Tools:
 
 Resources:
 - pcp://health - Quick system health summary
+- pcp://host/{{hostname}}/health - Per-host health summary (template)
+- pcp://metric/{{name}}/info - Detailed metric metadata (template)
 - pcp://metrics/common - Catalog of commonly used metrics
 - pcp://namespaces - Dynamically discovered metric namespaces
+
+Prompts (invoke for guided troubleshooting workflows):
+- diagnose_slow_system: Complete slowness investigation
+- investigate_memory_usage: Memory pressure analysis
+- find_io_bottleneck: Disk I/O troubleshooting
+- analyze_cpu_usage: CPU utilization analysis
+- check_network_performance: Network saturation detection
 """,
         lifespan=lifespan,
     )
 
+    mcp.add_middleware(
+        StructuredLoggingMiddleware(
+            include_payload_length=True,
+            estimate_payload_tokens=True,
+        )
+    )
+    mcp.add_middleware(MetricCacheMiddleware())
+
     from pcp_mcp.prompts import register_prompts
     from pcp_mcp.resources import register_resources
     from pcp_mcp.tools import register_tools

pcp_mcp/tools/AGENTS.md

@@ -0,0 +1,61 @@
+# MCP Tools
+
+## OVERVIEW
+
+MCP tool implementations. Two modules: metrics (query/search/describe) and system (snapshot/top).
+
+## STRUCTURE
+
+```
+tools/
+├── __init__.py    # register_tools() → calls both modules
+├── metrics.py     # query_metrics, search_metrics, describe_metric
+└── system.py      # get_system_snapshot, get_process_top
+```
+
+## REGISTRATION PATTERN
+
+```python
+def register_metrics_tools(mcp: FastMCP) -> None:
+    @mcp.tool()
+    async def query_metrics(
+        ctx: Context,
+        names: Annotated[list[str], Field(description="Metric names to fetch")],
+    ) -> list[MetricValue]:
+        client = get_client(ctx)
+        # ...
+```
+
+## TOOL REQUIREMENTS
+
+1. **Decorator**: `@mcp.tool()`
+2. **Context**: First param is `ctx: Context`
+3. **Annotations**: `Annotated[type, Field(description="...")]` for all params
+4. **Return**: Pydantic model (not dict)
+5. **Errors**: Wrap with `handle_pcp_error()`
+
+## TOOLS
+
+| Tool | Purpose | Returns |
+|------|---------|---------|
+| `query_metrics` | Fetch raw metric values | `list[MetricValue]` |
+| `search_metrics` | Find metrics by prefix | `list[MetricSearchResult]` |
+| `describe_metric` | Get metric metadata | `MetricInfo` |
+| `get_system_snapshot` | System overview with rates | `SystemSnapshot` |
+| `quick_health` | Fast health check (cached) | `str` (formatted summary) |
+| `get_process_top` | Top N processes | `ProcessTopResult` |
+| `smart_diagnose` | AI-assisted diagnosis | `str` (LLM-generated analysis) |
+
+## ANTI-PATTERNS
+
+- **NEVER** return raw dicts (use Pydantic models)
+- **NEVER** skip `Annotated[..., Field(...)]` on params
+- **NEVER** let httpx exceptions escape (wrap with `handle_pcp_error`)
+- **NEVER** block async (no `time.sleep()`, use `asyncio.sleep()`)
+
+## ADDING NEW TOOL
+
+1. Add function in `metrics.py` or `system.py`
+2. Use `@mcp.tool()` decorator
+3. Add response model to `models.py` if needed
+4. Register in module's `register_*_tools()` function

pcp_mcp/tools/metrics.py

@@ -1,148 +1,186 @@
 """Core metric tools for querying PCP metrics."""
 
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Annotated
+from typing import TYPE_CHECKING, Annotated, Optional
 
 from fastmcp import Context
-from pydantic import Field
-
-from pcp_mcp.context import get_client
+from mcp.types import ToolAnnotations
+from pydantic import Field, TypeAdapter
+
+from pcp_mcp.context import get_client_for_host
+from pcp_mcp.icons import (
+    ICON_INFO,
+    ICON_METRICS,
+    ICON_SEARCH,
+    TAGS_DISCOVERY,
+    TAGS_METRICS,
+)
 from pcp_mcp.models import MetricInfo, MetricSearchResult, MetricValue
-from pcp_mcp.utils.extractors import extract_help_text
+from pcp_mcp.utils.extractors import extract_help_text, format_units
 
 if TYPE_CHECKING:
     from fastmcp import FastMCP
 
+TOOL_ANNOTATIONS = ToolAnnotations(readOnlyHint=True, openWorldHint=True)
+METRIC_VALUE_LIST_SCHEMA = TypeAdapter(list[MetricValue]).json_schema()
+METRIC_SEARCH_LIST_SCHEMA = TypeAdapter(list[MetricSearchResult]).json_schema()
+
 
-def register_metrics_tools(mcp: FastMCP) -> None:
+def register_metrics_tools(mcp: "FastMCP") -> None:
     """Register core metric tools with the MCP server."""
 
-    @mcp.tool()
+    @mcp.tool(
+        annotations=TOOL_ANNOTATIONS,
+        output_schema=METRIC_VALUE_LIST_SCHEMA,
+        icons=[ICON_METRICS],
+        tags=TAGS_METRICS,
+    )
     async def query_metrics(
         ctx: Context,
         names: Annotated[
             list[str],
             Field(description="List of PCP metric names to fetch (e.g., ['kernel.all.load'])"),
         ],
+        host: Annotated[
+            Optional[str],
+            Field(description="Target pmcd host to query (default: server's configured target)"),
+        ] = None,
     ) -> 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)
+        Examples:
+            query_metrics(["kernel.all.load"]) - Get load averages
+            query_metrics(["mem.util.available", "mem.physmem"]) - Get memory stats
+            query_metrics(["hinv.ncpu"]) - Get CPU count
+            query_metrics(["kernel.all.load"], host="web1.example.com") - Query remote host
 
-        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)
+        Warning: CPU, disk, and network metrics are counters (cumulative since boot).
+        Use get_system_snapshot() instead for rates.
+        """
+        from pcp_mcp.errors import handle_pcp_error
 
-                results.append(
-                    MetricValue(
-                        name=metric_name,
-                        value=value,
-                        instance=instance_name,
+        async with get_client_for_host(ctx, host) as client:
+            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
+            return results
 
-    @mcp.tool()
+    @mcp.tool(
+        annotations=TOOL_ANNOTATIONS,
+        output_schema=METRIC_SEARCH_LIST_SCHEMA,
+        icons=[ICON_SEARCH],
+        tags=TAGS_METRICS | TAGS_DISCOVERY,
+    )
     async def search_metrics(
         ctx: Context,
         pattern: Annotated[
             str,
             Field(description="Metric name prefix to search for (e.g., 'kernel.all', 'mem')"),
         ],
+        host: Annotated[
+            Optional[str],
+            Field(description="Target pmcd host to query (default: server's configured target)"),
+        ] = None,
     ) -> list[MetricSearchResult]:
         """Find PCP metrics matching a name pattern.
 
         Use this to discover available metrics before querying them.
         Returns metric names and brief descriptions.
+
+        Examples:
+            search_metrics("kernel.all") - Find kernel-wide metrics
+            search_metrics("mem.util") - Find memory utilization metrics
+            search_metrics("disk.dev") - Find per-disk metrics
+            search_metrics("network.interface") - Find per-interface metrics
+            search_metrics("kernel", host="db1.example.com") - Search on remote host
         """
         from pcp_mcp.errors import handle_pcp_error
 
-        client = get_client(ctx)
+        async with get_client_for_host(ctx, host) as client:
+            try:
+                metrics = await client.search(pattern)
+            except Exception as e:
+                raise handle_pcp_error(e, "searching metrics") from e
 
-        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()
+            return [
+                MetricSearchResult(
+                    name=m.get("name", ""),
+                    help_text=extract_help_text(m),
+                )
+                for m in metrics
+            ]
+
+    @mcp.tool(
+        annotations=TOOL_ANNOTATIONS,
+        output_schema=MetricInfo.model_json_schema(),
+        icons=[ICON_INFO],
+        tags=TAGS_METRICS | TAGS_DISCOVERY,
+    )
     async def describe_metric(
         ctx: Context,
         name: Annotated[
             str,
             Field(description="Full PCP metric name (e.g., 'kernel.all.cpu.user')"),
         ],
+        host: Annotated[
+            Optional[str],
+            Field(description="Target pmcd host to query (default: server's configured target)"),
+        ] = None,
     ) -> 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.
+
+        Examples:
+            describe_metric("kernel.all.load") - Learn about load average semantics
+            describe_metric("mem.util.available") - Understand available memory
+            describe_metric("disk.all.read_bytes") - Check if metric is counter vs instant
+            describe_metric("kernel.all.load", host="web1.example.com") - Describe on remote
         """
         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"
+        async with get_client_for_host(ctx, host) as client:
+            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"),
+            )