NOVA MCP Server

Model Context Protocol-Server im Nur-Lese-Modus, der die Buchhaltungs- und Geschäftsdaten der Demonstrationsgesellschaft NOVA (Dolibarr 23.0.3) für die schrittweise Untersuchung durch einen KI-Assistenten über Cowork bereitstellt. Siehe spec-final.md für die vollständige Spezifikation.

Architektur

• Auth (app/auth/) : JWT-Keycloak-Validierung (JWKS über PyJWKClient), Identitätsauflösung (iss, sub), CredentialStore (lokales YAML), das auf einen Dolibarr-API-Schlüssel pro Benutzer abbildet, Middleware credential_gate (403, wenn die Identität nicht zugeordnet ist).

• Dolibarr (app/dolibarr/) : zentraler HTTP-Client (persistenter Verbindungspool, begrenzte Wiederholungsversuche, Decimal-Konvertierung) für die Dolibarr-REST-API (Drittanbieter, Rechnungen, Zahlungen, Bank).

• NOVA-Begleitmodul (dolibarr-module/) : Der Kontenplan und das Hauptbuch werden von der Standard-Dolibarr-API nicht bereitgestellt – siehe den entsprechenden Abschnitt unten.

• Privacy Layer (app/privacy/) : ersetzt jede Drittanbieter-Identität durch eine stabile technische Referenz (THIRDPARTY:<id>, usw.), die von den Diensten systematisch angewendet wird.

• Domain (app/domain/) : deterministische Buchhaltungsregeln (EBITDA, Aging, Paginierung, Validierung), unabhängig von jedem Framework.

• Services (app/services/) : Geschäftslogik, ein Modul pro Domäne.

• MCP (app/mcp_server/) : MCP-Server (offizielles Anthropic-SDK), Tools pro Domäne, zentraler Dekorator für Fehlerübersetzung + Protokollierung (errors.py).

Related MCP server: NuMetric MCP Server

Warum ein Dolibarr-Begleitmodul?

Die Dolibarr-23.0-REST-API bietet keinen Endpoint für den Kontenplan oder das Hauptbuch (der einzige native Einstiegspunkt, GET /accountancy/exportdata, schreibt eine Datei auf der Serverseite, ohne sie in der HTTP-Antwort zurückzugeben). dolibarr-module/nova/ fügt zwei Nur-Lese-Endpoints hinzu (GET /nova/accounts, GET /nova/bookkeeping) unter demselben nativen REST-Mechanismus (DOLAPIKEY, Anwendungsberechtigungen). Dieses Modul wird separat auf der Dolibarr-NOVA-Instanz installiert – siehe dolibarr-module/README.md.

Lokaler Start

uv sync --extra dev
cp .env.example .env        # renseigner OIDC_ISSUER, CREDENTIAL_STORE_PATH, DOLIBARR_API_URL
cp credentials/credentials.example.yaml credentials/credentials.yaml   # ne pas versionner
uv run uvicorn app.main:app --reload

• GET /health/live, GET /health/ready : Healthchecks (nicht authentifiziert).

• POST /mcp : MCP-Endpoint (Streamable HTTP).

Tests

uv run pytest                      # suite complète (couverture terminal + coverage.xml)
uv run pytest --cov=app --cov-report=html

Keine Datenbank: Die Tests verwenden einen Test-Double (tests/fixtures/) für DolibarrClient, keine PostgreSQL/NullPool-Fixtures.

Docker

docker compose up --build

Der CredentialStore ist schreibgeschützt gemountet (./credentials:/app/credentials:ro) – credentials/credentials.yaml niemals versionieren.

Voraussetzungen auf der Dolibarr-NOVA-Seite

1. dolibarr-module/nova/ installieren (siehe dessen README).

2. Für jeden Prüfer: einen dedizierten Dolibarr-Benutzer erstellen, dessen DOLAPIKEY generieren, das Recht Kontenplan und Hauptbuch über die NOVA-API lesen gewähren und dann seinen Eintrag in credentials/credentials.yaml hinzufügen (mit dem sub seines Keycloak-Tokens) – den MCP-Server neu starten, damit die Änderung wirksam wird (kein Hot-Reload, H2).

3. Für get_company: die Dolibarr-Konstante API_LOGINS_ALLOWED_FOR_GET_COMPANY ausfüllen (oder das Admin-Recht gewähren) für jeden verwendeten Login – andernfalls schlägt genau dieses Tool mit einem Upstream-403-Fehler fehl (erwartetes Verhalten).