Ir al contenido

Datos y sincronización

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 plan; los gastos son negativos, las entradas positivas.

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.

El registro de cambios de la API de YNAB indica que en la versión 1.79.0, publicada el 5 de marzo de 2026, se cambió el nombre de /budgets por /plans: 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.

La mayoría de las herramientas necesitan las transacciones del plan: 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 plan, 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 plan, 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 planes. Con varios planes, 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.

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 plan 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_age_of_money, get_category_balances, get_budget_vs_actual, get_underfunded_targets, get_debt_payoff_plan, approve_transactions, la vista previa de set_category_budget, la vista previa de move_money, la vista previa de flag_transactions, la vista previa de set_category_target
2 get_net_worth_trend, get_runway, get_debt_payoff_plan sin monthly_budget cuando falta un pago mínimo, reconcile_account, create_transactions, create_category, update_category, list_payees, la vista previa de rename_payee, undo_operation
3 get_runway con essential_groups, get_savings_rate, find_transactions, find_recurring_charges, 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, y esa respuesta nunca se reintenta: avenir-mcp devuelve … YNAB 429: … y no envía ninguna petición durante 10 minutos, o durante el número de segundos que indica la cabecera Retry-After de YNAB cuando la respuesta la incluye (mantenido entre 1 minuto y 1 hora). avenir-mcp 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.

Una lectura que falla de camino — un tiempo de espera agotado, una conexión rechazada, un 502, un 503 o un 504 — se envía de nuevo, tres veces en total, con una breve espera que se duplica entre cada intento. Repetir una lectura no cambia nada, así que solo le cuesta peticiones, y cada intento se descuenta de las 180 de la hora.

Una escritura es distinta. Una vez que un POST, un PATCH o un DELETE ha salido, avenir-mcp nunca lo vuelve a enviar: YNAB puede haberlo aplicado y haber respondido por una conexión que ya no existía, y una segunda copia crearía una segunda transacción o un segundo cambio. El único fallo que vuelve a enviar una escritura es el que demuestra que nunca salió, como una conexión rechazada.

Así, una escritura cuya respuesta nunca llegó termina en una respuesta que dice exactamente eso: el cambio puede estar aplicado o no, y se le indica al agente que mire con find_transactions o get_category_balances en lugar de repetirla. Una lectura que nunca llegó a su destino dice, en cambio, que no se cambió nada y que se puede volver a pedir en unos minutos.

avenir-mcp no guarda ninguna copia en disco. Las transacciones viven en memoria mientras el servidor se ejecuta; el diario solo contiene identificadores, los importes asignados por un cambio de presupuesto o un movimiento entre categorías, el objetivo que restaurar y los dos nombres de un beneficiario renombrado; el token se queda en el entorno y nunca se registra.

Proyecto no oficial. «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.» No estamos afiliados, asociados ni conectados oficialmente de ninguna manera con YNAB ni con sus filiales o empresas afiliadas. El sitio web oficial de YNAB se encuentra en https://www.ynab.com. Los nombres YNAB y You Need A Budget, así como los nombres, nombres comerciales, marcas, emblemas e imágenes relacionados, son marcas registradas de YNAB. avenir-mcp se ofrece tal cual, sin garantía, y no es asesoramiento financiero. Aviso legal · Privacidad