Desarrollo
Organización
Sección titulada «Organización»Directorioavenir_mcp/ — el servidor (vea Arquitectura)
- …
Directoriotests/ — pruebas unitarias, del protocolo, de la documentación y de higiene
- …
Directorioevals/ — el plan de demostración, un sustituto de la API de YNAB, la evaluación con agente
- …
Directoriodocsgen/ — genera la referencia de herramientas, el catálogo de errores y los ejemplos
- …
Directoriodocs/ — este sitio (Astro Starlight, inglés, francés, español, alemán, neerlandés)
- …
Directorioplugin/ — avenir-mcp como plugin de Claude Code, fijado a una versión y bloqueado
- …
- AGENTS.md — el contrato de los colaboradores, humanos o no
- justfile — todos los comandos de abajo
- pyproject.toml, uv.lock — el proyecto Python, bloqueado
Instalación
Sección titulada «Instalación»git clone https://github.com/mathbeal/avenir-mcp && cd avenir-mcpuv sync # Python 3.15 y las dependencias bloqueadasjust check # todos los controles de la CILos controles
Sección titulada «Los controles»just check ejecuta, en el orden de la CI:
| Control | Comando | Falla cuando |
|---|---|---|
| formato | ruff format --check |
un archivo no está formateado |
| lint | pylint |
la nota es inferior a 10,00; cuatro o más líneas de cálculo repetidas entre dos de los archivos que lee bastan para que baje de ahí (duplicate-code) |
| ruff | ruff check |
un docstring del paquete no sigue el estilo Google u omite un argumento, el valor devuelto o una excepción lanzada; los imports no están ordenados; los controles de seguridad de bandit encuentran un patrón de riesgo (TLS sin verificar, un comando shell, una contraseña en el código…); la complejidad ciclomática de una función supera 19, el valor más alto que alcanza actualmente el repositorio, un límite máximo que solo puede bajar (C901) |
| docstrings | pydoclint |
un docstring del paquete enumera los argumentos en otro orden que la firma, da un tipo que la anotación ya da, o se reduce a un resumen en una función que recibe argumentos o devuelve un valor |
| Condiciones de la API de YNAB | pytest -m ynab_terms, python -m docsgen.terms |
no se cumple una regla de las condiciones de la API de YNAB (nombre, mención palabra por palabra, imagen oficial de YNAB, token solo para su titular, límite de solicitudes por hora), o YNAB cambió sus condiciones desde la fecha comprobada; el distintivo del README lo muestra |
| código muerto | vulture |
un nombre que ninguna otra parte del repositorio lee, y que no está registrado por un decorador (@mcp.tool, @pytest.fixture…) ni inscrito, con la razón por la que sigue vivo, en vulture_whitelist.py |
| dependencias | deptry . |
el código importa un paquete que pyproject.toml no declara, o declara uno que no usa |
| tipos | mypy (estricto) |
cualquier error de tipos |
| pruebas | pytest |
una prueba falla, se emite cualquier aviso, o la cobertura de líneas o ramas es inferior al 100 % |
| vocabulario | lexdrift check avenir_mcp --baseline lexdrift.lock |
aparece una palabra nueva para una idea ya nombrada |
| bloqueo | uv lock --check |
uv.lock no corresponde a pyproject.toml |
La CI ejecuta además lychee sobre cada enlace del README y de la documentación (just links,
y cada lunes, porque una página externa puede desaparecer), gitleaks sobre cada commit del historial (just secrets, con
Docker), typos, zizmor sobre los workflows, reuse lint (cada archivo indica su copyright y su licencia), dos construcciones del wheel y del sdist que deben ser idénticas bit a bit (just reproducible), pip-audit sobre las
dependencias bloqueadas, la construcción de la documentación con las pruebas de su propio
código y npm audit sobre sus dependencias, CodeQL y el OpenSSF Scorecard (una vez público el repositorio), una comparación semanal de
la API de YNAB con su instantánea (just api-drift), una campaña de mutación semanal (just mutate, más abajo), y el MCP Inspector oficial (just inspect), que comprueba el servidor como lo ve un
cliente, sobre el plan de demostración: sus listas, la portabilidad de los esquemas
de sus herramientas y una llamada de cada tipo. La batería de pruebas se
ejecuta en Linux y macOS con Python 3.12, 3.13, 3.14 y 3.15, y en Windows con Python 3.15
(en una pull request, macOS solo prueba la versión más reciente de Python, la 3.15: sus
máquinas cuestan diez veces las de Linux); la cobertura se exige en Linux y macOS, donde
se aplican los controles de permisos de
archivos. En una pull request, cada commit debe llevar sign-off y el
título debe empezar por el tipo de cambio. Dos controles deben estar en verde:
CI passed, que resume todos los jobs del workflow de calidad, y MCP Inspector, un
workflow aparte para que su badge lo muestre solo.
Dependencias
Sección titulada «Dependencias»Renovate abre pull requests cada lunes por la mañana:
| Actualización | Tratamiento |
|---|---|
| herramientas de desarrollo, acciones de CI, sitio de documentación (menores y parches) | agrupadas, fusionadas solas cuando la CI pasa |
fastmcp, httpx, pydantic — se ejecutan frente a los planes de los usuarios |
una pull request cada una, revisada a mano; la evaluación se ejecuta antes de actualizar fastmcp |
| cualquier versión mayor | una pull request cada una, revisada a mano |
| la actualización semanal del archivo de bloqueo | una pull request, revisada a mano |
| una vulnerabilidad conocida | de inmediato, sea el día que sea |
Una versión nueva espera siete días antes de que Renovate la proponga: una versión rota o maliciosa retirada rápido nunca llega al proyecto. Por ahora, mientras el proyecto está en construcción, la actualización semanal del archivo de bloqueo queda exenta.
Pruebas
Sección titulada «Pruebas»| Tipo | Archivos | Qué comprueban |
|---|---|---|
| Unitarias | test_classifier, test_triage, test_writes, test_reconcile, test_forecast, test_analytics, test_journal, test_client |
la lógica pura y el cliente HTTP, con datos inventados |
| Propiedades | test_properties |
con Hypothesis, reglas que se cumplen para cualquier entrada: ida y vuelta de importes, reparto sin perder un céntimo, meses que se encadenan, cursores, texto bancario, huellas de confirmación |
| Protocolo | test_protocol*, test_context, test_policy |
las herramientas a través de un cliente MCP en memoria: esquemas, anotaciones, caminos de confirmación, deshacer |
| Documentación | test_docs |
las páginas y ejemplos generados corresponden al código; cada página existe en cada traducción; cada variable de entorno está documentada |
| Cobertura de la API | test_api_coverage |
cada operación de la API de YNAB la usa una herramienta, está prevista o se descarta con su razón; el cliente solo llama a rutas documentadas |
| Higiene | test_hygiene |
ni IBAN, ni token, ni extracto, ni ruta personal, ni copia del Finder en el repositorio |
| Evaluación | test_evals |
las comprobaciones de la evaluación son correctas |
Las pruebas se escriben primero. Ninguna prueba llama a YNAB.
just mutate ejecuta las pruebas de mutación (mutmut) sobre los módulos de cálculo: modifica
a propósito el código, unas 4.500 veces, y comprueba que una prueba falla cada vez. Un cambio
que ninguna prueba detecta es una línea cuya decisión nada lee: la respuesta es la prueba que
falta, o la marca # pragma: no mutate sobre una instrucción de una sola línea, con la razón
por la que ese cambio no puede alterar ninguna respuesta. Hoy se detecta cada mutante.
Lo que se mide es la lógica pura. do_not_mutate, en pyproject.toml, descarta los módulos
que hablan con YNAB, con el transporte o con el disco — el cliente, el servidor y sus módulos
de herramientas, el diario, los logs, la autenticación HTTP, la confirmación, la aplicación —
y los que solo contienen anotaciones y constantes: sus pruebas son las de protocolo y las de
cliente, lentas de ejecutar contra cada mutante, y comprueban cómo se conectan las piezas
entre sí más que lo que decide una línea. Solo los archivos listados en
pytest_add_cli_args_test_selection se ejecutan contra un mutante, así que cada módulo medido
debe estar cubierto por uno de ellos: un módulo al que no llega ningún archivo listado vuelve
con “no tests”, lo que no mide nada.
El workflow mutation ejecuta la campaña cada lunes, en dos núcleos y en unos ocho minutos, y
falla cuando un mutante sobrevive, cuando algún mutante no ejecuta ninguna prueba, o cuando la campaña
no encuentra ningún mutante: de lo contrario, una configuración que no mide nada pasaría. Su
badge en el README muestra esa única ejecución: un mutante superviviente lo deja en rojo toda
la semana, hasta el lunes siguiente o hasta una ejecución lanzada a mano. Un mutante que hace
que una prueba entre en un bucle sin fin en lugar de fallar, no: la prueba sí lo detectó, y
mutmut lo cuenta aparte, como un tiempo de espera agotado.
just bench mide cuánto tardan los módulos de cálculo sobre un plan generado de cinco años,
unas 9.000 transacciones (pytest-benchmark). En un portátil, la operación más lenta (preparar
una página de sugerencias) tarda unos 30 ms: el tiempo de una herramienta se va en esperar a
YNAB, no en calcular.
just fuzz ejecuta las propiedades Hypothesis con 50.000 ejemplos cada una en lugar de 100
(unos minutos; just fuzz 200000 para ir más lejos), sobre lo que viene de fuera: etiquetas
bancarias, diarios dañados, cabeceras HTTP, importes, cursores de paginación. Un fallo se guarda y se
vuelve a ejecutar, reducido al caso más pequeño, en la ejecución siguiente. La CI lo hace
cada noche con 200.000. La primera pasada encontró un byte del diario que no era texto
(0x80) y aparecía como un error de códec en bruto en lugar de nombrar la línea que corregir.
just complexity enumera las funciones que radon clasifica como C o peor, con una
complejidad ciclomática de 11 o superior, mostrando primero las peores de cada archivo y,
a continuación, la media sobre todos los bloques, incluyendo aquellos que no se muestran.
Asimismo, muestra el índice de mantenibilidad de cada módulo del paquete, ordenados de
menor a mayor: una cifra que agrupa el volumen de Halstead, la complejidad ciclomática y
el recuento de líneas, la cual clasifica los archivos entre sí y muestra la tendencia de
cada uno en lugar de emitir un veredicto, ya que la clasificación A de radon comienza en
20 y todos los archivos del paquete se sitúan muy por encima de ese valor. Un informe para
leer, no un filtro: nunca falla, y la CI no lo ejecuta. Su versión está fijada y uvx lo
recupera, al igual que con pydoclint. La complejidad que muestra no es la que limita
C901: radon cuenta los operadores booleanos, las expresiones condicionales y las
comprensiones, que el mccabe de ruff omite, por lo que la misma función obtiene una
puntuación más alta aquí que la que obtendría según el límite.
Documentación
Sección titulada «Documentación»uv run python -m docsgen # páginas de herramientas, catálogo de errores, ejemplosjust docs # construye el sitio en todos los idiomas; un enlace roto fallajust docs-serve # vista previa en vivo en http://localhost:4321/avenir-mcp/docsgen ejecuta avenir-mcp sobre el plan de demostración y escribe lo que realmente
responde, con la fecha fijada y los ids aleatorios sustituidos. Las páginas escritas a
mano existen en inglés, francés, español, alemán y neerlandés; una prueba falla si falta una.
Alojamiento
Sección titulada «Alojamiento»El sitio está alojado en Cloudflare Pages (avenir-mcp.pages.dev), que lo construye desde
el repositorio con npm run build:cloudflare y lo sirve bajo /avenir-mcp/; la raíz
redirige allí. GitHub Pages, que no puede enviar cabeceras de seguridad, solo redirige los
enlaces antiguos: el workflow docs publica allí, para cada página del sitio, una página
que lleva al lector a la misma dirección en Cloudflare, y una página 404 que hace lo mismo
con cualquier otra ruta. Cloudflare Pages envía las cabeceras de
docs/cloudflare/_headers con cada archivo: una Content-Security-Policy, HSTS,
X-Content-Type-Options: nosniff, X-Frame-Options: DENY, una política de referente,
una política de permisos y una política de apertura. La política autoriza los archivos
del sitio y cada script o estilo en línea de las páginas construidas por su SHA-256,
calculado al construir; 'wasm-unsafe-eval' permite que la búsqueda ejecute su
WebAssembly, y los atributos de estilo solo se autorizan mediante style-src-attr. La
construcción falla, también en CI, si falta una cabecera requerida o se debilita. La
variable de entorno DOCS_SITE fija la dirección de los enlaces canónicos y del mapa del sitio.
Evaluación
Sección titulada «Evaluación»just evaluate # todas las tareas, Sonnet, alrededor de 1 USD de su plan de Claudeuv run python -m evals.run --task classify --model haikuVea Evaluación.
Commits y versiones
Sección titulada «Commits y versiones»- Los mensajes de commit empiezan por un tipo —
feat:,fix:,docs:,refactor:,test:,build:,ci:,chore:— porque git-cliff generaCHANGELOG.mda partir de ellos y, además, determina la siguiente versión basándose en ellos: un cambio incompatible aumenta el número mayor, unfeat:aumenta el menor y cualquier otra cosa, el número de parche. - Para publicar una versión: abra una pull request titulada
chore(release): X.Y.Z, dondeX.Y.Zes el resultado que muestra el comandogit-cliff --bumped-versionen la rama. Ejecutejust changelog(git-cliff --bump, el mismo cálculo, que se escribe en la nueva entrada deCHANGELOG.md) y actualiceavenir_mcp.__version__con el mismo número. Una comprobación de CI repite el propio comandogit-cliff --bumped-versiony rechaza la pull request, indicando el número que esperaba, cuando el título o cualquier versión inferior no coincidan con él: el número nunca se elige manualmente. Una vez fusionado, se etiquetavX.Y.Zpara que coincida conavenir_mcp.__version__y se publica una versión en GitHub. El flujo de trabajopublishrealiza dos compilaciones con la fecha de la confirmación etiquetada, se detiene a menos que ambas compilaciones coincidan, ejecutatwine check --stricty realiza la subida a PyPI a través de Trusted Publishing: no se almacena ningún token. - A continuación, el registro de servidores MCP:
server.jsonlleva la misma versión (se trata de una prueba; la comprobación de CI de la pull request de la versión lo verifica); ejecutemcp-publisher login githuby, a continuación,mcp-publisher publish. La titularidad en PyPI queda demostrada mediante la líneamcp-name:del README. - La extensión de Claude Desktop también la lleva:
mcpb/manifest.jsony el anclajeavenir-mcp==demcpb/pyproject.tomlsiguen aavenir_mcp.__version__(una prueba y la misma comprobación de CI verifican ambos); de lo contrario, la extensión instala la versión anterior. - A continuación, el plugin de Claude Code, una vez que PyPI tenga la versión publicada:
actualice la versión en
plugin/.claude-plugin/plugin.jsony la versión fijada enplugin/pyproject.toml, ejecuteuv lock --project pluginy haga commit deplugin/uv.lock. Los tres designan una misma versión, y una prueba falla mientras no coincidan. La prueba que compara el complemento con esta versión aparece marcada comoxfailmientras el complemento siga apuntando a la versión anterior; por lo tanto, pytest informa de dicha prueba como un fallo esperado en lugar de provocar el fallo de la compilación; un complemento que vaya dos versiones por detrás o una por delante de esta versión seguirá fallando.uv locksolo resuelve una versión que PyPI ya ofrece, por lo que este es el commit que sigue a la publicación en lugar de formar parte de ella.
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