zapi-mcp: Instructions file for Claude Code

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 MCPServer.

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

• Credentials: zabbix_credentials() is the single reader (used by _client() and __main__). ZABBIX_API_TOKEN (zapi-lib >= 0.9.0 api_token=) wins over a leftover ZABBIX_USER; a token plus both user and password raises CredentialConflict; anything missing (empty counts) raises MissingEnv. Both are KeyErrors, reported via _env_error_text(). _client() and reset_client() hold _CLIENT_LOCK (sync tools run in worker threads).
• Every tool carries ToolAnnotations. A tool annotated read_only_hint=False is a write tool: _Server.tool records it in server.WRITE_TOOLS and wraps it with _refuse_in_read_only_mode, so the annotation is the only thing to set. ZABBIX_READ_ONLY removes the write tools at import time via mcp.remove_tool; an unrecognized value is treated as read-only (read_only_mode). A new write tool must also be added to tests/test_smoke_probes.STATE_CHANGING.
• zapi_mcp/server.py — MCPServer 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).