Ga naar inhoud

Gegevens en synchronisatie

YNAB bewaart elk bedrag als een geheel aantal milliunits: 1,00 is 1000, −12,34 is -12340. avenir-mcp rekent om aan de grens en laat de agent nooit milliunits zien:

Richting Regel
YNAB → agent milliunits / 1000
agent → YNAB round(amount × 1000): 111,32 wordt precies 111320

Sommen, verschillen en verdelingen worden in milliunits berekend en daarna één keer omgerekend, zodat geen afrondingsfout een cent kan laten ontstaan of verdwijnen. Bedragen zijn in de eigen valuta van het plan; uitgaven zijn negatief, inkomend geld positief.

client.py is de enige module die de API van YNAB aanroept:

Basis-URL https://api.ynab.com/v1, of AVENIR_MCP_YNAB_URL
Authenticatie Authorization: Bearer <YNAB_API_KEY> bij elk verzoek
Gebruikte methoden GET om te lezen; PATCH, POST en DELETE op transacties, categorieën en maandbudgetten
Fouten elke 4xx of 5xx komt terug als Error calling tool '<tool>': YNAB <status>: <detail>, met de eigen uitleg van YNAB

plan_id accepteertlast-used, wat door YNAB wordt omgezet naar het plan dat u als laatste hebt geopend.

In het wijzigingslogboek van de YNAB-API staat vermeld dat in versie 1.79.0, uitgebracht op 5 maart 2026, /budgets is gewijzigd in /plans: de specificatie documenteert alleen nog paden /plans. avenir-mcp volgt dat: zijn client roept /plans aan, en zijn tools zeggen list_plans en plan_id. Het woord budget blijft waar YNAB het houdt, voor het geld dat aan een categorie is toegewezen (budgeted, getoond als Assigned), vandaar set_category_budget en get_budget_vs_actual.

De meeste tools hebben de transacties van het plan nodig: om te vinden wat openstaat, te leren van de geschiedenis, te vergelijken met de bank, vooruit te rekenen. Ze bij elke aanroep allemaal downloaden zou traag zijn en het quotum van YNAB opmaken. avenir-mcp houdt per plan een kopie in het geheugen en werkt die bij met de delta-synchronisatie van YNAB:

  1. De eerste keer laden vraagt om elke transactie en bewaart de server_knowledge van YNAB, een teller van wijzigingen.
  2. De volgende keer laden stuurt last_knowledge_of_server en ontvangt alleen wat er sindsdien is veranderd: nieuwe, gewijzigde en verwijderde transacties.
  3. avenir-mcp voegt ze samen in zijn kopie: een gewijzigde transactie vervangt de oude, een verwijderde wordt weggehaald.

Met de id van een plan wordt de kopie vernieuwd via delta-synchronisatie. Met last-used, wat verwijst naar het plan dat u het laatst in YNAB hebt geopend en dat tussen twee aanroepen kan veranderen, worden transacties elke keer volledig geladen — nog steeds via één verzoek — zodat twee plannen nooit door elkaar worden gehaald. Bij meerdere plannen dient u de id uit door te gevenlist_plans.

De kopie leeft zo lang als het serverproces. Gefilterde leesacties – op datum of op categorie – gaan eromheen.

YNAB staat 200 verzoeken per uur per token toe, over een voortschrijdend venster. Wat elke tool kost met een lege cache, wordt gemeten op het demoplan en vermeld op zijn naslagpagina:

Kosten Tools
0 elke aanroep die door de controle wordt geweigerd (een verkeerd geschreven maand, een lege naam…)
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, een voorbeeld van set_category_budget, een voorbeeld van move_money, een voorbeeld van flag_transactions, een voorbeeld van set_category_target
2 get_net_worth_trend, get_runway, get_debt_payoff_plan zonder monthly_budget als een minimale betaling ontbreekt, reconcile_account, create_transactions, create_category, update_category, list_payees, een voorbeeld van rename_payee, undo_operation
3 get_runway met essential_groups, get_savings_rate, find_transactions, find_recurring_charges, list_scheduled_transactions, suggest_categories (een hele pagina), apply_categories, een voorbeeld van split_transaction
4 forecast_balance
1 + N get_spending_trends over N maanden

Het toepassen van een bevestigde schrijfactie voegt een eigen verzoek toe (één gebundelde PATCH voor elk aantal transacties). Met een warme cache kost opnieuw lezen van de transacties één klein deltaverzoek.

Wanneer het quotum is opgebruikt, geeft YNAB het antwoord 429, en dat antwoord wordt nooit opnieuw geprobeerd: avenir-mcp retourneert … YNAB 429: … en verstuurt gedurende 10 minuten helemaal geen verzoek, of voor het aantal seconden dat in de Retry-After-header van YNAB wordt gevraagd wanneer het antwoord er een draagt (gehouden tussen 1 minuut en 1 uur). Het stopt ook vanzelf bij 180 verzoeken in het afgelopen uur, waarbij de rest wordt overgelaten aan andere apps die hetzelfde token gebruiken, en geeft aan over hoeveel minuten het volgende verzoek kan worden verzonden. In beide gevallen krijgt de agent de opdracht om u hiervan op de hoogte te stellen en niet eerder opnieuw te proberen.

Een leesbewerking die onderweg mislukt — een time-out, een geweigerde verbinding, een 502, een 503 of een 504 — wordt opnieuw verzonden, in totaal drie keer, met een korte wachttijd die zich tussendoor verdubbelt. Een leesbewerking herhalen verandert niets, dus het kost u alleen verzoeken, en elke poging telt mee voor de 180 van het uur.

Een schrijfbewerking is anders. Zodra een POST, een PATCH of een DELETE is verzonden, verstuurt avenir-mcp deze nooit nogmaals: YNAB heeft de bewerking mogelijk al toegepast en geantwoord via een verbinding die er niet meer was, en een tweede exemplaar zou een tweede transactie of een tweede wijziging aanmaken. De enige fout waarbij een schrijfbewerking wel opnieuw wordt verzonden, is die welke bewijst dat ze nooit is verzonden, bijvoorbeeld een geweigerde verbinding.

Een schrijfbewerking waarvan het antwoord nooit is teruggekomen, eindigt dus in een antwoord dat precies dat zegt: de wijziging is misschien wel en misschien niet doorgevoerd, en de agent krijgt de opdracht om met find_transactions of get_category_balances te kijken in plaats van ze te herhalen. Een leesbewerking die nooit is doorgekomen, zegt juist dat er niets is gewijzigd en dat ze over enkele minuten opnieuw kan worden gevraagd.

avenir-mcp bewaart geen kopie op schijf. De transacties leven in het geheugen zolang de server draait; het journaal bevat alleen id’s, de bedragen die een budgetwijziging of verschuiving toewees, het doel om te herstellen en de twee namen van een hernoemde begunstigde; het token blijft in de omgeving en wordt nooit gelogd.

Onofficieel project. “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.” We zijn op geen enkele manier verbonden, geassocieerd of officieel gelieerd aan YNAB of een van zijn dochterondernemingen of gelieerde bedrijven. De officiële website van YNAB vind je op https://www.ynab.com. De namen YNAB en You Need A Budget, evenals verwante namen, handelsnamen, merken, emblemen en afbeeldingen, zijn geregistreerde handelsmerken van YNAB. avenir-mcp wordt geleverd zoals het is, zonder garantie, en is geen financieel advies. Juridische informatie · Privacy