tom/mcp-calculator
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
mcp-calculator/README.md
Thomas Adamek 45214ff6f3 initial commit
2026-09-15 20:38:16 +02:00

27 KiB
Raw Permalink Blame History

mcp-calculator

MCP-Server, der LLMs exakte, deterministische Mathematik gibt. LLMs sagen Tokens voraus und verrechnen sich deshalb bei großen Zahlen, vielen Rechenschritten, Wahrscheinlichkeiten oder Einheiten. Dieser Server übernimmt das Rechnen. Das LLM formuliert nur den Aufruf und deutet das Ergebnis.

  • 13 Tools: Arithmetik mit beliebiger Präzision, Algebra, Gleichungen, Analysis, Kurvendiskussion, Differentialgleichungen, lineare Algebra, Statistik, Regression, Verteilungen, Hypothesentests, Zahlentheorie, Einheiten
  • Beide Transporte: stdio (lokal) und Streamable HTTP (zentral, zustandslos, skalierbar)
  • Sicher: Parser mit Whitelist statt eval, Worker-Prozesse mit hartem Timeout und Speicherlimit
  • Client-Verwaltung: API-Tokens (nur als Hash gespeichert) und Netz-Freigaben in einer Datei auf dem gemeinsamen Volume, änderbar zur Laufzeit per CLI oder Admin-API, mit Audit-Log
  • Überlastschutz: Verbindungslimit, Limit pro Client, Kapazitätsgrenze, Wartezeit-Limit, Timeout, Abbruch bei Verbindungsende
  • Betriebsbereit: Health/Readiness, Prometheus-Metriken, Graceful Shutdown, JSON-Logging, Konfiguration komplett über Env-Variablen, festgeschriebene Abhängigkeiten

Stack: Python ≥ 3.12, MCP Python SDK 2.x, SymPy, mpmath, NumPy, SciPy, Pint, Pebble, prometheus-client. Tests mit unittest (Standardbibliothek).

Offene Ideen und geplante Features: BACKLOG.md.

Inhalt

  1. Schnellstart
  2. Tools im Überblick
  3. Transporte
  4. Clients anbinden
  5. Konfiguration
  6. Sicherheit
  7. Betrieb
  8. Monitoring
  9. Architektur
  10. Entwicklung
  11. Grenzen

Die ausführliche Referenz aller Parameter steht in docs/tools.md.

Schnellstart

Alles wird ausschließlich im virtuellen Environment des Projekts installiert, exakt in den Versionen aus dem Lockfile.

# venv anlegen und exakt nach uv.lock installieren (inkl. Dev-Werkzeug ruff)
uv sync --frozen --extra dev --python 3.12
source .venv/bin/activate

# alternativ ohne uv, mit pip (Hashes werden geprüft)
python3.12 -m venv .venv && source .venv/bin/activate
pip install --require-hashes -r requirements.lock
pip install --no-deps -e .

# Tests (unittest aus der Standardbibliothek)
python -m unittest                           # alle Tests (~50 s)
MCP_CALC_SKIP_SLOW=1 python -m unittest      # ohne Subprozess-/Server-Tests (~1 s)

# Server starten
mcp-calculator                                   # stdio (Standard)
mcp-calculator --transport http --port 8080      # HTTP auf 127.0.0.1:8080/mcp
python -m mcp_calculator --help                  # alle Optionen

Ausprobieren:

# Beispiel-Client (startet den Server selbst über stdio)
python examples/client_example.py

# gegen einen laufenden HTTP-Server
python examples/client_example.py http://localhost:8080/mcp [TOKEN]

# interaktiv im Browser mit dem MCP Inspector (braucht Node.js)
npx @modelcontextprotocol/inspector .venv/bin/mcp-calculator

Tools im Überblick

Tool Zweck Beispiel
evaluate Wert exakt und dezimal, beliebige Präzision 1000*(1+0.05)^10 → 1628.89462678
transform simplify, expand, factor, apart, substitute, nsimplify … x^2-5x+6 → (x-3)(x-2)
solve Gleichungen, Systeme, Ungleichungen, numerisch ["x+y=10","x-y=2"] → x=6, y=4
calculus Ableitung, Integral, Grenzwert, Reihe, Summe, Gradient, Hesse, Jacobi ∫e^(-x²) von -∞ bis ∞ → sqrt(pi)
analyze_function komplette Kurvendiskussion Nullstellen, Extrema, Wendepunkte, Asymptoten …
solve_ode Differentialgleichungen mit Anfangswerten y''+y=0, y(0)=0, y'(0)=1 → sin(x)
matrix Determinante, Inverse, Eigenwerte, LGS, SVD … (exakt oder numerisch) [[1,2],[3,4]] → det -2
statistics deskriptive Statistik, Korrelation Mittel, Median, Quartile, Schiefe …
regression linear, polynomial, exponentiell, logarithmisch, Potenz Koeffizienten, R², Vorhersage
probability 14 Verteilungen: pdf/cdf/sf/Quantil/Intervall P(85 < X ≤ 115) bei N(100, 15)
hypothesis_test t-Tests, ANOVA, χ², Mann-Whitney, Wilcoxon, Shapiro, Binomial p-Wert und Entscheidung im Klartext
number_theory Primzahlen, ggT/kgV, Modular, CRT, Kombinatorik, Basen factorize 360 → 2^3 * 3^2 * 5
convert_units Einheiten umrechnen und mit Einheiten rechnen 100 km/h → 27.78 m/s

Designentscheidungen, die die Treffsicherheit des LLMs erhöhen:

  • Wenige Tools, klar abgegrenzt. Verwandte Operationen hängen an einem operation-Enum. Das LLM wählt zuverlässiger aus 13 Tools als aus 60.
  • Server-instructions erklären beim Verbindungsaufbau, welches Tool wofür gedacht ist, und beschreiben die Syntax.
  • Verkettbare Ergebnisse: result hat dieselbe Syntax wie die Eingabe. Eine Ableitung lässt sich also direkt an solve weitergeben.
  • Exakt statt Gleitkomma: 0.1 + 0.2 = 3/10. Dezimalwerte kommen als String mit der gewünschten Stellenzahl zurück.
  • Selbsterklärende Ergebnisse: meaning bei Wahrscheinlichkeiten (P(X > 7) = P(X >= 8)), conclusion bei Tests, note bei Sonderfällen.
  • Hilfreiche Fehler: Tool-Fehler mit konkretem Hinweis (matrix is singular …; try 'pseudo_inverse'), damit das LLM den Aufruf selbst korrigieren kann.

Transporte

stdio Streamable HTTP
Start Client startet den Prozess Server läuft dauerhaft
Einsatz lokal, Einzelplatz, Entwicklung zentral fürs Team, Pod
Auth keine API-Token pro Client oder Netz-Freigabe, siehe docs/auth.md
Endpoint – POST http://<host>:8080/mcp

Der HTTP-Transport läuft zustandslos (stateless_http, JSON-Antworten). Es gibt keine MCP-Sessions, deshalb braucht es keine Sticky Sessions, und beliebig viele Replicas sind möglich.

# Client anlegen (Token wird einmalig angezeigt)
mcp-calculator-admin --file ./data/clients.json create mein-client

# HTTP, wie im Container
MCP_CALC_TRANSPORT=http \
MCP_CALC_HOST=0.0.0.0 \
MCP_CALC_CLIENTS_FILE=./data/clients.json \
MCP_CALC_LOG_FORMAT=json \
mcp-calculator

Rohtest mit curl:

curl -s -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer mcpc_…" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"evaluate","arguments":{"expression":"2^100"}}}'

Clients anbinden

Die Konfigurationsformate der Clients ändern sich gelegentlich. Die Beispiele entsprechen dem Stand bei der Erstellung. Bitte gegen die Doku der eingesetzten Client-Version prüfen.

Jeder Client (Team, IDE-Installation, Dienst) bekommt ein eigenes Token: mcp-calculator-admin create <name>. Das Token wird im Header Authorization: Bearer <token> mitgeschickt, alternativ als X-API-Key: <token>. Verwaltung und Sperren: docs/auth.md.

opencode

opencode.json (Projekt) oder ~/.config/opencode/opencode.json (global):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "calculator": {
      "type": "remote",
      "url": "https://calculator.intern.example/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MCP_CALC_TOKEN}"
      }
    }
  }
}

Lokal über stdio:

{
  "mcp": {
    "calculator": {
      "type": "local",
      "command": ["/pfad/zu/mcp-calculator/.venv/bin/mcp-calculator"],
      "enabled": true
    }
  }
}

Cline

cline_mcp_settings.json (in Cline über „MCP Servers → Configure“ erreichbar):

{
  "mcpServers": {
    "calculator": {
      "type": "streamableHttp",
      "url": "https://calculator.intern.example/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      },
      "disabled": false,
      "autoApprove": [
        "evaluate", "transform", "solve", "calculus", "analyze_function", "solve_ode", "matrix",
        "statistics", "regression", "probability", "hypothesis_test", "number_theory", "convert_units"
      ]
    }
  }
}

Alle Tools sind rein lesend, deshalb ist autoApprove unbedenklich. Lokal über stdio:

{
  "mcpServers": {
    "calculator": {
      "command": "/pfad/zu/mcp-calculator/.venv/bin/mcp-calculator",
      "args": []
    }
  }
}

Claude Code

claude mcp add --transport http calculator https://calculator.intern.example/mcp \
  --header "Authorization: Bearer <token>"
# oder lokal
claude mcp add calculator -- /pfad/zu/mcp-calculator/.venv/bin/mcp-calculator

Eigene Tools / Agenten

Jede Anwendung mit MCP-Client-SDK (Python, TypeScript, Java, Go …) kann den Server nutzen. Ein lauffähiges Python-Beispiel liegt in examples/client_example.py:

import httpx2
from mcp import Client
from mcp.client.streamable_http import streamable_http_client

async with httpx2.AsyncClient(headers={"Authorization": f"Bearer {token}"}) as http:
    async with Client(streamable_http_client("https://calculator.intern.example/mcp", http_client=http)) as client:
        tools = (await client.list_tools()).tools          # -> als Tool-Definitionen ans LLM
        result = await client.call_tool("solve", {"equations": "x^2 = 2", "domain": "real"})
        print(result.structured_content)

Einbindung in eine eigene LLM-Schleife:

  1. list_tools() ausführen und name, description und input_schema jedes Tools als Tool-Definition an das Modell geben.
  2. Fordert das Modell einen Tool-Call an, call_tool(name, arguments) aufrufen.
  3. result.content[0].text zurückgeben. Bei result.is_error den Rückgabewert als Fehler markieren.

Hinweis: Serverseitige MCP-Connectoren von LLM-Anbietern rufen den MCP-Server aus der Cloud des Anbieters auf. Ein nur intern erreichbarer Server funktioniert damit nicht. Bei internem Betrieb muss der eigene Code MCP-Client sein (wie oben).

Konfiguration

Jede Option ist per Umgebungsvariable MCP_CALC_<NAME> oder per CLI-Flag --<name> setzbar. Die CLI hat Vorrang vor der Umgebung, die Umgebung vor den Defaults. Eine Vorlage liegt in .env.example. Die Datei wird nicht automatisch geladen, sie dient als Referenz für die Pod-Umgebung.

Variable Default Beschreibung
MCP_CALC_TRANSPORT stdio stdio oder http
MCP_CALC_HOST 127.0.0.1 Bind-Adresse; im Container 0.0.0.0
MCP_CALC_PORT 8080 HTTP-Port
MCP_CALC_PATH /mcp Pfad des MCP-Endpoints
MCP_CALC_ALLOWED_HOSTS – erlaubte Host-Header, kommagetrennt; aktiviert den DNS-Rebinding-Schutz
MCP_CALC_ALLOWED_ORIGINS – erlaubte Origin-Header (nur für Browser-Clients relevant)
MCP_CALC_TRUSTED_PROXIES – IPs/CIDRs von Proxys (OpenShift-Router), deren X-Forwarded-For ausgewertet wird
MCP_CALC_MAX_REQUEST_BODY_BYTES 1048576 maximale Request-Größe
MCP_CALC_MAX_CONNECTIONS 200 gleichzeitige HTTP-Verbindungen; darüber antwortet uvicorn mit 503
MCP_CALC_METRICS true Prometheus-Metriken unter /metrics (nur HTTP)
Authentifizierung nur HTTP; Details in docs/auth.md
MCP_CALC_CLIENTS_FILE – Client-Datei (z. B. /data/clients.json auf RWX-PVC); aktiviert die Authentifizierung
MCP_CALC_CLIENTS_RELOAD_SECONDS 5 wie oft die Datei auf Änderungen geprüft wird
MCP_CALC_AUTH_TOKENS – statische Tokens name:token,… (einfache Alternative, Änderung nur per Neustart)
MCP_CALC_AUDIT_FILE audit.log neben der Client-Datei Änderungsprotokoll
MCP_CALC_ADMIN_TOKENS – Admin-Tokens name:token,…; nur wenn gesetzt, startet die Admin-API
MCP_CALC_ADMIN_HOST 127.0.0.1 Bind-Adresse der Admin-API (Default: nur per oc port-forward/exec)
MCP_CALC_ADMIN_PORT 9090 Port der Admin-API
MCP_CALC_EXECUTOR process process (isolierter Worker-Pool) oder inline (nur Entwicklung)
MCP_CALC_WORKERS 2 Anzahl Worker-Prozesse (≈ CPU-Kerne)
MCP_CALC_MAX_QUEUE 20 so viele Berechnungen dürfen auf einen freien Worker warten; darüber wird sofort mit „busy“ abgelehnt (0 = keine Warteschlange)
MCP_CALC_MAX_QUEUE_WAIT_SECONDS 30 maximale Wartezeit auf einen freien Worker, danach „busy“
MCP_CALC_CLIENT_MAX_CONCURRENT 10 gleichzeitige Berechnungen pro Client (0 = unbegrenzt); pro Client überschreibbar
MCP_CALC_TIMEOUT_SECONDS 10 harter Timeout pro Berechnung
MCP_CALC_MAX_TASKS_PER_WORKER 200 Worker nach N Aufgaben recyceln (0 = nie)
MCP_CALC_MEMORY_LIMIT_MB 512 zusätzlicher Speicher, den eine Berechnung pro Worker belegen darf (nur Linux; 0 = aus), siehe docs/memory.md
MCP_CALC_MAX_INPUT_LENGTH 5000 max. Zeichen pro Ausdruck
MCP_CALC_MAX_OUTPUT_LENGTH 20000 längere Ergebnisse werden gekürzt
MCP_CALC_MAX_PRECISION 1000 max. signifikante Stellen
MCP_CALC_MAX_MATRIX_SIZE 30 max. Zeilen/Spalten
MCP_CALC_MAX_DATA_POINTS 1000000 max. Werte pro Datensatz
MCP_CALC_MAX_LIST_ITEMS 10000 max. Einträge sonstiger Listen
MCP_CALC_LOG_LEVEL INFO DEBUG, INFO, WARNING, ERROR
MCP_CALC_LOG_FORMAT text text oder json (eine Zeile pro Eintrag)

Sicherheit

Ausdrucks-Parser (ops/parsing.py). SymPys parse_expr nutzt intern eval. Abgesichert wird das in drei Schichten:

  1. Die Eingabe wird vorab geprüft: Zeichen-Whitelist (keine Quotes, [], {}, ;, :, \), kein __, kein Attributzugriff (.name), keine Python-Keywords, keine Namen mit _.
  2. Ausgewertet wird in einem Namensraum, der nur freigegebene SymPy-Funktionen und ein leeres __builtins__ enthält. Unbekannte Namen werden zu mathematischen Symbolen, nie zu Python-Objekten.
  3. Die Berechnung läuft isoliert in einem Worker-Prozess (siehe unten).

Die Tests in tests/test_parsing.py decken typische Injection-Versuche ab (__import__, ().__class__, lambda, open(...), getattr, …).

Worker-Pool (executor.py). Jede Berechnung läuft in einem separaten Prozess (Pebble-Pool, spawn):

  • Wird der Timeout überschritten, wird der Worker hart beendet und ersetzt. 9^9^9^9 blockiert also nichts.
  • Unter Linux darf eine Berechnung pro Worker höchstens MCP_CALC_MEMORY_LIMIT_MB zusätzlich belegen (RLIMIT_AS, gesetzt nach dem Laden der Bibliotheken). Ein Ausreißer endet mit MemoryError, statt den Pod zu killen.
  • BLAS/OpenMP laufen pro Worker einthreadig. Die Parallelität kommt aus der Worker-Anzahl, das CPU-Limit des Pods wird nicht überbucht.
  • Worker werden nach N Aufgaben recycelt, damit die SymPy-Caches nicht unbegrenzt wachsen.
  • Ist der Pool defekt, startet er sich selbst neu.

HTTP.

  • Authentifizierung pro Client (API-Token oder Netz-Freigabe). Tokens sind 256 Bit zufällig und werden nur als SHA-256-Hash gespeichert; Sperren, Ablaufdatum, Netz-Einschränkung und Rotation sind zur Laufzeit möglich. Details: docs/auth.md.
  • Die Admin-API läuft auf eigenem Port, standardmäßig nur auf 127.0.0.1, mit eigenen Admin-Tokens; jede Änderung landet im Audit-Log.
  • /healthz, /readyz und /metrics bleiben offen für Probes und Prometheus.
  • Request-Body-Limit (Default 1 MiB), dazu Längenlimits für alle Eingaben.
  • DNS-Rebinding-Schutz: bei 127.0.0.1 automatisch aktiv, bei 0.0.0.0 über MCP_CALC_ALLOWED_HOSTS einschaltbar.
  • Ohne Client-Konfiguration und nicht an localhost gebunden, protokolliert der Server beim Start eine Warnung.

Die Einheiten-Umrechnung (Pint) nutzt einen eigenen Tokenizer ohne eval.

Betrieb

Die Anbindung an OpenShift ist nicht Teil dieses Projekts. Für die eigene Integration relevant:

Punkt Wert
Start mcp-calculator (Entry Point) oder python -m mcp_calculator
Pflicht-Env im Container MCP_CALC_TRANSPORT=http, MCP_CALC_HOST=0.0.0.0
Ports 8080 MCP; 9090 Admin-API (nur mit MCP_CALC_ADMIN_TOKENS, Default nur 127.0.0.1). Unprivilegiert, beliebige UID möglich
Volume RWX-PVC z. B. unter /data für clients.json und audit.log, sonst wird nichts geschrieben
Liveness GET /healthz → 200 {"status":"ok","version":…}
Readiness GET /readyz → 200 erst, wenn die Worker gestartet sind und ihre Bibliotheken geladen haben, sonst 503
Metriken GET /metrics (Prometheus, ohne Token), siehe Monitoring
Shutdown SIGTERM: keine neuen Verbindungen, laufende Requests werden fertig gerechnet, danach wird der Worker-Pool geordnet gestoppt (Log: worker pool stopped)
Überlast Sechs Schutzschichten (Verbindungen, pro Client, Kapazität, Wartezeit, Timeout, Abbruch bei Verbindungsende); Ablehnungen sind Tool-Fehler mit „retry“-Hinweis. Siehe docs/auth.md → Überlastschutz
Skalierung zustandslos, horizontal skalierbar, keine Sticky Sessions
Ressourcen MCP_CALC_WORKERS ≈ CPU-Limit. Leerlauf gemessen (macOS, RSS): ~90 MB + ~140 MB je Worker, mit 2 Workern ~360 MB. Pod-Limit ≥ Leerlauf + WORKERS × MEMORY_LIMIT_MB. Analyse, Profile und Messskript: docs/memory.md
Logs stderr; MCP_CALC_LOG_FORMAT=json für Log-Aggregation. Pro Tool-Aufruf: tool=<name> client=<client> status=… duration_ms=…; abgelehnte Anfragen: auth rejected: reason=… client=… ip=…
Startzeit /readyz nach ~1,2 s (Worker vorgewärmt); der erste Aufruf ist danach sofort schnell

Monitoring

GET /metrics liefert Prometheus-Textformat. Wie /healthz und /readyz ist der Endpoint ohne Token erreichbar, damit Prometheus im Cluster scrapen kann. Er enthält Zähler und Client-Namen, keine Rechen-Eingaben. Wer das nicht möchte, schränkt den Zugriff per NetworkPolicy ein oder setzt MCP_CALC_METRICS=false.

Metrik Typ Bedeutung
mcp_calc_tool_calls_total{tool, client, status} Counter Aufrufe je Tool, Client und Ergebnis: ok, error (Mathe-/Eingabefehler), timeout, busy (Kapazität, Wartezeit oder Client-Limit), cancelled (Client hat Verbindung getrennt), crashed (Worker gestorben). client ist local bei stdio, anonymous ohne Client-Konfiguration
mcp_calc_tool_duration_seconds{tool} Histogram Dauer inkl. Wartezeit in der Queue
mcp_calc_inflight_computations Gauge laufende + wartende Berechnungen
mcp_calc_capacity Gauge WORKERS + MAX_QUEUE; darüber wird abgelehnt
mcp_calc_workers Gauge konfigurierte Worker
mcp_calc_pool_restarts_total Counter Neustarts des Pools nach internem Fehler
mcp_calc_client_inflight_computations{client} Gauge laufende + wartende Berechnungen je Client
mcp_calc_auth_failures_total{reason} Counter abgelehnte Anfragen: missing_credentials, invalid_token, disabled, expired, network_denied
mcp_calc_clients{status} Gauge konfigurierte Clients: active, disabled, expired
mcp_calc_build_info{version} Info Version
process_*, python_* Standard CPU, RSS, Dateien des Server-Prozesses (Worker nicht enthalten)

Nicht gezählt werden Aufrufe, die schon an der Schema-Validierung scheitern (falscher Parametertyp). Die beantwortet das MCP SDK, bevor der Tool-Code läuft.

Nützliche Abfragen:

# Fehler- und Timeout-Quote je Tool (5 min)
sum by (tool, status) (rate(mcp_calc_tool_calls_total{status!="ok"}[5m]))
  / ignoring(status) group_left sum by (tool) (rate(mcp_calc_tool_calls_total[5m]))

# p95-Dauer je Tool
histogram_quantile(0.95, sum by (tool, le) (rate(mcp_calc_tool_duration_seconds_bucket[5m])))

# Auslastung (Alarm z. B. > 0.8 über 5 min → mehr Worker oder Replicas)
mcp_calc_inflight_computations / mcp_calc_capacity

# Überlast-Ablehnungen, nach Client
sum by (client) (rate(mcp_calc_tool_calls_total{status="busy"}[5m]))

# Wer belegt gerade die Kapazität?
topk(5, mcp_calc_client_inflight_computations)

# Auffällige Auth-Fehler (falsch konfigurierte Clients oder Rateversuche)
sum by (reason) (rate(mcp_calc_auth_failures_total[5m]))

Architektur

                 ┌────────────────────────── Server-Prozess ──────────────────────────┐
 Client ─stdio──►│ MCPServer (server.py)                                               │
        ─HTTP───►│  └ Starlette/uvicorn (http_app.py): Bearer-Auth, /healthz, /readyz  │
                 │     Tool-Funktionen: Validierung (Pydantic-Schemas) → Executor      │
                 └───────────────────────────────┬─────────────────────────────────────┘
                                                 │ Task-Name + Argumente, Timeout
                              ┌──────────────────▼──────────────────┐
                              │ Worker-Pool (executor.py, Pebble)   │
                              │  ops/*.py  – reine Mathe-Funktionen │
                              │  SymPy · mpmath · NumPy · SciPy · Pint
                              └─────────────────────────────────────┘

Der Server-Prozess lädt nur MCP SDK und HTTP-Stack, die Worker nur die Mathe-Bibliotheken. Das halbiert den Speicherbedarf ungefähr (Details in docs/memory.md) und wird von tests/test_footprint.py abgesichert.

src/mcp_calculator/
├── __main__.py        Entry Point: Konfiguration laden, Logging, Transport starten
├── config.py          Settings aus Env/CLI, Validierung, Limits
├── server.py          MCP-Tools: Schemas, Beschreibungen, Server-Instructions
├── http_app.py        HTTP-Transport: ASGI-App, Abbruch bei Verbindungsende, Health, Admin-Server
├── auth.py            Authentifizierung (Token, Netz) und Client-Identität je Request
├── clients.py         Client-Modell, Client-Datei (Lock, atomar), Hot-Reload
├── admin.py           Client-Verwaltung (gemeinsame Logik), Audit-Log, Admin-API
├── admin_cli.py       CLI mcp-calculator-admin
├── ratelimit.py       Limit gleichzeitiger Berechnungen pro Client
├── executor.py        Worker-Pool: Timeout, Speicherlimit, Backpressure, Vorwärmen, Selbstheilung
├── metrics.py         Prometheus-Metriken
├── logging_setup.py   Text-/JSON-Logging nach stderr
└── ops/               reine, synchrone Mathe-Funktionen (dict rein, dict raus)
    ├── spec.py        Typen/Enums/Hilfetexte für die Tool-Schemas (import-leicht, auch im Server)
    ├── context.py     Fehlertyp und Limits (import-leicht)
    ├── parsing.py     sicherer Ausdrucks-Parser
    ├── common.py      Ergebnis-Formatierung, Limit-Prüfungen
    ├── algebra.py     evaluate, transform, solve
    ├── calculus.py    calculus, analyze_function, solve_ode
    ├── linalg.py      matrix
    ├── stats.py       statistics, regression, probability, hypothesis_test
    ├── number_theory.py
    └── units.py
tests/                 unittest: pro Modul + End-to-End (in-process, HTTP, stdio, Pool, Footprint)
examples/              lauffähiger MCP-Client
scripts/               measure_memory.py – Speicher messen
docs/tools.md          vollständige Tool-Referenz
docs/memory.md         Speicheranalyse und Dimensionierung
docs/auth.md           Authentifizierung, Client-Verwaltung, Überlastschutz (Betriebshandbuch)
uv.lock                Lockfile (uv), Quelle der Wahrheit für Versionen
requirements.lock      daraus exportiert, mit Hashes, für pip/Container-Builds
BACKLOG.md             geplante Features und offene Themen

Neues Tool hinzufügen

  1. Eine reine Funktion in ops/<bereich>.py schreiben: Parameter rein, JSON-fähiges dict raus. Erwartbare Fehler als MathError("verständliche Meldung") werfen. Bei einem neuen Modul dieses in executor.TASK_MODULES eintragen.
  2. Enums/Literal-Typen für die Parameter in ops/spec.py definieren, nicht im Rechenmodul. server.py darf nur spec importieren, sonst landen SymPy/SciPy wieder im Server-Prozess (tests/test_footprint.py schlägt dann fehl).
  3. In server.py ein @mcp.tool(annotations=READ_ONLY) mit typisierten, per Field(description=…) beschriebenen Parametern anlegen, das await run("<name>", "<modul>.<funktion>", **kwargs) aufruft.
  4. Das Tool in INSTRUCTIONS (Abschnitt „Which tool“) und in docs/tools.md ergänzen.
  5. Tests schreiben: Fachlogik direkt in tests/test_<bereich>.py, Aufruf über MCP in tests/test_server.py (dort auch die Liste EXPECTED_TOOLS anpassen).

Entwicklung

source .venv/bin/activate
python -m unittest                              # alle Tests
MCP_CALC_SKIP_SLOW=1 python -m unittest         # schnelle Tests ohne Subprozesse
python -m unittest tests.test_parsing -v        # nur Parser/Sicherheit
python -m unittest tests.test_algebra.SolveTest.test_quadratic   # ein einzelner Test
ruff check src tests examples scripts           # Linting (Konfiguration in pyproject.toml)
MCP_CALC_EXECUTOR=inline MCP_CALC_LOG_LEVEL=DEBUG mcp-calculator   # Debugging ohne Worker-Pool

Abhängigkeiten aktualisieren. pyproject.toml enthält die erlaubten Bereiche, uv.lock die exakt getesteten Versionen. Nach einer Aktualisierung immer beide Lock-Dateien committen:

uv lock --upgrade                                   # oder gezielt: uv lock --upgrade-package mcp
uv export --frozen --format requirements-txt --no-emit-project --no-header -o requirements.lock
uv sync --frozen --extra dev --python 3.12 && python -m unittest

Hinweis zur Python-Version: Ist in der Shell UV_PYTHON gesetzt (z. B. UV_PYTHON=3.13), hat das bei uv Vorrang vor .python-version. Deshalb steht in den Befehlen oben --python 3.12 explizit.

Code, Docstrings und Tool-Beschreibungen sind auf Englisch. Das ist die Sprache, mit der LLMs Tool-Schemas am zuverlässigsten interpretieren. Die Projektdokumentation ist auf Deutsch.

Grenzen

  • Formulierung bleibt beim LLM. Der Server rechnet korrekt, aber das Modell muss die Aufgabe richtig in einen Aufruf übersetzen. Diese Fehlerquelle bleibt.
  • Symbolik hat Grenzen. Nicht jedes Integral, jede Gleichung und jede DGL hat eine geschlossene Form. Der Server fällt dann auf numerische Verfahren zurück (Integral, Summe) oder gibt einen Hinweis (numeric_only). Aufwendige Probleme laufen in den Timeout.
  • Numerisches Lösen (numeric_only) liefert bei nicht-polynomialen Gleichungen eine Wurzel nahe dem Startwert, nicht alle.
  • Speicherlimit pro Worker greift nur unter Linux. Unter macOS gilt nur der Timeout. Die Speicherwerte in der Doku sind unter macOS gemessen; im Container bitte mit scripts/measure_memory.py nachmessen.
  • Keine Plots, keine Finanzmathematik-Spezialfunktionen (IRR, Annuitäten lassen sich über evaluate/solve abbilden). Geplant siehe BACKLOG.md.
  • Warteschlange pro Replica. MAX_QUEUE begrenzt nur den einzelnen Pod; Lastverteilung über mehrere Replicas übernimmt der Service/Router.