NOVA MCP Server

Сервер Model Context Protocol в режиме только для чтения, предоставляющий бухгалтерские и коммерческие данные демонстрационной компании NOVA (Dolibarr 23.0.3), для постепенного исследования ИИ-ассистентом через Cowork. См. spec-final.md для полной спецификации.

Архитектура

• Auth (app/auth/): проверка JWT Keycloak (JWKS через PyJWKClient), разрешение идентичности (iss, sub), CredentialStore (локальный YAML), сопоставляющий пользователей с ключом API Dolibarr, middleware credential_gate (403, если идентичность не сопоставлена).

• Dolibarr (app/dolibarr/): централизованный HTTP-клиент (постоянный пул соединений, ограниченные повторные попытки, преобразование в Decimal) для стандартного REST API Dolibarr (контрагенты, счета-фактуры, платежи, банк).

• Модуль-компаньон NOVA (dolibarr-module/): план счетов и Главная книга не предоставляются стандартным API Dolibarr — см. соответствующий раздел ниже.

• Privacy Layer (app/privacy/): заменяет любую идентичность контрагента стабильной технической ссылкой (THIRDPARTY:<id> и т. д.), систематически применяется сервисами.

• Domain (app/domain/): детерминированные правила бухгалтерского учёта (EBITDA, aging, пагинация, валидация), не зависящие от какого-либо фреймворка.

• Services (app/services/): бизнес-логика, по одному модулю на домен.

• MCP (app/mcp_server/): MCP-сервер (официальный SDK Anthropic), инструменты по доменам, центральный декоратор перевода ошибок + логирование (errors.py).

Related MCP server: NuMetric MCP Server

Зачем нужен модуль-компаньон Dolibarr?

Стандартный REST API Dolibarr 23.0 не предоставляет ни одного endpoint для плана счетов или Главной книги (единственная нативная точка входа, GET /accountancy/exportdata, записывает файл на стороне сервера, не возвращая его в HTTP-ответе). dolibarr-module/nova/ добавляет два endpoint только для чтения (GET /nova/accounts, GET /nova/bookkeeping) через тот же нативный REST-механизм (DOLAPIKEY, права приложения). Этот модуль устанавливается отдельно на инстанс Dolibarr NOVA — см. dolibarr-module/README.md.

Локальный запуск

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: проверки работоспособности (без аутентификации).

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

Тесты

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

База данных не используется: тесты используют тестовый двойник (tests/fixtures/) для DolibarrClient, без фикстур PostgreSQL/NullPool.

Docker

docker compose up --build

CredentialStore монтируется в режиме только для чтения (./credentials:/app/credentials:ro) — никогда не добавляйте credentials/credentials.yaml в систему контроля версий.

Предварительные требования на стороне Dolibarr NOVA

1. Установите dolibarr-module/nova/ (см. его README).

2. Для каждого аудитора: создайте выделенного пользователя Dolibarr, сгенерируйте его DOLAPIKEY, предоставьте право Чтение плана счетов и Главной книги через API NOVA, затем добавьте его запись в credentials/credentials.yaml (с sub из его токена Keycloak) — перезапустите MCP-сервер для применения изменений (без горячей перезагрузки, H2).

3. Для get_company: укажите константу Dolibarr API_LOGINS_ALLOWED_FOR_GET_COMPANY (или предоставьте право администратора) для каждого используемого логина — иначе этот конкретный инструмент завершится ошибкой upstream 403 (ожидаемое поведение).