Contributing¶
The contributor guide lives at the repo root so it's the first thing a developer sees on GitHub. It is the source of truth for the development workflow:
It covers:
- Prerequisites — Go 1.26.3; Docker + kind for the cluster tiers (optional).
- Project layout (hexagonal) — the package tree and the invariants you must not break.
- The five-tier test pyramid — what each tier proves and how to run it.
- Test commands —
make test(fast, no Docker),make test-envtest,make e2e. - Adding a new tool — the checklist — TDD-first, tier selection, which gate to run.
- Raising a PR — branch off
master, run the gate, keep the diff surgical.
Documentation¶
When you change a tool's name, description, or input/output schema, the per-tool Tool reference must be regenerated:
make docs-gen # regenerate docs/tools/ from the live schemas
make docs-check # what CI runs — fails if the committed docs are stale
The tool reference is generated by cmd/docsgen, which builds the server offline
and reads the tools straight from the MCP schemas — so it never drifts from the code.
To preview the site locally:
pip install -r docs/requirements.txt
make docs-gen && mkdocs serve # http://127.0.0.1:8000