Build from source¶
truenas-mcp is a Go module. This page names the toolchain, the build, and the checks a pull request must pass.
Toolchain¶
- Go, at the release in the
goline ofgo.mod(1.26 or later). - mise, for the pinned
golangci-lintand Node.js. Runmise installin the clone. - Node.js 22 or later, for the template checks.
- Python 3, only for this site.
Build and check¶
make # format, vet and build into build/truenas-mcp
make verify # the gate without credentials: static checks, template checks and tests
make ci # the CI gate: verify, race tests and cross-builds
make help # list every target
make build stamps the binary with the git tag, the commit and the build time.
Run make verify before you call a change done. make ci BASE=origin/main
also checks the records in .memory/corrections/ against the base: no record
is removed or renamed, and only an empty promoted_to may be filled.
The unit tests use an in-memory MCP client and a mock of the appliance. No test talks to a real appliance.
Build this site¶
The documentation site lives in site/ and is built with ProperDocs and the
MaterialX theme:
make site # strict build into site/dist
make site-serve # preview at http://127.0.0.1:8000/truenas-mcp/
The site needs the Python lock in site/requirements.txt and writes its
virtual environment to build/site-venv. make ci does not build the site.
A strict build fails on a broken relative link or a missing anchor.
Write for users¶
Pages live in site/content/. A page explains what a user does, not how the
code works: the maintainer contracts stay in
docs/. A change
to user-visible behavior updates the affected page in the same pull request.
Commit messages follow Conventional Commits: the release version and the changelog come from them. See CONTRIBUTING.md.