Ontwikkeling

Indeling

• Directoryavenir_mcp/ — de server (zie Architectuur)

  • …
• Directorytests/ — unittests, protocoltests, documentatie- en hygiënetests

  • …
• Directoryevals/ — het demoplan, een vervanger voor de API van YNAB, de evaluatie van agents

  • …
• Directorydocsgen/ — genereert de toolnaslag, de foutencatalogus en de voorbeelden

  • …
• Directorydocs/ — deze site (Astro Starlight, Engels, Frans, Spaans, Duits, Nederlands)

  • …
• AGENTS.md — het contract voor bijdragers, mens of niet
• justfile — elk commando hieronder
• pyproject.toml, uv.lock — het Python-project, vastgelegd

Installeren

git clone https://github.com/mathbeal/avenir-mcp && cd avenir-mcp
uv sync            # Python 3.14 en de vastgelegde afhankelijkheden
just check         # elke controle die de CI draait

Tip

Staat het project in een map die iCloud Drive synchroniseert, houd de virtuele omgeving dan erbuiten: UV_PROJECT_ENVIRONMENT=~/.local/share/avenir-mcp/venv uv sync. iCloud kan het bestand .pth van een bewerkbare installatie verbergen, dat Python dan negeert.

De controles

just check draait, in de volgorde van de CI:

Controle	Commando	Faalt als
opmaak	ruff format --check	een bestand niet is opgemaakt
lint	pylint	de score onder 10,00 ligt
ruff	ruff check	een docstring van het pakket niet in Google-stijl is of een argument, de returnwaarde of een opgeworpen exceptie weglaat; imports niet gesorteerd zijn; de beveiligingscontroles van bandit een riskant patroon vinden (TLS niet gecontroleerd, een shellcommando, een wachtwoord in de code…)
docstrings	pydoclint	een docstring van het pakket de argumenten in een andere volgorde noemt dan de signatuur, een type geeft dat de annotatie al geeft, of alleen een samenvatting is voor een functie die argumenten neemt of een waarde teruggeeft
YNAB-API-voorwaarden	pytest -m ynab_terms, python -m docsgen.terms	een regel uit de YNAB-API-voorwaarden niet wordt nageleefd (naam, vermelding woord voor woord, YNAB’s eigen afbeelding, token alleen voor de eigenaar, limiet van verzoeken per uur), of YNAB de voorwaarden heeft gewijzigd sinds de gecontroleerde datum; de badge in de README toont het
afhankelijkheden	deptry .	de code een pakket importeert dat pyproject.toml niet declareert, of er een declareert dat ze niet gebruikt
types	mypy (strikt)	welke typefout ook
tests	pytest	een test faalt, er welke waarschuwing ook optreedt, of de dekking van regels of vertakkingen onder 100 % ligt
woordenschat	lexdrift check avenir_mcp --baseline lexdrift.lock	er een nieuw woord verschijnt voor een idee dat al een naam heeft
lock	uv lock --check	uv.lock niet overeenkomt met pyproject.toml

De CI controleert ook met lychee elke link in de README en de documentatie (just links, en elke maandag, want een pagina elders kan verdwijnen), en draait typos, zizmor op de workflows, pip-audit op de vastgelegde afhankelijkheden, gitleaks op elke commit van de geschiedenis (just secrets, met Docker), de build van de documentatie met de tests van haar eigen code, CodeQL en de OpenSSF Scorecard (zodra de repository openbaar is), een wekelijkse vergelijking van de API van YNAB met zijn momentopname (just api-drift), en de officiële MCP Inspector (just inspect), die de server controleert zoals een client hem op het demoplan ziet: zijn lijsten, de overdraagbaarheid van zijn toolschema’s, en één aanroep van elk soort. De testsuite draait op Linux en macOS met Python 3.12, 3.13 en 3.14, en op Windows met Python 3.14 (bij een pull request probeert macOS alleen 3.14: zijn runners kosten evenveel als tien Linux-runners); de dekking wordt afgedwongen op Linux en macOS, waar de controles van bestandsrechten gelden. Python 3.15 draait ook, als experiment: een fout daar is een waarschuwing, geen rode controle. Bij een pull request moet elke commit afgetekend zijn (sign-off) en moet de titel met het soort wijziging beginnen. Twee controles moeten groen zijn: CI passed, die voor elke job van de kwaliteitsworkflow staat, en MCP Inspector, een eigen workflow zodat zijn badge hem alleen toont.

Afhankelijkheden

Renovate opent elke maandagochtend pull requests:

Update	Behandeling
ontwikkeltools, CI-actions, de documentatiesite (minor en patch)	gegroepeerd, vanzelf samengevoegd zodra de CI groen is
fastmcp, httpx, pydantic – ze draaien vóór de plans van gebruikers	elk een eigen pull request, met de hand beoordeeld; de evaluatie draait vóór een update van fastmcp
elke major-versie	elk een eigen pull request, met de hand beoordeeld
een bekende kwetsbaarheid	meteen, op welke dag ook

Een nieuwe release wacht drie dagen voordat Renovate haar voorstelt, zodat een kapotte of kwaadaardige versie die snel wordt ingetrokken het project nooit bereikt.

Tests

Soort	Bestanden	Wat ze controleren
Unit	test_classifier, test_triage, test_writes, test_reconcile, test_forecast, test_analytics, test_journal, test_client	de pure logica en de HTTP-client, met verzonnen gegevens
Eigenschappen	test_properties	met Hypothesis, regels die voor elke invoer gelden: bedragen overleven de heen- en terugweg, verdelen houdt elke cent, maanden tellen op, cursors, banktekst, vingerafdrukken van bevestigingen
Protocol	test_protocol*, test_context, test_policy	tools via een MCP-client in het geheugen: schema’s, annotaties, bevestigingspaden, ongedaan maken
Documentatie	test_docs	gegenereerde pagina’s en voorbeelden komen overeen met de code; elke pagina bestaat in elke vertaling; elke omgevingsvariabele is gedocumenteerd
API-dekking	test_api_coverage	elke operatie van de API van YNAB wordt door een tool gebruikt, is gepland of met een reden weggelaten; de client roept alleen gedocumenteerde paden aan
Hygiëne	test_hygiene	geen IBAN, token, afschrift, thuispad of Finder-kopie in de repository
Evaluatie	test_evals	de eigen controles van de evaluatie kloppen

Tests worden eerst geschreven. Geen enkele test roept YNAB aan.

just mutate draait mutatietests (mutmut) op de modules die rekenen: het verandert de code expres, zo’n 1.500 keer, en controleert dat er elke keer een test faalt. De wijzigingen die geen enkele test opmerkt, wijzen naar de tests die nog geschreven moeten worden; veel zijn onschuldig, zoals de formulering van een melding.

just bench meet hoe lang de rekenende modules duren op een gegenereerd plan van vijf jaar, zo’n 9.000 transacties (pytest-benchmark). Op een laptop duurt de traagste stap (een pagina met suggesties voorbereiden) ongeveer 30 ms: de tijd van een tool gaat op aan wachten op YNAB, niet aan rekenen.

just fuzz draait de Hypothesis-eigenschappen (properties) met elk 50.000 voorbeelden in plaats van 100 (een paar minuten; just fuzz 200000 voor meer), op wat van buiten komt: bankomschrijvingen, beschadigde journalen, HTTP-headers, bedragen, paginacursors. Een fout wordt bewaard en bij de volgende run, teruggebracht tot het kleinste geval, opnieuw gedraaid. De CI doet het elke nacht met 200.000. De eerste run vond een byte in het journaal die geen tekst was (0x80) en als kale codecfout verscheen in plaats van de regel te noemen die moet worden hersteld.

Documentatie

uv run python -m docsgen   # toolpagina's, foutencatalogus, voorbeelden
just docs                  # bouwt de site in elke taal; kapotte links falen
just docs-serve            # live voorbeeld op http://localhost:4321/avenir-mcp/

docsgen draait avenir-mcp op het demoplan en schrijft op wat het werkelijk antwoordt, met vaste datum en vervangen willekeurige id’s. Met de hand geschreven pagina’s bestaan in het Engels, Frans, Spaans, Duits en Nederlands; een test faalt als er een ontbreekt.

Evaluatie

just evaluate    # alle taken, Sonnet, ongeveer 1 USD van je Claude-abonnement
uv run python -m evals.run --task classify --model haiku

Zie Evaluatie.

Commits en releases

• Commitberichten beginnen met een type – feat:, fix:, docs:, refactor:, test:, build:, ci:, chore: – omdat git-cliff er CHANGELOG.md uit genereert.
• Om te releasen: just changelog, committen, tag vX.Y.Z passend bij avenir_mcp.__version__, en een GitHub-release publiceren. De workflow publish bouwt, draait twine check --strict en uploadt naar PyPI via Trusted Publishing: er wordt geen token opgeslagen.
• Daarna de MCP-registry: server.json draagt dezelfde versie (een test controleert dat); voer mcp-publisher login github en daarna mcp-publisher publish uit. De regel mcp-name: in de README bewijst dat het PyPI-pakket van jou is.