Ga naar inhoud

Ontwikkeling

  • 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
Terminal window
git clone https://github.com/mathbeal/avenir-mcp && cd avenir-mcp
uv sync # Python 3.15 en de vastgelegde afhankelijkheden
just check # elke controle die de CI draait

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.

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.

Terminal window
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.

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.

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

Zie Evaluatie.

  • Commitberichten beginnen met een type — feat:, fix:, docs:, refactor:, test:, build:, ci:, chore: — omdat CHANGELOG.md hieruit wordt gegenereerd door git-cliff, dat op basis hiervan ook de volgende versie bepaalt: een brekende wijziging verhoogt het hoofdnummer, een feat: 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, waarbij X.Y.Z overeenkomt met wat git-cliff --bumped-version op de branch weergeeft. Voer just changelog uit (git-cliff --bump, dezelfde berekening, die in het nieuwe item van CHANGELOG.md wordt geschreven) en pas avenir_mcp.__version__ aan naar hetzelfde getal. Een CI-controle voert zelf git-cliff --bumped-version uit 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 tag vX.Y.Z aan die overeenkomt met avenir_mcp.__version__ en publiceert u een GitHub-release. De publish-workflow voert twee keer een build uit met de datum van de getagde commit, stopt tenzij beide builds overeenkomen, voert twine check --strict uit en uploadt naar PyPI via Trusted Publishing: er wordt geen token opgeslagen.
  • Vervolgens het MCP-register: server.json heeft dezelfde versie (dit is een test; de CI-controle van de pull request voor de release bevestigt dit); voer mcp-publisher login github uit, gevolgd door mcp-publisher publish. Het eigendom van PyPI wordt aangetoond door de regel mcp-name: in de README.
  • De Claude Desktop-extensie draagt die ook: mcpb/manifest.json en de vastzetting avenir-mcp== in mcpb/pyproject.toml volgen avenir_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.json en de vastgezette versie in plugin/pyproject.toml, voer uv lock --project plugin uit en commit plugin/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 als xfail zolang 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 lock lost 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