mcp-gee-sweet 0.0.0.dev133__tar.gz

mcp_gee_sweet-0.0.0.dev133/.claude/commands/prep-for-pr.md

@@ -0,0 +1,36 @@
+# PR Readiness Checklist
+
+Review the current branch against this checklist and report the status of each item. Be specific — name the files, test IDs, or code paths involved rather than answering generically.
+
+## 1. Tests
+
+- [ ] **Unit tests written** — are there new tests in `tests/` covering the changed code?
+- [ ] **Unit tests passing** — has `uv run python -m pytest tests/` been run and passed?
+- [ ] **Regression coverage** — were tests that touch the modified files (not just new tests) also run?
+- [ ] **QA test cases written** — are there AI-driven test cases in `docs/qa/tests/` for the new/changed tools?
+- [ ] **QA tests run** — have those test cases been executed live against the fixture doc?
+- [ ] **QA results recorded** — does each test case have a `**Result (date) ✅/❌**` entry with actual observed output?
+
+## 2. QA test case tags
+
+- [ ] **`⚠️ requires-oauth` accuracy** — scan all new and modified test cases:
+  - Tag IS present when: the tool itself requires OAuth (e.g. creates files in personal Drive: `create_doc`, `create_doc_from_file`)
+  - Tag IS NOT present when: the tool is auth-agnostic and only the test fixture happens to live in personal Drive (`write_doc_content`, `get_doc_structure`, `insert_doc_text`, `delete_doc_range`, `style_doc_range`, `style_doc_table_cells`, etc.)
+  - Tag IS NOT present on error-path tests that return before making any API call
+
+## 3. Safety
+
+- [ ] **No resource IDs committed** — no Google Drive/Docs/Sheets/Calendar IDs appear in committed files. IDs belong in `.env` or `fixtures.local.md` (both gitignored).
+- [ ] **No secrets or credentials** — no API keys, tokens, or service account JSON content committed.
+
+## 4. Documentation
+
+- [ ] **Design doc** — if the work involved an architectural decision or a non-obvious design choice, is it captured in `docs/design/`?
+- [ ] **CLAUDE.md** — if a new tool was added or the architecture changed, does `CLAUDE.md` reflect it?
+
+## 5. PR hygiene
+
+- [ ] **Feature branch** — changes are on a named branch, not directly on `main`.
+- [ ] **Issues referenced** — the PR body includes `Closes #N` for every issue this work resolves. Check the branch name, commit messages, and code for issue numbers — all referenced tickets must be linked, not just the primary one.
+- [ ] **PR preview shown** — the full PR title and body were displayed to the user for review before the PR was opened.
+- [ ] **No auto-push** — `git push` only happened after the user approved.

mcp_gee_sweet-0.0.0.dev133/.dockerignore

@@ -0,0 +1,4 @@
+.venv/
+__pycache__/
+dist/
+.env

mcp_gee_sweet-0.0.0.dev133/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Lint and test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-extras --dev --python 3.12
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format check
+        run: uv run ruff format --check .
+
+      - name: Run tests
+        run: uv run python -m pytest --tb=short

mcp_gee_sweet-0.0.0.dev133/.github/workflows/docs.yml

@@ -0,0 +1,30 @@
+name: Docs
+
+on:
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: write  # needed for gh-deploy to push to gh-pages branch
+
+jobs:
+  deploy:
+    name: Build and publish docs
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0  # full history for git-revision-date plugins if added later
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-extras --dev --python 3.12
+
+      - name: Deploy docs
+        run: uv run mkdocs gh-deploy --force

mcp_gee_sweet-0.0.0.dev133/.github/workflows/publish-dev.yml

@@ -0,0 +1,55 @@
+name: Publish dev
+
+on:
+  push:
+    branches: ["develop"]
+
+permissions:
+  contents: read
+  id-token: write  # for OIDC trusted publishing
+
+jobs:
+  test:
+    name: Run tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0  # full history so uv-dynamic-versioning can read tags
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-extras --dev --python 3.12
+
+      - name: Run tests
+        run: uv run python -m pytest --tb=short
+
+  build-and-publish:
+    name: Build and publish dev release
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0  # full history so uv-dynamic-versioning can read tags
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-extras --dev --python 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@v1.14.0

mcp_gee_sweet-0.0.0.dev133/.github/workflows/release.yml

@@ -0,0 +1,72 @@
+name: Publishing
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read  # default minimal; pypi-publish job overrides with id-token: write
+
+jobs:
+  test:
+    name: Run tests before release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-extras --dev --python 3.12
+
+      - name: Run tests
+        run: uv run python -m pytest --tb=short
+
+  release-build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --frozen --all-extras --dev --python 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload distribution
+        uses: actions/upload-artifact@v7
+
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    needs: release-build
+    permissions:
+      id-token: write  # For trusted publishing
+
+    steps:
+      - name: Download release dists
+        uses: actions/download-artifact@v8
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@v1.14.0

mcp_gee_sweet-0.0.0.dev133/.gitignore

@@ -0,0 +1,18 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+**/credentials.json
+**/token.json
+**/service_account.json
+
+.env
+
+# Virtual environments
+.venv
+timings.log
+site/
+.workspace

mcp_gee_sweet-0.0.0.dev133/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

mcp_gee_sweet-0.0.0.dev133/.python-version

@@ -0,0 +1 @@
+3.13

mcp_gee_sweet-0.0.0.dev133/CLAUDE.md

@@ -0,0 +1,73 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+Run locally from the cloned repo:
+```bash
+uv run mcp-gee-sweet
+uv run mcp-gee-sweet --transport sse   # SSE instead of stdio
+```
+
+Build and publish:
+```bash
+uv build       # produces dist/*.whl
+uv sync        # install deps from uv.lock
+```
+
+Docker:
+```bash
+docker build -t mcp-gee-sweet .
+docker run --rm -p 8000:8000 \
+  -e CREDENTIALS_CONFIG=<base64> \
+  -e DRIVE_FOLDER_ID=<id> \
+  mcp-gee-sweet
+```
+
+Tests live in `tests/` and can be run with `uv run pytest`.
+
+## Architecture
+
+Logic is split across `src/mcp_gee_sweet/`: `server.py` (MCP setup, tool decorator, resources), `auth.py` (lifespan, `SpreadsheetContext`), and `tools/` (domain-based layout):
+
+- `tools/sheets/data.py` — read/write cell data (`get_sheet_data`, `get_sheet_formulas`, `get_multiple_*`, `find_in_spreadsheet`, `update_cells`, `batch_update_cells`, `batch_update`)
+- `tools/sheets/structure.py` — sheet structure (`list_sheets`, `copy_sheet`, `rename_sheet`, `create_sheet`, `add_rows`, `add_columns`, `add_chart`)
+- `tools/sheets/helpers.py` — A1 notation helpers (`_parse_a1_notation`, `_column_index_to_letter`, etc.)
+- `tools/drive/files.py` — file/folder operations (`create_spreadsheet`, `list_spreadsheets`, `list_files`, `search_files`, `create_folder`, `copy_file`, `move_file`, `rename_file`, `delete_file`, etc.)
+- `tools/drive/sharing.py` — permissions (`share_spreadsheet`, `share_file`, `list_permissions`, `update_permission`, `remove_permission`)
+- `tools/drive/transfer.py` — upload/download/sync/export/revisions
+- `tools/docs/` — Google Docs package (`create_doc`, `get_doc_content`, `write_doc_content`, `create_doc_from_file`, `insert_doc_text`, `delete_doc_range`, `get_doc_structure`, `style_doc_range`, `style_doc_table_cells`, `get_doc_theme`, `get_doc_named_styles`, `apply_theme`); sub-modules: `ast.py` (dataclass schema), `html_parser.py` (HTML→AST), `emitter.py` (AST→Docs API requests + multi-phase table fill including nested table and cell styling support)
+- `tools/cache.py` — `refresh_cache`
+- `tools/calendar.py` — Calendar API tools
+
+`__init__.py` just re-exports `main()`.
+
+**Startup / auth** (`spreadsheet_lifespan`): FastMCP lifespan context manager that authenticates on server start and injects a `SpreadsheetContext` (holding `sheets_service` and `drive_service`) into every tool call via `ctx.request_context.lifespan_context`.
+
+The project philosophy is to be as powerful and flexible as possible by default, while giving security-conscious users the configuration knobs to lock things down. Two mechanisms reflect this:
+
+- **Auth** (`AUTH_METHOD`): out of the box the waterfall tries everything so the server just works; setting `AUTH_METHOD` restricts it to exactly one method with no fallback.
+- **Tool surface** (`ENABLED_TOOLS` / `--include-tools`): by default all tools are registered; setting `ENABLED_TOOLS` to a comma-separated list of function names limits the server to exactly that subset. This lets operators expose only the tools their users need.
+
+By default (`AUTH_METHOD` unset), auth falls through in order: OAuth (`CREDENTIALS_PATH`/`TOKEN_PATH`) → service account (`CREDENTIALS_CONFIG` or `SERVICE_ACCOUNT_PATH`) → Application Default Credentials. OAuth is tried first because it authenticates as the user (full personal Drive access); service account is a fallback for headless/server deployments.
+
+Set `AUTH_METHOD` to pin a specific method with no fallback — removes ambiguity for security audits, CI, or testing a tool's behavior under a known credential type:
+- `AUTH_METHOD=oauth` — OAuth only; fails fast if credentials are missing
+- `AUTH_METHOD=service_account` — service account only; requires `CREDENTIALS_CONFIG` or `SERVICE_ACCOUNT_PATH`
+- `AUTH_METHOD=adc` — ADC only
+
+**Tool registration** (`tool` decorator wrapper): A custom `@tool()` decorator wraps `@mcp.tool()`. It checks `ENABLED_TOOLS` (set via `ENABLED_TOOLS` env var or `--include-tools` CLI arg) and skips registration for any tool not in the allowlist. This is how tool filtering works — tools simply aren't registered with FastMCP rather than being conditionally hidden.
+
+**Two Google API clients**: The server builds both a Sheets client (`sheets/v4`) and a Drive client (`drive/v3`). Most tools use only the Sheets client; `list_spreadsheets`, `create_spreadsheet`, `share_spreadsheet`, and `list_folders` use Drive. `create_spreadsheet` uses Drive to create the file (so it can place it in a folder), not the Sheets API.
+
+**A1 notation helpers**: `_parse_a1_notation`, `_column_index_to_letter`, and `_letter_to_column_index` convert between A1 ranges and the 0-based row/column indices the Sheets batchUpdate API requires. The Sheets values API uses A1 notation directly; batchUpdate requires numeric indices — keep that distinction in mind when adding new tools.
+
+**MCP resources**: Two resources are registered — `server://auth-status` (active auth method and Drive capability limits) and `spreadsheet://{spreadsheet_id}/info` (sheet list and grid properties). Both use `mcp.get_lifespan_context()` (not `ctx`) because resources don't receive a `Context` argument the same way tools do.
+
+**`batch_update` tool**: This is a passthrough to the Sheets `spreadsheets().batchUpdate()` endpoint and accepts raw request objects. It's the escape hatch for any operation not covered by the named tools (formatting, conditional formatting, dimension properties, etc.).
+
+## Development workflow
+
+**MCP restart**: After `docker compose restart mcp-gee-sweet`, Claude Code does not automatically reconnect to the SSE server — you must restart Claude Code too to re-establish the connection.
+

mcp_gee_sweet-0.0.0.dev133/CONTRIBUTING.md

@@ -0,0 +1,155 @@
+# Contributing to mcp-gee-sweet
+
+## Quick orientation
+
+- `src/mcp_gee_sweet/tools/` — one file per tool category
+- `docs/qa/tests/` — one QA test file per category, matching the tool files
+- `docs/decisions/` — ADRs; `docs/design.md` — living principles doc
+- `docs/qa/operations.yaml` — machine-readable QA operations manifest (see below)
+
+---
+
+## First-time setup
+
+### 1. Clone and install
+
+```bash
+git clone https://github.com/khuisman/mcp-gee-sweet.git
+cd mcp-gee-sweet
+uv sync
+make install-hooks
+```
+
+### 2. Configure auth and environment
+
+Copy the environment template and fill in your credentials:
+
+```bash
+# .env is gitignored — create it at the repo root
+cp /dev/null .env
+```
+
+At minimum you need one auth method and a Drive folder. See [Authentication in the README](README.md#-authentication--environment-variables-detailed) for all options.
+
+#### Choosing an auth method
+
+| Method | Setup | QA coverage | Best for |
+|---|---|---|---|
+| **Service account** | Place `service_account.json` in repo root; share your Drive folder with the service account email | ~85% of tests — Drive file creation/copy/upload skipped (service accounts have no Drive storage quota) | Headless server deployment; most development work |
+| **OAuth** | Download OAuth client JSON; set `CREDENTIALS_PATH`; browser login on first run | ~95% of tests — all Drive create/copy/upload tests eligible | Full QA runs; local development with a personal Drive |
+| **ADC** | `gcloud auth application-default login` | Same as OAuth | Google Cloud environments; local dev with gcloud installed |
+
+**For contributors:** service account covers all read, write, sheets, and chart tests. If you're adding or fixing Drive create/copy/upload tools, OAuth or ADC gives full coverage. Set `QA_AUTH_METHOD` in `.env` to match — the QA conductor will warn you which tests will be skipped before each run.
+
+The most common setup for local development:
+
+```
+SERVICE_ACCOUNT_PATH=./service_account.json
+DRIVE_FOLDER_ID=<your folder id>
+QA_AUTH_METHOD=service_account
+```
+
+### 3. Set up QA fixtures
+
+Give your AI assistant a writable Drive folder and tell it to set up your fixtures:
+
+> "Read `docs/qa/operations.yaml` and run the `setup_fixtures` operation. My Drive folder is at https://drive.google.com/drive/folders/YOUR_FOLDER_ID"
+
+The assistant will:
+- List the folder contents
+- Identify or ask you to create the fixture spreadsheet and doc
+- Populate them with known fixture data
+- Write `TEST_*` IDs to your `.env`
+
+**If you are using service account auth:** the folder and both files must be shared with the service account email. Find it at `service_account.json` → `client_email`. The service account cannot access files in personal Drive unless explicitly shared — see [the README](README.md#-google-cloud-platform-setup-detailed) for the sharing steps.
+
+### 4. Run the server
+
+```bash
+make start   # Docker (recommended)
+# or
+uv run mcp-gee-sweet --transport sse
+```
+
+---
+
+## QA operations
+
+All QA workflows are defined in [`docs/qa/operations.yaml`](qa/operations.yaml). Any AI assistant that can read files can parse this manifest and offer the operations as a menu.
+
+**To see what's available:**
+> "Read `docs/qa/operations.yaml` and tell me what QA operations are available and which ones I can run right now."
+
+The assistant will check preconditions (`.env` keys, server connectivity) and tell you which operations are ready.
+
+| Operation | When to use |
+|---|---|
+| `setup_fixtures` | First time; or after losing your `.env` |
+| `reset_fixtures` | After destructive tests; any time fixture state is uncertain |
+| `run_suite` | Full regression run across all tool categories |
+| `run_group` | Focused run after changing a specific tool category |
+| `human_confirmation` | Step-by-step with human sign-off on each result |
+
+### Running a group
+
+> "Read `docs/qa/operations.yaml` and run the `run_group` operation for `sheets`."
+
+Available groups: `read`, `write`, `sheets`, `drive`, `charts`, `calendar`, `infra`
+
+### Human confirmation flow
+
+The `human_confirmation` operation steps through tests one at a time — the AI presents each prompt and its evaluation, you confirm the verdict. This is the primary QA method for new test cases and first-time verification. See [`docs/decisions/decision-testing.md`](decisions/decision-testing.md) for the full rationale and phased trust model.
+
+---
+
+## Adding a new tool
+
+1. Add the implementation to the appropriate file in `src/mcp_gee_sweet/tools/`.
+2. Add QA test cases to the matching file in `docs/qa/tests/` with the next sequential TC number.
+3. Add the tool name to the `Available Tool Names` list in `README.md`.
+4. Run `run_group` for the affected category to verify.
+
+Every new tool must have at least:
+- A happy-path test case
+- An error/edge-case test case
+- The tool included in the `docs/qa-checklist.md` attestation
+
+See [`docs/design.md`](design.md) for the tool inclusion criteria and composite tool rules.
+
+---
+
+## Development workflow
+
+```bash
+make test        # unit tests (no credentials needed)
+make lint        # ruff linter + formatter
+make logs        # tail server logs (Docker)
+make restart     # restart server after code changes, then restart your MCP client
+```
+
+Pre-commit hooks run `ruff` on staged files. If a commit is blocked, fix the lint issue and commit again — don't skip hooks.
+
+---
+
+## Tracking work
+
+Active tasks, bugs, product decisions, and QA gaps are tracked in [GitHub Issues](https://github.com/khuisman/mcp-gee-sweet/issues). Labels:
+
+| Label | Used for |
+|---|---|
+| `bug` | Confirmed defects |
+| `decision-needed` | Observed behaviours that need a deliberate product or design decision |
+| `qa` | Missing fixtures, test infrastructure plans, QA gaps |
+| `infrastructure` | Build, CI, publishing, dev tooling |
+| `enhancement` | New features from the roadmap tiers |
+
+`docs/roadmap.md` is an orientation doc — feature ideas and historical context. Open an issue when a feature is scheduled to be built.
+
+---
+
+## Pull requests
+
+- Open a feature branch before pushing (`feat/`, `fix/`, `docs/` prefixes).
+- New tools require QA test cases and a checklist entry — PRs without them will be asked to add them.
+- Update `docs/design.md` if your change affects scope, tool inclusion criteria, or testing approach.
+- If your change warrants a new ADR, add it to `docs/decisions/` following the existing format.

mcp_gee_sweet-0.0.0.dev133/Dockerfile

@@ -0,0 +1,45 @@
+FROM alpine:latest AS base
+
+WORKDIR /app
+# Set environment variables for non-interactive installs and minimal locale
+ENV LANG=C.UTF-8
+
+# Update and install basic packages for a low resource machine
+RUN apk update && \
+    apk upgrade && \
+    apk add --no-cache \
+        bash \
+        curl \
+        tini \
+        curl \
+        coreutils \
+        git
+
+# Set tini as the init system to handle PID 1
+ENTRYPOINT ["/sbin/tini", "--"]
+
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Ensure uv is on PATH (installer places it in /root/.local/bin for root)
+ENV PATH="/root/.local/bin:${PATH}"
+
+COPY .python-version .
+
+RUN uv venv
+
+FROM base AS builder
+
+COPY . .
+
+RUN uv sync
+
+# Build the project (produces dist/*.whl)
+RUN uv build
+
+FROM base AS runner
+
+COPY --from=builder /app/dist/*.whl /app/
+
+RUN uv pip install /app/*.whl
+
+CMD ["uv", "run", "mcp-gee-sweet", "--transport", "sse"]

mcp_gee_sweet-0.0.0.dev133/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Xing Wu
+Copyright (c) 2026 Kevin Huisman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_gee_sweet-0.0.0.dev133/Makefile

@@ -0,0 +1,57 @@
+.DEFAULT_GOAL = help
+
+.PHONY: build
+build: ## Build container image.
+	docker compose build
+
+.PHONY: start
+start: ## Spin up container.
+	docker compose up -d
+
+.PHONY: down
+down: ## Stop and remove container.
+	docker compose down
+
+.PHONY: restart
+restart: ## Restart container (requires Claude Code restart to reconnect SSE).
+	docker compose restart mcp-gee-sweet
+
+.PHONY: recreate
+recreate: ## Recreate container from scratch (removes historical logs).
+	docker compose up -d --force-recreate
+
+.PHONY: logs
+logs: ## Tail container logs.
+	docker compose logs -f
+
+.PHONY: sh
+sh: ## Open a shell in the container.
+	docker compose exec mcp-gee-sweet bash
+
+.PHONY: docs
+docs: ## Serve docs locally at http://127.0.0.1:8000 (live reload).
+	uv run mkdocs serve
+
+.PHONY: install-hooks
+install-hooks: ## Install pre-commit hooks into the local git repo.
+	uv run pre-commit install
+
+.PHONY: test
+test: ## Run unit tests.
+	uv run python -m pytest
+
+.PHONY: lint
+lint: ## Run ruff linter and formatter, fixing issues in place.
+	uv run ruff check --fix src/
+	uv run ruff format src/
+
+.PHONY: lint-extra
+lint-extra: ## Run extended ruff rules (bugbear, pyupgrade, simplify) with fixes.
+	uv run ruff check --fix --extend-select B,UP,SIM,RUF src/
+	uv run ruff format src/
+
+# Self-documenting help
+# https://www.freecodecamp.org/news/self-documenting-makefile/
+.PHONY: help
+help: ## Show this help.
+	@egrep -h '\s##\s' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-16s\033[0m %s\n", $$1, $$2}'