gandi-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.

Project Overview

Production-grade Python MCP server for the Gandi v5 API (domains, LiveDNS, email, billing, organizations, certificates). Uses FastMCP with a three-tier safety model: readonly (default) → readwrite → readwrite+purchases. Follows the same architectural conventions as sister projects unifi-mcp and unraid-mcp.

Commands

# Install (development)
uv sync --extra dev

# Lint
uv run ruff check src/ tests/
uv run ruff format --check src/ tests/

# Type check
uv run ty check src/gandi_mcp/

# Test (unit only)
uv run pytest tests/unit/ -v

# Run a single test file / class / test
uv run pytest tests/unit/test_server_lifespan.py -v
uv run pytest tests/unit/test_server.py::TestReadOnlyGate -v
uv run pytest tests/unit/test_config.py::TestPurchaseGate::test_purchases_enabled_when_both_set -v

# Test with coverage
uv run pytest tests/unit/ --cov=gandi_mcp --cov-report=term-missing -m "not live"

# Security scan
uv run bandit -r src/gandi_mcp/ -c pyproject.toml

# Pre-commit hooks
uv run pre-commit run --all-files

# Build package
uv build

Architecture

src/gandi_mcp/
├── __init__.py          # Package root, exports __version__
├── __main__.py          # Entry point: creates and runs server
├── server.py            # FastMCP server creation + lifespan + mode/purchase gating
├── config.py            # Pydantic settings (env vars + safety-gate properties)
├── errors.py            # Exception hierarchy + error mapping (incl. ReadOnly/PurchaseBlocked)
├── clients/
│   ├── base.py          # BaseGandiClient with retry/auth/error mapping, sharing_id passthrough
│   └── gandi.py         # Typed method-per-endpoint wrapper over the v5 REST API
└── tools/
    ├── _common.py       # get_server_context, get_client, assert_readwrite, assert_purchases_allowed
    ├── organization.py  # organization tools (read)
    ├── billing.py       # billing tools (read)
    ├── domain.py        # domain tools (read + write + purchase)
    ├── livedns.py       # LiveDNS tools (read + write)
    ├── email.py         # email tools (read + write + purchase)
    └── certificate.py   # certificate tools (read + write + purchase)