prometheus-mcp 0.1.0__py3-none-any.whl

prometheus_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""prometheus-mcp — MCP server for Prometheus metrics and observability."""
+
+__version__ = "0.1.0"

prometheus_mcp/_mcp.py

@@ -0,0 +1,55 @@
+"""Shared FastMCP instance and client cache."""
+
+from __future__ import annotations
+
+import logging
+import threading
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from prometheus_mcp.client import PrometheusClient
+
+logger = logging.getLogger(__name__)
+
+_client: PrometheusClient | None = None
+_client_lock = threading.Lock()
+
+
+@asynccontextmanager
+async def app_lifespan(_app: FastMCP) -> AsyncIterator[dict[str, Any]]:
+    """Server lifespan: close HTTP session on shutdown."""
+    logger.debug("prometheus_mcp: startup")
+    try:
+        yield {}
+    finally:
+        global _client
+        with _client_lock:
+            if _client is not None:
+                try:
+                    _client.close()
+                except Exception:
+                    pass
+                _client = None
+        logger.debug("prometheus_mcp: shutdown — HTTP session closed")
+
+
+mcp = FastMCP("prometheus_mcp", lifespan=app_lifespan)
+
+
+def get_client() -> PrometheusClient:
+    """Return a cached :class:`PrometheusClient` (thread-safe lazy-init).
+
+    FastMCP runs synchronous tools in worker threads via
+    ``anyio.to_thread.run_sync``; concurrent first-calls could otherwise
+    race on the ``_client`` global. The lock ensures exactly one instance
+    is constructed.
+    """
+    global _client
+    if _client is None:
+        with _client_lock:
+            if _client is None:  # double-checked locking
+                _client = PrometheusClient()
+    return _client

prometheus_mcp/client.py

@@ -0,0 +1,155 @@
+"""HTTP client for the Prometheus HTTP API v1.
+
+Thin wrapper around :mod:`requests` — reads config from env vars, supports
+Bearer-token auth, HTTP Basic auth, SSL-verify toggling, and exposes get().
+Errors bubble up as :class:`requests.HTTPError` and are mapped to
+user-facing messages by :mod:`prometheus_mcp.errors`.
+
+**Auth priority:** PROMETHEUS_TOKEN (Bearer) takes precedence over
+PROMETHEUS_USERNAME/PROMETHEUS_PASSWORD (Basic). If neither is set the session
+is unauthenticated — valid for many internal Prometheus deployments.
+
+**Threading model.** The client uses ``requests`` (synchronous). FastMCP
+runs synchronous ``@mcp.tool`` in a worker thread via
+``anyio.to_thread.run_sync``, so blocking HTTP calls don't block the
+asyncio event loop.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+from urllib.parse import urlparse
+
+import requests
+import urllib3
+
+from prometheus_mcp.errors import ConfigError
+
+
+def _parse_bool(value: str | bool | None, *, default: bool) -> bool:
+    """Parse an env-var boolean.
+
+    Accepts true/false/1/0/yes/no/on/off (case-insensitive). Returns
+    ``default`` when ``value`` is ``None`` or empty.
+    """
+    if value is None or value == "":
+        return default
+    if isinstance(value, bool):
+        return value
+    return str(value).strip().lower() not in ("false", "0", "no", "off")
+
+
+def _validate_url(url: str) -> str:
+    """Validate that ``url`` is a well-formed HTTP/HTTPS URL.
+
+    Returns the URL with leading/trailing whitespace and any trailing slash
+    stripped. Raises :class:`ConfigError` if the URL is missing scheme/host
+    or uses an unsupported scheme.
+    """
+    if not url:
+        raise ConfigError("PROMETHEUS_URL is not set — configure the env var (e.g. https://prometheus.example.com)")
+
+    cleaned = url.strip()
+    parsed = urlparse(cleaned)
+    if parsed.scheme not in ("http", "https"):
+        raise ConfigError(f"PROMETHEUS_URL must start with http:// or https:// (got: {url!r})")
+    if not parsed.netloc:
+        raise ConfigError(f"PROMETHEUS_URL is missing host (got: {url!r})")
+    return cleaned.rstrip("/")
+
+
+class PrometheusClient:
+    """Minimal Prometheus HTTP API v1 client.
+
+    The client reads ``PROMETHEUS_URL``, ``PROMETHEUS_TOKEN``,
+    ``PROMETHEUS_USERNAME``, ``PROMETHEUS_PASSWORD``, ``PROMETHEUS_SSL_VERIFY``
+    from the environment. Instances are safe to reuse — a single
+    :class:`requests.Session` is kept for connection pooling.
+
+    Auth selection:
+        - If ``PROMETHEUS_TOKEN`` is set → Bearer auth (ignores username/password).
+        - Else if both ``PROMETHEUS_USERNAME`` and ``PROMETHEUS_PASSWORD`` are set → Basic auth.
+        - Else → no auth (valid for internal/unauthenticated Prometheus instances).
+
+    Args:
+        url: Override ``PROMETHEUS_URL``. If ``None``, read from env.
+        token: Override ``PROMETHEUS_TOKEN``. If ``None``, read from env.
+        username: Override ``PROMETHEUS_USERNAME``. If ``None``, read from env.
+        password: Override ``PROMETHEUS_PASSWORD``. If ``None``, read from env.
+        ssl_verify: Override ``PROMETHEUS_SSL_VERIFY``. If ``None``, read from env.
+
+    Raises:
+        ConfigError: If PROMETHEUS_URL is missing or malformed.
+    """
+
+    def __init__(
+        self,
+        url: str | None = None,
+        token: str | None = None,
+        username: str | None = None,
+        password: str | None = None,
+        ssl_verify: bool | None = None,
+    ) -> None:
+        raw_url = url if url is not None else os.environ.get("PROMETHEUS_URL", "")
+        self.url = _validate_url(raw_url)
+        self.api_url = f"{self.url}/api/v1"
+
+        self.token = token if token is not None else os.environ.get("PROMETHEUS_TOKEN", "")
+        self.username = username if username is not None else os.environ.get("PROMETHEUS_USERNAME", "")
+        self.password = password if password is not None else os.environ.get("PROMETHEUS_PASSWORD", "")
+
+        if ssl_verify is None:
+            ssl_verify = _parse_bool(os.environ.get("PROMETHEUS_SSL_VERIFY"), default=True)
+        self.ssl_verify = ssl_verify
+
+        self.session = requests.Session()
+        self.session.verify = self.ssl_verify
+        self.session.headers.update(
+            {
+                "Accept": "application/json",
+                "User-Agent": "prometheus-mcp",
+            }
+        )
+        # Prometheus is typically an internal service not reachable via env proxy.
+        self.session.trust_env = False
+
+        # Auth priority: Bearer > Basic > none.
+        if self.token:
+            self.session.headers["Authorization"] = f"Bearer {self.token}"
+        elif self.username and self.password:
+            self.session.auth = (self.username, self.password)
+
+        if not self.ssl_verify:
+            urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+    def _request(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> requests.Response:
+        response = self.session.request(
+            method=method,
+            url=f"{self.api_url}{endpoint}",
+            params=params,
+            timeout=30,
+        )
+        response.raise_for_status()
+        return response
+
+    def get(self, endpoint: str, params: dict[str, Any] | None = None) -> Any:
+        """GET ``{api_url}{endpoint}`` and return parsed JSON.
+
+        Prometheus always returns JSON for 2xx responses; returns ``None`` for
+        empty bodies.
+        """
+        response = self._request("GET", endpoint, params=params)
+        if not response.content:
+            return None
+        return response.json()
+
+    def close(self) -> None:
+        """Close the underlying HTTP session (called from lifespan on shutdown)."""
+        self.session.close()

prometheus_mcp/errors.py

@@ -0,0 +1,103 @@
+"""Actionable error messages for Prometheus HTTP errors."""
+
+from __future__ import annotations
+
+import requests
+
+
+class ConfigError(ValueError):
+    """Raised when required environment variables are missing or malformed.
+
+    Subclass of :class:`ValueError` so callers can continue to use
+    ``isinstance(..., ValueError)``, but narrow enough that :func:`handle`
+    can distinguish config errors from Pydantic validation errors bubbling
+    up from tool input.
+    """
+
+
+def handle(exc: Exception, action: str) -> str:
+    """Convert an exception raised while performing ``action`` into an
+    LLM-readable string with a suggested next step.
+
+    The goal is that the agent sees *why* the call failed and *what it could
+    do about it* without needing to inspect a Python traceback.
+    """
+    if isinstance(exc, ConfigError):
+        return (
+            f"Error: configuration problem while {action} — {exc}. "
+            "Check PROMETHEUS_URL, PROMETHEUS_TOKEN, PROMETHEUS_USERNAME, PROMETHEUS_PASSWORD, "
+            "PROMETHEUS_SSL_VERIFY environment variables."
+        )
+
+    if isinstance(exc, requests.HTTPError):
+        code = exc.response.status_code if exc.response is not None else None
+        if code == 401:
+            return (
+                f"Error: authentication failed (HTTP 401) while {action}. "
+                "Verify PROMETHEUS_TOKEN (Bearer) or PROMETHEUS_USERNAME/PROMETHEUS_PASSWORD (Basic auth) "
+                "are set correctly. Many internal Prometheus instances require no auth — "
+                "try unsetting those env vars if this is an internal deployment."
+            )
+        if code == 403:
+            return (
+                f"Error: forbidden (HTTP 403) while {action}. "
+                "The provided credentials lack permission for this Prometheus resource. "
+                "Check PROMETHEUS_TOKEN or PROMETHEUS_USERNAME/PROMETHEUS_PASSWORD and "
+                "Prometheus's auth configuration."
+            )
+        if code == 404:
+            return (
+                f"Error: resource not found (HTTP 404) while {action}. "
+                "Check PROMETHEUS_URL points to a valid Prometheus instance. "
+                "Use prometheus_list_metrics to discover valid metric names."
+            )
+        if code in (400, 422):
+            body = ""
+            if exc.response is not None:
+                try:
+                    data = exc.response.json()
+                    body = data.get("error", exc.response.text[:300])
+                except Exception:
+                    body = exc.response.text[:300]
+            return (
+                f"Error: bad request (HTTP {code}) while {action}. "
+                "Prometheus rejected the parameters — check your PromQL expression syntax, "
+                "time range, or step value. "
+                f"Prometheus error: {body}"
+            )
+        if code == 429:
+            return (
+                f"Error: rate-limited (HTTP 429) while {action}. "
+                "Wait 30-60s before retrying; narrow the time range or reduce the step resolution."
+            )
+        if code is not None and 500 <= code < 600:
+            return (
+                f"Error: Prometheus server error (HTTP {code}) while {action}. "
+                "This is usually transient — retry in a few seconds; "
+                "check Prometheus health at PROMETHEUS_URL/-/healthy."
+            )
+        body = ""
+        if exc.response is not None:
+            try:
+                body = exc.response.text[:200]
+            except Exception:
+                pass
+        return f"Error: HTTP {code} while {action}. Response: {body}"
+
+    if isinstance(exc, requests.ConnectionError):
+        return (
+            f"Error: could not connect to Prometheus while {action}. "
+            "Check PROMETHEUS_URL is set and reachable (e.g. https://prometheus.example.com). "
+            "Prometheus HTTP API runs on port 9090 by default."
+        )
+
+    if isinstance(exc, requests.Timeout):
+        return (
+            f"Error: request timed out while {action}. "
+            "Check network latency and retry; narrow the time range or increase the step for range queries."
+        )
+
+    if isinstance(exc, ValueError):
+        return f"Error: invalid input while {action} — {exc}"
+
+    return f"Error: unexpected {type(exc).__name__} while {action}: {exc}"

prometheus_mcp/models.py

@@ -0,0 +1,125 @@
+"""TypedDict output schemas for every MCP tool.
+
+These schemas are read by FastMCP (``structured_output=True``) to generate
+a JSON-Schema ``outputSchema`` for each tool. Clients that support
+structured data use that schema to validate the ``structuredContent``
+payload; clients that don't use the markdown ``content`` block instead.
+
+**Python / Pydantic compat note.** We deliberately avoid
+``Required`` / ``NotRequired`` qualifiers: Pydantic 2.13+ mishandles them
+during runtime schema generation on Py < 3.12 (see
+https://errors.pydantic.dev/2.13/u/typed-dict-version). Optional fields use
+``| None`` convention; the code always sets the key (``None`` when absent).
+"""
+
+from __future__ import annotations
+
+import sys
+
+if sys.version_info >= (3, 12):
+    from typing import TypedDict
+else:
+    from typing_extensions import TypedDict
+
+
+# ── Metrics list ──────────────────────────────────────────────────────────────
+
+
+class ListMetricsOutput(TypedDict):
+    total_count: int
+    returned_count: int
+    truncated: bool
+    pattern: str | None
+    metrics: list[str]
+
+
+# ── Instant query ─────────────────────────────────────────────────────────────
+
+
+class InstantSample(TypedDict):
+    labels: dict[str, str]
+    timestamp: float
+    value: str
+
+
+class QueryOutput(TypedDict):
+    query: str
+    time: str | None
+    result_type: str
+    result_count: int
+    data: list[InstantSample]
+
+
+# ── Range query ───────────────────────────────────────────────────────────────
+
+
+class RangeSeries(TypedDict):
+    labels: dict[str, str]
+    point_count: int
+    values: list[list[float | str]]
+
+
+class QueryRangeOutput(TypedDict):
+    query: str
+    start: str
+    end: str
+    step: str
+    result_type: str
+    series_count: int
+    total_points: int
+    truncated: bool
+    data: list[RangeSeries]
+
+
+# ── Alerts ────────────────────────────────────────────────────────────────────
+
+
+class AlertItem(TypedDict):
+    labels: dict[str, str]
+    annotations: dict[str, str]
+    state: str
+    active_at: str
+    value: str
+
+
+class AlertStateSummary(TypedDict):
+    state: str
+    count: int
+
+
+class ListAlertsOutput(TypedDict):
+    total_count: int
+    firing_count: int
+    pending_count: int
+    state_summary: list[AlertStateSummary]
+    alerts: list[AlertItem]
+
+
+# ── Targets ───────────────────────────────────────────────────────────────────
+
+
+class TargetItem(TypedDict):
+    job: str
+    instance: str
+    health: str
+    last_scrape_duration_ms: float
+    last_error: str | None
+    labels: dict[str, str]
+
+
+class TargetJobSummary(TypedDict):
+    job: str
+    total: int
+    up: int
+    down: int
+    unknown: int
+
+
+class ListTargetsOutput(TypedDict):
+    state_filter: str
+    total_count: int
+    up_count: int
+    down_count: int
+    unknown_count: int
+    job_summary: list[TargetJobSummary]
+    targets: list[TargetItem]

prometheus_mcp/output.py

@@ -0,0 +1,28 @@
+"""Helpers that produce the dual-channel tool result."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, NoReturn
+
+from mcp.server.fastmcp.exceptions import ToolError
+from mcp.types import CallToolResult, TextContent
+
+from prometheus_mcp import errors
+
+
+def ok(data: Mapping[str, Any], markdown: str) -> CallToolResult:
+    """Wrap ``data`` + a markdown rendering into a non-error tool result."""
+    return CallToolResult(
+        content=[TextContent(type="text", text=markdown)],
+        structuredContent=dict(data),
+    )
+
+
+def fail(exc: Exception, action: str) -> NoReturn:
+    """Raise a ``ToolError`` carrying the actionable error message.
+
+    The ``NoReturn`` annotation lets type-checkers understand that control
+    flow does not return from this function.
+    """
+    raise ToolError(errors.handle(exc, action)) from exc

prometheus_mcp/server.py

@@ -0,0 +1,20 @@
+"""FastMCP server entry point for Prometheus MCP."""
+
+from __future__ import annotations
+
+# Importing the tools module attaches @mcp.tool decorators to the shared
+# FastMCP instance.
+from prometheus_mcp import tools as _tools  # noqa: F401
+from prometheus_mcp._mcp import app_lifespan, mcp
+
+
+def main() -> None:
+    """Entry point for the ``prometheus-mcp`` console script (stdio)."""
+    mcp.run()
+
+
+__all__ = ["mcp", "app_lifespan", "main"]
+
+
+if __name__ == "__main__":
+    main()