clover-mcp-server: Instructions file for Claude Code

CLAUDE.md — Development Guidelines for clover-mcp

This file defines the coding principles and best practices that every contributor (human or AI) must follow in this project.

---

Principles

1. KISS — Keep It Simple, Stupid

Prefer the simplest solution that correctly solves the problem. Complexity is a liability.

• A new function should do one thing and do it clearly.
• If you find yourself explaining what a block of code does, simplify it first.
• Avoid abstractions until they are earned by repetition (see DRY below). A premature abstraction is worse than a copy.
• When two implementations both work, the shorter one wins — unless clarity suffers.

Applied here: resolve_base_url() in config.py is a single dict lookup, not a class hierarchy. _pick() in shaping.py is three lines. Keep new helpers at that level.

---

2. DRY — Don't Repeat Yourself

Every piece of knowledge has a single authoritative home. Duplication is the root of maintenance bugs.

• If the same logic appears in two tools, extract a shared helper in src/clover_mcp/ (formatting, shaping, windowing, etc.).
• Region → base-URL mapping lives only in config.resolve_base_url(). Never hardcode a hostname elsewhere.
• Allowlist field names live only in shaping.py. Never re-list them in a tool or a test.
• Shared test fixtures live only in tests/conftest.py.

Red flag: if you copy-paste a block and change one variable, that is a signal to parameterise, not to paste.

---

3. SOLID Principles — The Core of OOP

Applied pragmatically to this Python/async codebase:

Principle	What it means here
S — Single Responsibility	Each module has one job: config.py loads config, client.py sends HTTP, shaping.py projects responses, windowing.py splits date ranges. Don't blur those lines.
O — Open/Closed	Add new Clover resources by adding a new file under tools/ and registering it in server.py. Do not modify client.py or shaping.py to accommodate a specific tool's quirks.
L — Liskov Substitution	Not deeply relevant in a mostly-functional codebase, but: if you subclass CloverClient, the subclass must be a drop-in replacement — do not weaken the contract.
I — Interface Segregation	Keep tool signatures narrow. A tool that only reads inventory should not accept payment-related parameters. Pass only what is needed.
D — Dependency Inversion	Tools depend on CloverClient (the abstraction), not on httpx directly. Tests inject a mock-backed client — not the real network. Never import httpx inside a tool file.