NOVA MCP Server

只读的 Model Context Protocol 服务器，暴露演示公司 NOVA（Dolibarr 23.0.3）的会计和商业数据，供 AI 助手通过 Cowork 进行渐进式调查。完整规范见 spec-final.md。

架构

• Auth（app/auth/）：Keycloak JWT 验证（通过 PyJWKClient 的 JWKS）、身份解析 (iss, sub)、CredentialStore（本地 YAML）将每个用户映射到 Dolibarr API 密钥、中间件 credential_gate（身份未映射时返回 403）。

• Dolibarr（app/dolibarr/）：用于 Dolibarr 标准 REST API（第三方、发票、付款、银行）的集中式 HTTP 客户端（持久连接池、有限重试、Decimal 转换）。

• NOVA 配套模块（dolibarr-module/）：会计科目表和总账不由 Dolibarr 标准 API 暴露——见下文专门章节。

• 隐私层（app/privacy/）：将任何第三方身份替换为稳定的技术引用（THIRDPARTY:<id> 等），由服务系统性地应用。

• Domain（app/domain/）：独立于任何框架的确定性会计规则（EBITDA、账龄、分页、验证）。

• Services（app/services/）：业务逻辑，每个领域一个模块。

• 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、应用权限）下添加了两个只读端点（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 fixtures。

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（或授予管理员权限）——否则该特定工具会因上游 403 错误而失败（预期行为）。