swahili-health-mcp: Instructions file for Codex

AGENTS.md — swahili-health-mcp

What this is

MCP server for Kenya county health indicators: maternal care, immunization and child stunting from the Kenya DHS 2022.

Read first

• README.md
• agent-context.json
• Portfolio reasoning standard: https://github.com/gabrielmahia/nairobi-stack/blob/main/docs/COVERAGE_ADAPTIVE_REASONING.md

Critical rules

• Truth labels: never present synthetic, simulated, demo or hand-compiled data as real or verified. Mark it in the data itself (synthetic: true, a source that says so) and in the README. If a real source cannot be cited with an as-of date, the output must say so.
• Any number a user might act on (tax rates and limits, phone numbers, emergency lines) needs a primary source or two independent listings, with the date checked in the source field. Unverifiable entries are removed, never labelled 'DEMO - verified'.
• The README tool table must list exactly the tools the server exposes; do not hard-code server counts. Keep <!-- mcp-name: io.github.gabrielmahia/swahili-health-mcp --> in the README: the MCP registry refuses a release without it.
• Every tool declares MCP annotations (readOnlyHint, idempotentHint, openWorldHint; destructiveHint for anything that sends money or messages, or writes). Read-only means no side effects.
• CI installs this repository's code (never the published package) on Python 3.11-3.15; lint failures are real (no || true). Python 3.10 reaches end of life on 2026-10-31: drop it then.
• Releases are tag-driven and tokenless: bump version in pyproject.toml and server.json together, merge to main, push tag vX.Y.Z; the Publish workflow (test, PyPI Trusted Publisher, MCP registry) does the rest. PyPI releases are immutable. After a release run scripts/glama_sync.py --apply from nature-ai-evolution-lab to regenerate glama.json from the running server (a weekly audit flags drift).
• The pyproject description must be a complete sentence naming what the tools do: it is what PyPI, the MCP registry and Glama show (six were once cut off mid-word at 80 characters). Do not hard-code tool counts in it.
• Prefer a bundled, dated, sourced snapshot (offline-first) over live calls that can hang; never call an endpoint that has not been verified to exist.
• At the tool boundary return errors to the model as data instead of crashing the server; a broad except needs # noqa: BLE001 and a reason.
• The data is the DHS Program's Kenya DHS 2022, bundled in swahili_health_mcp/data/kdhs2022_counties.json; rebuild with scripts/refresh_kdhs.py. Use the DHS-preferred reference period only, and read Nairobi from its region row (it has no county row).
• Answers must carry source, survey, period and sample size; unknown counties or vaccines are errors, never defaults.