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

pcp_mcp/AGENTS.md

@@ -0,0 +1,70 @@
+# pcp_mcp Core Package
+
+## OVERVIEW
+
+Core MCP server package. Entry point, HTTP client, configuration, models, error handling.
+
+## STRUCTURE
+
+```
+pcp_mcp/
+├── __init__.py     # CLI entry (main() with argparse)
+├── server.py       # FastMCP setup, lifespan context
+├── client.py       # PCPClient async httpx wrapper
+├── config.py       # PCPMCPSettings (Pydantic)
+├── models.py       # Response models (SystemSnapshot, ProcessInfo, etc.)
+├── errors.py       # Exception → ToolError mapping
+├── context.py      # get_client(), get_settings() helpers
+├── middleware.py   # Request caching middleware
+├── icons.py        # System assessment icons (emoji mappings)
+├── tools/          # MCP tools (see tools/AGENTS.md)
+├── resources/      # MCP resources (health.py, catalog.py)
+├── utils/          # Extractors, builders
+└── prompts/        # LLM system prompts
+```
+
+## KEY PATTERNS
+
+### Server Lifespan
+```python
+@asynccontextmanager
+async def lifespan(mcp: FastMCP) -> AsyncIterator[dict]:
+    async with PCPClient(...) as client:
+        yield {"client": client, "settings": settings}
+```
+Tools access via `ctx.request_context.lifespan_context["client"]`.
+
+### Client Rate Calculation
+`fetch_with_rates()` takes two samples, calculates per-second rates for counters.
+Handles counter wrap-around (reset to 0) gracefully.
+
+### Error Mapping
+```python
+try:
+    result = await client.fetch(names)
+except Exception as e:
+    raise handle_pcp_error(e, "fetching metrics") from e
+```
+
+### Configuration
+Pydantic settings with `env_prefix="PCP_"`. Computed properties: `base_url`, `auth`.
+
+## WHERE TO LOOK
+
+| Task | File | Notes |
+|------|------|-------|
+| Add CLI flag | `__init__.py` | argparse in `main()` |
+| Change transport | `__init__.py` | `server.run(transport=...)` |
+| Add env var | `config.py` | Add field with `Field(default=...)` |
+| New response type | `models.py` | Inherit `BaseModel` |
+| Map new exception | `errors.py` | Add case to `handle_pcp_error()` |
+| Access client in tool | `context.py` | Use `get_client(ctx)` |
+| Add caching | `middleware.py` | Request caching layer |
+| System icons | `icons.py` | Assessment emoji mappings |
+
+## ANTI-PATTERNS
+
+- **NEVER** call `client.fetch()` for counter metrics expecting rates
+- **NEVER** use client outside `async with` context
+- **NEVER** log credentials from settings
+- **ALWAYS** use `handle_pcp_error()` for exception wrapping

pcp_mcp/__init__.py

@@ -17,9 +17,13 @@ Environment Variables:
   PCP_PORT          pmproxy port (default: 44322)
   PCP_TARGET_HOST   Target pmcd host to monitor (default: localhost)
   PCP_USE_TLS       Use HTTPS for pmproxy connection (default: false)
+  PCP_TLS_VERIFY    Verify TLS certificates (default: true)
+  PCP_TLS_CA_BUNDLE Path to custom CA bundle for TLS (optional)
   PCP_TIMEOUT       Request timeout in seconds (default: 30)
   PCP_USERNAME      HTTP basic auth user (optional)
   PCP_PASSWORD      HTTP basic auth password (optional)
+  PCP_ALLOWED_HOSTS Comma-separated hostspecs allowed via host parameter (optional)
+                    If not set, only target_host is allowed. Use '*' for any host.
 
 Examples:
   # Monitor localhost (default)

pcp_mcp/client.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import asyncio
 import sys
+from typing import TYPE_CHECKING
 
 if sys.version_info >= (3, 11):
     from typing import Self
@@ -12,6 +13,12 @@ else:
 
 import httpx
 
+if TYPE_CHECKING:
+    from collections.abc import Callable, Coroutine
+    from typing import Any
+
+    ProgressCallback = Callable[[float, float, str], Coroutine[Any, Any, None]]
+
 
 class PCPClient:
     """Async client for pmproxy REST API.
@@ -24,6 +31,7 @@ class PCPClient:
         target_host: Which pmcd host to connect to (passed as hostspec).
         auth: Optional HTTP basic auth tuple (username, password).
         timeout: Request timeout in seconds.
+        verify: TLS verification (True, False, or path to CA bundle).
     """
 
     def __init__(
@@ -32,12 +40,14 @@ class PCPClient:
         target_host: str = "localhost",
         auth: tuple[str, str] | None = None,
         timeout: float = 30.0,
+        verify: bool | str = True,
     ) -> None:
         """Initialize the PCP client."""
         self._base_url = base_url
         self._target_host = target_host
         self._auth = auth
         self._timeout = timeout
+        self._verify = verify
         self._client: httpx.AsyncClient | None = None
         self._context_id: int | None = None
 
@@ -47,6 +57,7 @@ class PCPClient:
             base_url=self._base_url,
             auth=self._auth,
             timeout=self._timeout,
+            verify=self._verify,
         )
         resp = await self._client.get(
             "/pmapi/context",
@@ -185,6 +196,7 @@ class PCPClient:
         metric_names: list[str],
         counter_metrics: set[str],
         sample_interval: float = 1.0,
+        progress_callback: ProgressCallback | None = None,
     ) -> dict[str, dict]:
         """Fetch metrics, calculating rates for counters.
 
@@ -196,15 +208,31 @@ class PCPClient:
             metric_names: List of PCP metric names to fetch.
             counter_metrics: Set of metric names that are counters.
             sample_interval: Seconds between samples for rate calculation.
+            progress_callback: Optional async callback for progress updates.
+                Called with (current, total, message) during long operations.
 
         Returns:
             Dict mapping metric name to {value, instances} where value/instances
             contain the rate (for counters) or instant value (for gauges).
         """
+        if progress_callback:
+            await progress_callback(0, 100, "Collecting first sample...")
+
         t1 = await self.fetch(metric_names)
+
+        if progress_callback:
+            await progress_callback(20, 100, f"Waiting {sample_interval}s for rate calculation...")
+
         await asyncio.sleep(sample_interval)
+
+        if progress_callback:
+            await progress_callback(70, 100, "Collecting second sample...")
+
         t2 = await self.fetch(metric_names)
 
+        if progress_callback:
+            await progress_callback(90, 100, "Computing rates...")
+
         ts1 = t1.get("timestamp", 0.0)
         ts2 = t2.get("timestamp", 0.0)
         if isinstance(ts1, dict):

pcp_mcp/config.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from pydantic import Field
+from pydantic import Field, computed_field
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
@@ -28,6 +28,14 @@ class PCPMCPSettings(BaseSettings):
     host: str = Field(default="localhost", description="pmproxy host")
     port: int = Field(default=44322, description="pmproxy port")
     use_tls: bool = Field(default=False, description="Use HTTPS for pmproxy connection")
+    tls_verify: bool = Field(
+        default=True,
+        description="Verify TLS certificates when use_tls is enabled",
+    )
+    tls_ca_bundle: str | None = Field(
+        default=None,
+        description="Path to custom CA bundle for TLS verification",
+    )
     timeout: float = Field(default=30.0, description="Request timeout in seconds")
     target_host: str = Field(
         default="localhost",
@@ -35,16 +43,65 @@ class PCPMCPSettings(BaseSettings):
     )
     username: str | None = Field(default=None, description="HTTP basic auth user")
     password: str | None = Field(default=None, description="HTTP basic auth password")
+    allowed_hosts: list[str] | None = Field(
+        default=None,
+        description=(
+            "Allowlist of hostspecs that can be queried via the host parameter. "
+            "If None, only the configured target_host is allowed (default). "
+            "Set to ['*'] to allow any host (use with caution)."
+        ),
+    )
 
+    @computed_field
     @property
     def base_url(self) -> str:
         """URL for connecting to pmproxy."""
         scheme = "https" if self.use_tls else "http"
         return f"{scheme}://{self.host}:{self.port}"
 
+    @computed_field
     @property
     def auth(self) -> tuple[str, str] | None:
         """Auth tuple for httpx, or None if no auth configured."""
         if self.username and self.password:
             return (self.username, self.password)
         return None
+
+    @computed_field
+    @property
+    def verify(self) -> bool | str:
+        """TLS verification setting for httpx.
+
+        Returns:
+            False if verification disabled, path to CA bundle if specified,
+            or True for default system verification.
+        """
+        if not self.tls_verify:
+            return False
+        if self.tls_ca_bundle:
+            return self.tls_ca_bundle
+        return True
+
+    def is_host_allowed(self, host: str) -> bool:
+        """Check if a host is allowed by the allowlist.
+
+        Args:
+            host: The hostspec to validate.
+
+        Returns:
+            True if the host is allowed, False otherwise.
+        """
+        # Always allow the configured target_host
+        if host == self.target_host:
+            return True
+
+        # If no allowlist configured, only target_host is allowed
+        if self.allowed_hosts is None:
+            return False
+
+        # Wildcard allows everything
+        if "*" in self.allowed_hosts:
+            return True
+
+        # Check exact match in allowlist
+        return host in self.allowed_hosts

pcp_mcp/context.py

@@ -2,13 +2,16 @@
 
 from __future__ import annotations
 
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
 from typing import TYPE_CHECKING
 
 from fastmcp import Context
 from fastmcp.exceptions import ToolError
 
+from pcp_mcp.client import PCPClient
+
 if TYPE_CHECKING:
-    from pcp_mcp.client import PCPClient
     from pcp_mcp.config import PCPMCPSettings
 
 
@@ -38,6 +41,8 @@ def get_client(ctx: Context) -> PCPClient:
         ToolError: If context is not available.
     """
     _validate_context(ctx)
+    assert ctx.request_context is not None
+    assert ctx.request_context.lifespan_context is not None
     return ctx.request_context.lifespan_context["client"]
 
 
@@ -54,4 +59,46 @@ def get_settings(ctx: Context) -> PCPMCPSettings:
         ToolError: If context is not available.
     """
     _validate_context(ctx)
+    assert ctx.request_context is not None
+    assert ctx.request_context.lifespan_context is not None
     return ctx.request_context.lifespan_context["settings"]
+
+
+@asynccontextmanager
+async def get_client_for_host(ctx: Context, host: str | None = None) -> AsyncIterator[PCPClient]:
+    """Get a PCPClient for the specified host.
+
+    If host is None or matches the configured target_host, yields the existing
+    lifespan client. Otherwise, creates a new ad-hoc client for the specified
+    hostspec and cleans it up on exit.
+
+    Args:
+        ctx: MCP context.
+        host: Target pmcd hostspec to query. None uses the default.
+
+    Yields:
+        PCPClient connected to the specified host.
+
+    Raises:
+        ToolError: If context is not available, host is not allowed, or host is unreachable.
+    """
+    settings = get_settings(ctx)
+
+    if host is None or host == settings.target_host:
+        yield get_client(ctx)
+        return
+
+    if not settings.is_host_allowed(host):
+        raise ToolError(
+            f"Host '{host}' is not in the allowed hosts list. "
+            f"Configure PCP_ALLOWED_HOSTS to permit additional hosts."
+        )
+
+    async with PCPClient(
+        base_url=settings.base_url,
+        target_host=host,
+        auth=settings.auth,
+        timeout=settings.timeout,
+        verify=settings.verify,
+    ) as client:
+        yield client

pcp_mcp/icons.py

@@ -0,0 +1,31 @@
+"""Centralized icons and tags for MCP components."""
+
+from __future__ import annotations
+
+from mcp.types import Icon
+
+ICON_METRICS = Icon(src="data:,📊", mimeType="text/plain")
+ICON_SEARCH = Icon(src="data:,🔍", mimeType="text/plain")
+ICON_INFO = Icon(src="data:,📋", mimeType="text/plain")
+ICON_SYSTEM = Icon(src="data:,💻", mimeType="text/plain")
+ICON_PROCESS = Icon(src="data:,⚙️", mimeType="text/plain")
+ICON_HEALTH = Icon(src="data:,💚", mimeType="text/plain")
+ICON_CATALOG = Icon(src="data:,📚", mimeType="text/plain")
+ICON_NAMESPACE = Icon(src="data:,🗂️", mimeType="text/plain")
+ICON_DIAGNOSE = Icon(src="data:,🔬", mimeType="text/plain")
+ICON_CPU = Icon(src="data:,🖥️", mimeType="text/plain")
+ICON_MEMORY = Icon(src="data:,🧠", mimeType="text/plain")
+ICON_DISK = Icon(src="data:,💾", mimeType="text/plain")
+ICON_NETWORK = Icon(src="data:,🌐", mimeType="text/plain")
+
+TAGS_METRICS = {"metrics", "pcp"}
+TAGS_SYSTEM = {"system", "monitoring", "performance"}
+TAGS_PROCESS = {"processes", "monitoring"}
+TAGS_HEALTH = {"health", "status", "summary"}
+TAGS_CATALOG = {"catalog", "reference", "documentation"}
+TAGS_DISCOVERY = {"discovery", "namespace", "exploration"}
+TAGS_CPU = {"cpu", "troubleshooting", "performance"}
+TAGS_MEMORY = {"memory", "troubleshooting", "performance"}
+TAGS_DISK = {"disk", "io", "troubleshooting", "performance"}
+TAGS_NETWORK = {"network", "troubleshooting", "performance"}
+TAGS_DIAGNOSE = {"diagnosis", "troubleshooting", "workflow"}

pcp_mcp/middleware.py

@@ -0,0 +1,75 @@
+"""Custom middleware for pcp-mcp server."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from cachetools import TTLCache
+from fastmcp.server.middleware import Middleware
+from fastmcp.tools.tool import ToolResult
+
+if TYPE_CHECKING:
+    from fastmcp.server.middleware.middleware import CallNext, MiddlewareContext
+    from mcp import types as mt
+
+
+CACHEABLE_TOOLS = frozenset({"describe_metric", "search_metrics"})
+DEFAULT_TTL_SECONDS = 300
+DEFAULT_MAX_SIZE = 100
+
+
+class MetricCacheMiddleware(Middleware):
+    """Cache responses for describe_metric and search_metrics tools.
+
+    These tools query PCP metric metadata which changes infrequently.
+    Caching reduces pmproxy load and improves LLM response times.
+    """
+
+    def __init__(
+        self, ttl_seconds: int = DEFAULT_TTL_SECONDS, maxsize: int = DEFAULT_MAX_SIZE
+    ) -> None:
+        """Initialize the cache middleware.
+
+        Args:
+            ttl_seconds: Time-to-live for cached entries in seconds.
+            maxsize: Maximum number of entries in the cache.
+        """
+        self._cache: TTLCache[str, ToolResult] = TTLCache(maxsize=maxsize, ttl=ttl_seconds)
+
+    def _make_cache_key(self, tool_name: str, arguments: dict | None) -> str:
+        args_str = str(sorted((arguments or {}).items()))
+        return f"{tool_name}:{args_str}"
+
+    async def on_call_tool(
+        self,
+        context: MiddlewareContext[mt.CallToolRequestParams],
+        call_next: CallNext[mt.CallToolRequestParams, ToolResult],
+    ) -> ToolResult:
+        """Intercept tool calls and cache describe_metric/search_metrics responses."""
+        tool_name = context.message.name
+        arguments = context.message.arguments
+
+        if tool_name not in CACHEABLE_TOOLS:
+            return await call_next(context)
+
+        if arguments and arguments.get("host"):
+            return await call_next(context)
+
+        cache_key = self._make_cache_key(tool_name, arguments)
+
+        cached = self._cache.get(cache_key)
+        if cached is not None:
+            return cached
+
+        result = await call_next(context)
+        self._cache[cache_key] = result
+        return result
+
+    @property
+    def cache_size(self) -> int:
+        """Number of entries in the cache."""
+        return len(self._cache)
+
+    def clear_cache(self) -> None:
+        """Clear all cached entries."""
+        self._cache.clear()

pcp_mcp/models.py

@@ -140,3 +140,13 @@ class ProcessTopResult(BaseModel):
     total_memory_bytes: int = Field(description="Total system memory")
     ncpu: int = Field(description="Number of CPUs")
     assessment: str = Field(description="Brief interpretation of top processes")
+
+
+class DiagnosisResult(BaseModel):
+    """LLM-powered system diagnosis."""
+
+    timestamp: str = Field(description="ISO8601 timestamp")
+    hostname: str = Field(description="Target host name")
+    diagnosis: str = Field(description="LLM-generated analysis of system health")
+    severity: str = Field(description="Severity level: healthy, warning, or critical")
+    recommendations: list[str] = Field(description="Actionable recommendations")

pcp_mcp/prompts/__init__.py

@@ -4,6 +4,19 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
+from pcp_mcp.icons import (
+    ICON_CPU,
+    ICON_DIAGNOSE,
+    ICON_DISK,
+    ICON_MEMORY,
+    ICON_NETWORK,
+    TAGS_CPU,
+    TAGS_DIAGNOSE,
+    TAGS_DISK,
+    TAGS_MEMORY,
+    TAGS_NETWORK,
+)
+
 if TYPE_CHECKING:
     from fastmcp import FastMCP
 
@@ -15,7 +28,7 @@ def register_prompts(mcp: FastMCP) -> None:
         mcp: The FastMCP server instance.
     """
 
-    @mcp.prompt()
+    @mcp.prompt(icons=[ICON_DIAGNOSE], tags=TAGS_DIAGNOSE)
     def diagnose_slow_system() -> str:
         """Diagnose why a system is running slowly.
 
@@ -61,7 +74,7 @@ def register_prompts(mcp: FastMCP) -> None:
    - Recommendations (kill process, add RAM, optimize queries, etc.)
 """
 
-    @mcp.prompt()
+    @mcp.prompt(icons=[ICON_MEMORY], tags=TAGS_MEMORY)
     def investigate_memory_usage() -> str:
         """Investigate memory consumption and identify memory pressure.
 
@@ -113,7 +126,7 @@ def register_prompts(mcp: FastMCP) -> None:
      * Single process consuming >50% = Investigate for memory leak
 """
 
-    @mcp.prompt()
+    @mcp.prompt(icons=[ICON_DISK], tags=TAGS_DISK)
     def find_io_bottleneck() -> str:
         """Find disk I/O bottlenecks and identify processes causing high I/O.
 
@@ -174,7 +187,7 @@ def register_prompts(mcp: FastMCP) -> None:
      * Backup/batch jobs during business hours → Reschedule
 """
 
-    @mcp.prompt()
+    @mcp.prompt(icons=[ICON_CPU], tags=TAGS_CPU)
     def analyze_cpu_usage() -> str:
         """Analyze CPU utilization patterns and identify CPU-bound processes.
 
@@ -235,7 +248,7 @@ def register_prompts(mcp: FastMCP) -> None:
      * Many small processes → Reduce process spawning overhead
 """
 
-    @mcp.prompt()
+    @mcp.prompt(icons=[ICON_NETWORK], tags=TAGS_NETWORK)
     def check_network_performance() -> str:
         """Check network performance and identify bandwidth/error issues.
 

pcp_mcp/resources/catalog.py

@@ -6,6 +6,16 @@ from typing import TYPE_CHECKING
 
 from fastmcp import Context
 
+from pcp_mcp.icons import (
+    ICON_CATALOG,
+    ICON_INFO,
+    ICON_NAMESPACE,
+    TAGS_CATALOG,
+    TAGS_DISCOVERY,
+    TAGS_METRICS,
+)
+from pcp_mcp.utils.extractors import extract_help_text, format_units
+
 if TYPE_CHECKING:
     from fastmcp import FastMCP
 
@@ -17,7 +27,71 @@ def register_catalog_resources(mcp: FastMCP) -> None:
         mcp: The FastMCP server instance.
     """
 
-    @mcp.resource("pcp://metrics/common")
+    @mcp.resource(
+        "pcp://metric/{metric_name}/info",
+        icons=[ICON_INFO],
+        tags=TAGS_METRICS | TAGS_DISCOVERY,
+    )
+    async def metric_info(ctx: Context, metric_name: str) -> str:
+        """Detailed metadata for a specific PCP metric.
+
+        Returns type, semantics, units, and help text. Use to understand
+        what a metric measures and how to interpret its values.
+        """
+        from pcp_mcp.context import get_client
+        from pcp_mcp.errors import handle_pcp_error
+
+        client = get_client(ctx)
+
+        try:
+            info = await client.describe(metric_name)
+        except Exception as e:
+            raise handle_pcp_error(e, "describing metric") from e
+
+        if not info:
+            return f"# Metric Not Found\n\nNo metric named `{metric_name}` was found."
+
+        semantics = info.get("sem", "unknown")
+        metric_type = info.get("type", "unknown")
+        units = format_units(info)
+        help_text = extract_help_text(info) or "No description available."
+        indom = info.get("indom")
+
+        is_counter = semantics == "counter"
+        counter_warning = (
+            "\n\n> **Warning**: This is a counter metric (cumulative since boot). "
+            "Use `get_system_snapshot()` or `get_process_top()` for rate calculation."
+            if is_counter
+            else ""
+        )
+
+        instances_info = (
+            f"\n- **Instance Domain**: {indom} (has per-instance values)"
+            if indom and indom != "PM_INDOM_NULL"
+            else ""
+        )
+
+        return f"""# Metric: {metric_name}
+
+{help_text}{counter_warning}
+
+## Properties
+- **Type**: {metric_type}
+- **Semantics**: {semantics}
+- **Units**: {units}{instances_info}
+
+## Usage
+
+```python
+# Query current value
+query_metrics(["{metric_name}"])
+
+# Search related metrics
+search_metrics("{".".join(metric_name.split(".")[:2])}")
+```
+"""
+
+    @mcp.resource("pcp://metrics/common", icons=[ICON_CATALOG], tags=TAGS_CATALOG)
     def common_metrics_catalog() -> str:
         """Catalog of commonly used metric groups.
 
@@ -96,7 +170,7 @@ def register_catalog_resources(mcp: FastMCP) -> None:
 (counter) = Cumulative counter since boot
 """
 
-    @mcp.resource("pcp://namespaces")
+    @mcp.resource("pcp://namespaces", icons=[ICON_NAMESPACE], tags=TAGS_DISCOVERY)
     async def metric_namespaces(ctx: Context) -> str:
         """List available PCP metric namespaces discovered from the live system.