Gegevens en synchronisatie
Bedragen
Section titled “Bedragen”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.
Praten met YNAB
Section titled “Praten met YNAB”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.
Plans, vroeger budgets
Section titled “Plans, vroeger budgets”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 bronnen van YNAB
Section titled “De bronnen van YNAB”- Documentatie van de YNAB-API – endpoints, authenticatie, verzoeklimiet
- OpenAPI-specificatie – de bron van de pagina Dekking van de YNAB-API
- Wijzigingslogboek van de YNAB-API – versie 1.79.0, uitgebracht op 5 maart 2026:
/budgetsis hernoemd naar/plans - Navigating Multiple Plans in YNAB
- How to Adjust Your Plan Settings
De lokale kopie van transacties
Section titled “De lokale kopie van transacties”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:
- De eerste keer laden vraagt om elke transactie en bewaart de
server_knowledgevan YNAB, een teller van wijzigingen. - De volgende keer laden stuurt
last_knowledge_of_serveren ontvangt alleen wat er sindsdien is veranderd: nieuwe, gewijzigde en verwijderde transacties. - 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.
De verzoeklimiet van YNAB
Section titled “De verzoeklimiet van YNAB”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.
Wanneer YNAB geen antwoord geeft
Section titled “Wanneer YNAB geen antwoord geeft”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.
Wat nooit wordt opgeslagen
Section titled “Wat nooit wordt opgeslagen”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