Entwicklung
Ordneravenir_mcp/ — der Server (siehe Architektur)
- …
Ordnertests/ — Unit-Tests, Protokolltests, Dokumentations- und Hygienetests
- …
Ordnerevals/ — der Demo-Plan, ein Ersatz für die API von YNAB, die Evaluierung der Agenten
- …
Ordnerdocsgen/ — erzeugt die Tool-Referenz, den Fehlerkatalog und die Beispiele
- …
Ordnerdocs/ — diese Website (Astro Starlight, Englisch, Französisch, Spanisch, Deutsch, Niederländisch)
- …
Ordnerplugin/ — avenir-mcp als Claude-Code-Plugin, an eine Version gebunden und festgeschrieben
- …
- AGENTS.md — der Vertrag für Mitwirkende, menschlich oder nicht
- justfile — jeder Befehl unten
- pyproject.toml, uv.lock — das Python-Projekt, festgeschrieben
Einrichten
Abschnitt betitelt „Einrichten“git clone https://github.com/mathbeal/avenir-mcp && cd avenir-mcpuv sync # Python 3.15 und die festgeschriebenen Abhängigkeitenjust check # jede Prüfung, die die CI ausführtDie Prüfungen
Abschnitt betitelt „Die Prüfungen“just check führt in der Reihenfolge der CI aus:
| Prüfung | Befehl | Schlägt fehl, wenn |
|---|---|---|
| Format | ruff format --check |
eine Datei nicht formatiert ist |
| Lint | pylint |
die Bewertung unter 10,00 liegt; vier oder mehr rechnende Zeilen, die sich zwischen zwei der von ihm gelesenen Dateien wiederholen, genügen dafür (duplicate-code) |
| ruff | ruff check |
ein Docstring des Pakets nicht im Google-Stil ist oder ein Argument, den Rückgabewert oder eine ausgelöste Ausnahme auslässt; Importe nicht sortiert sind; die Sicherheitsprüfungen von bandit ein riskantes Muster finden (TLS nicht geprüft, ein Shell-Befehl, ein Passwort im Code…); die zyklomatische Komplexität einer Funktion über 19 liegt, dem derzeit höchsten Wert im Repository, einer Obergrenze, die sich nur nach unten bewegen kann (C901) |
| Docstrings | pydoclint |
ein Docstring des Pakets die Argumente in anderer Reihenfolge als die Signatur nennt, einen Typ angibt, den die Annotation schon angibt, oder nur eine Zusammenfassung ist, obwohl die Funktion Argumente nimmt oder einen Wert zurückgibt |
| YNAB-API-Bedingungen | pytest -m ynab_terms, python -m docsgen.terms |
eine Regel der YNAB-API-Bedingungen verletzt ist (Name, Hinweis auf die fehlende Zugehörigkeit im Wortlaut, YNABs eigenes Bild, Token nur für seinen Inhaber, Limit an Anfragen pro Stunde) oder YNAB seine Bedingungen seit dem geprüften Datum geändert hat; das Badge in der README zeigt es an |
| Toter Code | vulture |
ein Name, den sonst nichts im Repository liest, weder von einem Dekorator (@mcp.tool, @pytest.fixture…) registriert noch mit dem Grund, warum er lebt, in vulture_whitelist.py eingetragen ist |
| Abhängigkeiten | deptry . |
der Code ein Paket importiert, das pyproject.toml nicht deklariert, oder eines deklariert, das er nicht nutzt |
| Typen | mypy (strikt) |
irgendein Typfehler |
| Tests | pytest |
ein Test fehlschlägt, irgendeine Warnung ausgelöst wird oder die Abdeckung der Zeilen oder Zweige unter 100 % liegt |
| Vokabular | lexdrift check avenir_mcp --baseline lexdrift.lock |
ein neues Wort für eine bereits benannte Idee auftaucht |
| Lock | uv lock --check |
uv.lock nicht zu pyproject.toml passt |
Die CI prüft außerdem mit lychee jeden Link der README und der Dokumentation (just links,
und jeden Montag, denn eine fremde Seite kann verschwinden), führt typos aus, zizmor auf den Workflows, reuse lint (jede Datei nennt ihr Copyright und ihre Lizenz), zwei Builds von Wheel und Sdist, die bitgenau gleich sein müssen (just reproducible), pip-audit auf den
festgeschriebenen Abhängigkeiten, gitleaks auf jedem Commit der Historie (just secrets,
mit Docker), den Build der Dokumentation mit den Tests ihres eigenen Codes und npm audit auf ihren Abhängigkeiten, CodeQL und die
OpenSSF Scorecard (sobald das Repository öffentlich ist), einen wöchentlichen Vergleich der
API von YNAB mit ihrem Schnappschuss (just api-drift), eine wöchentliche Mutationskampagne
(just mutate, weiter unten) und den offiziellen MCP Inspector
(just inspect), der den Server so prüft, wie ein Client ihn auf dem Demo-Plan sieht:
seine Listen, die Portabilität seiner Tool-Schemas und je einen Aufruf jeder Art. Die
Testsuite läuft unter Linux und macOS mit Python 3.12, 3.13, 3.14 und 3.15 und unter
Windows mit Python 3.15 (bei einem Pull Request probiert macOS nur die neueste
Python-Version, 3.15: seine Runner kosten so viel wie zehn Linux-Runner); die Abdeckung
wird unter Linux und macOS durchgesetzt, wo die
Prüfungen der Dateiberechtigungen gelten. Bei einem Pull Request muss jeder
Commit abgezeichnet sein (sign-off), und der Titel muss mit der Art der Änderung beginnen.
Zwei Prüfungen müssen grün sein: CI passed, die für jeden Job des Qualitäts-Workflows
steht, und MCP Inspector, ein eigener Workflow, damit sein Badge ihn allein zeigt.
Abhängigkeiten
Abschnitt betitelt „Abhängigkeiten“Renovate eröffnet jeden Montagmorgen Pull Requests:
| Aktualisierung | Behandlung |
|---|---|
| Entwicklungswerkzeuge, CI-Actions, die Dokumentationswebsite (Minor und Patch) | gruppiert, von selbst zusammengeführt, sobald die CI grün ist |
fastmcp, httpx, pydantic – sie laufen vor den Plans der Nutzer |
je ein Pull Request, von Hand geprüft; die Evaluierung läuft vor einer Aktualisierung von fastmcp |
| jede Major-Version | je ein Pull Request, von Hand geprüft |
| die wöchentliche Auffrischung der Lock-Datei | ein Pull Request, von Hand geprüft |
| eine bekannte Schwachstelle | sofort, an jedem Tag |
Eine neue Version wartet sieben Tage, bevor Renovate sie vorschlägt, damit eine fehlerhafte oder bösartige, schnell zurückgezogene Version das Projekt nie erreicht. Vorerst, solange das Projekt im Aufbau ist, gilt das nicht für die wöchentliche Auffrischung der Lock-Datei.
| Art | Dateien | Was sie prüfen |
|---|---|---|
| Unit | test_classifier, test_triage, test_writes, test_reconcile, test_forecast, test_analytics, test_journal, test_client |
die reine Logik und den HTTP-Client, mit erfundenen Daten |
| Eigenschaften | test_properties |
mit Hypothesis Regeln, die für jede Eingabe gelten: Beträge überstehen den Hin- und Rückweg, die Verteilung behält jeden Cent, Monate summieren sich, Cursor, Banktext, Fingerabdrücke der Bestätigung |
| Protokoll | test_protocol*, test_context, test_policy |
Tools über einen MCP-Client im Speicher: Schemas, Annotationen, Bestätigungswege, Rückgängig |
| Dokumentation | test_docs |
erzeugte Seiten und Beispiele passen zum Code; jede Seite existiert in jeder Übersetzung; jede Umgebungsvariable ist dokumentiert |
| API-Abdeckung | test_api_coverage |
jede Operation der API von YNAB wird von einem Tool genutzt, ist geplant oder mit Begründung ausgelassen; der Client ruft nur dokumentierte Pfade auf |
| Hygiene | test_hygiene |
keine IBAN, kein Token, kein Kontoauszug, kein Home-Pfad und keine Finder-Kopie im Repository |
| Evaluierung | test_evals |
die eigenen Prüfungen der Evaluierung sind richtig |
Tests werden zuerst geschrieben. Kein Test ruft YNAB auf.
just mutate führt Mutationstests (mutmut) auf den rechnenden Modulen aus: Es ändert den
Code absichtlich, etwa 4.500 Mal, und prüft, dass jedes Mal ein Test fehlschlägt. Eine
Änderung, die kein Test bemerkt, ist eine Zeile, deren Entscheidung nichts liest: Die
Antwort ist der fehlende Test oder die Markierung # pragma: no mutate auf einer
einzeiligen Anweisung, mit dem Grund, warum diese Änderung keine Antwort ändern kann.
Heute wird jeder Mutant bemerkt.
Gemessen wird die reine Logik. do_not_mutate in pyproject.toml lässt die Module aus,
die mit YNAB, mit dem Transport oder mit der Festplatte sprechen — den Client, den Server und
seine Tool-Module, das Journal, die Protokolle, die HTTP-Authentifizierung, die
Bestätigung, die Anwendung — und jene, die nur Annotationen und Konstanten enthalten: Deren
Tests sind die Protokoll- und Client-Tests, deren Ausführung gegen jeden Mutanten lange
dauert, und sie prüfen, wie die Teile miteinander verbunden sind, statt was eine Zeile
entscheidet. Nur die in pytest_add_cli_args_test_selection aufgeführten Dateien laufen
gegen einen Mutanten, deshalb muss jedes gemessene Modul von einer von ihnen abgedeckt sein:
Ein Modul, das von keiner aufgeführten Datei erreicht wird, kommt als “no tests” zurück, was
nichts misst.
Der Workflow mutation führt die Kampagne jeden Montag aus, auf zwei Kernen in etwa acht
Minuten, und schlägt fehl, wenn ein Mutant überlebt, wenn einer keinen Test ausführt oder
wenn die Kampagne überhaupt keinen Mutanten findet — andernfalls würde eine Konfiguration
bestehen, die nichts misst. Sein Badge in der README zeigt diesen einen Durchlauf: Ein
überlebender Mutant lässt es die Woche über rot, bis zum nächsten Montag oder bis zu einem
von Hand gestarteten Durchlauf. Ein Mutant, der einen Test endlos schleifen lässt, statt ihn
fehlschlagen zu lassen, nicht: Der Test hat ihn bemerkt, und mutmut zählt ihn getrennt, als
Timeout.
just bench misst die rechnenden Module auf einem generierten Budget über fünf Jahre, etwa
9.000 Buchungen (pytest-benchmark). Auf einem Laptop braucht der langsamste Schritt (eine Seite mit
Vorschlägen vorbereiten) etwa 30 ms: Die Zeit eines Werkzeugs vergeht beim Warten auf
YNAB, nicht beim Rechnen.
just fuzz führt die Hypothesis-Eigenschaften (Properties) mit je 50.000 statt 100 Beispielen aus (einige
Minuten; just fuzz 200000 für mehr), auf dem, was von außen kommt: Buchungstexte der Bank,
beschädigte Journale, HTTP-Header, Beträge, Seiten-Cursor. Ein Fehlschlag wird gespeichert und beim
nächsten Lauf, auf den kleinsten Fall verkleinert, wiederholt. Die CI tut das jede Nacht mit
200.000. Der erste Lauf fand ein Byte im Journal, das kein Text war (0x80) und als rohe
Codec-Fehlermeldung statt als zu korrigierende Zeile erschien.
just complexity listet die Funktionen auf, bei denen der radon-Rang C oder schlechter
ist und die zyklomatische Komplexität 11 oder höher beträgt, wobei zunächst die
schlechtesten Werte jeder Datei und anschließend der Durchschnitt über alle Blöcke
angegeben werden, wobei auch die nicht angezeigten Werte berücksichtigt werden. Außerdem
wird der Wartbarkeitsindex jedes Moduls des Pakets ausgegeben, beginnend mit dem
niedrigsten Wert: eine Zahl, die das Halstead-Volumen, die zyklomatische Komplexität und
die Zeilenzahl zusammenfasst. Diese Wertung vergleicht die Dateien untereinander und zeigt
auf, in welche Richtung sich jede einzelne entwickelt, anstatt ein endgültiges Urteil zu
fällen, da die Einstufung A bei radon bereits bei 20 beginnt und jede Datei des Pakets
weit darüber liegt. Ein Bericht zum Lesen, kein Prüfschritt: Er schlägt niemals fehl, und
die CI führt ihn nicht aus. Seine Version ist festgesetzt, und uvx holt es ab, ebenso
wie bei pydoclint. Die hier ausgegebene Komplexität ist nicht die Komplexität, die C901
begrenzt: radon zählt boolesche Operatoren, bedingte Ausdrücke und Comprehensions, die
das mccabe von ruff ausklammert, sodass dieselbe Funktion hier einen höheren Wert erzielt
als bei der Bewertung anhand des Grenzwerts.
Dokumentation
Abschnitt betitelt „Dokumentation“uv run python -m docsgen # Tool-Seiten, Fehlerkatalog, Beispielejust docs # baut die Website in allen Sprachen; defekte Links schlagen fehljust docs-serve # Live-Vorschau auf http://localhost:4321/avenir-mcp/docsgen führt avenir-mcp auf dem Demo-Plan aus und schreibt, was es wirklich
antwortet, mit festem Datum und ersetzten Zufallskennungen. Handgeschriebene Seiten gibt
es auf Englisch, Französisch, Spanisch, Deutsch und Niederländisch; ein Test schlägt fehl, wenn eine fehlt.
Hosting
Abschnitt betitelt „Hosting“Die Website liegt auf Cloudflare Pages (avenir-mcp.pages.dev), das sie aus dem
Repository mit npm run build:cloudflare baut und unter /avenir-mcp/ ausliefert; die
Wurzel leitet dorthin um. GitHub Pages, das keine Sicherheits-Header senden kann, leitet nur
noch alte Links weiter: Der Workflow docs veröffentlicht dort für jede Seite der Website
eine Seite, die Lesende zur gleichen Adresse bei Cloudflare schickt, und eine 404-Seite, die
dasselbe für jeden anderen Pfad tut. Cloudflare Pages sendet die Header aus
docs/cloudflare/_headers mit jeder Datei: eine Content-Security-Policy, HSTS,
X-Content-Type-Options: nosniff, X-Frame-Options: DENY, eine Referrer-Policy, eine
Permissions-Policy und eine Opener-Policy. Die Richtlinie erlaubt die eigenen Dateien der
Website und jedes Inline-Skript und jeden Inline-Stil der gebauten Seiten über seinen
SHA-256, beim Bauen berechnet; 'wasm-unsafe-eval' lässt die Suche ihr WebAssembly
ausführen, und Stilattribute sind nur über style-src-attr erlaubt. Der Build schlägt
fehl, auch in der CI, wenn ein erforderlicher Header fehlt oder abgeschwächt ist. Die
Umgebungsvariable DOCS_SITE setzt die Adresse in kanonischen Links und in der Sitemap.
Evaluierung
Abschnitt betitelt „Evaluierung“just evaluate # alle Aufgaben, Sonnet, etwa 1 USD Ihres Claude-Abosuv run python -m evals.run --task classify --model haikuSiehe Evaluierung.
Commits und Veröffentlichungen
Abschnitt betitelt „Commits und Veröffentlichungen“- Commit-Nachrichten beginnen mit einem Typ –
feat:,fix:,docs:,refactor:,test:,build:,ci:,chore:–, weilCHANGELOG.mdvon git-cliff daraus erzeugt wird, das daraus auch die nächste Versionsnummer ermittelt: Eine inkompatible Änderung erhöht die Hauptversionsnummer, einfeat:die Nebenversionsnummer, alles andere die Patch-Nummer. - Zur Veröffentlichung: Erstellen Sie einen Pull-Request mit dem Titel
chore(release): X.Y.Z, wobeiX.Y.Zdem Wert entspricht, dengit-cliff --bumped-versionauf dem Zweig ausgibt. Führen Siejust changelogaus (git-cliff --bump, dieselbe Berechnung, die in den neuen Eintrag inCHANGELOG.mdgeschrieben wird), und setzen Sieavenir_mcp.__version__auf dieselbe Zahl. Eine CI-Prüfung wiederholtgit-cliff --bumped-versionselbst und lehnt den Pull-Request mit Angabe der erwarteten Nummer ab, wenn der Titel oder eine darunterliegende Version davon abweicht: Die Nummer wird niemals manuell festgelegt. Nach der Zusammenführung erstellen Sie ein TagvX.Y.Z, das mitavenir_mcp.__version__übereinstimmt, und veröffentlichen eine GitHub-Version. Derpublish-Workflow führt zwei Builds mit dem Datum des getaggten Commits durch, bricht ab, sofern nicht beide Builds übereinstimmen, führttwine check --strictaus und lädt die Datei über Trusted Publishing auf PyPI hoch: Es wird kein Token gespeichert. - Anschließend die MCP-Registrierung: Die Datei
server.jsonweist dieselbe Version auf (ein Test; die CI-Prüfung des Pull-Requests für die Veröffentlichung bestätigt dies); führen Siemcp-publisher login githubund anschließendmcp-publisher publishaus. Die Eigentümerschaft bei PyPI wird durch die Zeilemcp-name:in der README-Datei nachgewiesen. - Auch die Claude-Desktop-Erweiterung enthält dies:
mcpb/manifest.jsonund deravenir-mcp==-Pin inmcpb/pyproject.tomlpassen sich anavenir_mcp.__version__an (ein Test sowie die entsprechende CI-Prüfung überprüfen beides), andernfalls installiert die Erweiterung die vorherige Version. - Danach das Claude-Code-Plugin, sobald die Version auf PyPI verfügbar ist: Erhöhen Sie
die Versionsnummer in
plugin/.claude-plugin/plugin.jsonund die festgeschriebene Version inplugin/pyproject.toml, führen Sieuv lock --project pluginaus und committen Sieplugin/uv.lock. Die drei bezeichnen eine Version, und ein Test schlägt fehl, solange sie nicht übereinstimmen. Der Test, der das Plugin mit dieser Version vergleicht, wird so lange alsxfailmarkiert, wie das Plugin noch auf die vorherige Version verweist; daher meldet pytest diesen Test als erwarteten Fehler, anstatt den Build abzubrechen; ein Plugin, das zwei Versionen hinter dieser Version zurückliegt oder eine Version vor ihr liegt, führt weiterhin zu einem Fehler.uv locklöst nur eine Version auf, die PyPI bereits bereitstellt; daher handelt es sich um den Commit, der auf die Veröffentlichung folgt, und nicht um einen Teil davon.
Inoffizielles Projekt. „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.“ Wir sind mit YNAB oder einer seiner Tochtergesellschaften oder verbundenen Unternehmen weder verbunden noch assoziiert noch in irgendeiner Weise offiziell verknüpft. Die offizielle Website von YNAB finden Sie unter https://www.ynab.com. Die Namen YNAB und You Need A Budget sowie zugehörige Namen, Handelsnamen, Zeichen, Marken, Embleme und Bilder sind eingetragene Marken von YNAB. avenir-mcp wird ohne Gewähr bereitgestellt und ist keine Finanzberatung. Rechtliche Hinweise · Datenschutz