mad-invoice-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

mad-invoice-mcp is an MCP (Model Context Protocol) server for creating, storing, and rendering invoices as JSON + LaTeX + PDF. Data is stored locally in .mad_invoice/ (gitignored) with no external database dependency. The project is designed for single-company/single-user workflows.

Development Commands

Start the server

./bin/dev                      # create .venv and start uvicorn on 127.0.0.1:8000
MCP_ENABLE_WRITES=1 ./bin/dev  # enable write-capable tools

Docker

docker build -t mad-invoice-mcp .
docker run --rm -p 8000:8000 -e MCP_ENABLE_WRITES=1 \
  -v $(pwd)/.mad_invoice:/app/.mad_invoice \
  mad-invoice-mcp

Environment Setup

• Python 3.11+
• pdflatex from TeX Live 2024+ required for PDF rendering
  • Auto-discovered in system PATH, ~/.local/texlive/, /usr/local/texlive/
  • Override with PDFLATEX_PATH=/path/to/pdflatex
  • Docker image includes TeX Live 2025 to avoid pdflatex bugs (optional)
• Requirements: pip install -r requirements.txt

Architecture

Data Model (bridge/backends/invoices_models.py)

• Party: Represents supplier or customer. Supports:
  • name: Natural person name (required, appears first)
  • business_name: Optional trade/brand name (renders as second line)
  • Address, contact, and tax fields with validation
• LineItem: Invoice line with description, quantity, unit, unit_price
• Invoice: Main entity with:
  • Strict Pydantic validation (extra="forbid" rejects unexpected fields)
  • status: Lifecycle flag ("draft" | "final")
  • payment_status: Payment tracking ("open" | "paid" | "overdue" | "cancelled")
  • small_business: Boolean for German §19 UStG (VAT exemption)
  • vat_rate: Float 0-1 for VAT calculation when small_business=False
  • language: "de" | "en" for localization
  • Validation: due_date >= invoice_date, subtotal >= 0