NOVA MCP Server

읽기 전용 Model Context Protocol 서버로, Cowork를 통해 AI 어시스턴트가 점진적으로 조사할 수 있도록 데모 회사 NOVA(Dolibarr 23.0.3)의 회계 및 상업 데이터를 노출합니다. 전체 사양은 spec-final.md를 참조하세요.

아키텍처

• 인증 (app/auth/) : Keycloak JWT 검증(PyJWKClient를 통한 JWKS), (iss, sub) 신원 확인, 사용자별 Dolibarr API 키에 매핑하는 CredentialStore(로컬 YAML), credential_gate 미들웨어(신원이 매핑되지 않으면 403).

• Dolibarr (app/dolibarr/) : Dolibarr 표준 REST API(거래처, 송장, 지불, 은행)를 위한 중앙 집중식 HTTP 클라이언트(지속 연결 풀, 제한된 재시도, Decimal 변환).

• NOVA 동반 모듈 (dolibarr-module/) : 표준 Dolibarr API는 계정과목표와 총계정원장을 노출하지 않습니다 — 아래 전용 섹션을 참조하세요.

• 프라이버시 계층 (app/privacy/) : 모든 거래처 신원을 안정적인 기술 참조(THIRDPARTY:<id> 등)로 대체하며, 서비스에서 일관되게 적용합니다.

• 도메인 (app/domain/) : 프레임워크에 독립적인 결정적 회계 규칙(EBITDA, aging, 페이지네이션, 검증).

• 서비스 (app/services/) : 비즈니스 로직, 도메인별 모듈 하나.

• MCP (app/mcp_server/) : MCP 서버(Anthropic 공식 SDK), 도메인별 도구, 오류 변환 및 로깅 중앙 데코레이터(errors.py).

Related MCP server: ERPNext MCP Server

왜 Dolibarr 동반 모듈인가?

Dolibarr 23.0 표준 REST API는 계정과목표나 총계정원장에 대한 엔드포인트를 노출하지 않습니다(유일한 기본 제공 진입점인 GET /accountancy/exportdata는 서버 측에서 파일을 작성할 뿐 HTTP 응답으로 반환하지 않습니다). dolibarr-module/nova/는 동일한 기본 REST 메커니즘(DOLAPIKEY, 애플리케이션 권한) 아래 두 개의 읽기 전용 엔드포인트(GET /nova/accounts, GET /nova/bookkeeping)를 추가합니다. 이 모듈은 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 : MCP 엔드포인트(Streamable HTTP).

테스트

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

데이터베이스 없음: 테스트는 DolibarrClient에 대해 테스트 더블(tests/fixtures/)을 사용하며, 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를 생성하고, NOVA API를 통해 계정과목표와 총계정원장 읽기 권한을 부여한 다음, credentials/credentials.yaml에 항목을 추가합니다(Keycloak 토큰의 sub 포함) — 적용하려면 MCP 서버를 다시 시작합니다(핫 리로드 없음, H2).

3. get_company의 경우: 사용되는 각 로그인에 대해 Dolibarr 상수 API_LOGINS_ALLOWED_FOR_GET_COMPANY를 설정하거나 admin 권한을 부여합니다 — 그렇지 않으면 이 특정 도구는 업스트림 403 오류로 실패합니다(예상된 동작).