mcp-calculator/BACKLOG.md

Backlog

Geplante Features und offene Themen für mcp-calculator. Priorität: hoch / mittel / niedrig. Aufwand: S (≤ ½ Tag), M (1–2 Tage), L (> 2 Tage).

---

Entscheidungen

Thema	Entscheidung	Konsequenz
Authentifizierung	Jetzt API-Tokens, später Keycloak (OIDC/JWT). Lokal (stdio) keine Auth.	Umgesetzt in 1.2.0: Client-Datei auf RWX-PVC, CLI + Admin-API, Audit-Log, Token- und Netz-Clients. Keycloak siehe Features. HMAC-Signaturen aktuell nicht.
Token-Verwaltung	Datei auf dem PVC als einziger Speicher, Admin-API und CLI schreiben dieselbe Datei.	Keine Datenbank, funktioniert mit mehreren Replicas (RWX, Hot-Reload).
Rate-Limiting	Ziel ist Überlastschutz, nicht Fairness zwischen Nutzern.	Umgesetzt in 1.2.0 (sechs Schichten, pro Replica). Kein zentraler Zähler nötig.
Replicas	Aktuell eine, bei Bedarf mehrere.	Server ist zustandslos, Skalierung ohne Codeänderung möglich. Readiness und Backpressure wirken pro Pod.

Offen, erledigt das Team

Thema	Details
Linux-Verifikation im Pod	python scripts/measure_memory.py server; speicherhungrige Anfrage (z. B. evaluate mit factorial(10^7)) muss mit Memory-/Timeout-Meldung enden, ohne Pod-Neustart. Siehe docs/memory.md
Clients end-to-end	opencode, Cline und eigene Tools gegen den Pod; Konfigurationsfelder der README gegen die eingesetzten Client-Versionen prüfen
Git-Repository	inkl. uv.lock und requirements.lock committen

---

Features

Hohe Priorität

Keycloak (OIDC/JWT) · Aufwand M

Zusätzlich zu API-Tokens: Keycloak-JWTs prüfen (Signatur gegen JWKS, iss, aud, Ablauf) über den TokenVerifier des MCP SDK; Identität aus azp/Client-ID oder einem Claim, gleiche Limits und Metriken wie heute. Umschaltbar per MCP_CALC_AUTH_MODE=token|oidc|both.

• Vorher klären: Unterstützen opencode und Cline den OAuth-Ablauf von MCP gegen Keycloak? Sonst both (IDE-Clients mit API-Token, Dienste mit Client-Credentials).
• Voraussetzung: Keycloak-Realm/Client, erreichbar aus dem Pod (JWKS).

Eval-Suite für die Tool-Nutzung · Aufwand M

Realistische Aufgaben (mit bekannter Lösung) gegen das eingesetzte Modell laufen lassen, jeweils mit und ohne MCP-Server. Gemessen werden Trefferquote, Tool-Wahl, Anzahl der Aufrufe und Fehlversuche.

• Nutzen: belegt den Mehrwert und zeigt, welche Tool-Beschreibungen nachgeschärft werden müssen. Basis für die Priorisierung der übrigen Features.
• Braucht: Modell-Zugang und idealerweise echte, anonymisierte Nutzerfragen.
• Ansatz: eigener MCP-Client (siehe examples/client_example.py) in einer LLM-Schleife, Aufgaben als JSON/YAML, Report als Tabelle.

Finanzmathematik · Aufwand M

Neues Tool finance: Barwert/Endwert, Annuität und Tilgungsplan, NPV, IRR (interner Zinsfuß), effektiver Jahreszins, Abschreibungen.

• Nutzen: häufige Business-Fragen, bei denen LLMs regelmäßig falsch runden oder Formeln verwechseln.
• Ansatz: exakte Arithmetik über SymPy/Decimal, IRR numerisch (scipy.optimize.brentq); Tilgungsplan als Tabelle mit Längenlimit.

Datum und Zeit · Aufwand S–M

Neues Tool datetime_calc: Differenz zwischen Daten, Datum ± Dauer, Arbeitstage (mit Feiertagskalender je Bundesland), Wochentag, Kalenderwoche (ISO), Zeitzonen-Umrechnung, Fristen.

• Nutzen: LLMs sind hier notorisch unzuverlässig (Schaltjahre, Monatslängen, Wochentage).
• Ansatz: Standardbibliothek datetime/zoneinfo; Feiertage über das Paket holidays (neue Abhängigkeit).

Mittlere Priorität

Optimierung · Aufwand M

Neues Tool optimize: Minimum/Maximum einer Funktion (mit Schranken und Nebenbedingungen), lineare Optimierung, Nullstellensuche in Intervallen.

• Ansatz: scipy.optimize (minimize, linprog, brentq); symbolisch über solve des Gradienten, wo möglich.

Numerische Differentialgleichungen · Aufwand M

solve_ode um einen numerischen Modus erweitern: Anfangswertprobleme und Systeme ohne geschlossene Lösung, Ergebnis als Wertetabelle an gewählten Stellen.

• Ansatz: scipy.integrate.solve_ivp; Rechte Seite über den sicheren Parser, dann lambdify.

Batch-Aufrufe · Aufwand S

Mehrere Ausdrücke oder Aufgaben in einem Tool-Aufruf (z. B. evaluate mit Liste).

• Nutzen: weniger Roundtrips bei Tabellen und Serienrechnungen, geringere Latenz im Agenten.
• Achtung: Timeout und Limits pro Batch sinnvoll definieren.

Typisierte Ausgabeschemas · Aufwand M

Rückgabewerte als Pydantic-Modelle statt dict[str, Any], damit Clients ein präzises outputSchema erhalten.

• Nutzen: Clients und Agenten können Ergebnisse maschinell sicher weiterverarbeiten.

Signierte Requests (HMAC) · Aufwand S–M

Für Dienste: Signatur über Zeitstempel + Body mit einem gemeinsamen Geheimnis (X-Signature, X-Timestamp), Schutz vor Replay durch ein Zeitfenster. Als weitere Methode in der Auth-Kette (auth: "hmac"). Aktuell nicht benötigt; Token + Netz-Einschränkung decken den Fall ab.

Worker-Metriken · Aufwand S

RSS und Anzahl erledigter Aufgaben je Worker als Metrik (heute enthalten die process_*-Metriken nur den Server-Prozess).

• Ansatz: Worker melden Kennzahlen mit dem Ergebnis zurück, oder der Server liest /proc/<pid>/status der Worker.

Niedrige Priorität

Plots · Aufwand M

Funktionsgraphen (z. B. zur Kurvendiskussion) als PNG/SVG im MCP-Bildformat.

• Achtung: neue Abhängigkeit (matplotlib, ~+40 MB je Worker); nicht jeder Client zeigt Bilder an.

LaTeX-Eingabe · Aufwand S

Ausdrücke in LaTeX-Notation akzeptieren (\frac{1}{2}, \int_0^1).

• Ansatz: sympy.parsing.latex.parse_latex; braucht antlr4-python3-runtime in passender Version. Sicherheitsprüfung wie beim bestehenden Parser.

MCP-Prompts · Aufwand S

Vorlagen wie „Kurvendiskussion“, „Statistik-Report“, „Einheiten-Check“ als MCP-Prompts, die Clients im Menü anbieten.

Komplexe Zahlen in Polarform · Aufwand S

Ergebnisse zusätzlich als Betrag/Winkel und in Exponentialform ausgeben.

---

Qualität und Betrieb

Thema	Priorität	Aufwand	Details
CI-Pipeline	hoch	S	python -m unittest, ruff check, pip-audit -r requirements.lock bei jedem Push
Regelmäßige Abhängigkeits-Updates	mittel	S	z. B. monatlich uv lock --upgrade, Tests, beide Lock-Dateien committen; Renovate/Dependabot möglich
Lasttest	mittel	S–M	Durchsatz und Latenz je Worker-Zahl messen, Grundlage für Worker- und Replica-Anzahl
Weitere Python-Versionen	niedrig	S	Tests zusätzlich mit 3.13 (lokal ist z. B. UV_PYTHON=3.13 bereits verbreitet)

---

Erledigt

Version	Thema
1.2.0	Client-Verwaltung: Client-Datei auf RWX-PVC mit Hot-Reload, Token-Hashes, Token- und Netz-Clients, Ablaufdatum, Sperren, Limits pro Client
1.2.0	CLI mcp-calculator-admin und Admin-API (eigener Port, Admin-Tokens), Audit-Log
1.2.0	Überlastschutz: Limit pro Client, Wartezeit-Limit in der Queue, Abbruch bei Verbindungsende, Verbindungslimit; Client-Label in Metriken und Logs
1.1.0	Backpressure (MCP_CALC_MAX_QUEUE), sofortige „busy“-Ablehnung
1.1.0	Prometheus-Metriken unter /metrics
1.1.0	Graceful Shutdown: Worker-Pool wird bei SIGTERM geordnet gestoppt (behebt die Semaphore-Warnung)
1.1.0	Vorgewärmte Worker, Readiness erst nach dem Laden der Bibliotheken
1.1.0	Abhängigkeiten festgeschrieben (uv.lock, requirements.lock mit Hashes), Python ≥ 3.12
1.1.0	Tests auf unittest umgestellt
1.0.x	Speicheroptimierung (Server ohne Mathe-Bibliotheken, Worker ohne Server-Stack), siehe docs/memory.md
1.0.0	13 Tools, stdio + Streamable HTTP, sicherer Parser, Worker-Pool mit Timeout und Speicherlimit