Zum Inhalt springen

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
Terminal-Fenster
git clone https://github.com/mathbeal/avenir-mcp && cd avenir-mcp
uv sync # Python 3.15 und die festgeschriebenen Abhängigkeiten
just check # jede Prüfung, die die CI ausführt

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.

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.

Terminal-Fenster
uv run python -m docsgen # Tool-Seiten, Fehlerkatalog, Beispiele
just docs # baut die Website in allen Sprachen; defekte Links schlagen fehl
just 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.

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.

Terminal-Fenster
just evaluate # alle Aufgaben, Sonnet, etwa 1 USD Ihres Claude-Abos
uv run python -m evals.run --task classify --model haiku

Siehe Evaluierung.

  • Commit-Nachrichten beginnen mit einem Typ – feat:, fix:, docs:, refactor:, test:, build:, ci:, chore: –, weil CHANGELOG.md von git-cliff daraus erzeugt wird, das daraus auch die nächste Versionsnummer ermittelt: Eine inkompatible Änderung erhöht die Hauptversionsnummer, ein feat: die Nebenversionsnummer, alles andere die Patch-Nummer.
  • Zur Veröffentlichung: Erstellen Sie einen Pull-Request mit dem Titel chore(release): X.Y.Z, wobei X.Y.Z dem Wert entspricht, den git-cliff --bumped-version auf dem Zweig ausgibt. Führen Sie just changelog aus (git-cliff --bump, dieselbe Berechnung, die in den neuen Eintrag in CHANGELOG.md geschrieben wird), und setzen Sie avenir_mcp.__version__ auf dieselbe Zahl. Eine CI-Prüfung wiederholt git-cliff --bumped-version selbst 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 Tag vX.Y.Z, das mit avenir_mcp.__version__ übereinstimmt, und veröffentlichen eine GitHub-Version. Der publish-Workflow führt zwei Builds mit dem Datum des getaggten Commits durch, bricht ab, sofern nicht beide Builds übereinstimmen, führt twine check --strict aus und lädt die Datei über Trusted Publishing auf PyPI hoch: Es wird kein Token gespeichert.
  • Anschließend die MCP-Registrierung: Die Datei server.json weist dieselbe Version auf (ein Test; die CI-Prüfung des Pull-Requests für die Veröffentlichung bestätigt dies); führen Sie mcp-publisher login github und anschließend mcp-publisher publish aus. Die Eigentümerschaft bei PyPI wird durch die Zeile mcp-name: in der README-Datei nachgewiesen.
  • Auch die Claude-Desktop-Erweiterung enthält dies: mcpb/manifest.json und der avenir-mcp==-Pin in mcpb/pyproject.toml passen sich an avenir_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.json und die festgeschriebene Version in plugin/pyproject.toml, führen Sie uv lock --project plugin aus und committen Sie plugin/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 als xfail markiert, 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 lock lö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