pcp-mcp 1.3.2__py3-none-any.whl → 1.4.0__py3-none-any.whl

pcp_mcp/prompts/network.py

@@ -0,0 +1,67 @@
+"""Check network performance prompt."""
+
+from __future__ import annotations
+
+from fastmcp.prompts import prompt
+
+from pcp_mcp.icons import ICON_NETWORK, TAGS_NETWORK
+
+
+@prompt(icons=[ICON_NETWORK], tags=TAGS_NETWORK)
+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/server.py

@@ -4,10 +4,12 @@ from __future__ import annotations
 
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
+from pathlib import Path
 from typing import Any
 
 from fastmcp import FastMCP
 from fastmcp.server.middleware.logging import StructuredLoggingMiddleware
+from fastmcp.server.providers import FileSystemProvider
 
 from pcp_mcp.client import PCPClient
 from pcp_mcp.config import PCPMCPSettings
@@ -126,10 +128,12 @@ Prompts (invoke for guided troubleshooting workflows):
     )
     mcp.add_middleware(MetricCacheMiddleware())
 
-    from pcp_mcp.prompts import register_prompts
-    from pcp_mcp.tools import register_tools
-
-    register_tools(mcp)
-    register_prompts(mcp)
+    # Auto-discover tools and prompts from filesystem
+    base_dir = Path(__file__).parent
+    provider = FileSystemProvider(
+        root=base_dir,
+        reload=False,
+    )
+    mcp.add_provider(provider)
 
     return mcp

pcp_mcp/tools/__init__.py

@@ -14,8 +14,24 @@ def register_tools(mcp: FastMCP) -> None:
     Args:
         mcp: The FastMCP server instance.
     """
-    from pcp_mcp.tools.metrics import register_metrics_tools
-    from pcp_mcp.tools.system import register_system_tools
+    from pcp_mcp.tools.metrics import (
+        describe_metric,
+        query_metrics,
+        search_metrics,
+    )
+    from pcp_mcp.tools.system import (
+        get_filesystem_usage,
+        get_process_top,
+        get_system_snapshot,
+        quick_health,
+        smart_diagnose,
+    )
 
-    register_metrics_tools(mcp)
-    register_system_tools(mcp)
+    mcp.add_tool(query_metrics)
+    mcp.add_tool(search_metrics)
+    mcp.add_tool(describe_metric)
+    mcp.add_tool(get_system_snapshot)
+    mcp.add_tool(quick_health)
+    mcp.add_tool(get_process_top)
+    mcp.add_tool(smart_diagnose)
+    mcp.add_tool(get_filesystem_usage)

pcp_mcp/tools/metrics.py

@@ -1,11 +1,16 @@
 """Core metric tools for querying PCP metrics."""
 
-from typing import TYPE_CHECKING, Annotated, Optional
+import json
+from typing import Annotated, Optional
 
 from fastmcp import Context
+from fastmcp.tools import tool
+from fastmcp.tools.tool import ToolResult
 from mcp.types import ToolAnnotations
 from pydantic import Field
 
+__all__ = ["query_metrics", "search_metrics", "describe_metric"]
+
 from pcp_mcp.context import get_client_for_host
 from pcp_mcp.icons import (
     ICON_INFO,
@@ -19,171 +24,180 @@ from pcp_mcp.models import (
     MetricSearchResult,
     MetricSearchResultList,
     MetricValue,
-    MetricValueList,
 )
 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)
 
 
-def register_metrics_tools(mcp: "FastMCP") -> None:
-    """Register core metric tools with the MCP server."""
-
-    @mcp.tool(
-        annotations=TOOL_ANNOTATIONS,
-        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,
-    ) -> MetricValueList:
-        """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.
-
-        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
-
-        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
-
-        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,
-                        )
+@tool(
+    annotations=TOOL_ANNOTATIONS,
+    icons=[ICON_METRICS],
+    tags=TAGS_METRICS,
+    timeout=30.0,
+)
+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,
+) -> ToolResult:
+    """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.
+
+    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
+
+    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
+
+    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 MetricValueList(metrics=results)
-
-    @mcp.tool(
-        annotations=TOOL_ANNOTATIONS,
-        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,
-    ) -> MetricSearchResultList:
-        """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
-
-        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
-
-            results = [
-                MetricSearchResult(
-                    name=m.get("name", ""),
-                    help_text=extract_help_text(m),
                 )
-                for m in metrics
-            ]
-            return MetricSearchResultList(results=results)
-
-    @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
-
-        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"),
+
+        return ToolResult(
+            content=json.dumps([v.model_dump() for v in results]),
+            structured_content={"metrics": [v.model_dump() for v in results]},
+        )
+
+
+@tool(
+    annotations=TOOL_ANNOTATIONS,
+    icons=[ICON_SEARCH],
+    tags=TAGS_METRICS | TAGS_DISCOVERY,
+    timeout=30.0,
+)
+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,
+) -> ToolResult:
+    """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
+
+    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
+
+        results = [
+            MetricSearchResult(
+                name=m.get("name", ""),
+                help_text=extract_help_text(m),
             )
+            for m in metrics
+        ]
+        result = MetricSearchResultList(results=results)
+        return ToolResult(
+            content=result.model_dump_json(),
+            structured_content=result.model_dump(),
+        )
+
+
+@tool(
+    annotations=TOOL_ANNOTATIONS,
+    output_schema=MetricInfo.model_json_schema(),
+    icons=[ICON_INFO],
+    tags=TAGS_METRICS | TAGS_DISCOVERY,
+    timeout=30.0,
+)
+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,
+) -> ToolResult:
+    """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
+
+    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}")
+
+        result = 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"),
+        )
+        return ToolResult(
+            content=result.model_dump_json(),
+            structured_content=result.model_dump(),
+        )