mcp-zen-of-languages: Instructions file for Claude Code

Claude Code Instructions

GitHub operations

Use GitHub MCP tools (mcp__github__*) for all GitHub operations — listing PRs, reading diffs, viewing issues, creating PRs, etc. Do not use the gh CLI. The project uses Keysafe which blocks third-party CLI token consumers, so gh will always return 401 Bad credentials.

Package manager

This project uses uv exclusively. Never use pip or pip install directly.

uv sync --all-groups --all-extras   # install all deps (dev + docs)
uv sync --group dev                 # dev deps only
uv run <command>                    # run any tool in the project venv
uvx <tool>                          # run a one-off tool without installing

Running tests

uv run pytest -xvs                  # run full suite (stops at first failure)
uv run pytest -x -q --no-cov <path> # fast run without coverage

Coverage threshold is 95% — pytest will fail if it drops below. Coverage is measured over src/mcp_zen_of_languages/ only; scripts/ and tests/ are excluded.

Linting and type checking

uv run ruff check --fix             # lint with auto-fix
uv run ruff format                  # format
uv run ty check --error-on-warning  # strict type checking (ty, not mypy)
uvx pre-commit run --all-files      # run all pre-commit hooks

Ruff is configured with select = ["ALL"] — all rules enabled, only a handful explicitly suppressed (see [tool.ruff.lint.extend-ignore] in pyproject.toml). scripts/** have relaxed rules (D, T201, INP001, S, ANN ignored).

Ruff 0.16 formats Markdown. ruff format with no path argument reformats Python inside fenced code blocks in .md files, not just .py sources. The pre-commit hook is deliberately gated types_or: ["python", "pyi"] and does not do this, so a bare uv run ruff format and pre-commit run ruff-format produce different results. Prefer the hook. If you run ruff format directly, check git status for unintended .md changes before staging.