pcp-mcp 0.1.0__py3-none-any.whl

pcp_mcp/__init__.py

@@ -0,0 +1,59 @@
+"""PCP MCP Server - Performance Co-Pilot metrics via Model Context Protocol."""
+
+from __future__ import annotations
+
+import argparse
+import os
+
+
+def main() -> None:
+    """Run the PCP MCP server."""
+    parser = argparse.ArgumentParser(
+        description="PCP MCP Server - Performance Co-Pilot Metrics",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Environment Variables:
+  PCP_HOST          pmproxy host (default: localhost)
+  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_TIMEOUT       Request timeout in seconds (default: 30)
+  PCP_USERNAME      HTTP basic auth user (optional)
+  PCP_PASSWORD      HTTP basic auth password (optional)
+
+Examples:
+  # Monitor localhost (default)
+  pcp-mcp
+
+  # Monitor a remote host
+  PCP_TARGET_HOST=webserver1.example.com pcp-mcp
+
+  # Connect to pmproxy on a different host
+  PCP_HOST=metrics.example.com pcp-mcp
+
+  # Use SSE transport
+  pcp-mcp --transport sse
+""",
+    )
+    parser.add_argument(
+        "--target-host",
+        help="Target pmcd host to monitor (overrides PCP_TARGET_HOST)",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["stdio", "sse", "streamable-http"],
+        default="stdio",
+        help="Transport protocol (default: stdio)",
+    )
+    args = parser.parse_args()
+
+    if args.target_host:
+        os.environ["PCP_TARGET_HOST"] = args.target_host
+
+    from pcp_mcp.server import create_server
+
+    server = create_server()
+    server.run(transport=args.transport)
+
+
+__all__ = ["main"]

pcp_mcp/client.py

@@ -0,0 +1,246 @@
+"""Async client for pmproxy REST API."""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+
+if sys.version_info >= (3, 11):
+    from typing import Self
+else:
+    from typing_extensions import Self
+
+import httpx
+
+
+class PCPClient:
+    """Async client for pmproxy REST API.
+
+    Handles PMAPI context management and metric fetching via the pmproxy
+    REST API endpoints.
+
+    Args:
+        base_url: Base URL for pmproxy (e.g., http://localhost:44322).
+        target_host: Which pmcd host to connect to (passed as hostspec).
+        auth: Optional HTTP basic auth tuple (username, password).
+        timeout: Request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        target_host: str = "localhost",
+        auth: tuple[str, str] | None = None,
+        timeout: float = 30.0,
+    ) -> None:
+        """Initialize the PCP client."""
+        self._base_url = base_url
+        self._target_host = target_host
+        self._auth = auth
+        self._timeout = timeout
+        self._client: httpx.AsyncClient | None = None
+        self._context_id: int | None = None
+
+    async def __aenter__(self) -> Self:
+        """Enter async context and establish pmapi context."""
+        self._client = httpx.AsyncClient(
+            base_url=self._base_url,
+            auth=self._auth,
+            timeout=self._timeout,
+        )
+        resp = await self._client.get(
+            "/pmapi/context",
+            params={"hostspec": self._target_host},
+        )
+        resp.raise_for_status()
+        self._context_id = resp.json()["context"]
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: object,
+    ) -> None:
+        """Exit async context and close httpx client."""
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+
+    @property
+    def target_host(self) -> str:
+        """The pmcd host this client is connected to."""
+        return self._target_host
+
+    @property
+    def context_id(self) -> int | None:
+        """The pmapi context ID, or None if not connected."""
+        return self._context_id
+
+    async def _recreate_context(self) -> None:
+        """Recreate the pmapi context after expiration."""
+        if self._client is None:
+            raise RuntimeError("Client not connected. Use async with context.")
+        resp = await self._client.get(
+            "/pmapi/context",
+            params={"hostspec": self._target_host},
+        )
+        resp.raise_for_status()
+        self._context_id = resp.json()["context"]
+
+    async def _request_with_retry(self, method: str, **kwargs) -> httpx.Response:
+        """Make a request, recreating context on expiration errors.
+
+        Args:
+            method: HTTP method to call.
+            **kwargs: Arguments to pass to the request.
+
+        Returns:
+            The HTTP response.
+
+        Raises:
+            RuntimeError: If client is not connected.
+            httpx.HTTPStatusError: If the request fails after retry.
+        """
+        if self._client is None:
+            raise RuntimeError("Client not connected. Use async with context.")
+
+        resp = await self._client.request(method, **kwargs)
+
+        if resp.status_code == 400:
+            data = resp.json()
+            if "unknown context identifier" in data.get("message", ""):
+                await self._recreate_context()
+                kwargs["params"]["context"] = self._context_id
+                resp = await self._client.request(method, **kwargs)
+
+        return resp
+
+    async def fetch(self, metric_names: list[str]) -> dict:
+        """Fetch current values for metrics.
+
+        Args:
+            metric_names: List of PCP metric names to fetch.
+
+        Returns:
+            Raw JSON response from pmproxy /pmapi/fetch endpoint.
+
+        Raises:
+            RuntimeError: If client is not connected.
+            httpx.HTTPStatusError: If the request fails.
+        """
+        resp = await self._request_with_retry(
+            "GET",
+            url="/pmapi/fetch",
+            params={"context": self._context_id, "names": ",".join(metric_names)},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    async def search(self, pattern: str) -> list[dict]:
+        """Search for metrics matching pattern.
+
+        Args:
+            pattern: Metric name prefix to search for (e.g., "kernel.all").
+
+        Returns:
+            List of metric metadata dicts from pmproxy.
+
+        Raises:
+            RuntimeError: If client is not connected.
+            httpx.HTTPStatusError: If the request fails.
+        """
+        resp = await self._request_with_retry(
+            "GET",
+            url="/pmapi/metric",
+            params={"context": self._context_id, "prefix": pattern},
+        )
+        resp.raise_for_status()
+        return resp.json().get("metrics", [])
+
+    async def describe(self, metric_name: str) -> dict:
+        """Get metric metadata.
+
+        Args:
+            metric_name: Full PCP metric name.
+
+        Returns:
+            Metric metadata dict, or empty dict if not found.
+
+        Raises:
+            RuntimeError: If client is not connected.
+            httpx.HTTPStatusError: If the request fails.
+        """
+        resp = await self._request_with_retry(
+            "GET",
+            url="/pmapi/metric",
+            params={"context": self._context_id, "names": metric_name},
+        )
+        resp.raise_for_status()
+        metrics = resp.json().get("metrics", [])
+        return metrics[0] if metrics else {}
+
+    async def fetch_with_rates(
+        self,
+        metric_names: list[str],
+        counter_metrics: set[str],
+        sample_interval: float = 1.0,
+    ) -> dict[str, dict]:
+        """Fetch metrics, calculating rates for counters.
+
+        Takes two samples separated by sample_interval seconds.
+        Counter metrics are converted to per-second rates.
+        Gauge metrics return the second sample's value.
+
+        Args:
+            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.
+
+        Returns:
+            Dict mapping metric name to {value, instances} where value/instances
+            contain the rate (for counters) or instant value (for gauges).
+        """
+        t1 = await self.fetch(metric_names)
+        await asyncio.sleep(sample_interval)
+        t2 = await self.fetch(metric_names)
+
+        ts1 = t1.get("timestamp", 0.0)
+        ts2 = t2.get("timestamp", 0.0)
+        if isinstance(ts1, dict):
+            ts1 = ts1.get("s", 0) + ts1.get("us", 0) / 1e6
+        if isinstance(ts2, dict):
+            ts2 = ts2.get("s", 0) + ts2.get("us", 0) / 1e6
+        elapsed = ts2 - ts1 if ts2 > ts1 else sample_interval
+
+        results: dict[str, dict] = {}
+
+        values_t1 = {v.get("name"): v for v in t1.get("values", [])}
+        values_t2 = {v.get("name"): v for v in t2.get("values", [])}
+
+        for metric_name in metric_names:
+            v1_data = values_t1.get(metric_name, {})
+            v2_data = values_t2.get(metric_name, {})
+
+            instances_t1 = {
+                inst.get("instance", -1): inst.get("value", 0)
+                for inst in v1_data.get("instances", [])
+            }
+            instances_t2 = {
+                inst.get("instance", -1): inst.get("value", 0)
+                for inst in v2_data.get("instances", [])
+            }
+
+            if metric_name in counter_metrics:
+                computed: dict[str | int, float] = {}
+                for inst_id, val2 in instances_t2.items():
+                    val1 = instances_t1.get(inst_id, val2)
+                    delta = val2 - val1
+                    if delta < 0:
+                        delta = val2
+                    computed[inst_id] = delta / elapsed
+                results[metric_name] = {"instances": computed, "is_rate": True}
+            else:
+                results[metric_name] = {"instances": instances_t2, "is_rate": False}
+
+        return results

pcp_mcp/config.py

@@ -0,0 +1,50 @@
+"""Configuration for the PCP MCP server."""
+
+from __future__ import annotations
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class PCPMCPSettings(BaseSettings):
+    """Configuration for the PCP MCP server.
+
+    Attributes:
+        host: pmproxy host.
+        port: pmproxy port.
+        use_tls: Use HTTPS for pmproxy connection.
+        timeout: Request timeout in seconds.
+        target_host: Target pmcd host to monitor (can be remote hostname).
+        username: HTTP basic auth user.
+        password: HTTP basic auth password.
+    """
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_prefix="PCP_",
+        extra="ignore",
+    )
+
+    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")
+    timeout: float = Field(default=30.0, description="Request timeout in seconds")
+    target_host: str = Field(
+        default="localhost",
+        description="Target pmcd host to monitor (can be remote hostname)",
+    )
+    username: str | None = Field(default=None, description="HTTP basic auth user")
+    password: str | None = Field(default=None, description="HTTP basic auth password")
+
+    @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}"
+
+    @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

pcp_mcp/context.py

@@ -0,0 +1,57 @@
+"""Context helpers for safe lifespan context access."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from fastmcp import Context
+from fastmcp.exceptions import ToolError
+
+if TYPE_CHECKING:
+    from pcp_mcp.client import PCPClient
+    from pcp_mcp.config import PCPMCPSettings
+
+
+def _validate_context(ctx: Context) -> None:
+    """Validate context has lifespan_context available.
+
+    Args:
+        ctx: MCP context.
+
+    Raises:
+        ToolError: If context is not available.
+    """
+    if ctx.request_context is None or ctx.request_context.lifespan_context is None:
+        raise ToolError("Server context not available")
+
+
+def get_client(ctx: Context) -> PCPClient:
+    """Get PCPClient from context.
+
+    Args:
+        ctx: MCP context.
+
+    Returns:
+        The PCPClient instance.
+
+    Raises:
+        ToolError: If context is not available.
+    """
+    _validate_context(ctx)
+    return ctx.request_context.lifespan_context["client"]
+
+
+def get_settings(ctx: Context) -> PCPMCPSettings:
+    """Get settings from context.
+
+    Args:
+        ctx: MCP context.
+
+    Returns:
+        The PCPMCPSettings instance.
+
+    Raises:
+        ToolError: If context is not available.
+    """
+    _validate_context(ctx)
+    return ctx.request_context.lifespan_context["settings"]

pcp_mcp/errors.py

@@ -0,0 +1,47 @@
+"""Error mapping from httpx to MCP ToolErrors."""
+
+from __future__ import annotations
+
+import httpx
+from fastmcp.exceptions import ToolError
+
+
+class PCPError(Exception):
+    """Base PCP error."""
+
+
+class PCPConnectionError(PCPError):
+    """Cannot connect to pmproxy."""
+
+
+class PCPMetricNotFoundError(PCPError):
+    """Metric does not exist."""
+
+
+def handle_pcp_error(e: Exception, operation: str) -> ToolError:
+    """Convert PCP/httpx exceptions to MCP ToolErrors.
+
+    Args:
+        e: The exception to convert.
+        operation: Description of the operation that failed.
+
+    Returns:
+        A ToolError with an appropriate message.
+    """
+    match e:
+        case httpx.ConnectError():
+            return ToolError("Cannot connect to pmproxy. Is it running? (systemctl start pmproxy)")
+        case httpx.HTTPStatusError() as he if he.response.status_code == 400:
+            return ToolError(f"Bad request during {operation}: {he.response.text}")
+        case httpx.HTTPStatusError() as he if he.response.status_code == 404:
+            return ToolError(f"Metric not found during {operation}")
+        case httpx.HTTPStatusError() as he:
+            return ToolError(f"pmproxy error ({he.response.status_code}): {he.response.text}")
+        case httpx.TimeoutException():
+            return ToolError(f"Request timed out during {operation}")
+        case PCPConnectionError():
+            return ToolError(str(e))
+        case PCPMetricNotFoundError():
+            return ToolError(f"Metric not found: {e}")
+        case _:
+            return ToolError(f"Error during {operation}: {e}")

pcp_mcp/models.py

@@ -0,0 +1,142 @@
+"""Pydantic response models for strict output schemas."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class MetricValue(BaseModel):
+    """A single metric value from PCP."""
+
+    name: str = Field(description="Full metric name")
+    value: float | int | str | None = Field(description="Metric value")
+    units: str | None = Field(default=None, description="Unit of measurement")
+    semantics: str | None = Field(default=None, description="counter, instant, or discrete")
+    instance: str | None = Field(default=None, description="Instance name if per-instance metric")
+
+
+class MetricInfo(BaseModel):
+    """Metadata about a PCP metric."""
+
+    name: str = Field(description="Full metric name")
+    type: str = Field(description="Data type (u32, u64, float, string, etc.)")
+    semantics: str = Field(description="counter, instant, or discrete")
+    units: str = Field(description="Unit of measurement")
+    help_text: str | None = Field(default=None, description="Metric help text")
+    indom: str | None = Field(default=None, description="Instance domain if per-instance")
+
+
+class MetricSearchResult(BaseModel):
+    """Result from searching for metrics."""
+
+    name: str = Field(description="Full metric name")
+    help_text: str | None = Field(default=None, description="Brief description")
+
+
+class InstancedMetric(BaseModel):
+    """Metric with per-instance values (e.g., per-CPU, per-disk)."""
+
+    name: str = Field(description="Metric name")
+    instances: dict[str, float | int] = Field(
+        description="Per-instance values, e.g., {'cpu0': 15.2, 'sda': 1000}"
+    )
+    aggregate: float | None = Field(
+        default=None, description="Optional rollup (sum/avg) for quick reference"
+    )
+
+
+class CPUMetrics(BaseModel):
+    """CPU utilization summary."""
+
+    user_percent: float = Field(description="User CPU time percentage")
+    system_percent: float = Field(description="System CPU time percentage")
+    idle_percent: float = Field(description="Idle CPU time percentage")
+    iowait_percent: float = Field(description="I/O wait percentage")
+    ncpu: int = Field(description="Number of CPUs")
+    assessment: str = Field(description="Brief interpretation of CPU state")
+
+
+class MemoryMetrics(BaseModel):
+    """Memory utilization summary."""
+
+    total_bytes: int = Field(description="Total physical memory")
+    used_bytes: int = Field(description="Used memory")
+    free_bytes: int = Field(description="Free memory")
+    available_bytes: int = Field(description="Available memory for applications")
+    cached_bytes: int = Field(description="Cached memory")
+    buffers_bytes: int = Field(description="Buffer memory")
+    swap_used_bytes: int = Field(description="Used swap space")
+    swap_total_bytes: int = Field(description="Total swap space")
+    used_percent: float = Field(description="Memory usage percentage")
+    assessment: str = Field(description="Brief interpretation of memory state")
+
+
+class DiskMetrics(BaseModel):
+    """Disk I/O summary."""
+
+    read_bytes_per_sec: float = Field(description="Read throughput in bytes/sec")
+    write_bytes_per_sec: float = Field(description="Write throughput in bytes/sec")
+    reads_per_sec: float = Field(description="Read operations per second")
+    writes_per_sec: float = Field(description="Write operations per second")
+    assessment: str = Field(description="Brief interpretation of disk I/O state")
+
+
+class NetworkMetrics(BaseModel):
+    """Network I/O summary."""
+
+    in_bytes_per_sec: float = Field(description="Inbound throughput in bytes/sec")
+    out_bytes_per_sec: float = Field(description="Outbound throughput in bytes/sec")
+    in_packets_per_sec: float = Field(description="Inbound packets per second")
+    out_packets_per_sec: float = Field(description="Outbound packets per second")
+    assessment: str = Field(description="Brief interpretation of network state")
+
+
+class LoadMetrics(BaseModel):
+    """System load summary."""
+
+    load_1m: float = Field(description="1-minute load average")
+    load_5m: float = Field(description="5-minute load average")
+    load_15m: float = Field(description="15-minute load average")
+    runnable: int = Field(description="Number of runnable processes")
+    nprocs: int = Field(description="Total number of processes")
+    assessment: str = Field(description="Brief interpretation of load state")
+
+
+class SystemSnapshot(BaseModel):
+    """Point-in-time system health overview."""
+
+    timestamp: str = Field(description="ISO8601 timestamp")
+    hostname: str = Field(description="Target host name")
+    cpu: CPUMetrics | None = Field(default=None, description="CPU metrics if requested")
+    memory: MemoryMetrics | None = Field(default=None, description="Memory metrics if requested")
+    disk: DiskMetrics | None = Field(default=None, description="Disk I/O metrics if requested")
+    network: NetworkMetrics | None = Field(
+        default=None, description="Network I/O metrics if requested"
+    )
+    load: LoadMetrics | None = Field(default=None, description="Load metrics if requested")
+
+
+class ProcessInfo(BaseModel):
+    """A process with resource consumption details."""
+
+    pid: int = Field(description="Process ID")
+    command: str = Field(description="Command name")
+    cmdline: str = Field(description="Full command line (truncated)")
+    cpu_percent: float | None = Field(default=None, description="CPU usage percentage")
+    rss_bytes: int = Field(description="Resident set size in bytes")
+    rss_percent: float = Field(description="RSS as percentage of total memory")
+    io_read_bytes_per_sec: float | None = Field(default=None, description="Read bytes/sec")
+    io_write_bytes_per_sec: float | None = Field(default=None, description="Write bytes/sec")
+
+
+class ProcessTopResult(BaseModel):
+    """Top processes by resource consumption."""
+
+    timestamp: str = Field(description="ISO8601 timestamp")
+    hostname: str = Field(description="Target host name")
+    sort_by: str = Field(description="Resource used for sorting")
+    sample_interval: float = Field(description="Sampling interval used")
+    processes: list[ProcessInfo] = Field(description="Top processes sorted by requested resource")
+    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")