NOVA MCP Server

Serveur Model Context Protocol en lecture seule exposant les données comptables et commerciales de la société de démonstration NOVA (Dolibarr 23.0.3), pour investigation progressive par un assistant IA via Cowork. Voir spec-final.md pour la spécification complète.

Architecture

• Auth (app/auth/) : validation JWT Keycloak (JWKS via PyJWKClient), résolution d'identité (iss, sub), CredentialStore (YAML local) mappant vers une clé API Dolibarr par utilisateur, middleware credential_gate (403 si identité non mappée).

• Dolibarr (app/dolibarr/) : client HTTP centralisé (pool de connexions persistant, retries limités, conversion Decimal) pour l'API REST Dolibarr stock (tiers, factures, paiements, banque).

• Module compagnon NOVA (dolibarr-module/) : le plan comptable et le Grand livre ne sont pas exposés par l'API Dolibarr standard — voir la section dédiée ci-dessous.

• Privacy Layer (app/privacy/) : remplace toute identité de tiers par une référence technique stable (THIRDPARTY:<id>, etc.), appliquée systématiquement par les services.

• Domain (app/domain/) : règles comptables déterministes (EBITDA, aging, pagination, validation) indépendantes de tout framework.

• Services (app/services/) : logique métier, un module par domaine.

• MCP (app/mcp_server/) : serveur MCP (SDK officiel Anthropic), tools par domaine, décorateur central de traduction d'erreurs + logging (errors.py).

Related MCP server: NuMetric MCP Server

Pourquoi un module compagnon Dolibarr ?

L'API REST stock de Dolibarr 23.0 n'expose aucun endpoint pour le plan comptable ou le Grand livre (le seul point d'entrée natif, GET /accountancy/exportdata, écrit un fichier côté serveur sans le retourner dans la réponse HTTP). dolibarr-module/nova/ ajoute deux endpoints en lecture seule (GET /nova/accounts, GET /nova/bookkeeping) sous le même mécanisme REST natif (DOLAPIKEY, permissions applicatives). Ce module s'installe séparément sur l'instance Dolibarr NOVA — voir dolibarr-module/README.md.

Démarrage local

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 (non authentifiés).

• POST /mcp : endpoint MCP (Streamable HTTP).

Tests

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

Aucune base de données : les tests utilisent un double de test (tests/fixtures/) pour DolibarrClient, pas de fixtures PostgreSQL/NullPool.

Docker

docker compose up --build

Le CredentialStore est monté en lecture seule (./credentials:/app/credentials:ro) — ne jamais versionner credentials/credentials.yaml.

Prérequis côté Dolibarr NOVA

1. Installer dolibarr-module/nova/ (voir son README).

2. Pour chaque auditeur : créer un utilisateur Dolibarr dédié, générer sa DOLAPIKEY, accorder le droit Lire le plan comptable et le Grand livre via l'API NOVA, puis ajouter son entrée dans credentials/credentials.yaml (avec le sub de son token Keycloak) — redémarrer le serveur MCP pour la prise en compte (pas de rechargement à chaud, H2).

3. Pour get_company : renseigner la constante Dolibarr API_LOGINS_ALLOWED_FOR_GET_COMPANY (ou accorder le droit admin) pour chaque login utilisé — sinon ce tool précis échoue avec une erreur upstream 403 (comportement attendu).