Desarrollo

Organización

• Directorioavenir_mcp/ — el servidor (vea Arquitectura)

  • …
• Directoriotests/ — pruebas unitarias, del protocolo, de la documentación y de higiene

  • …
• Directorioevals/ — el presupuesto 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)

  • …
• 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

git clone https://github.com/mathbeal/avenir-mcp && cd avenir-mcp
uv sync            # Python 3.14 y las dependencias bloqueadas
just check         # todos los controles de la CI

Consejo

Si el proyecto está en una carpeta sincronizada por iCloud Drive, mantenga el entorno virtual fuera: UV_PROJECT_ENVIRONMENT=~/.local/share/avenir-mcp/venv uv sync. iCloud puede ocultar el archivo .pth de una instalación editable, que Python entonces ignora.

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
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…)
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 gitleaks sobre cada commit del historial (just secrets, con Docker), typos, zizmor sobre los workflows, pip-audit sobre las dependencias bloqueadas, la construcción de la documentación con las pruebas de su propio código, 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), y el MCP Inspector oficial (just inspect), que comprueba el servidor como lo ve un cliente, sobre el presupuesto 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 y 3.14, y en Windows con Python 3.14 (en una pull request, macOS solo prueba 3.14: 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. Python 3.15 también se ejecuta, como experimento: un fallo allí es un aviso, no un control en rojo. En una pull request, cada commit debe estar firmado 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

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 presupuestos 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
una vulnerabilidad conocida	de inmediato, sea el día que sea

Una versión nueva espera tres días antes de que Renovate la proponga: una versión rota o maliciosa retirada rápido nunca llega al proyecto.

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 francés y en español; 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 1.500 veces, y comprueba que una prueba falla cada vez. Los cambios que ninguna prueba detecta señalan las pruebas que escribir; muchos no tienen efecto, como la redacción de un mensaje.

Documentación

uv run python -m docsgen   # páginas de herramientas, catálogo de errores, ejemplos
just docs                  # construye el sitio en tres idiomas; un enlace roto falla
just docs-serve            # vista previa en vivo en http://localhost:4321/avenir-mcp/

docsgen ejecuta avenir-mcp sobre el presupuesto 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 y español; una prueba falla si falta una.

Evaluación

just evaluate    # todas las tareas, Sonnet, alrededor de 1 USD de su plan de Claude
uv run python -m evals.run --task classify --model haiku

Vea Evaluación.

Commits y versiones

• Los mensajes de commit empiezan por un tipo — feat:, fix:, docs:, refactor:, test:, build:, ci:, chore: — porque CHANGELOG.md se genera a partir de ellos con git-cliff.
• Para publicar: just changelog, commit, etiqueta vX.Y.Z igual a avenir_mcp.__version__, y una release de GitHub. El workflow publish construye, ejecuta twine check --strict y sube a PyPI mediante Trusted Publishing: no se guarda ningún token.