架构

面向好奇者和贡献者。权威来源是仓库中的 docs/architecture.md。

Claude (MCP 客户端)
      │  stdio (JSON-RPC MCP)
      ▼
odoo_mcp.server  ──列出/派发──▶  registry (ToolRegistry)
      │                                     │
      │                                     ▼
      │                              tools/ (crud, meta, export, i18n, report)
      │                                     │  resolve_model / resolve_fields
      │                                     ▼
      │                              compat/ (detect → deltas → resolve)
      ▼                                     │
tenancy.ConnectionManager ──▶ session.OdooSession ──▶ transport/
   (按租户)                     (认证, facts, 缓存)      fallback → jsonrpc | xmlrpc
                                                              │
                                                              ▼
                                                        Odoo 实例

层次

• transport/ — XmlRpcTransport、JsonRpcTransport 和 FallbackTransport （auto：优先 JSON-RPC，当 API key 被拒绝或发生传输错误时透明回退到 XML-RPC； 在第一次回退后固定为 XML-RPC，并提示一次）。
• session.py — OdooSession 保存凭据、以惰性方式认证（uid）、 缓存版本/版本类型/部署方式的 facts，并将模式读取包裹在 TTL 缓存 SchemaCache 中。ConnectionManager（tenancy.py）将租户指纹 （url|db|login，从不 包含密钥）映射到一个会话。
• compat/ — detect.probe() 构建 EnvFacts；deltas.py 是声明式的 deltas 映射表；resolve.py 将请求的模型/字段/能力转换为目标中实际存在的 内容。每个工具都在调用 ORM 之前先调用 resolve_*。
• tools/ — 注册在共享 registry 上的轻量处理器。 写入工具带有 read_only=False 以备将来的策略门槛之用；公开核心 不 施加 审批门槛（那属于一个私有的治理层）。
• observability.py — 可选的 Prometheus 指标和 OTLP 追踪，两者默认均关闭， 且在附加项未安装时为 no-ops。
• server.py / main.py — MCP stdio 的接线以及 odoo-mcp 入口点。 处理器运行在一个工作线程中（anyio.to_thread）， 从而使一次阻塞的 RPC 永远不会拖住 event loop。日志输出到 stderr； stdout 专供 MCP 通道使用。

传输方式与模式

• stdio（默认）： 单租户，凭据来自环境。这是插件的 mcpServers 条目所用的 模式。
• HTTP（docker，可选/路线图）： 多租户，通过请求头 X-Odoo-Url/Db/Login + Bearer 密钥实现，由 tenancy.from_headers 解析。

设计原则

• 跨版本的单一工具接口 — 调用方使用现代名称。
• 失败时给出补救建议 — CompatError 会解释需要更改什么；不可用的字段会 降级为警告，而非硬性失败。
• 轻量的基础安装 — 可选依赖（cache/metrics/otel）永不阻塞启动。
• 日志和磁盘中没有任何密钥。