Développement

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 budget 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)

  • …
• AGENTS.md — le contrat des contributeurs, humains ou non
• justfile — toutes les commandes ci-dessous
• pyproject.toml, uv.lock — le projet Python, verrouillé

Installation

git clone https://github.com/mathbeal/avenir-mcp && cd avenir-mcp
uv sync            # Python 3.14 et les dépendances verrouillées
just check         # tous les contrôles de la CI

Astuce

Si le projet est dans un dossier synchronisé par iCloud Drive, gardez l’environnement virtuel en dehors : UV_PROJECT_ENVIRONMENT=~/.local/share/avenir-mcp/venv uv sync. iCloud peut masquer le fichier .pth d’une installation éditable, que Python ignore alors.

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
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…)
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 gitleaks sur chaque commit de l’historique (just secrets, avec Docker), typos, zizmor sur les workflows, pip-audit sur les dépendances verrouillées, la construction de la documentation avec les tests de son propre code, 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), et le MCP Inspector officiel (just inspect), qui contrôle le serveur comme le voit un client, sur le budget 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 et 3.14, et sous Windows avec Python 3.14 (sur une pull request, macOS n’essaie que 3.14 : 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. Python 3.15 tourne aussi, à titre expérimental : un échec y est un avertissement, pas un contrôle en rouge. Sur une pull request, chaque commit doit être signé 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

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 budgets 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
une vulnérabilité connue	aussitôt, quel que soit le jour

Une nouvelle version attend trois jours avant que Renovate la propose : une version cassée ou malveillante vite retirée n’atteint jamais le projet.

Tests

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 en français et en espagnol ; 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 1 500 fois, et vérifie qu’un test échoue à chaque fois. Les modifications qu’aucun test ne remarque désignent les tests à écrire ; beaucoup sont sans effet, comme la formulation d’un message.

Documentation

uv run python -m docsgen   # pages des outils, catalogue des erreurs, exemples
just docs                  # construit le site en trois 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 budget 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 et en espagnol ; un test échoue s’il en manque une.

Évaluation

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.

Commits et versions

• Les messages de commit commencent par un type — feat:, fix:, docs:, refactor:, test:, build:, ci:, chore: — car CHANGELOG.md en est généré par git-cliff.
• Pour publier : just changelog, commit, étiquette vX.Y.Z égale à avenir_mcp.__version__, puis une release GitHub. Le workflow publish construit, lance twine check --strict et envoie sur PyPI par Trusted Publishing : aucun jeton n’est stocké.