NOVA MCP Server

Servidor Model Context Protocol de solo lectura que expone los datos contables y comerciales de la empresa de demostración NOVA (Dolibarr 23.0.3), para investigación progresiva por un asistente de IA a través de Cowork. Ver spec-final.md para la especificación completa.

Arquitectura

• Auth (app/auth/) : validación JWT Keycloak (JWKS vía PyJWKClient), resolución de identidad (iss, sub), CredentialStore (YAML local) que mapea hacia una clave API Dolibarr por usuario, middleware credential_gate (403 si la identidad no está mapeada).

• Dolibarr (app/dolibarr/) : cliente HTTP centralizado (pool de conexiones persistente, reintentos limitados, conversión Decimal) para la API REST Dolibarr stock (terceros, facturas, pagos, banco).

• Módulo complementario NOVA (dolibarr-module/) : el plan contable y el Libro Mayor no están expuestos por la API Dolibarr estándar — ver la sección dedicada a continuación.

• Privacy Layer (app/privacy/) : reemplaza cualquier identidad de terceros por una referencia técnica estable (THIRDPARTY:<id>, etc.), aplicada sistemáticamente por los servicios.

• Domain (app/domain/) : reglas contables deterministas (EBITDA, aging, paginación, validación) independientes de cualquier framework.

• Services (app/services/) : lógica de negocio, un módulo por dominio.

• MCP (app/mcp_server/) : servidor MCP (SDK oficial de Anthropic), tools por dominio, decorador central de traducción de errores + logging (errors.py).

Related MCP server: NuMetric MCP Server

¿Por qué un módulo complementario Dolibarr?

La API REST stock de Dolibarr 23.0 no expone ningún endpoint para el plan contable o el Libro Mayor (el único punto de entrada nativo, GET /accountancy/exportdata, escribe un archivo del lado del servidor sin devolverlo en la respuesta HTTP). dolibarr-module/nova/ añade dos endpoints de solo lectura (GET /nova/accounts, GET /nova/bookkeeping) bajo el mismo mecanismo REST nativo (DOLAPIKEY, permisos de aplicación). Este módulo se instala por separado en la instancia Dolibarr NOVA — ver dolibarr-module/README.md.

Inicio 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 (no autenticados).

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

Pruebas

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

Sin base de datos: las pruebas utilizan un doble de prueba (tests/fixtures/) para DolibarrClient, sin fixtures PostgreSQL/NullPool.

Docker

docker compose up --build

El CredentialStore se monta en solo lectura (./credentials:/app/credentials:ro) — nunca versionar credentials/credentials.yaml.

Requisitos del lado de Dolibarr NOVA

1. Instalar dolibarr-module/nova/ (ver su README).

2. Para cada auditor: crear un usuario Dolibarr dedicado, generar su DOLAPIKEY, otorgar el derecho Leer el plan contable y el Libro Mayor a través de la API NOVA, luego añadir su entrada en credentials/credentials.yaml (con el sub de su token Keycloak) — reiniciar el servidor MCP para que se aplique (sin recarga en caliente, H2).

3. Para get_company: completar la constante Dolibarr API_LOGINS_ALLOWED_FOR_GET_COMPANY (o otorgar el derecho de administrador) para cada login utilizado — de lo contrario, esta tool concreta falla con un error upstream 403 (comportamiento esperado).