NOVA MCP Server

読み取り専用のModel Context Protocolサーバーで、デモ企業 NOVA (Dolibarr 23.0.3) の会計・商取引データを公開し、Cowork を介した AI アシスタントによる段階的な調査を可能にします。完全な仕様については spec-final.md を参照してください。

Architecture

• Auth (app/auth/) : Keycloak JWT 検証 (PyJWKClient による JWKS)、(iss, sub) による ID 解決、ユーザーごとの Dolibarr API キーにマッピングする CredentialStore (ローカル YAML)、credential_gate ミドルウェア (ID がマッピングされていない場合は 403)。

• Dolibarr (app/dolibarr/) : 標準の Dolibarr REST API (取引先、請求書、支払い、銀行) のための集中型 HTTP クライアント (永続的な接続プール、制限付きリトライ、Decimal 変換)。

• NOVA コンパニオンモジュール (dolibarr-module/) : 勘定科目表と元帳は標準の Dolibarr API では公開されません — 以下の専用セクションを参照してください。

• Privacy Layer (app/privacy/) : すべての取引先 ID を安定した技術参照 (THIRDPARTY:<id> など) に置き換え、サービスによって常に適用されます。

• Domain (app/domain/) : あらゆるフレームワークから独立した決定的な会計ルール (EBITDA、aging、ページネーション、検証)。

• Services (app/services/) : ビジネスロジック。ドメインごとに 1 つのモジュール。

• MCP (app/mcp_server/) : MCP サーバー (公式 Anthropic SDK)、ドメインごとのツール、エラー変換 + ロギングの集中デコレータ (errors.py)。

Related MCP server: NuMetric MCP Server

なぜ Dolibarr コンパニオンモジュールなのか ?

Dolibarr 23.0 の標準 REST API には、勘定科目表や元帳を公開するエンドポイントがありません (唯一のネイティブエントリポイント GET /accountancy/exportdata はサーバー側でファイルを書き込むだけで、HTTP レスポンスでは返しません)。dolibarr-module/nova/ は、同じネイティブ REST メカニズム (DOLAPIKEY、アプリケーション権限) の下で、読み取り専用の 2 つのエンドポイント (GET /nova/accounts、GET /nova/bookkeeping) を追加します。このモジュールは NOVA Dolibarr インスタンスに別途インストールされます — 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 をバージョン管理に含めないでください。

NOVA Dolibarr 側の前提条件

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 を設定します (または管理者権限を付与します) — そうしないと、この特定のツールは上流の 403 エラーで失敗します (想定された動作)。