Développement
Organisation
Section intitulée « Organisation »Répertoireavenir_mcp/ — le serveur (voir Architecture)
- …
Répertoiretests/ — tests unitaires, tests du protocole, de la documentation et d’hygiène
- …
Répertoireevals/ — le plan de démonstration, une doublure de l’API YNAB, l’évaluation par agent
- …
Répertoiredocsgen/ — génère la référence des outils, le catalogue des erreurs et les exemples
- …
Répertoiredocs/ — ce site (Astro Starlight, anglais, français, espagnol, allemand, néerlandais)
- …
Répertoireplugin/ — avenir-mcp en tant que plugin Claude Code, épinglé à une version et verrouillé
- …
- AGENTS.md — le contrat des contributeurs, humains ou non
- justfile — toutes les commandes ci-dessous
- pyproject.toml, uv.lock — le projet Python, verrouillé
Installation
Section intitulée « Installation »git clone https://github.com/mathbeal/avenir-mcp && cd avenir-mcpuv sync # Python 3.15 et les dépendances verrouilléesjust check # tous les contrôles de la CILes contrôles
Section intitulée « Les contrôles »just check lance, dans l’ordre de la CI :
| Contrôle | Commande | Échoue quand |
|---|---|---|
| format | ruff format --check |
un fichier n’est pas formaté |
| lint | pylint |
la note est sous 10,00 ; quatre lignes de calcul ou plus répétées entre deux des fichiers qu’il lit suffisent à l’y faire tomber (duplicate-code) |
| ruff | ruff check |
une docstring du paquet n’est pas au format Google ou omet un argument, la valeur de retour ou une exception levée ; les imports ne sont pas triés ; les contrôles de sécurité de bandit trouvent un motif risqué (TLS non vérifié, commande shell, mot de passe dans le code…) ; la complexité cyclomatique d’une fonction dépasse 19, le pire niveau atteint à ce jour dans le dépôt, un plafond qui ne peut que baisser (C901) |
| docstrings | pydoclint |
une docstring du paquet liste les arguments dans un autre ordre que la signature, donne un type que l’annotation donne déjà, ou se réduit à un résumé pour une fonction qui prend des arguments ou renvoie une valeur |
| Conditions de l’API YNAB | pytest -m ynab_terms, python -m docsgen.terms |
une règle des conditions de l’API YNAB n’est pas respectée (nommage, mention mot pour mot, image officielle de YNAB, jeton réservé à son titulaire, limite de requêtes par heure), ou YNAB a changé ses conditions depuis la date vérifiée ; le badge du README l’affiche |
| code mort | vulture |
un nom que rien d’autre dans le dépôt ne lit n’est ni enregistré par un décorateur (@mcp.tool, @pytest.fixture…) ni inscrit, avec la raison qui le garde vivant, dans vulture_whitelist.py |
| dépendances | deptry . |
le code importe un paquet que pyproject.toml ne déclare pas, ou en déclare un qu’il n’utilise pas |
| types | mypy (strict) |
une erreur de type |
| tests | pytest |
un test échoue, un avertissement est émis, ou la couverture des lignes ou des branches est sous 100 % |
| vocabulaire | lexdrift check avenir_mcp --baseline lexdrift.lock |
un nouveau mot apparaît pour une idée déjà nommée |
| verrou | uv lock --check |
uv.lock ne correspond pas à pyproject.toml |
La CI lance aussi lychee sur chaque lien du README et de la documentation (just links,
et chaque lundi, car une page ailleurs peut disparaître), gitleaks sur chaque commit de l’historique (just secrets, avec
Docker), typos, zizmor sur les workflows, reuse lint (chaque fichier indique son copyright et sa licence), deux constructions du wheel et du sdist qui doivent être identiques au bit près (just reproducible), pip-audit sur les dépendances
verrouillées, la construction de la documentation avec les tests de son propre code et npm audit sur ses dépendances, CodeQL et
l’OpenSSF Scorecard (une fois le dépôt public), une comparaison hebdomadaire de l’API YNAB
avec son instantané (just api-drift), une campagne de mutation hebdomadaire (just mutate, plus bas), et
le MCP Inspector officiel (just inspect), qui contrôle le serveur comme le voit un
client, sur le plan de démonstration : ses listes, la portabilité des schémas de ses
outils et un appel de chaque sorte. La suite de tests tourne sous Linux
et macOS avec Python 3.12, 3.13, 3.14 et 3.15, et sous Windows avec Python 3.15 (sur une
pull request, macOS n’essaie que la dernière version de Python, la 3.15 : ses machines
coûtent dix fois celles de Linux) ; la couverture est exigée sous Linux et macOS, où
s’appliquent les vérifications de permissions de
fichiers. Sur une pull request, chaque commit doit porter un sign-off et le titre doit commencer par la nature du changement. Deux contrôles doivent être
au vert : CI passed, qui résume tous les jobs du workflow de qualité, et
MCP Inspector, un workflow à part pour que son badge le montre seul.
Dépendances
Section intitulée « Dépendances »Renovate ouvre des pull requests chaque lundi matin :
| Mise à jour | Traitement |
|---|---|
| outils de développement, actions de la CI, site de documentation (mineures et correctifs) | regroupées, fusionnées d’elles-mêmes une fois la CI au vert |
fastmcp, httpx, pydantic — ils tournent devant les plans des utilisateurs |
une pull request chacune, relue à la main ; l’évaluation est lancée avant une mise à jour de fastmcp |
| toute version majeure | une pull request chacune, relue à la main |
| le rafraîchissement hebdomadaire du fichier de verrouillage | une pull request, relue à la main |
| une vulnérabilité connue | aussitôt, quel que soit le jour |
Une nouvelle version attend sept jours avant que Renovate la propose : une version cassée ou malveillante vite retirée n’atteint jamais le projet. Pour l’instant, en phase de construction, le rafraîchissement hebdomadaire du fichier de verrouillage en est exempté.
| Sorte | Fichiers | Ce qu’ils vérifient |
|---|---|---|
| Unitaires | test_classifier, test_triage, test_writes, test_reconcile, test_forecast, test_analytics, test_journal, test_client |
la logique pure et le client HTTP, sur des données inventées |
| Propriétés | test_properties |
avec Hypothesis, des règles vraies pour toute entrée : aller-retour des montants, répartition sans perdre un centime, mois qui s’enchaînent, curseurs, texte bancaire, empreintes de confirmation |
| Protocole | test_protocol*, test_context, test_policy |
les outils via un client MCP en mémoire : schémas, annotations, chemins de confirmation, annulation |
| Documentation | test_docs |
les pages et exemples générés correspondent au code ; chaque page existe dans chaque traduction ; chaque variable d’environnement est documentée |
| Couverture de l’API | test_api_coverage |
chaque opération de l’API YNAB est utilisée par un outil, prévue, ou écartée avec sa raison ; le client n’appelle que des chemins documentés |
| Hygiène | test_hygiene |
ni IBAN, ni jeton, ni relevé, ni chemin personnel, ni copie du Finder dans le dépôt |
| Évaluation | test_evals |
les vérifications de l’évaluation sont justes |
Les tests sont écrits d’abord. Aucun test n’appelle YNAB.
just mutate lance les tests de mutation (mutmut) sur les modules de calcul : il modifie
volontairement le code, quelque 4 500 fois, et vérifie qu’un test échoue à chaque fois. Une
modification qu’aucun test ne remarque est une ligne dont rien ne lit la décision : la réponse
est le test manquant, ou la marque # pragma: no mutate sur une instruction d’une seule ligne,
avec la raison pour laquelle cette modification ne peut changer aucune réponse. Aujourd’hui,
chaque mutant est remarqué.
Ce qui est mesuré, c’est la logique pure. do_not_mutate, dans pyproject.toml, écarte les
modules qui parlent à YNAB, au transport ou au disque — le client, le serveur et ses modules
d’outils, le journal, les logs, l’authentification HTTP, la confirmation, l’application — et
ceux qui ne contiennent que des annotations et des constantes : leurs tests sont les tests de
protocole et de client, lents à lancer contre chaque mutant, et ils vérifient comment les
pièces sont reliées entre elles plutôt que ce qu’une ligne décide. Seuls les fichiers listés
dans pytest_add_cli_args_test_selection tournent contre un mutant, donc chaque module mesuré
doit être couvert par l’un d’eux : un module qu’aucun fichier listé n’atteint revient en
“no tests”, ce qui ne mesure rien.
Le workflow mutation lance la campagne chaque lundi, sur deux cœurs et en quelque huit
minutes, et échoue quand un mutant survit, quand l’un d’eux ne lance aucun test, ou quand la
campagne ne trouve aucun mutant : sinon, une configuration qui ne mesure rien passerait. Son
badge dans le README montre ce seul passage : un mutant survivant le laisse rouge pour la
semaine, jusqu’au lundi suivant ou jusqu’à un passage lancé à la main. Un mutant qui fait
boucler un test sans fin au lieu de le faire échouer, non : le test l’a bien remarqué, et
mutmut le compte à part, comme un dépassement de délai.
just bench mesure la durée des modules de calcul sur un plan généré de cinq ans, environ
9 000 transactions (pytest-benchmark). Sur un portable, l’opération la plus lente (préparer
une page de suggestions) prend environ 30 ms : le temps d’un outil passe à attendre YNAB, pas
à calculer.
just fuzz lance les propriétés Hypothesis avec 50 000 exemples chacune au lieu de 100
(quelques minutes ; just fuzz 200000 pour aller plus loin), sur ce qui vient de l’extérieur :
libellés bancaires, journaux abîmés, en-têtes HTTP, montants, curseurs de pagination. Un échec est
enregistré et rejoué, réduit au plus petit cas, au lancement suivant. La CI le fait chaque
nuit avec 200 000. Le premier passage a trouvé un octet du journal qui n’était pas du texte
(0x80) et remontait en erreur de codec brute au lieu de nommer la ligne à corriger.
just complexity répertorie les fonctions que radon classe C ou pire, dont la complexité
cyclomatique est supérieure ou égale à 11, en commençant par les plus mauvaises de chaque
fichier, puis en indiquant la moyenne sur l’ensemble des blocs, en tenant compte de ceux
qui ne sont pas affichés. Il affiche également l’indice de maintenabilité de chaque module
du paquet, en commençant par le plus bas : un chiffre agrégant le volume de Halstead, la
complexité cyclomatique et le nombre de lignes, qui classe les fichiers les uns par
rapport aux autres et indique la tendance de chacun plutôt que de rendre un verdict,
puisque le classement A de radon commence à 20 et que tous les fichiers du paquet se
situent bien au-dessus de ce seuil. Un rapport à lire, pas un critère de validation : il
ne donne jamais d’échec, et la CI ne l’exécute pas. Sa version est figée et uvx le
récupère, comme pour pydoclint. La complexité qu’il affiche n’est pas celle que limite
C901 : radon compte les opérateurs booléens, les expressions conditionnelles et les
compréhensions, que le mccabe de ruff ne prend pas en compte ; ainsi, une même fonction
obtient ici un score plus élevé que celui obtenu par rapport à la limite.
Documentation
Section intitulée « Documentation »uv run python -m docsgen # pages des outils, catalogue des erreurs, exemplesjust docs # construit le site dans toutes les langues ; un lien cassé échouejust docs-serve # aperçu en direct sur http://localhost:4321/avenir-mcp/docsgen fait tourner avenir-mcp sur le plan de démonstration et écrit ce qu’il répond
réellement, date fixée et identifiants aléatoires remplacés. Les pages écrites à la main
existent en anglais, en français, en espagnol, en allemand et en néerlandais ; un test échoue s’il en manque une.
Hébergement
Section intitulée « Hébergement »Le site est hébergé sur Cloudflare Pages (avenir-mcp.pages.dev), qui le construit depuis
le dépôt avec npm run build:cloudflare et le sert sous /avenir-mcp/ ; la racine y
redirige. GitHub Pages, qui ne peut pas envoyer d’en-têtes de sécurité, ne fait plus que
rediriger les anciens liens : le workflow docs y publie, pour chaque page du site, une
page qui envoie le lecteur à la même adresse sur Cloudflare, et une page 404 qui fait de
même pour tout autre chemin. Cloudflare Pages envoie les en-têtes de
docs/cloudflare/_headers avec chaque fichier : une Content-Security-Policy, HSTS,
X-Content-Type-Options: nosniff, X-Frame-Options: DENY, une politique de référent,
une politique de permissions et une politique d’ouverture. La politique autorise les
fichiers du site et chaque script ou style en ligne des pages construites par son
SHA-256, calculé à la construction ; 'wasm-unsafe-eval' laisse la recherche exécuter
son WebAssembly, et les attributs de style ne sont autorisés que par style-src-attr. La
construction échoue, en CI aussi, si un en-tête requis manque ou est affaibli. La variable
d’environnement DOCS_SITE fixe l’adresse des liens canoniques et du plan du site.
Évaluation
Section intitulée « Évaluation »just evaluate # toutes les tâches, Sonnet, environ 1 USD de votre forfait Claudeuv run python -m evals.run --task classify --model haikuVoir Évaluation.
Commits et versions
Section intitulée « Commits et versions »- Les messages de commit commencent par un type —
feat:,fix:,docs:,refactor:,test:,build:,ci:,chore:— car le fichierCHANGELOG.mdest généré à partir de ceux-ci par git-cliff, qui détermine également la version suivante en fonction de ces messages : une modification rompant la compatibilité fait augmenter le numéro de version majeur, unfeat:fait augmenter le numéro de version mineur, et tout autre changement fait augmenter le numéro de patch. - Pour publier une version : ouvrez une pull request intitulée
chore(release): X.Y.Z, oùX.Y.Zcorrespond à la valeur affichée par la commandegit-cliff --bumped-versionsur la branche. Exécutezjust changelog(git-cliff --bump, le même calcul, transcrit dans la nouvelle entrée du fichierCHANGELOG.md), puis mettez à jouravenir_mcp.__version__avec ce même numéro. Un contrôle CI répète lui-même la commandegit-cliff --bumped-versionet rejette la pull request en indiquant le numéro attendu, lorsque le titre ou l’une des versions inférieures ne correspond pas à celui-ci : le numéro n’est jamais choisi manuellement. Une fois la fusion effectuée, créez une balisevX.Y.Zcorrespondant àavenir_mcp.__version__et publiez une version sur GitHub. Le workflowpublisheffectue deux compilations avec la date du commit balisé, s’arrête si les deux compilations ne concordent pas, exécutetwine check --strictet effectue le téléchargement vers PyPI via Trusted Publishing : aucun jeton n’est stocké. - Ensuite, le registre MCP : le fichier
server.jsonporte la même version (il s’agit d’un test ; la vérification CI de la pull request de publication permet de le confirmer) ; exécutez la commandemcp-publisher login github, puismcp-publisher publish. La propriété sur PyPI est attestée par la lignemcp-name:du fichier README. - L’extension Claude Desktop la porte aussi : le fichier
mcpb/manifest.jsonet l’épinglageavenir-mcp==du fichiermcpb/pyproject.tomlsuiventavenir_mcp.__version__(un test, ainsi que la même vérification CI, permettent de s’assurer que les deux sont cohérents) ; sinon l’extension installe la version précédente. - Ensuite, le plugin Claude Code, une fois que la version est disponible sur PyPI :
mettez à jour la version dans
plugin/.claude-plugin/plugin.jsonet l’épinglage dansplugin/pyproject.toml, exécutezuv lock --project plugin, puis ajoutezplugin/uv.lockdans un commit. Ces trois éléments désignent une même version, et un test échoue s’ils ne concordent pas. Le test qui compare le plugin à cette version est marquéxfailtant que le plugin pointe encore vers la version précédente ; ainsi, pytest signale ce test comme un échec attendu au lieu de faire échouer la compilation ; un plugin qui a deux versions de retard, ou une version d’avance par rapport à celle-ci, échoue quand même. La commandeuv lockne résout qu’une version déjà disponible sur PyPI ; il s’agit donc d’un commit qui suit la publication plutôt qu’une partie de celle-ci.
Projet non officiel. « 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. » Nous ne sommes ni affiliés, ni associés, ni liés officiellement de quelque manière que ce soit à YNAB ou à ses filiales et sociétés affiliées. Le site officiel de YNAB se trouve à l’adresse https://www.ynab.com. Les noms YNAB et You Need A Budget, ainsi que les noms, dénominations commerciales, marques, emblèmes et images qui s’y rattachent, sont des marques déposées de YNAB. avenir-mcp est fourni tel quel, sans garantie, et n’est pas un conseil financier. Mentions légales · Confidentialité