odoo-mcp-tools 1.3.0__tar.gz

odoo_mcp_tools-1.3.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.venv-*/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Node
+node_modules/
+cli/dist/
+
+# Env / secrets
+.env
+*.env
+!docker/*.example.yml
+
+# OS / editors
+.DS_Store
+Thumbs.db

odoo_mcp_tools-1.3.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.5
+Name: odoo-mcp-tools
+Version: 1.3.0
+Summary: Clean-room MCP server for Odoo (Community, Enterprise, online) across versions 10-19.
+Project-URL: Homepage, https://github.com/Transgenia/MCP-Odoo-Tools-CE-EE-and-online
+Project-URL: Repository, https://github.com/Transgenia/MCP-Odoo-Tools-CE-EE-and-online
+Author-email: Transgenia <dev@transgenia.org>
+License: MIT
+Keywords: erp,json-rpc,mcp,model-context-protocol,odoo,xml-rpc
+Requires-Python: >=3.9
+Provides-Extra: cache
+Requires-Dist: cachetools>=5.3; extra == 'cache'
+Provides-Extra: dev
+Requires-Dist: mcp<2,>=1.2; (python_version >= '3.10') and extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: metrics
+Requires-Dist: prometheus-client>=0.20; extra == 'metrics'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.24; extra == 'otel'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.24; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.24; extra == 'otel'
+Description-Content-Type: text/markdown
+
+# odoo-mcp-tools (server)
+
+Clean-room MIT MCP server for Odoo — Community, Enterprise and online (SaaS),
+across major versions **10 to 19**. This is the Python package that backs the
+`MCP-Odoo-Tools-CE-EE-and-online` Claude plugin.
+
+It exposes generic Odoo tools (search / read / search_read / create / write /
+unlink / execute / export / translate / report / version / connections) over a
+transport layer that speaks JSON-RPC with automatic XML-RPC fallback, and a
+**cross-version compatibility layer** that resolves model/field names so a
+single tool call works across every supported version.
+
+Not derived from any AGPL project; relies only on Odoo's public RPC interfaces.
+It has **no third-party runtime dependencies**: the MCP stdio protocol and both
+transports use only the Python standard library. Requires Python 3.9+.
+
+## Install & run
+
+```bash
+python3 run_stdio.py               # from a checkout of server/, nothing to install
+pip install . && odoo-mcp          # or install the package, then the entry point
+```
+
+The Claude plugin runs `python3 ${CLAUDE_PLUGIN_ROOT}/server/run_stdio.py`
+directly, so nothing is installed when the plugin starts. A Dockerfile is in
+the repository's `docker/` folder.
+
+Configure via environment: `ODOO_URL`, `ODOO_DB`, `ODOO_LOGIN`,
+`ODOO_API_KEY` (or `ODOO_PASSWORD`). Optional: `ODOO_TRANSPORT_PREF`
+(`auto`|`jsonrpc`|`xmlrpc`), `ODOO_TIMEOUT`, `ODOO_CACHE_TTL`, `ODOO_METRICS`,
+`ODOO_OTEL_ENDPOINT`.
+
+See the repository root README for the full plugin, the CLI fallback, and the
+compatibility matrix.
+
+## License
+
+MIT © Transgenia (Centrum Transgenia S.A.S. de C.V.)

odoo_mcp_tools-1.3.0/README.md

@@ -0,0 +1,38 @@
+# odoo-mcp-tools (server)
+
+Clean-room MIT MCP server for Odoo — Community, Enterprise and online (SaaS),
+across major versions **10 to 19**. This is the Python package that backs the
+`MCP-Odoo-Tools-CE-EE-and-online` Claude plugin.
+
+It exposes generic Odoo tools (search / read / search_read / create / write /
+unlink / execute / export / translate / report / version / connections) over a
+transport layer that speaks JSON-RPC with automatic XML-RPC fallback, and a
+**cross-version compatibility layer** that resolves model/field names so a
+single tool call works across every supported version.
+
+Not derived from any AGPL project; relies only on Odoo's public RPC interfaces.
+It has **no third-party runtime dependencies**: the MCP stdio protocol and both
+transports use only the Python standard library. Requires Python 3.9+.
+
+## Install & run
+
+```bash
+python3 run_stdio.py               # from a checkout of server/, nothing to install
+pip install . && odoo-mcp          # or install the package, then the entry point
+```
+
+The Claude plugin runs `python3 ${CLAUDE_PLUGIN_ROOT}/server/run_stdio.py`
+directly, so nothing is installed when the plugin starts. A Dockerfile is in
+the repository's `docker/` folder.
+
+Configure via environment: `ODOO_URL`, `ODOO_DB`, `ODOO_LOGIN`,
+`ODOO_API_KEY` (or `ODOO_PASSWORD`). Optional: `ODOO_TRANSPORT_PREF`
+(`auto`|`jsonrpc`|`xmlrpc`), `ODOO_TIMEOUT`, `ODOO_CACHE_TTL`, `ODOO_METRICS`,
+`ODOO_OTEL_ENDPOINT`.
+
+See the repository root README for the full plugin, the CLI fallback, and the
+compatibility matrix.
+
+## License
+
+MIT © Transgenia (Centrum Transgenia S.A.S. de C.V.)

odoo_mcp_tools-1.3.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "odoo-mcp-tools"
+version = "1.3.0"
+description = "Clean-room MCP server for Odoo (Community, Enterprise, online) across versions 10-19."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Transgenia", email = "dev@transgenia.org" }]
+keywords = ["odoo", "erp", "mcp", "model-context-protocol", "xml-rpc", "json-rpc"]
+# No runtime dependencies: the MCP stdio protocol and both Odoo transports are
+# implemented on the standard library, so the plugin runs the shipped source
+# directly with python3 and installs nothing. Extras below are optional.
+dependencies = []
+
+[project.optional-dependencies]
+cache = ["cachetools>=5.3"]
+metrics = ["prometheus-client>=0.20"]
+otel = [
+    "opentelemetry-api>=1.24",
+    "opentelemetry-sdk>=1.24",
+    "opentelemetry-exporter-otlp-proto-http>=1.24",
+]
+dev = [
+    # Interop check only: tests drive our server with the official MCP client.
+    "mcp>=1.2,<2; python_version >= '3.10'",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.5",
+    "mypy>=1.10",
+]
+
+[project.scripts]
+odoo-mcp = "odoo_mcp.__main__:main"
+
+[project.urls]
+Homepage = "https://github.com/Transgenia/MCP-Odoo-Tools-CE-EE-and-online"
+Repository = "https://github.com/Transgenia/MCP-Odoo-Tools-CE-EE-and-online"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/odoo_mcp"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+# Optional-dependency loaders intentionally catch broad exceptions to degrade
+# gracefully when an extra (cachetools/prometheus/otel) is not installed.
+ignore = ["BLE001"]
+
+[tool.pytest.ini_options]
+markers = ["live: tests that require a real/ephemeral Odoo instance (opt-in)"]
+asyncio_mode = "auto"

odoo_mcp_tools-1.3.0/run_stdio.py

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Transgenia (Centrum Transgenia S.A.S. de C.V.)
+"""Entry point the plugin runs: ``python3 ${CLAUDE_PLUGIN_ROOT}/server/run_stdio.py``.
+
+Standard library only. It puts the bundled ``src`` folder first on
+``sys.path`` (so a different ``odoo_mcp`` package installed on the machine can
+never shadow the reviewed code) and starts the stdio MCP server. It installs
+nothing and downloads nothing.
+"""
+
+import os
+import sys
+
+# Runs before any project code, so it must also parse on older interpreters:
+# hence the explicit check and %-formatting rather than an f-string.
+if sys.version_info < (3, 9):  # noqa: UP036
+    sys.stderr.write(
+        "odoo-tools: Python 3.9 or newer is required (found %s)\n"  # noqa: UP031
+        % sys.version.split()[0]
+    )
+    sys.exit(1)
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "src"))
+
+from odoo_mcp.__main__ import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

odoo_mcp_tools-1.3.0/src/odoo_mcp/__init__.py

@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Transgenia (Centrum Transgenia S.A.S. de C.V.)
+"""Clean-room MCP server for Odoo CE/EE/online, versions 10-19.
+
+This package is an original implementation. It does NOT derive from any
+AGPL-licensed Odoo MCP project; it only relies on Odoo's public XML-RPC /
+JSON-RPC interfaces and publicly known model/field naming, which are not
+themselves copyrightable.
+"""
+
+__version__ = "0.1.0"

odoo_mcp_tools-1.3.0/src/odoo_mcp/__main__.py

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Transgenia (Centrum Transgenia S.A.S. de C.V.)
+"""CLI entry point: ``odoo-mcp`` / ``python -m odoo_mcp``."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+
+from .config import Settings
+from .server import serve
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="odoo-mcp", description=__doc__)
+    parser.add_argument(
+        "--transport",
+        choices=["stdio"],
+        default="stdio",
+        help="MCP transport (only stdio is supported in this build)",
+    )
+    parser.add_argument("--log-level", default="INFO")
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(
+        level=getattr(logging, args.log_level.upper(), logging.INFO),
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        stream=sys.stderr,  # never pollute stdout (the MCP channel)
+    )
+    serve(Settings.from_env())
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

odoo_mcp_tools-1.3.0/src/odoo_mcp/cache.py

@@ -0,0 +1,193 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Transgenia (Centrum Transgenia S.A.S. de C.V.)
+"""In-process TTL cache for schema metadata (fields_get / name_get / model lists).
+
+Uses ``cachetools.TTLCache`` when available, otherwise a small stdlib fallback
+so the server has zero hard dependency on the optional ``cache`` extra.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+from collections.abc import Callable, Hashable
+from typing import Any
+
+try:  # optional dependency
+    from cachetools import TTLCache  # type: ignore
+
+    _HAS_CACHETOOLS = True
+except Exception:  # pragma: no cover - exercised when extra is absent
+    _HAS_CACHETOOLS = False
+
+
+class _SimpleTTLCache:
+    """Minimal thread-safe TTL cache used when cachetools is not installed."""
+
+    def __init__(self, maxsize: int, ttl: float) -> None:
+        self._maxsize = maxsize
+        self._ttl = ttl
+        self._data: dict[Hashable, tuple[float, Any]] = {}
+        self._lock = threading.Lock()
+
+    def get(self, key: Hashable, default: Any = None) -> Any:
+        now = time.monotonic()
+        with self._lock:
+            item = self._data.get(key)
+            if item is None:
+                return default
+            expires, value = item
+            if expires < now:
+                self._data.pop(key, None)
+                return default
+            return value
+
+    def set(self, key: Hashable, value: Any) -> None:
+        now = time.monotonic()
+        with self._lock:
+            if len(self._data) >= self._maxsize:
+                # drop the oldest-expiring entry
+                oldest = min(self._data.items(), key=lambda kv: kv[1][0], default=None)
+                if oldest is not None:
+                    self._data.pop(oldest[0], None)
+            self._data[key] = (now + self._ttl, value)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._data.clear()
+
+    def delete(self, key: Hashable) -> None:
+        with self._lock:
+            self._data.pop(key, None)
+
+    def keys(self) -> list[Hashable]:
+        with self._lock:
+            return list(self._data.keys())
+
+
+class SchemaCache:
+    """TTL cache keyed by ``(tenant, model, version, kind)``.
+
+    ``kind`` distinguishes ``fields`` from ``name`` and ``models`` lookups so a
+    single cache instance serves all schema reads. Records ``hit``/``miss``
+    counters that :mod:`odoo_mcp.observability` can export.
+    """
+
+    def __init__(self, ttl: int = 300, maxsize: int = 2048) -> None:
+        self.ttl = ttl
+        self.hits = 0
+        self.misses = 0
+        self._lock = threading.Lock()
+        # Per-(tenant, model) generation bumped by invalidate_fields. Callers
+        # include it in their cache key so an in-flight fill computed BEFORE
+        # an invalidation (but stored AFTER) lands under a stale generation
+        # and is never served.
+        self._generations: dict[tuple[str, str], int] = {}
+        if _HAS_CACHETOOLS:
+            self._impl: Any = TTLCache(maxsize=maxsize, ttl=ttl)
+            self._is_cachetools = True
+        else:
+            self._impl = _SimpleTTLCache(maxsize=maxsize, ttl=ttl)
+            self._is_cachetools = False
+
+    def get_or_compute(self, key: Hashable, compute: Callable[[], Any]) -> Any:
+        cached = self._get(key)
+        if cached is not None:
+            with self._lock:
+                self.hits += 1
+            return cached
+        with self._lock:
+            self.misses += 1
+        value = compute()
+        self._set(key, value)
+        return value
+
+    def _get(self, key: Hashable) -> Any:
+        if self._is_cachetools:
+            try:
+                return self._impl[key]
+            except KeyError:
+                return None
+        return self._impl.get(key)
+
+    def _set(self, key: Hashable, value: Any) -> None:
+        if self._is_cachetools:
+            self._impl[key] = value
+        else:
+            self._impl.set(key, value)
+
+    def clear(self) -> None:
+        if self._is_cachetools:
+            self._impl.clear()
+        else:
+            self._impl.clear()
+        with self._lock:
+            self.hits = 0
+            self.misses = 0
+
+    def delete(self, key: Hashable) -> None:
+        try:
+            if self._is_cachetools:
+                self._impl.pop(key, None)
+            else:
+                self._impl.delete(key)
+        except Exception:  # noqa: S110 — best-effort cache eviction
+            pass
+
+    def invalidate(self, predicate: Callable[[Hashable], bool]) -> int:
+        """Delete every key matching ``predicate``. Returns count removed."""
+        if self._is_cachetools:
+            try:
+                keys = list(self._impl.keys())
+            except Exception:
+                return 0
+            removed = 0
+            for k in keys:
+                try:
+                    if predicate(k):
+                        self._impl.pop(k, None)
+                        removed += 1
+                except Exception:  # noqa: S112 — keep evicting other keys
+                    continue
+            return removed
+        try:
+            keys = self._impl.keys()
+        except Exception:
+            return 0
+        removed = 0
+        for k in keys:
+            try:
+                if predicate(k):
+                    self._impl.delete(k)
+                    removed += 1
+            except Exception:  # noqa: S112 — keep evicting other keys
+                continue
+        return removed
+
+    def invalidate_fields(self, fingerprint: str, model: str) -> int:
+        """Drop cached ``fields_get`` entries for ``model``/tenant.
+
+        Called after ``odoo_add_field`` so an immediate verification
+        ``odoo_fields_get`` does not serve the pre-create schema (TTL 300s).
+        Also bumps the per-model generation so concurrent fills that started
+        before this call cannot repopulate stale data afterwards.
+        """
+        with self._lock:
+            gen_key = (fingerprint, model)
+            self._generations[gen_key] = self._generations.get(gen_key, 0) + 1
+
+        def _match(key: Hashable) -> bool:
+            return (
+                isinstance(key, tuple)
+                and len(key) >= 3
+                and key[0] == fingerprint
+                and key[1] == "fields"
+                and key[2] == model
+            )
+
+        return self.invalidate(_match)
+
+    def generation(self, fingerprint: str, model: str) -> int:
+        """Current generation for ``(fingerprint, model)`` (0 = never invalidated)."""
+        with self._lock:
+            return self._generations.get((fingerprint, model), 0)

odoo_mcp_tools-1.3.0/src/odoo_mcp/compat/__init__.py

@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Transgenia (Centrum Transgenia S.A.S. de C.V.)
+"""Cross-version compatibility layer for Odoo 10-19 / CE / EE / online."""
+
+from .detect import EnvFacts, probe
+from .resolve import (
+    FieldResolution,
+    assert_capability,
+    has_capability,
+    requires_edition,
+    resolve_field,
+    resolve_fields,
+    resolve_model,
+)
+
+__all__ = [
+    "EnvFacts",
+    "FieldResolution",
+    "assert_capability",
+    "has_capability",
+    "probe",
+    "requires_edition",
+    "resolve_field",
+    "resolve_fields",
+    "resolve_model",
+]

odoo_mcp_tools-1.3.0/src/odoo_mcp/compat/deltas.py

@@ -0,0 +1,143 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Transgenia (Centrum Transgenia S.A.S. de C.V.)
+"""Declarative cross-version delta map for Odoo 10-19.
+
+This is DATA, not logic. New deltas are added here and covered by table-driven
+tests. All entries reflect publicly known Odoo API/schema changes; version
+boundaries marked "best-effort" should be confirmed by a live probe when a user
+reports a mismatch (that is what the compat layer's graceful errors are for).
+
+Conventions:
+  * ``changed_in`` = the first major version where the NEW name/behavior applies.
+  * ``since`` = feature/model available from this major version onward.
+  * ``until`` = feature/model available up to and including this major version.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+MIN_VERSION = 10
+MAX_VERSION = 19
+
+
+@dataclass(frozen=True)
+class ModelRename:
+    old: str
+    new: str
+    changed_in: int
+    note: str = ""
+    # A "merge" is NOT a clean rename: the ``new`` model already exists as a
+    # DISTINCT model before ``changed_in`` (e.g. account.move = journal entries
+    # exists on v10-12 alongside account.invoice = invoices, which was folded into
+    # account.move at v13). For merges we must only resolve old->new on
+    # ``version >= changed_in`` (where ``old`` is gone) and NEVER rewrite
+    # new->old on older versions, or a call meant for the ``new`` model would be
+    # redirected to a different model with different semantics.
+    merge: bool = False
+
+
+@dataclass(frozen=True)
+class FieldRename:
+    model: str
+    old: str
+    new: str
+    changed_in: int
+    note: str = ""
+
+
+@dataclass(frozen=True)
+class FieldRemoved:
+    model: str
+    field: str
+    removed_in: int
+    use_instead: str = ""
+    note: str = ""
+
+
+@dataclass(frozen=True)
+class Capability:
+    feature: str
+    since: int | None = None  # available from this version
+    until: int | None = None  # available up to and including this version
+    note: str = ""
+
+
+# --- Model renames -----------------------------------------------------------
+MODEL_RENAMES: tuple[ModelRename, ...] = (
+    # MERGE, not a rename: account.move (journal entries) already exists on v10-12
+    # as a distinct model; account.invoice (invoices) was folded into it at v13.
+    ModelRename(
+        "account.invoice", "account.move", 13,
+        "Invoices merged into account.move in v13; account.move pre-exists as journal entries",
+        merge=True,
+    ),
+    ModelRename(
+        "account.invoice.line", "account.move.line", 13,
+        "Invoice lines merged into account.move.line in v13; account.move.line pre-exists",
+        merge=True,
+    ),
+    # True rename: stock.package did not exist before v19.
+    ModelRename(
+        "stock.quant.package", "stock.package", 19, "Package model renamed (best-effort; saas~19.3)"
+    ),
+)
+
+# --- Field renames -----------------------------------------------------------
+FIELD_RENAMES: tuple[FieldRename, ...] = (
+    FieldRename(
+        "account.move.line",
+        "analytic_account_id",
+        "analytic_distribution",
+        16,
+        "Analytic accounting became distribution-based in v16",
+    ),
+)
+
+# --- Field removals ----------------------------------------------------------
+FIELD_REMOVED: tuple[FieldRemoved, ...] = (
+    FieldRemoved(
+        "product.template",
+        "uom_po_id",
+        17,
+        use_instead="uom_id",
+        note="Purchase UoM unified into uom_id (best-effort boundary)",
+    ),
+    FieldRemoved(
+        "res.partner",
+        "company_type",
+        19,
+        use_instead="is_company",
+        note="company_type dropped; use is_company boolean (best-effort; saas~19.3)",
+    ),
+)
+
+# --- Capabilities ------------------------------------------------------------
+CAPABILITIES: tuple[Capability, ...] = (
+    Capability("api_key_auth", since=14, note="API keys introduced in v14; older needs password"),
+    Capability(
+        "jsonrpc_api_key",
+        until=16,
+        note="/jsonrpc execute_kw rejects API keys on v17+; use XML-RPC (auto-fallback handles it)",
+    ),
+    Capability(
+        "update_field_translations",
+        since=16,
+        note="Native translation write API; older versions need per-lang context writes",
+    ),
+)
+
+# --- Edition-only models (heuristic; runtime probe is authoritative) ---------
+# Presence of these models strongly implies Enterprise. The compat layer only
+# BLOCKS when edition was positively detected as community.
+ENTERPRISE_ONLY_MODELS: frozenset[str] = frozenset(
+    {
+        "documents.document",
+        "sign.request",
+        "account.consolidation.period",
+        "quality.check",  # quality is EE in most lines
+        "helpdesk.ticket",
+        "planning.slot",
+        "appraisal.appraisal",
+    }
+)