zapi-mcp CLAUDE.md

CLAUDE.md

Overview

MCP (Model Context Protocol) server for the Zabbix API. Exposes a daily_brief morning-patrol summary plus problem/host/item query and acknowledgement tools to AI assistants via STDIO transport, built on the official mcp Python SDK's FastMCP.

Commands

uv sync --dev
uv run pytest -v                    # run all tests
uv run ruff check .                 # lint
uv run ruff format --check .        # format check

This mirrors .github/workflows/ci.yml (separate lint and test jobs; test runs on Python 3.10/3.12/3.13 on Linux plus one Windows 3.12 smoke job to guard against stdio newline regressions).

Architecture

• zapi_mcp/server.py — FastMCP server with 8 tools: health_check, daily_brief, get_problems, get_hosts, get_host_items, acknowledge_problem, set_maintenance (idempotent maintenance window, by location tag or by exact host name — exactly one of the two required; thin wrapper over zapi_lib.ZapiClient.set_maintenance/ set_maintenance_for_hosts, which live on the base client, not just ZapiProvisioner, specifically so this MCP server's plain ZapiClient can call them), get_maintenance_windows (the read counterpart: lists Active/Upcoming/Expired windows via zapi_lib.ZapiClient.get_maintenances, classifying "active" against each window's own one-time time period, not just its outer active_since/active_till frame — exact for windows set_maintenance creates; a recurring time period falls back to the outer frame and is labeled accordingly). daily_brief also gains an "In Maintenance" section, independent of Active Problems, listing hosts under an active window plus any starting later today — cross-check other tools' findings against it before treating a planned outage as a new incident.
• zapi_mcp/client.py — backward-compatible re-export shim; the real ZapiClient/ZapiError/tag_filter now live in the separate zapi-lib package.
• zapi_mcp/categories.py — Category dataclass + load_categories() for the optional ZABBIX_CATEGORIES_INI-driven daily_brief sections.
• zapi_mcp/__main__.py — CLI entry point (--version/--check/--brief) and the mcp.run() stdio server start. The mcp.run() call is wrapped in except (KeyboardInterrupt, asyncio.CancelledError) → os._exit(0): what escapes on ^C is Python-version-dependent (3.10 raises CancelledError, 3.12/3.13 raise KeyboardInterrupt) and os._exit(0) suppresses anyio's teardown traceback (guarded by test_main.py::test_sigint_exits_cleanly).