Données et synchronisation

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 budget ; les dépenses sont négatives, les entrées positives.

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

YNAB a renommé les budgets en plans, dans ses applications et dans son API : 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

• 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
• We Renamed the Budget Tab to Plan — l’annonce de YNAB (en anglais)
• Navigating Multiple Plans in YNAB
• How to Adjust Your Plan Settings

La copie locale des transactions

La plupart des outils ont besoin des transactions du budget : 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 budget, en mémoire, et la rafraîchit par la synchronisation incrémentale de YNAB :

1. Le premier chargement demande toutes les transactions et garde le server_knowledge de YNAB, un compteur de modifications.
2. Le chargement suivant envoie last_knowledge_of_server et ne reçoit que ce qui a changé depuis : transactions nouvelles, modifiées et supprimées.
3. 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 budget, 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 budgets. Avec plusieurs budgets, 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.

Note

Une première version ne gardait que le compteur, pas les transactions : chaque chargement après le premier ne renvoyait que les changements, souvent rien, et les suggestions ne trouvaient jamais d’historique. Un test vérifie désormais qu’un delta vide laisse la liste complète intacte.

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 budget 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_category_balances, get_budget_vs_actual, approve_transactions, l’aperçu de set_category_budget
2	reconcile_account, create_transactions, create_category, update_category, undo_operation
3	find_transactions, 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 sans dire quand revenir : avenir-mcp ne réessaie donc rien. Il renvoie … YNAB 429: … et n’envoie plus aucune requête pendant 10 minutes. Il 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.

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 ; le jeton reste dans l’environnement et n’est jamais journalisé.