Datos y sincronización

Importes

YNAB guarda cada importe como un número entero de miliunidades: 1,00 es 1000, −12,34 es -12340. avenir-mcp convierte en la frontera y nunca muestra miliunidades al agente:

Sentido	Regla
YNAB → agente	miliunidades / 1000
agente → YNAB	round(importe × 1000): 111,32 pasa a ser exactamente 111320

Sumas, diferencias y prorrateos se calculan en miliunidades y se convierten una sola vez: ningún error de redondeo crea ni pierde un céntimo. Los importes están en la moneda del presupuesto; los gastos son negativos, las entradas positivas.

Hablar con YNAB

client.py es el único módulo que llama a la API de YNAB:

URL base	https://api.ynab.com/v1, o AVENIR_MCP_YNAB_URL
Autenticación	Authorization: Bearer <YNAB_API_KEY> en cada petición
Métodos	GET para leer; PATCH, POST y DELETE sobre transacciones, categorías y presupuestos mensuales
Errores	cualquier 4xx o 5xx vuelve como Error calling tool '<tool>': YNAB <status>: <detail>, con la explicación de YNAB

plan_id acepta last-used, que YNAB resuelve como el último plan abierto.

Los planes, antes presupuestos

YNAB renombró los presupuestos como planes, en sus aplicaciones y en su API: la especificación ya solo documenta rutas /plans. avenir-mcp la sigue: su cliente llama a /plans, y sus herramientas dicen list_plans y plan_id. La palabra budget se queda donde YNAB la mantiene, para el dinero asignado a una categoría (budgeted, mostrado como Assigned), de ahí set_category_budget y get_budget_vs_actual.

Las referencias de YNAB

• Documentación de la API de YNAB — endpoints, autenticación, cuota (en inglés)
• Especificación OpenAPI — la fuente de la página Cobertura de la API de YNAB
• We Renamed the Budget Tab to Plan — el anuncio de YNAB (en inglés)
• Navigating Multiple Plans in YNAB
• How to Adjust Your Plan Settings

La copia local de las transacciones

La mayoría de las herramientas necesitan las transacciones del presupuesto: encontrar lo pendiente, aprender del historial, comparar con el banco, prever. Descargarlo todo en cada llamada sería lento y gastaría la cuota de YNAB. avenir-mcp guarda una copia por presupuesto, en memoria, y la actualiza con la sincronización incremental de YNAB:

1. La primera carga pide todas las transacciones y guarda el server_knowledge de YNAB, un contador de cambios.
2. La carga siguiente envía last_knowledge_of_server y recibe solo lo que cambió desde entonces: transacciones nuevas, modificadas y borradas.
3. avenir-mcp las fusiona en su copia: una transacción modificada sustituye a la anterior, una borrada se elimina.

Con el id de un presupuesto, la copia se actualiza por sincronización incremental. Con last-used, que designa el último plan abierto en YNAB y puede cambiar de una llamada a otra, las transacciones se cargan completas cada vez — sigue siendo una sola petición — para no mezclar nunca dos presupuestos. Con varios presupuestos, pase el id que da list_plans.

La copia vive tanto como el proceso del servidor. Las lecturas filtradas — por fecha o por categoría — no la usan.

Nota

Una primera versión solo guardaba el contador, no las transacciones: cada carga tras la primera devolvía solo los cambios, normalmente nada, y las sugerencias nunca encontraban historial. Una prueba comprueba ahora que un delta vacío deja la lista completa intacta.

La cuota de YNAB

YNAB permite 200 peticiones por hora por token, en una ventana deslizante. Lo que cuesta cada herramienta, con la caché fría, se mide sobre el presupuesto de demostración y se indica en su página de referencia:

Coste	Herramientas
0	toda llamada rechazada por la validación (un mes mal formado, un nombre vacío…)
1	list_plans, list_accounts, list_category_groups, get_monthly_summary, get_category_balances, get_budget_vs_actual, approve_transactions, la vista previa de set_category_budget
2	reconcile_account, create_transactions, create_category, update_category, undo_operation
3	find_transactions, list_scheduled_transactions, suggest_categories (una página entera), apply_categories, la vista previa de split_transaction
4	forecast_balance
1 + N	get_spending_trends sobre N meses

Aplicar una escritura confirmada añade su propia petición (un único PATCH agrupado, sea cual sea el número de transacciones). Con la caché caliente, releer las transacciones cuesta una pequeña petición incremental.

Cuando se agota la cuota, YNAB responde 429 sin decir cuándo volver, así que avenir-mcp no reintenta nada: devuelve … YNAB 429: … y no envía ninguna petición durante 10 minutos. También se detiene por sí mismo en 180 peticiones en la última hora, dejando el resto a otras aplicaciones que usen el mismo token, e indica en cuántos minutos podrá salir la siguiente petición. En ambos casos, el agente debe avisarle y no reintentar antes.

Lo que nunca se guarda

avenir-mcp no guarda ninguna copia en disco. Las transacciones viven en memoria mientras el servidor se ejecuta; el diario solo contiene identificadores; el token se queda en el entorno y nunca se registra.