Ontwikkeling
Indeling
Section titled “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)
- …
Directoryplugin/ — avenir-mcp als Claude Code-plugin, vastgezet op een release en vastgelegd
- …
- AGENTS.md — het contract voor bijdragers, mens of niet
- justfile — elk commando hieronder
- pyproject.toml, uv.lock — het Python-project, vastgelegd
Installeren
Section titled “Installeren”git clone https://github.com/mathbeal/avenir-mcp && cd avenir-mcpuv sync # Python 3.15 en de vastgelegde afhankelijkhedenjust check # elke controle die de CI draaitDe controles
Section titled “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; vier of meer coderegels die rekenen en die zich tussen twee van de gelezen bestanden herhalen, zijn al genoeg om hem daaronder te brengen (duplicate-code) |
| 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…); de cyclomatische complexiteit van een functie hoger is dan 19, de hoogste waarde die de repository momenteel bereikt, een maximum dat alleen kan dalen (C901) |
| 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 |
| dode code | vulture |
een naam die door niets anders in de repository wordt gelezen en die noch door een decorator (@mcp.tool, @pytest.fixture…) is geregistreerd, noch met de reden waarom hij leeft in vulture_whitelist.py staat |
| 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, reuse lint (elk bestand vermeldt zijn copyright en licentie), twee builds van de wheel en de sdist die bit voor bit gelijk moeten zijn (just reproducible), 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 en npm audit op haar afhankelijkheden, CodeQL en de
OpenSSF Scorecard (zodra de repository openbaar is), een wekelijkse vergelijking van de API
van YNAB met zijn momentopname (just api-drift), een wekelijkse mutatiecampagne
(just mutate, hieronder), 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, 3.14 en 3.15, en op Windows met
Python 3.15 (bij een pull request probeert macOS alleen de nieuwste Python-versie, 3.15:
zijn runners kosten evenveel als tien Linux-runners); de dekking wordt afgedwongen op
Linux en macOS, waar de controles van
bestandsrechten gelden. 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
Section titled “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 |
| de wekelijkse verversing van het lockbestand | één pull request, met de hand beoordeeld |
| een bekende kwetsbaarheid | meteen, op welke dag ook |
Een nieuwe release wacht zeven dagen voordat Renovate haar voorstelt, zodat een kapotte of kwaadaardige versie die snel wordt ingetrokken het project nooit bereikt. Voorlopig, zolang het project in opbouw is, geldt dit niet voor de wekelijkse verversing van het lockbestand.
| 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 4.500 keer, en controleert dat er elke keer een test faalt. Een wijziging die
geen enkele test opmerkt, is een regel waarvan niets de beslissing leest: het antwoord is de
ontbrekende test, of de markering # pragma: no mutate op een instructie van één regel, met
de reden waarom die wijziging geen enkel antwoord kan veranderen. Vandaag wordt elke mutant
opgemerkt.
Wat gemeten wordt, is de pure logica. do_not_mutate in pyproject.toml laat de modules weg
die met YNAB, met het transport of met de schijf praten — de client, de server en zijn
tool-modules, het journaal, de logs, de HTTP-authenticatie, de bevestiging, de applicatie —
en de modules die alleen annotaties en constanten bevatten: hun tests zijn de protocol- en
clienttests, traag om tegen elke mutant te draaien, en ze controleren hoe de onderdelen aan
elkaar zijn verbonden in plaats van wat een coderegel beslist. Alleen de bestanden die in
pytest_add_cli_args_test_selection staan, draaien tegen een mutant, dus elke gemeten module
moet door een van hen gedekt zijn: een module die door geen enkel vermeld bestand wordt
bereikt, komt terug als “no tests”, wat niets meet.
De workflow mutation draait de campagne elke maandag, op twee cores in zo’n acht minuten, en
faalt wanneer een mutant overleeft, wanneer er een mutant geen enkele test draait, of wanneer de
campagne helemaal geen mutant vindt — anders zou een configuratie die niets meet, slagen. De
badge in de README laat die ene run zien: een overlevende mutant laat hem de hele week rood,
tot de volgende maandag of tot een met de hand gestarte run. Een mutant die een test eindeloos
laat lussen in plaats van hem te laten falen, niet: de test heeft hem wel opgemerkt, en mutmut
telt hem apart, als een time-out.
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.
just complexity geeft een overzicht van de functies die volgens radon een C-beoordeling
of slechter hebben, met een cyclomatische complexiteit van 11 of hoger, waarbij eerst de
slechtste waarden van elk bestand worden weergegeven, gevolgd door het gemiddelde over elk
blok, waarbij ook de niet-weergegeven waarden worden meegeteld. Het geeft tevens de
onderhoudbaarheidsindex van elke module van het pakket weer, beginnend met de laagste: één
getal dat het Halstead-volume, de cyclomatische complexiteit en het aantal regels
samenvat, waarmee de bestanden ten opzichte van elkaar worden gerangschikt en wordt
aangegeven welke richting elk bestand opgaat, in plaats van een oordeel te vellen,
aangezien de A-rang van radon begint bij 20 en elk bestand van het pakket ver daarboven
ligt. Een rapport om te lezen, geen filter: het faalt nooit, en de CI voert het niet uit.
De versie ervan is vastgelegd en wordt opgehaald via uvx, net als bij pydoclint. De
complexiteit die het weergeeft, is niet de complexiteit die C901 als limiet hanteert:
radon telt booleaanse operatoren, voorwaardelijke uitdrukkingen en comprehensions, die
door de mccabe van ruff buiten beschouwing worden gelaten, waardoor dezelfde functie hier
hoger scoort dan bij de limiet.
Documentatie
Section titled “Documentatie”uv run python -m docsgen # toolpagina's, foutencatalogus, voorbeeldenjust docs # bouwt de site in elke taal; kapotte links falenjust 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.
Hosting
Section titled “Hosting”De site staat op Cloudflare Pages (avenir-mcp.pages.dev), dat hem vanuit de repository
bouwt met npm run build:cloudflare en onder /avenir-mcp/ serveert; de root stuurt
daarheen door. GitHub Pages, dat geen beveiligingsheaders kan sturen, stuurt alleen oude
links door: de workflow docs publiceert daar voor elke pagina van de site een pagina die
de lezer naar hetzelfde adres op Cloudflare stuurt, en een 404-pagina die hetzelfde doet
voor elk ander pad. Cloudflare Pages stuurt de headers uit docs/cloudflare/_headers met
elk bestand mee: een Content-Security-Policy, HSTS,
X-Content-Type-Options: nosniff, X-Frame-Options: DENY, een referrer-policy, een
permissions-policy en een opener-policy. Het beleid staat de eigen bestanden van de site
toe en elk inline script en elke inline stijl van de gebouwde pagina’s via de SHA-256,
berekend bij het bouwen; 'wasm-unsafe-eval' laat de zoekfunctie haar WebAssembly
uitvoeren, en stijlattributen zijn alleen via style-src-attr toegestaan. De build faalt,
ook in CI, als een vereiste header ontbreekt of verzwakt is. De omgevingsvariabele
DOCS_SITE bepaalt het adres in canonieke links en in de sitemap.
Evaluatie
Section titled “Evaluatie”just evaluate # alle taken, Sonnet, ongeveer 1 USD van uw Claude-abonnementuv run python -m evals.run --task classify --model haikuZie Evaluatie.
Commits en releases
Section titled “Commits en releases”- Commitberichten beginnen met een type —
feat:,fix:,docs:,refactor:,test:,build:,ci:,chore:— omdatCHANGELOG.mdhieruit wordt gegenereerd door git-cliff, dat op basis hiervan ook de volgende versie bepaalt: een brekende wijziging verhoogt het hoofdnummer, eenfeat:het subnummer en al het overige het patchnummer. - Om een release uit te brengen: open een pull request met de titel
chore(release): X.Y.Z, waarbijX.Y.Zovereenkomt met watgit-cliff --bumped-versionop de branch weergeeft. Voerjust changeloguit (git-cliff --bump, dezelfde berekening, die in het nieuwe item vanCHANGELOG.mdwordt geschreven) en pasavenir_mcp.__version__aan naar hetzelfde getal. Een CI-controle voert zelfgit-cliff --bumped-versionuit en keurt de pull request af, waarbij het verwachte getal wordt vermeld, wanneer de titel of een lagere versie hiermee niet overeenkomt: het getal wordt nooit handmatig gekozen. Zodra de samenvoeging is voltooid, maakt u een tagvX.Y.Zaan die overeenkomt metavenir_mcp.__version__en publiceert u een GitHub-release. Depublish-workflow voert twee keer een build uit met de datum van de getagde commit, stopt tenzij beide builds overeenkomen, voerttwine check --strictuit en uploadt naar PyPI via Trusted Publishing: er wordt geen token opgeslagen. - Vervolgens het MCP-register:
server.jsonheeft dezelfde versie (dit is een test; de CI-controle van de pull request voor de release bevestigt dit); voermcp-publisher login githubuit, gevolgd doormcp-publisher publish. Het eigendom van PyPI wordt aangetoond door de regelmcp-name:in de README. - De Claude Desktop-extensie draagt die ook:
mcpb/manifest.jsonen de vastzettingavenir-mcp==inmcpb/pyproject.tomlvolgenavenir_mcp.__version__(een test en dezelfde CI-controle verifiëren beide), anders installeert de extensie de vorige versie. - Vervolgens de Claude Code-plugin, zodra de release op PyPI staat: pas de versie aan in
plugin/.claude-plugin/plugin.jsonen de vastgezette versie inplugin/pyproject.toml, voeruv lock --project pluginuit en commitplugin/uv.lock. De drie verwijzen naar één release, en een test mislukt zolang ze niet overeenkomen. De test waarin de plug-in met deze versie wordt vergeleken, wordt gemarkeerd alsxfailzolang de plug-in nog naar de vorige release verwijst; pytest rapporteert die test dan als een verwachte fout in plaats van de build te laten mislukken; een plug-in die twee versies achterloopt op deze versie, of één versie voorloopt, leidt nog steeds tot een fout.uv locklost alleen een release op die PyPI al aanbiedt, dus dit is de commit die volgt op de publicatie en er geen deel van uitmaakt.
Onofficieel project. “We are not affiliated, associated, or in any way officially connected with YNAB or any of its subsidiaries or affiliates. The official YNAB website can be found at https://www.ynab.com. The names YNAB and You Need A Budget, as well as related names, tradenames, marks, trademarks, emblems, and images are registered trademarks of YNAB.” We zijn op geen enkele manier verbonden, geassocieerd of officieel gelieerd aan YNAB of een van zijn dochterondernemingen of gelieerde bedrijven. De officiële website van YNAB vind je op https://www.ynab.com. De namen YNAB en You Need A Budget, evenals verwante namen, handelsnamen, merken, emblemen en afbeeldingen, zijn geregistreerde handelsmerken van YNAB. avenir-mcp wordt geleverd zoals het is, zonder garantie, en is geen financieel advies. Juridische informatie · Privacy