idfkit-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Common Commands

# Install dependencies
uv sync

# Run all quality checks (lint, format, type check, deptry)
make check

# Run tests
make test

# Run a single test
uv run pytest tests/test_file.py::test_function -v

# Serve documentation locally
make docs

# Build and run Docker container
make docker-build && make docker-run

Before Committing

Always run the full quality gate before proposing changes:

make check && make test

This runs: lock file validation, pre-commit hooks (ruff format/lint), pyright, deptry, and pytest.

The consumer register

This repository is idfkit-mcp in the consumer register, governance/consumers.toml in idfkit-conformance, read at the governance tag pinned in .github/workflows/main.yml. The register records where the idfkit level is declared and never the level itself.

• Where the level lives: the exact idfkit==X pin in project.dependencies of pyproject.toml, and nowhere else. Bumping it needs no register change.
• Self-check: the consumer-register job in main.yml calls check-consumer.yml at that tag. It fails when the level moves to a file the register does not point at, or when a new dependency on either library appears that the register does not name. It does not care whether the level is current. Moving where the level is declared is a change to the register, in idfkit-conformance, reviewed by both languages.
• Rehearsal: .github/workflows/rehearse-candidate.yml builds a wheel from any idfkit ref and runs uv run pyright, then the tests, against it, without touching pyproject.toml or uv.lock. Run it before an idfkit release, not after one. pyright is the instrument that sees write_idf(doc, path) in tools/write.py stop meaning "save".
• Version: idfkit-mcp --version prints this server's version and the idfkit it runs against. The plugin and the hosted deployment both deliver this server to people, and each must be able to say which level it runs.