gnucash-mcp: Instructions file for Claude Code

GnuCash MCP Server — Contributor Guide

AI-facing orientation for contributors (human or AI) working on this codebase. See README.md for end-user usage and CHANGELOG.md for the per-release history.

Local working notes specific to the maintainer live in CLAUDE.local.md (not in version control).

---

Project at a glance

An MCP server that exposes a GnuCash SQLite book to AI assistants as a set of typed tools. Read and write transactions, run reports, manage scheduled transactions, budgets, investment lots, and a full business module (customers, vendors, employees, invoices, bills).

Tech stack:

• Python 3.10+
• piecash — GnuCash SQLite ORM
• MCP Python SDK (mcp[cli])
• SQLAlchemy under piecash; direct Core access where the ORM blocks us
• pytest for unit + integration coverage

---

How the codebase reached its current shape

A few architectural moves shaped the present structure. The full release-by-release history is in CHANGELOG.md; what follows is the arc, not the chronicle.

• Single-file → modular mixins. Early versions kept everything in one book.py. As the surface grew (reconciliation, reporting, budgets, scheduling, investments, business), the monolith was split into per-area mixins composed via build_book_class. Tools moved alongside under tools/<area>.py. Disabling a module via --modules skips both the mixin and the tool registration cleanly.
• Lazy load with a registry. TOOL_MODULES in server.py is the single source of truth for which tools belong to which module. _lazy_load_tool_module(name) imports tools/<name>.py only when the module is enabled, then _apply_module_filter removes anything registered that isn't in TOOL_MODULES[<name>]. A test in tests/test_modules.py::TestToolFileVsModulesMapping locks the contract — it catches the bug class where a new tool gets the @mcp.tool() decoration but is forgotten in TOOL_MODULES.
• Multi-currency rebuild. Originally USD-was-everywhere assumed. When the first non-USD-default book showed up, a class of bugs surfaced where reports summed raw split.quantity across commodities, prices defaulted to USD even for currency arguments, and FX gain/loss from rate drift wasn't recognized. The fix threaded _split_in_default_currency (or equivalent factor map) through every aggregation path, made create_price default to the book's default currency, and added realized FX recognition on cross-currency invoice payment.
• Dashboard as a work queue. get_book_summary started as a status snapshot and evolved into the LLM's first-call orientation surface. It now surfaces net-worth trajectory, runway, monthly net income, budget pacing, reconciliation backlog with split counts, warnings, and upcoming scheduled transactions — answering "what do I need to do next" in one call.
• Audit log dispatcher. Originally a 380-line if/elif chain; flattened into a (entity_type, operation) → formatter dispatch table. Adding a new entity-operation pair is one row in the table plus a small formatter function.