zapi-mcp 0.2.0__py3-none-any.whl

zapi_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""zapi-mcp — Zabbix API MCP Server."""
+
+__version__ = "0.2.0"  # x-release-please-version

zapi_mcp/__main__.py

@@ -0,0 +1,68 @@
+"""Entry point for zapi-mcp."""
+
+import argparse
+import os
+import sys
+
+from zapi_mcp import __version__
+from zapi_mcp.client import ZapiClient, ZapiError
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Zabbix API MCP Server",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Required environment variables:
+  ZABBIX_URL            Zabbix frontend URL (e.g. https://zabbix.example.com)
+  ZABBIX_USER           Zabbix API user
+  ZABBIX_PASSWORD       Zabbix API password
+  ZABBIX_CATEGORIES_INI Path to categories INI for --brief (optional)
+""",
+    )
+    parser.add_argument("--version", action="store_true", help="Print version and exit")
+    parser.add_argument("--check", action="store_true", help="Verify connection and exit")
+    parser.add_argument(
+        "--brief",
+        action="store_true",
+        help="Print the daily_brief to stdout and exit (handy for cron / smoke tests)",
+    )
+    args = parser.parse_args()
+
+    if args.version:
+        print(f"zapi-mcp {__version__}")
+        sys.exit(0)
+
+    url = os.environ.get("ZABBIX_URL")
+    user = os.environ.get("ZABBIX_USER")
+    password = os.environ.get("ZABBIX_PASSWORD")
+
+    if not all([url, user, password]):
+        pairs = [("ZABBIX_URL", url), ("ZABBIX_USER", user), ("ZABBIX_PASSWORD", password)]
+        missing = [v for v, k in pairs if not k]
+        print(f"Error: missing environment variables: {', '.join(missing)}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.check:
+        try:
+            client = ZapiClient(url, user, password)
+            auth = "Bearer header" if client._bearer else "auth field"
+            print(f"OK — Zabbix API {client.version} (auth: {auth})")
+            sys.exit(0)
+        except ZapiError as e:
+            print(f"Error: {e}", file=sys.stderr)
+            sys.exit(2)
+
+    if args.brief:
+        from zapi_mcp.server import daily_brief
+
+        print(daily_brief())
+        sys.exit(0)
+
+    from zapi_mcp.server import mcp
+
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

zapi_mcp/categories.py

@@ -0,0 +1,82 @@
+"""Site-specific monitoring categories for ``daily_brief``.
+
+Categories are loaded from an INI file pointed to by ``ZABBIX_CATEGORIES_INI``.
+This keeps organization-specific Zabbix tags and item keys out of the codebase
+so the server stays generic and publishable. When unset or missing,
+``daily_brief`` falls back to a generic active-problems summary.
+
+Each ``[section]`` defines one category::
+
+    [dhcp]
+    name = DHCP Pool Usage
+    tag = dhcp-pool-usage      ; Zabbix host tag identifying the group
+    item_key = usage           ; if set -> report current item values
+    threshold = 80             ; optional; flag values >= this
+
+    [core]
+    name = Core Network
+    tag = role
+    tag_value = main           ; tag must equal this value
+                               ; no item_key -> report active problems
+"""
+
+import configparser
+import os
+from dataclasses import dataclass
+
+
+def _safe_float(value: str | None) -> float | None:
+    try:
+        return float(value) if value else None
+    except (TypeError, ValueError):
+        return None
+
+
+@dataclass
+class Category:
+    """One monitoring category for the daily brief."""
+
+    key: str
+    name: str
+    tag: str
+    tag_value: str | None = None
+    item_key: str | None = None
+    item_key_search: str | None = None
+    threshold: float | None = None
+
+    @property
+    def kind(self) -> str:
+        """``items`` when an item key (exact or substring) is configured, else ``problems``."""
+        return "items" if (self.item_key or self.item_key_search) else "problems"
+
+
+def load_categories(path: str | None = None) -> list[Category]:
+    """Load categories from an INI file (env ``ZABBIX_CATEGORIES_INI`` by default).
+
+    Returns an empty list when no path is configured or the file is absent.
+    """
+    path = path or os.environ.get("ZABBIX_CATEGORIES_INI")
+    if not path or not os.path.isfile(path):
+        return []
+
+    cp = configparser.ConfigParser()
+    cp.read(path)
+
+    categories: list[Category] = []
+    for section in cp.sections():
+        s = cp[section]
+        tag = s.get("tag")
+        if not tag:
+            continue
+        categories.append(
+            Category(
+                key=section,
+                name=s.get("name", section),
+                tag=tag,
+                tag_value=s.get("tag_value") or None,
+                item_key=s.get("item_key") or None,
+                item_key_search=s.get("item_key_search") or None,
+                threshold=_safe_float(s.get("threshold")),
+            )
+        )
+    return categories

zapi_mcp/client.py

@@ -0,0 +1,286 @@
+"""Zabbix JSON-RPC API client.
+
+All requests target a single ``/api_jsonrpc.php`` endpoint; the called method is
+carried in the request body. Authentication is version-adaptive but always
+degrades to the proven ``user`` + ``auth``-field path used by older Zabbix
+(<= 6.2), so the client works against current production while staying
+forward-compatible with 6.4 / 7.0 (``username`` + ``Authorization: Bearer``).
+"""
+
+import httpx
+
+DEFAULT_TIMEOUT = 30
+
+# Zabbix tag-filter operators (host.get / problem.get / event.get)
+TAG_OP_EQUAL = "1"
+TAG_OP_EXISTS = "4"
+
+
+class ZapiError(Exception):
+    """Base error for Zabbix API failures."""
+
+
+class ZapiAuthError(ZapiError):
+    """Raised when authentication (user.login) fails."""
+
+
+def tag_filter(tag: str, value: str | None = None) -> dict:
+    """Build a Zabbix tag filter: Equal when a value is given, else Exists."""
+    if value:
+        return {"tag": tag, "value": value, "operator": TAG_OP_EQUAL}
+    return {"tag": tag, "operator": TAG_OP_EXISTS}
+
+
+class ZapiClient:
+    """Minimal Zabbix API client using JSON-RPC over a single endpoint."""
+
+    def __init__(self, url: str, user: str, password: str, *, timeout: int = DEFAULT_TIMEOUT):
+        base = url.rstrip("/")
+        if not base.endswith("/api_jsonrpc.php"):
+            base += "/api_jsonrpc.php"
+        self._url = base
+        self._http = httpx.Client(timeout=timeout, headers={"Content-Type": "application/json"})
+        self._token: str | None = None
+        self._bearer = False  # use Authorization: Bearer header instead of `auth` field
+        self.version = self.api_version()
+        self._token = self._login(user, password)
+
+    # ------------------------------------------------------------------
+    # Low-level call
+    # ------------------------------------------------------------------
+    def _call(self, method: str, params: dict, *, auth: bool = True) -> object:
+        data: dict = {"jsonrpc": "2.0", "method": method, "params": params, "id": 1}
+        headers: dict = {}
+        if auth and self._token:
+            if self._bearer:
+                headers["Authorization"] = f"Bearer {self._token}"
+            else:
+                data["auth"] = self._token
+        try:
+            resp = self._http.post(self._url, json=data, headers=headers or None)
+            resp.raise_for_status()
+            body = resp.json()
+        except httpx.HTTPStatusError as e:
+            raise ZapiError(f"HTTP {e.response.status_code}: {method}") from e
+        except httpx.HTTPError as e:
+            raise ZapiError(f"Connection error calling {method}: {e}") from e
+        if err := body.get("error"):
+            if method == "user.login":
+                raise ZapiAuthError(f"Authentication failed: {err}")
+            raise ZapiError(f"{method} failed: {err}")
+        return body["result"]
+
+    # ------------------------------------------------------------------
+    # Version detection & auth
+    # ------------------------------------------------------------------
+    def api_version(self) -> str:
+        return self._call("apiinfo.version", {}, auth=False)
+
+    @staticmethod
+    def _version_tuple(version: str) -> tuple[int, int]:
+        try:
+            parts = version.split(".")
+            return int(parts[0]), int(parts[1])
+        except (ValueError, IndexError):
+            return (0, 0)
+
+    def _login(self, user: str, password: str) -> str:
+        """Log in, choosing the param name by version and degrading to proven `user`.
+
+        Zabbix 6.4 renamed the login parameter ``user`` -> ``username`` and added
+        Bearer-header auth. We pick by detected version, then fall back to the
+        other param name if the first attempt errors (so a misdetected version
+        still authenticates).
+        """
+        modern = self._version_tuple(self.version) >= (6, 4)
+        self._bearer = modern
+        primary = "username" if modern else "user"
+        fallback = "user" if modern else "username"
+        try:
+            return self._call("user.login", {primary: user, "password": password}, auth=False)
+        except ZapiAuthError as e:
+            # A genuine credential failure must not trigger a second login
+            # attempt (avoid doubling lockout / audit pressure).
+            msg = str(e).lower()
+            if "incorrect" in msg or "password" in msg or "no permissions" in msg:
+                raise
+            # Otherwise the param name was likely wrong for this version: retry
+            # with the other name and degrade to the proven `auth` field.
+            self._bearer = False
+            return self._call("user.login", {fallback: user, "password": password}, auth=False)
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "ZapiClient":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
+
+    # ------------------------------------------------------------------
+    # Host groups
+    # ------------------------------------------------------------------
+    def _get_group_ids(self, group: str) -> list[str]:
+        result = self._call("hostgroup.get", {"output": "groupid", "filter": {"name": [group]}})
+        return [r["groupid"] for r in result]
+
+    # ------------------------------------------------------------------
+    # Hosts
+    # ------------------------------------------------------------------
+    def get_hosts(
+        self,
+        *,
+        tags: list[dict] | None = None,
+        group: str | None = None,
+        host: str | None = None,
+    ) -> list[dict]:
+        """Return hosts, optionally filtered by tags, group name, or exact host."""
+        params: dict = {
+            "output": ["hostid", "host", "name", "status"],
+            "selectTags": "extend",
+            "selectInterfaces": ["ip"],
+        }
+        if tags:
+            params["tags"] = tags
+        if group:
+            params["groupids"] = self._get_group_ids(group)
+        if host:
+            params["filter"] = {"host": host}
+        return self._call("host.get", params)
+
+    # ------------------------------------------------------------------
+    # Items (current values)
+    # ------------------------------------------------------------------
+    def get_items(
+        self,
+        host_ids: list[str],
+        *,
+        key: str | None = None,
+        key_search: str | None = None,
+        name_search: str | None = None,
+    ) -> list[dict]:
+        """Return items with last value for given hosts.
+
+        ``key`` filters by exact item key (key_); ``key_search`` does a substring
+        match on the key (e.g. ".usage" to catch ``pool.node0.usage``);
+        ``name_search`` does a substring match on the item name.
+        """
+        params: dict = {
+            "output": ["itemid", "hostid", "name", "key_", "lastvalue", "units", "lastclock"],
+            "hostids": host_ids,
+            "selectTags": "extend",
+        }
+        if key:
+            params["filter"] = {"key_": key}
+        search = {}
+        if key_search:
+            search["key_"] = key_search
+        if name_search:
+            search["name"] = name_search
+        if search:
+            params["search"] = search
+        return self._call("item.get", params)
+
+    # ------------------------------------------------------------------
+    # Problems
+    # ------------------------------------------------------------------
+    def get_problems(
+        self,
+        *,
+        severities: list[int] | None = None,
+        tags: list[dict] | None = None,
+        limit: int = 100,
+    ) -> list[dict]:
+        """Return active problems, optionally filtered by severity and tags.
+
+        Output includes ``eventid`` so callers can acknowledge problems.
+        """
+        params: dict = {
+            "output": "extend",
+            "selectAcknowledges": "count",
+            "selectTags": "extend",
+            # problem.get only permits "eventid" as a sortfield; callers that
+            # need severity ordering re-bucket in Python.
+            "sortfield": "eventid",
+            "sortorder": "DESC",
+            "limit": limit,
+            "suppressed": False,
+        }
+        if severities:
+            params["severities"] = severities
+        if tags:
+            params["tags"] = tags
+        return self._call("problem.get", params)
+
+    def count_problems(
+        self,
+        *,
+        severities: list[int] | None = None,
+        tags: list[dict] | None = None,
+    ) -> int:
+        """Return the total count of active problems matching the filters.
+
+        Uses Zabbix ``countOutput`` so callers can report an accurate total even
+        when ``get_problems`` is capped by ``limit`` (avoids silent truncation).
+        """
+        params: dict = {"countOutput": True, "suppressed": False}
+        if severities:
+            params["severities"] = severities
+        if tags:
+            params["tags"] = tags
+        result = self._call("problem.get", params)
+        try:
+            return int(result)  # countOutput returns the count as a numeric string
+        except (TypeError, ValueError) as e:
+            # A genuine API failure already raised in _call; an unexpected shape
+            # here is a contract violation worth surfacing, not masking as 0.
+            raise ZapiError(f"problem.get countOutput returned non-numeric: {result!r}") from e
+
+    # ------------------------------------------------------------------
+    # Events
+    # ------------------------------------------------------------------
+    def get_events(
+        self,
+        *,
+        time_from: int | None = None,
+        severities: list[int] | None = None,
+        limit: int = 100,
+    ) -> list[dict]:
+        """Return recent problem events (source=trigger, value=problem)."""
+        params: dict = {
+            "output": "extend",
+            "selectTags": "extend",
+            "selectHosts": ["host", "name"],
+            "source": 0,
+            "object": 0,
+            "value": 1,
+            "sortfield": ["clock", "eventid"],
+            "sortorder": "DESC",
+            "limit": limit,
+        }
+        if time_from:
+            params["time_from"] = time_from
+        if severities:
+            params["severities"] = severities
+        return self._call("event.get", params)
+
+    # ------------------------------------------------------------------
+    # Acknowledge
+    # ------------------------------------------------------------------
+    def acknowledge_problem(self, event_ids: list[str], message: str = "") -> dict:
+        """Acknowledge problems, optionally adding a message.
+
+        Action is a bitmask: acknowledge (2), plus add-message (4) only when a
+        non-empty message is given (Zabbix rejects an empty message when bit 4
+        is set). Does NOT close problems (close is bit 1), so the tool is safe
+        even when triggers disallow manual close.
+        """
+        action = 2 | (4 if message else 0)
+        params: dict = {"eventids": event_ids, "action": action}
+        if message:
+            params["message"] = message
+        return self._call("event.acknowledge", params)

zapi_mcp/server.py

@@ -0,0 +1,502 @@
+"""Zabbix API MCP Server — tools."""
+
+import os
+from datetime import datetime
+
+from mcp.server.fastmcp import FastMCP
+
+from zapi_mcp.categories import Category, load_categories
+from zapi_mcp.client import ZapiClient, ZapiError, tag_filter
+
+mcp = FastMCP("zapi-mcp")
+
+_SEVERITY = {
+    0: "Not classified",
+    1: "Information",
+    2: "Warning",
+    3: "Average",
+    4: "High",
+    5: "Disaster",
+}
+
+# Zabbix severity levels (Warning and above = the ones worth a morning glance)
+SEVERITY_WARNING_AND_ABOVE = [2, 3, 4, 5]
+MAX_SEVERITY = 5
+
+# How many item rows to show per brief category (plus any over threshold)
+BRIEF_ITEM_LIMIT = 12
+
+# How many active problems to fetch for the brief by default. Large enough to
+# cover a real warning+ backlog in one call; if the cap is hit we query an
+# accurate total separately so the count is never silently truncated. Tunable
+# via ZABBIX_BRIEF_PROBLEM_LIMIT.
+DEFAULT_BRIEF_PROBLEM_LIMIT = 1000
+
+# Default "recent" window: problems newer than this are listed in full, older
+# ("stale") ones are folded to a count. Tunable via ZABBIX_BRIEF_RECENT_HOURS so
+# a morning patrol can focus on what just happened, not year-old fossils that
+# Zabbix keeps active because their recovery is never auto-confirmed.
+DEFAULT_RECENT_HOURS = 24
+
+# Cached client: a stdio server is long-lived and single-user, so we build and
+# authenticate once, reusing the httpx pool and Zabbix session across calls.
+_CLIENT: ZapiClient | None = None
+
+
+def _client() -> ZapiClient:
+    global _CLIENT
+    if _CLIENT is None:
+        _CLIENT = ZapiClient(
+            os.environ["ZABBIX_URL"],
+            os.environ["ZABBIX_USER"],
+            os.environ["ZABBIX_PASSWORD"],
+        )
+    return _CLIENT
+
+
+def reset_client() -> None:
+    """Drop the cached client so the next call re-authenticates (token refresh)."""
+    global _CLIENT
+    if _CLIENT is not None:
+        try:
+            _CLIENT.close()
+        except Exception:
+            pass
+        _CLIENT = None
+
+
+def _fmt_time(epoch: int | str | None) -> str:
+    try:
+        e = int(epoch)
+    except (TypeError, ValueError):
+        return "—"
+    if e == 0:
+        return "—"
+    try:
+        return datetime.fromtimestamp(e).astimezone().strftime("%Y-%m-%d %H:%M:%S")
+    except (OverflowError, OSError):
+        return str(epoch)
+
+
+def _severity_name(sev: int | str | None) -> str:
+    try:
+        return _SEVERITY.get(int(sev), str(sev))
+    except (TypeError, ValueError):
+        return str(sev)
+
+
+def _fmt_tags(tags: list[dict]) -> str:
+    return ", ".join(f"{t['tag']}={t['value']}" if t.get("value") else t["tag"] for t in tags)
+
+
+def _is_acked(problem: dict) -> bool:
+    """True when the problem's `acknowledged` boolean field is set."""
+    return str(problem.get("acknowledged", "0")) == "1"
+
+
+def _item_value(item: dict) -> float:
+    try:
+        return float(item.get("lastvalue") or 0)
+    except (ValueError, TypeError):
+        return 0.0
+
+
+def _fmt_value(item: dict) -> str:
+    """Round numeric values to 1 decimal; pass non-numeric through; — for empty."""
+    raw = item.get("lastvalue")
+    if raw in (None, ""):
+        return "—"
+    try:
+        return f"{float(raw):.1f}"
+    except (ValueError, TypeError):
+        return str(raw)
+
+
+def _clock(problem: dict) -> int:
+    """Problem onset epoch as int (0 when missing or unparseable)."""
+    try:
+        return int(problem.get("clock") or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+def _fmt_age(epoch: int, now_ts: int) -> str:
+    """Coarse human age from `epoch` to `now_ts`, e.g. '<1m ago', '5m ago', '3h ago', '47d ago'."""
+    if epoch <= 0:
+        return "?"
+    secs = max(0, now_ts - epoch)
+    if secs < 60:
+        return "<1m ago"
+    if secs < 3600:
+        return f"{secs // 60}m ago"
+    if secs < 86400:
+        return f"{secs // 3600}h ago"
+    return f"{secs // 86400}d ago"
+
+
+def _recent_window_seconds() -> int:
+    """Seconds of the 'recent' window (env ZABBIX_BRIEF_RECENT_HOURS, default 24h)."""
+    try:
+        hours = float(os.environ.get("ZABBIX_BRIEF_RECENT_HOURS", DEFAULT_RECENT_HOURS))
+    except (TypeError, ValueError):
+        hours = float(DEFAULT_RECENT_HOURS)
+    return int(max(0.0, hours) * 3600)
+
+
+def _brief_problem_limit() -> int:
+    """Problem fetch cap for the brief (env ZABBIX_BRIEF_PROBLEM_LIMIT, default 1000).
+
+    Parsed via float() then int() so a stray decimal (e.g. "10.5") truncates to a
+    usable value rather than silently reverting to the default, matching how
+    _recent_window_seconds tolerates fractional input.
+    """
+    try:
+        limit = int(float(os.environ.get("ZABBIX_BRIEF_PROBLEM_LIMIT", DEFAULT_BRIEF_PROBLEM_LIMIT)))
+    except (TypeError, ValueError):
+        limit = DEFAULT_BRIEF_PROBLEM_LIMIT
+    return max(1, limit)
+
+
+def _window_label(seconds: int) -> str:
+    """Human label for the recent window, e.g. '24h', '90m', '30s'.
+
+    Rounds to whole minutes above a minute so a fractional ZABBIX_BRIEF_RECENT_HOURS
+    (e.g. 1.001 -> 3603s) still reads as a clean duration rather than raw seconds.
+    """
+    if seconds < 60:
+        return f"{seconds}s"
+    minutes = round(seconds / 60)
+    if minutes % 60 == 0:
+        return f"{minutes // 60}h"
+    return f"{minutes}m"
+
+
+def _count_fragment(shown: int, total: int) -> str:
+    """'5' when the listing is complete, 'showing 5 of 20' when capped."""
+    return f"showing {shown} of {total}" if total > shown else f"{total}"
+
+
+def _problem_line(problem: dict, now_ts: int, *, with_severity: bool = False) -> str:
+    """One problem row: name, optional severity, eventid, onset time and age."""
+    ack = " [ack]" if _is_acked(problem) else ""
+    sev = f"[{_severity_name(problem['severity'])}] " if with_severity else ""
+    clock = _clock(problem)
+    return (
+        f"- {sev}{problem['name']}{ack}  "
+        f"eventid={problem.get('eventid', '?')}  ({_fmt_time(clock)}, {_fmt_age(clock, now_ts)})"
+    )
+
+
+def _emit_problem_bucket(
+    lines: list[str],
+    problems: list[dict],
+    now_ts: int,
+    recent_window: int,
+    *,
+    with_severity: bool = False,
+) -> None:
+    """Append problem rows newest-first: recent ones in full, stale ones folded to a count."""
+    ordered = sorted(problems, key=_clock, reverse=True)
+    recent = [p for p in ordered if now_ts - _clock(p) <= recent_window]
+    stale = [p for p in ordered if now_ts - _clock(p) > recent_window]
+    for p in recent:
+        lines.append(_problem_line(p, now_ts, with_severity=with_severity))
+    if stale:
+        oldest = min(_clock(p) for p in stale)
+        lines.append(f"- … and {len(stale)} older (stale; oldest {_fmt_time(oldest)})")
+
+
+def _fetch_problems_with_total(
+    client: ZapiClient,
+    *,
+    severities: list[int] | None = None,
+    tags: list[dict] | None = None,
+    limit: int | None = None,
+) -> tuple[list[dict], int]:
+    """Fetch problems (capped at `limit`) plus the accurate total.
+
+    `limit` defaults to the brief's configurable cap (ZABBIX_BRIEF_PROBLEM_LIMIT);
+    callers that honour a user-supplied limit pass it explicitly. When the fetch
+    hits the cap, the total is queried via countOutput so callers can report
+    'showing N of TOTAL' rather than silently truncating. If only the (secondary)
+    count query fails, we keep the fetched rows and fall back to their count
+    rather than discarding everything.
+    """
+    if limit is None:
+        limit = _brief_problem_limit()
+    problems = client.get_problems(severities=severities, tags=tags, limit=limit)
+    if len(problems) < limit:
+        return problems, len(problems)
+    try:
+        total = client.count_problems(severities=severities, tags=tags)
+    except ZapiError:
+        total = len(problems)
+    return problems, max(total, len(problems))
+
+
+# ------------------------------------------------------------------
+# daily_brief — category-driven morning patrol
+# ------------------------------------------------------------------
+def _brief_item_category(client: ZapiClient, cat: Category) -> list[str]:
+    hosts = client.get_hosts(tags=[tag_filter(cat.tag, cat.tag_value)])
+    lines = [f"\n## {cat.name} ({len(hosts)} hosts)"]
+    if not hosts:
+        lines.append("No hosts found for this category.")
+        return lines
+    host_ids = [h["hostid"] for h in hosts]
+    host_name = {h["hostid"]: h["host"] for h in hosts}
+    items = client.get_items(host_ids, key=cat.item_key, key_search=cat.item_key_search)
+    if not items:
+        which = cat.item_key or cat.item_key_search
+        lines.append(f"No items matching '{which}' found.")
+        return lines
+
+    ranked = sorted(items, key=_item_value, reverse=True)
+    over = [it for it in ranked if cat.threshold is not None and _item_value(it) >= cat.threshold]
+    # Show every item at/over threshold, then fill to the cap with the highest.
+    shown = ranked[: max(BRIEF_ITEM_LIMIT, len(over))]
+
+    for item in shown:
+        host = host_name.get(item.get("hostid", ""), "")
+        name = item.get("name", "")
+        # For per-host gauges (item name == the configured key) the host already
+        # identifies the row; otherwise include the item name to disambiguate.
+        label = host
+        if name and name != cat.item_key:
+            label = f"{host} {name}".strip()
+        flag = "  ⚠️" if cat.threshold is not None and _item_value(item) >= cat.threshold else ""
+        units = item.get("units") or ""
+        unit_str = f" {units}" if units else ""
+        lines.append(f"- {label}: {_fmt_value(item)}{unit_str}{flag}  ({_fmt_time(item.get('lastclock'))})")
+
+    remaining = len(ranked) - len(shown)
+    if remaining > 0:
+        lines.append(f"- … and {remaining} more (≤ {_fmt_value(shown[-1])})")
+    return lines
+
+
+def _brief_problem_category(client: ZapiClient, cat: Category, now_ts: int, recent_window: int) -> list[str]:
+    problems, total = _fetch_problems_with_total(client, tags=[tag_filter(cat.tag, cat.tag_value)])
+    noun = "problem" if total == 1 else "problems"
+    lines = [f"\n## {cat.name} ({_count_fragment(len(problems), total)} active {noun})"]
+    if not problems:
+        lines.append("No active problems.")
+        return lines
+    _emit_problem_bucket(lines, problems, now_ts, recent_window, with_severity=True)
+    return lines
+
+
+@mcp.tool()
+def daily_brief() -> str:
+    """Morning patrol summary.
+
+    Reports active problems (Warning and above), then one section per category
+    configured via ZABBIX_CATEGORIES_INI (e.g. DHCP pool usage, SNAT session
+    usage, core-network problems). Item-based categories show current values
+    sorted high-to-low; problem-based categories list active problems.
+
+    Problems are listed newest-first with their age; those older than the recent
+    window (ZABBIX_BRIEF_RECENT_HOURS, default 24h) are folded to a count so a
+    long-standing backlog of un-recovered fossils doesn't bury today's events.
+    Section headers show the true total ('showing N of TOTAL' when capped).
+    """
+    try:
+        client = _client()
+    except KeyError as e:
+        return f"Missing environment variable: {e}"
+    except ZapiError as e:
+        reset_client()
+        return f"Zabbix error: {e}"
+
+    now_dt = datetime.now().astimezone()
+    now_ts = int(now_dt.timestamp())
+    recent_window = _recent_window_seconds()
+    window_label = _window_label(recent_window)
+    lines = [f"# Daily Brief — {now_dt.strftime('%Y-%m-%d %H:%M')}"]
+
+    # Active problems (Warning and above), newest first; stale ones folded away.
+    try:
+        problems, total = _fetch_problems_with_total(client, severities=SEVERITY_WARNING_AND_ABOVE)
+        lines.append(f"\n## Active Problems ({_count_fragment(len(problems), total)})")
+        if not problems:
+            lines.append("No active problems.")
+        else:
+            by_sev: dict[int, list] = {}
+            for p in problems:
+                by_sev.setdefault(int(p["severity"]), []).append(p)
+            for sev in sorted(by_sev, reverse=True):
+                bucket = by_sev[sev]
+                n_recent = sum(1 for p in bucket if now_ts - _clock(p) <= recent_window)
+                lines.append(f"\n### {_severity_name(sev)} ({len(bucket)}, {n_recent} in last {window_label})")
+                _emit_problem_bucket(lines, bucket, now_ts, recent_window)
+    except ZapiError as e:
+        # First real call failed (often a stale token); drop the client so the
+        # next invocation re-authenticates.
+        reset_client()
+        lines.append(f"\n## Active Problems\nError: {e}")
+        return "\n".join(lines)
+
+    # Per-category sections
+    categories = load_categories()
+    if not categories:
+        lines.append(
+            "\n(No categories configured. Set ZABBIX_CATEGORIES_INI to add "
+            "DHCP / SNAT / core-network sections — see categories.ini.example.)"
+        )
+    for cat in categories:
+        try:
+            if cat.kind == "items":
+                lines.extend(_brief_item_category(client, cat))
+            else:
+                lines.extend(_brief_problem_category(client, cat, now_ts, recent_window))
+        except ZapiError as e:
+            lines.append(f"\n## {cat.name}\nError: {e}")
+
+    return "\n".join(lines)
+
+
+# ------------------------------------------------------------------
+# Problems
+# ------------------------------------------------------------------
+@mcp.tool()
+def get_problems(
+    min_severity: int = 2,
+    tag_name: str | None = None,
+    tag_value: str | None = None,
+    limit: int = 50,
+) -> str:
+    """Get active Zabbix problems, newest first.
+
+    Problems are listed newest-first and annotated with their age. The header
+    shows the true total ('showing N of TOTAL' when the result is capped by
+    `limit`), so a capped listing is never mistaken for the full picture.
+
+    Args:
+        min_severity: Minimum severity (0=Not classified, 1=Info, 2=Warning, 3=Average, 4=High, 5=Disaster)
+        tag_name: Filter by tag name (optional)
+        tag_value: Filter by tag value (optional, requires tag_name)
+        limit: Maximum number of problems to return (floored at 1; when the result
+            hits this cap a second count query is issued to report the true total)
+    """
+    if min_severity > MAX_SEVERITY:
+        return "No problems at/above the requested severity."
+    try:
+        client = _client()
+        severities = list(range(max(min_severity, 0), 6))
+        tags = [tag_filter(tag_name, tag_value)] if tag_name else None
+        problems, total = _fetch_problems_with_total(client, severities=severities, tags=tags, limit=max(1, limit))
+    except KeyError as e:
+        return f"Missing environment variable: {e}"
+    except ZapiError as e:
+        reset_client()
+        return f"Zabbix error: {e}"
+    if not problems:
+        return "No active problems."
+    now_ts = int(datetime.now().astimezone().timestamp())
+    problems = sorted(problems, key=_clock, reverse=True)
+    lines = [f"Active Problems ({_count_fragment(len(problems), total)}):"]
+    for p in problems:
+        lines.append(_problem_line(p, now_ts, with_severity=True))
+        tag_str = _fmt_tags(p.get("tags", []))
+        if tag_str:
+            lines.append(f"  tags: {tag_str}")
+    return "\n".join(lines)
+
+
+# ------------------------------------------------------------------
+# Hosts
+# ------------------------------------------------------------------
+@mcp.tool()
+def get_hosts(
+    role: str | None = None,
+    tag_name: str | None = None,
+    tag_value: str | None = None,
+    group: str | None = None,
+) -> str:
+    """List Zabbix hosts filtered by tag or group.
+
+    Args:
+        role: Filter by role tag value (e.g. 'main', 'edge')
+        tag_name: Filter by arbitrary tag name
+        tag_value: Filter by tag value (requires tag_name)
+        group: Filter by host group name
+    """
+    try:
+        client = _client()
+        tags = []
+        if role:
+            tags.append(tag_filter("role", role))
+        if tag_name:
+            tags.append(tag_filter(tag_name, tag_value))
+        hosts = client.get_hosts(tags=tags or None, group=group)
+    except KeyError as e:
+        return f"Missing environment variable: {e}"
+    except ZapiError as e:
+        reset_client()
+        return f"Zabbix error: {e}"
+    if not hosts:
+        return "No hosts found."
+    lines = [f"Hosts ({len(hosts)}):"]
+    for h in sorted(hosts, key=lambda x: x["host"]):
+        tag_str = _fmt_tags(h.get("tags", []))
+        interfaces = h.get("interfaces") or [{}]
+        ip = interfaces[0].get("ip", "—")
+        lines.append(f"  {h['host']}  {ip}  [{tag_str}]")
+    return "\n".join(lines)
+
+
+# ------------------------------------------------------------------
+# Items (current values)
+# ------------------------------------------------------------------
+@mcp.tool()
+def get_host_items(host: str, search: str | None = None) -> str:
+    """Get current item values for a host.
+
+    Args:
+        host: Hostname (exact match)
+        search: Filter items by name (partial match)
+    """
+    try:
+        client = _client()
+        hosts = client.get_hosts(host=host)
+        if not hosts:
+            return f"Host '{host}' not found."
+        items = client.get_items([hosts[0]["hostid"]], name_search=search)
+    except KeyError as e:
+        return f"Missing environment variable: {e}"
+    except ZapiError as e:
+        reset_client()
+        return f"Zabbix error: {e}"
+    if not items:
+        return f"No items found for '{host}'."
+    lines = [f"Items for {host} ({len(items)}):"]
+    for item in sorted(items, key=lambda x: x["name"]):
+        ts = _fmt_time(item.get("lastclock"))
+        val = item.get("lastvalue") or "—"
+        lines.append(f"  {item['name']}: {val} {item.get('units', '')}  ({ts})")
+    return "\n".join(lines)
+
+
+# ------------------------------------------------------------------
+# Acknowledge
+# ------------------------------------------------------------------
+@mcp.tool()
+def acknowledge_problem(event_ids: str, message: str) -> str:
+    """Acknowledge Zabbix problems and add a message (does not close them).
+
+    Args:
+        event_ids: Comma-separated event IDs (from get_problems output)
+        message: Acknowledgement message
+    """
+    ids = [eid.strip() for eid in event_ids.split(",") if eid.strip()]
+    if not ids:
+        return "No event IDs provided."
+    try:
+        client = _client()
+        result = client.acknowledge_problem(ids, message)
+    except KeyError as e:
+        return f"Missing environment variable: {e}"
+    except ZapiError as e:
+        reset_client()
+        return f"Zabbix error: {e}"
+    return f"Acknowledged {len(ids)} event(s): {result}"

zapi_mcp-0.2.0.dist-info/METADATA

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: zapi-mcp
+Version: 0.2.0
+Summary: MCP server for Zabbix API — daily brief, problems, hosts, items
+Author: AIKAWA Shigechika
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/shigechika/zapi-mcp
+Project-URL: Repository, https://github.com/shigechika/zapi-mcp
+Project-URL: Issues, https://github.com/shigechika/zapi-mcp/issues
+Keywords: zabbix,mcp,model-context-protocol,monitoring,network
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.0
+Requires-Dist: httpx
+
+<!-- mcp-name: io.github.shigechika/zapi-mcp -->
+
+# zapi-mcp
+
+English | [日本語](README.ja.md)
+
+MCP (Model Context Protocol) server for the [Zabbix](https://www.zabbix.com/) API.
+
+Built for network operations: a single `daily_brief` call summarizes active
+problems plus site-specific categories (DHCP pool usage, SNAT session usage,
+core-network problems, …), and individual tools query problems, hosts, and item
+values. Organization-specific tags live in a config file, not the code, so the
+server stays generic.
+
+Version-adaptive auth: works against Zabbix 6.0 LTS (`user` + `auth` field) and
+forward-compatible with 6.4 / 7.0 (`username` + `Authorization: Bearer`).
+
+## Features
+
+| Tool | Description |
+|------|-------------|
+| `daily_brief` | Morning patrol: active problems (Warning+) plus one section per configured category |
+| `get_problems` | Active problems by severity and tag, newest-first with age; header shows the true total (`showing N of TOTAL` when capped); output includes `eventid` |
+| `get_hosts` | List hosts filtered by role/tag/group, with IP and tags |
+| `get_host_items` | Current item values for a host (server-side host filter) |
+| `acknowledge_problem` | Acknowledge problems and add a message (does not close them) |
+
+## Setup
+
+```bash
+# uv
+uv pip install zapi-mcp
+
+# pip
+pip install zapi-mcp
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/shigechika/zapi-mcp.git
+cd zapi-mcp
+
+# uv
+uv sync
+
+# pip
+pip install -e .
+```
+
+## Configuration
+
+Set the following environment variables:
+
+| Variable | Description | Default |
+|---|---|---|
+| `ZABBIX_URL` | Zabbix base URL (e.g. `https://zabbix.example.com`); `/api_jsonrpc.php` is appended if absent | *required* |
+| `ZABBIX_USER` | Zabbix API user | *required* |
+| `ZABBIX_PASSWORD` | Zabbix API password | *required* |
+| `ZABBIX_CATEGORIES_INI` | Path to a categories INI file for `daily_brief` (optional) | — |
+| `ZABBIX_BRIEF_RECENT_HOURS` | `daily_brief` "recent" window in hours; problems older than this are folded to a count | `24` |
+| `ZABBIX_BRIEF_PROBLEM_LIMIT` | Max active problems `daily_brief` fetches per call before counting the rest | `1000` |
+
+The API user needs read permission for the host groups you query, plus
+acknowledge permission if you use `acknowledge_problem`.
+
+### Active problems in `daily_brief`
+
+Problems are grouped by severity and listed **newest-first**, each annotated with
+its age (e.g. `3h ago`). Problems older than the recent window
+(`ZABBIX_BRIEF_RECENT_HOURS`, default 24h) are folded to a single
+`… and N older (stale; oldest …)` line — so a backlog of alerts that Zabbix
+keeps active because their recovery is never auto-confirmed (ICMP ping down, RDP
+down, …) doesn't bury what just happened. Section headers carry the true total
+and show `showing N of TOTAL` when the fetch is capped, never a silent truncation.
+
+### Categories for `daily_brief` (optional)
+
+`daily_brief` always lists active problems. To add site-specific sections —
+DHCP pool exhaustion, SNAT session usage, core-network problems — point
+`ZABBIX_CATEGORIES_INI` at an INI file. Each `[section]` is one category:
+
+```ini
+[dhcp]
+name = DHCP Pool Usage
+tag = dhcp-pool-usage      ; Zabbix host tag identifying the group
+item_key = usage           ; report current values for this exact item key
+threshold = 80             ; flag values >= this
+
+[snat]
+name = SNAT Session Pool
+tag = snat-pool-usage
+item_key_search = .usage   ; substring match (catches pool.node0.usage etc.)
+threshold = 80
+
+[core]
+name = Core Network
+tag = role
+tag_value = main           ; tag must equal this value
+                           ; no item key -> report active problems instead
+```
+
+- `tag` (required): host tag identifying the category. With `tag_value`, the tag
+  must equal it (Equal); without, any host carrying the tag matches (Exists).
+- `item_key` / `item_key_search`: when either is set, the section reports current
+  item values sorted high-to-low. `item_key` matches the key exactly; use
+  `item_key_search` for keys that embed an id (e.g. `.usage` catches
+  `pool.node0.usage`). When neither is set, it reports active problems for the tag.
+- `threshold`: optional; values at or above it are flagged.
+
+See [`categories.ini.example`](categories.ini.example). When the variable is
+unset or the file is missing, `daily_brief` reports active problems only.
+
+## Usage
+
+### Claude Code
+
+Add to `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "zapi-mcp": {
+      "type": "stdio",
+      "command": "zapi-mcp",
+      "env": {
+        "ZABBIX_URL": "https://zabbix.example.com",
+        "ZABBIX_USER": "api-user",
+        "ZABBIX_PASSWORD": "",
+        "ZABBIX_CATEGORIES_INI": "/path/to/categories.ini"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "zapi-mcp": {
+      "command": "zapi-mcp",
+      "env": {
+        "ZABBIX_URL": "https://zabbix.example.com",
+        "ZABBIX_USER": "api-user",
+        "ZABBIX_PASSWORD": ""
+      }
+    }
+  }
+}
+```
+
+### Direct Execution
+
+```bash
+export ZABBIX_URL=https://zabbix.example.com
+export ZABBIX_USER=api-user
+export ZABBIX_PASSWORD=your-password
+zapi-mcp
+```
+
+### CLI Options
+
+```bash
+zapi-mcp --version   # Print version and exit
+zapi-mcp --check     # Verify environment variables and authentication, then exit
+zapi-mcp --brief     # Print the daily_brief to stdout and exit (handy for cron)
+zapi-mcp             # Start MCP server (STDIO, default)
+```
+
+`--check` exit codes: `0` success, `1` config error, `2` auth/connection error.
+
+## Development
+
+```bash
+git clone https://github.com/shigechika/zapi-mcp.git
+cd zapi-mcp
+
+# uv
+uv sync --dev
+uv run pytest -v
+uv run ruff check .
+
+# pip
+python3 -m venv .venv
+.venv/bin/pip install -e . && .venv/bin/pip install pytest pytest-cov respx ruff
+.venv/bin/pytest -v
+.venv/bin/ruff check .
+```
+
+## Releasing
+
+Releases are automated with [release-please](https://github.com/googleapis/release-please).
+Merging [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, …)
+to `main` keeps a release PR open with the next version and changelog. Merging
+that PR tags `vX.Y.Z` and publishes a GitHub Release, whose `release: published`
+event triggers the `release` workflow to build and publish to PyPI and the MCP
+Registry. release-please owns the version in `zapi_mcp/__init__.py` and
+`server.json` (do not bump them by hand).
+
+> [!IMPORTANT]
+> The release-please workflow should be given a repository secret
+> `RELEASE_PLEASE_TOKEN` (a PAT with `contents: write` + `pull-requests: write`).
+> The default `GITHUB_TOKEN` cannot create the Release that triggers the
+> downstream `release` workflow (GitHub blocks workflow runs triggered by
+> `GITHUB_TOKEN`), so without the PAT nothing gets published. The workflow falls
+> back to `GITHUB_TOKEN` when the secret is unset so PR CI keeps working on forks.
+
+## Roadmap
+
+- Streamable HTTP transport + OAuth2 for remote / mobile use
+- Visual rendering of key metrics
+
+## License
+
+MIT

zapi_mcp-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+zapi_mcp/__init__.py,sha256=zpDQ5Yy87YovTsqwJthd7a6Tq9300bpj3g7N8Zvv0Gg,93
+zapi_mcp/__main__.py,sha256=yvT4cn5BS00Gwq5zKlS0h43hsLJZaXp5Jbwq8nLxTBI,2061
+zapi_mcp/categories.py,sha256=_mlbZB4uSrSFSsduv6MfknlUGCqzzqZis3sQ9hEbKNQ,2540
+zapi_mcp/client.py,sha256=nmK2HSi9qel4Ve_sU4oRPMcozKauPF5X026qNC-zKU0,11257
+zapi_mcp/server.py,sha256=AQ1dF35lkzlO9yAVYq5ab9qWegxzyN0-WV8hAX6P8lo,18610
+zapi_mcp-0.2.0.dist-info/METADATA,sha256=BWHwKxrmdPEIKTQgrdi-sQU59Ka0K1wdKYKAOswBY7E,7932
+zapi_mcp-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+zapi_mcp-0.2.0.dist-info/entry_points.txt,sha256=sOVZtazLbeClsjTCd-W3xp_WW5sv9ZII2yvZcm9arWw,52
+zapi_mcp-0.2.0.dist-info/top_level.txt,sha256=PvL5gJQP3TPZtbawoDIs_lyv5HJ70swzPHZPv17JXZ4,9
+zapi_mcp-0.2.0.dist-info/RECORD,,

zapi_mcp-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

zapi_mcp-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+zapi-mcp = zapi_mcp.__main__:main

zapi_mcp-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+zapi_mcp