NOVA MCP Server

Read-only Model Context Protocol server exposing the accounting and business data of the NOVA demonstration company (Dolibarr 23.0.3), for progressive investigation by an AI assistant via Cowork. See spec-final.md for the full specification.

Architecture

• Auth (app/auth/): Keycloak JWT validation (JWKS via PyJWKClient), identity resolution (iss, sub), CredentialStore (local YAML) mapping to a per-user Dolibarr API key, credential_gate middleware (403 if identity is not mapped).

• Dolibarr (app/dolibarr/): centralized HTTP client (persistent connection pool, limited retries, Decimal conversion) for the standard Dolibarr REST API (third parties, invoices, payments, bank).

• NOVA companion module (dolibarr-module/): the chart of accounts and the general ledger are not exposed by the standard Dolibarr API — see the dedicated section below.

• Privacy Layer (app/privacy/): replaces any third-party identity with a stable technical reference (THIRDPARTY:<id>, etc.), systematically applied by the services.

• Domain (app/domain/): deterministic accounting rules (EBITDA, aging, pagination, validation) independent of any framework.

• Services (app/services/): business logic, one module per domain.

• MCP (app/mcp_server/): MCP server (official Anthropic SDK), tools per domain, central error-translation + logging decorator (errors.py).

Related MCP server: ERPNext MCP Server

Why a Dolibarr companion module?

The standard Dolibarr 23.0 REST API exposes no endpoint for the chart of accounts or the general ledger (the only native entry point, GET /accountancy/exportdata, writes a file server-side without returning it in the HTTP response). dolibarr-module/nova/ adds two read-only endpoints (GET /nova/accounts, GET /nova/bookkeeping) under the same native REST mechanism (DOLAPIKEY, application permissions). This module is installed separately on the Dolibarr NOVA instance — see dolibarr-module/README.md.

Local startup

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: health checks (unauthenticated).

• 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

No database: tests use a test double (tests/fixtures/) for DolibarrClient, not PostgreSQL/NullPool fixtures.

Docker

docker compose up --build

The CredentialStore is mounted read-only (./credentials:/app/credentials:ro) — never version credentials/credentials.yaml.

Prerequisites on the Dolibarr NOVA side

1. Install dolibarr-module/nova/ (see its README).

2. For each auditor: create a dedicated Dolibarr user, generate their DOLAPIKEY, grant the right Read the chart of accounts and the general ledger via the NOVA API, then add their entry to credentials/credentials.yaml (with the sub of their Keycloak token) — restart the MCP server for it to take effect (no hot reload, H2).

3. For get_company: set the Dolibarr constant API_LOGINS_ALLOWED_FOR_GET_COMPANY (or grant the admin right) for each login used — otherwise this specific tool fails with an upstream 403 error (expected behavior).