Données et synchronisation
Montants
Section intitulée « Montants »YNAB stocke chaque montant en nombre entier de milliunités : 1,00 vaut 1000,
−12,34 vaut -12340. avenir-mcp convertit à la frontière et ne montre jamais de milliunités
à l’agent :
| Sens | Règle |
|---|---|
| YNAB → agent | milliunités / 1000 |
| agent → YNAB | round(montant × 1000) : 111,32 devient exactement 111320 |
Sommes, différences et proratas sont calculés en milliunités, puis convertis une seule fois : aucune erreur d’arrondi ne crée ni ne perd un centime. Les montants sont dans la devise du plan ; les dépenses sont négatives, les entrées positives.
Parler à YNAB
Section intitulée « Parler à YNAB »client.py est le seul module qui appelle l’API de YNAB :
| URL de base | https://api.ynab.com/v1, ou AVENIR_MCP_YNAB_URL |
| Authentification | Authorization: Bearer <YNAB_API_KEY> sur chaque requête |
| Méthodes | GET pour lire ; PATCH, POST et DELETE sur les transactions, les catégories et les budgets mensuels |
| Erreurs | tout 4xx ou 5xx revient en Error calling tool '<tool>': YNAB <status>: <detail>, avec l’explication de YNAB |
plan_id accepte last-used, que YNAB résout en votre dernier plan ouvert.
Les plans, anciens budgets
Section intitulée « Les plans, anciens budgets »Le journal des modifications de l’API de YNAB indique que
la version 1.79.0, publiée le 05/03/2026, a renommé /budgets en /plans : la
spécification ne documente plus que des chemins /plans. avenir-mcp suit : son client
appelle /plans, et ses outils disent list_plans et plan_id. Le mot budget reste là
où YNAB le garde, pour l’argent attribué à une catégorie (budgeted, affiché Assigned),
d’où set_category_budget et get_budget_vs_actual.
Les références de YNAB
Section intitulée « Les références de YNAB »- Documentation de l’API YNAB — points d’accès, authentification, quota (en anglais)
- Spécification OpenAPI — la source de la page Couverture de l’API YNAB
- Journal des modifications de l’API YNAB — version 1.79.0 publiée le 05/03/2026 :
/budgetsa été renommé/plans - Navigating Multiple Plans in YNAB
- How to Adjust Your Plan Settings
La copie locale des transactions
Section intitulée « La copie locale des transactions »La plupart des outils ont besoin des transactions du plan : trouver ce qui attend, apprendre de l’historique, comparer avec la banque, prévoir. Tout télécharger à chaque appel serait lent et consommerait le quota de YNAB. avenir-mcp garde une copie par plan, en mémoire, et la rafraîchit par la synchronisation incrémentale de YNAB :
- Le premier chargement demande toutes les transactions et garde le
server_knowledgede YNAB, un compteur de modifications. - Le chargement suivant envoie
last_knowledge_of_serveret ne reçoit que ce qui a changé depuis : transactions nouvelles, modifiées et supprimées. - avenir-mcp les fusionne dans sa copie : une transaction modifiée remplace l’ancienne, une transaction supprimée est retirée.
Avec l’identifiant d’un plan, la copie est rafraîchie par synchronisation
incrémentale. Avec last-used, qui désigne le dernier plan ouvert dans YNAB et peut
changer d’un appel à l’autre, les transactions sont chargées en entier à chaque fois —
toujours une seule requête — pour ne jamais mélanger deux plans. Avec plusieurs
plans, passez l’identifiant donné par list_plans.
La copie vit aussi longtemps que le processus du serveur. Les lectures filtrées — par date ou par catégorie — la contournent.
Le quota de YNAB
Section intitulée « Le quota de YNAB »YNAB autorise 200 requêtes par heure et par jeton, sur une fenêtre glissante. Le coût de chaque outil, cache froid, est mesuré sur le plan de démonstration et indiqué sur sa page de référence :
| Coût | Outils |
|---|---|
| 0 | tout appel refusé par la validation (mois mal formé, nom vide…) |
| 1 | list_plans, list_accounts, list_category_groups, get_monthly_summary, get_age_of_money, get_category_balances, get_budget_vs_actual, get_underfunded_targets, get_debt_payoff_plan, approve_transactions, l’aperçu de set_category_budget, l’aperçu de move_money, l’aperçu de flag_transactions, l’aperçu de set_category_target |
| 2 | get_net_worth_trend, get_runway, get_debt_payoff_plan sans monthly_budget quand un paiement minimum manque, reconcile_account, create_transactions, create_category, update_category, list_payees, un aperçu de rename_payee, undo_operation |
| 3 | get_runway avec essential_groups, get_savings_rate, find_transactions, find_recurring_charges, list_scheduled_transactions, suggest_categories (une page entière), apply_categories, l’aperçu de split_transaction |
| 4 | forecast_balance |
| 1 + N | get_spending_trends sur N mois |
Appliquer une écriture confirmée ajoute sa propre requête (un seul PATCH groupé, quel
que soit le nombre de transactions). Avec un cache chaud, relire les transactions coûte
une petite requête incrémentale.
Quand le quota est épuisé, YNAB répond 429, et cette réponse n’est jamais
réessayée : avenir-mcp renvoie … YNAB 429: … et n’envoie plus aucune requête pendant
10 minutes, ou pendant le nombre de secondes indiqué dans l’en-tête Retry-After de YNAB
lorsque la réponse en porte un (tenue entre 1 minute et 1 heure). avenir-mcp s’arrête
aussi de lui-même à 180 requêtes dans l’heure écoulée, laissant le reste aux autres
applications qui utilisent le même jeton, et dit dans combien de minutes la prochaine
requête pourra partir. Dans les deux cas, l’agent doit vous prévenir et ne pas réessayer
avant.
Lorsque YNAB ne répond pas
Section intitulée « Lorsque YNAB ne répond pas »Une lecture qui échoue en route — un délai d’attente dépassé, une connexion refusée, un
502, un 503 ou un 504 — est envoyée à nouveau, trois fois en tout, avec une
courte pause qui double à chaque fois. Répéter une lecture ne change rien : cela ne
coûte que des requêtes, et chaque tentative est décomptée des 180 de l’heure.
Une écriture est différente. Une fois qu’un POST, un PATCH ou un DELETE est parti,
avenir-mcp ne l’envoie jamais une deuxième fois : YNAB l’a peut-être déjà appliqué et
répondu dans une connexion qui n’existait plus, et une deuxième copie créerait une
deuxième transaction ou une deuxième modification. Le seul échec qui fait repartir une
écriture est celui qui prouve qu’elle n’est jamais partie, par exemple une connexion
refusée.
Ainsi, une écriture dont la réponse n’est jamais revenue se solde par une réponse qui dit
exactement cela : la modification est peut-être appliquée, peut-être pas, et l’agent doit
vérifier avec find_transactions ou get_category_balances plutôt que de la répéter.
Une lecture qui n’a jamais abouti dit au contraire que rien n’a été modifié et qu’elle
peut être redemandée dans quelques minutes.
Ce qui n’est jamais stocké
Section intitulée « Ce qui n’est jamais stocké »avenir-mcp ne garde aucune copie sur le disque. Les transactions vivent en mémoire tant que le serveur tourne ; le journal ne contient que des identifiants, les montants assignés par un changement de budget ou un déplacement entre catégories, l’objectif à rétablir et les deux noms d’un bénéficiaire renommé ; le jeton reste dans l’environnement et n’est jamais journalisé.
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é