Contributing¶

Thanks for improving MCP Zen of Languages. Whether you're fixing a bug, adding a detector, or bringing support for a new language — this section gives you the context to contribute effectively.

Local development workflow¶

Setup¶

uv sync --group dev --all-extras

This is enough for tests, linting and type checking. The docs group is only needed for documentation work (see Docs work).

Run Checks¶

uv run pytest -xvs
uv run ty check
uv run ruff check

Docs work¶

uv sync --group dev --group docs
uv run zensical build -f mkdocs.yml
uv run python scripts/check_docs_contrast.py --build --mode check

zensical is a Rust-built package. It ships prebuilt wheels for macOS (x86_64, arm64), Linux (manylinux x86_64, aarch64, armv7l; musllinux x86_64, aarch64) and Windows (amd64, arm64). On other platforms (32-bit Linux, musl armv7, 32-bit Windows) --group docs falls back to building from source, which needs a Rust toolchain. If you do not need to touch the docs, skip the group and let CI run the docs build; the docs-build-strict pre-push hook can be skipped with SKIP=docs-build-strict git push.

Pre-commit¶

pre-commit install
pre-commit run --all-files

Notes¶

• Use Python 3.12+ typing (str | None, list[str]).
• Pydantic v2 only (use ConfigDict, avoid class Config).
• Rule metrics must match detector config field names.
• Language modules must include __init__.py, analyzer.py, detectors.py, and rules.py.
• Follow the rendering conventions in docs/contributing/rendering-style-guide.md for all terminal UX changes.

Before opening a PR¶

uv run ruff check                # Lint
uv run pytest                     # Tests
uvx pre-commit run --all-files    # Pre-commit hooks

See Also¶

• Zensical Migration — Theme migration and docs build workflow updates.
• User Guide — End-user documentation surfaces impacted by contributor changes.
• API Reference — Generated API docs from docstrings.