Aller au contenu

Développement

  • 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é
Fenêtre de terminal
git clone https://github.com/mathbeal/avenir-mcp && cd avenir-mcp
uv sync # Python 3.15 et les dépendances verrouillées
just check # tous les contrôles de la CI

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.

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.

Fenêtre de terminal
uv run python -m docsgen # pages des outils, catalogue des erreurs, exemples
just docs # construit le site dans toutes les langues ; un lien cassé échoue
just 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.

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.

Fenêtre de terminal
just evaluate # toutes les tâches, Sonnet, environ 1 USD de votre forfait Claude
uv run python -m evals.run --task classify --model haiku

Voir Évaluation.

  • Les messages de commit commencent par un type — feat:, fix:, docs:, refactor:, test:, build:, ci:, chore: — car le fichier CHANGELOG.md est 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, un feat: 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.Z correspond à la valeur affichée par la commande git-cliff --bumped-version sur la branche. Exécutez just changelog (git-cliff --bump, le même calcul, transcrit dans la nouvelle entrée du fichier CHANGELOG.md), puis mettez à jour avenir_mcp.__version__ avec ce même numéro. Un contrôle CI répète lui-même la commande git-cliff --bumped-version et 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 balise vX.Y.Z correspondant à avenir_mcp.__version__ et publiez une version sur GitHub. Le workflow publish effectue deux compilations avec la date du commit balisé, s’arrête si les deux compilations ne concordent pas, exécute twine check --strict et effectue le téléchargement vers PyPI via Trusted Publishing : aucun jeton n’est stocké.
  • Ensuite, le registre MCP : le fichier server.json porte 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 commande mcp-publisher login github, puis mcp-publisher publish. La propriété sur PyPI est attestée par la ligne mcp-name: du fichier README.
  • L’extension Claude Desktop la porte aussi : le fichier mcpb/manifest.json et l’épinglage avenir-mcp== du fichier mcpb/pyproject.toml suivent avenir_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.json et l’épinglage dans plugin/pyproject.toml, exécutez uv lock --project plugin, puis ajoutez plugin/uv.lock dans 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é xfail tant 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 commande uv lock ne 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é