godoo-mcp-server 0.1.0__tar.gz

godoo_mcp_server-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.3
+Name: godoo-mcp-server
+Version: 0.1.0
+Summary: Stateless MCP server for Odoo — raw primitives + skill resources
+License: LGPL-3.0-or-later
+Requires-Dist: fastmcp>=3.3,<4
+Requires-Dist: godoo-client>=0.2,<0.3
+Requires-Dist: cachetools>=7,<8
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# godoo-mcp-server
+
+Stateless MCP server for Odoo — raw primitives + skill resources.
+
+## Installation
+
+```bash
+pip install godoo-mcp-server
+```
+
+Or with Docker:
+
+```bash
+docker run -e ODOO_URL=https://your.odoo.instance \
+           -e ODOO_DATABASE=mydb \
+           -e ODOO_USERNAME=admin \
+           -e ODOO_PASSWORD=secret \
+           -p 8000:8000 \
+           ghcr.io/godoo-dev/godoo-mcp-server:latest
+```
+
+## Configuration
+
+The server resolves Odoo credentials from request headers or environment variables. Headers take precedence over environment variables.
+
+| Credential | Header | Environment Variable |
+|-----------|--------|---------------------|
+| Odoo URL | `X-Odoo-Url` | `ODOO_URL` |
+| Database | `X-Odoo-Database` | `ODOO_DATABASE` |
+| Username | `X-Odoo-Username` | `ODOO_USERNAME` |
+| Password | `X-Odoo-Password` | `ODOO_PASSWORD` |
+
+If neither headers nor environment variables are set, the server returns a credential error.
+
+**Server bind address:** Defaults to `0.0.0.0:8000`. Override with `HOST` and `PORT` environment variables.
+
+> **Note:** If you override `PORT`, you must also update the Docker `HEALTHCHECK` to match the new port.
+
+## Security: Header Trust Model
+
+`godoo-mcp-server` authenticates Odoo users via `X-Odoo-Username` and
+`X-Odoo-Password` request headers (or `ODOO_USERNAME` / `ODOO_PASSWORD`
+environment variables). **This means any caller who can reach the server
+can impersonate any Odoo user by setting these headers.**
+
+This is intentional for self-hosted / trusted-network deployments. In
+production, you MUST deploy a header-stripping reverse proxy in front of
+the server that enforces identity. [`godoo-proxy`](https://github.com/godoo-dev/godoo-proxy)
+is the SaaS-safe gateway for this role — it implements OAuth 2.1 / SSO
+and injects verified per-user credentials before forwarding to
+`godoo-mcp-server`.
+
+If you expose `godoo-mcp-server` directly on a public network without a
+trusted proxy, any network peer gains full Odoo impersonation capability.
+
+## Running E2E tests locally
+
+**Prerequisites:**
+
+- Docker (for the Odoo testcontainer)
+- `claude` CLI on PATH (Claude Code)
+- Claude auth (API key or active OAuth session)
+- Python 3.14 + `uv`
+
+**Command:**
+
+```bash
+uv run pytest -m e2e -s -v
+```
+
+> **Cost warning:** Each run makes a real, billable Claude API call.
+> Keep the suite small and only run when needed.
+
+The test skips automatically when Docker or the `claude` CLI is absent — this is a clean skip, not an error.
+
+The default `uv run pytest` excludes e2e tests automatically via the `not e2e` `addopts` filter.

godoo_mcp_server-0.1.0/README.md

@@ -0,0 +1,76 @@
+# godoo-mcp-server
+
+Stateless MCP server for Odoo — raw primitives + skill resources.
+
+## Installation
+
+```bash
+pip install godoo-mcp-server
+```
+
+Or with Docker:
+
+```bash
+docker run -e ODOO_URL=https://your.odoo.instance \
+           -e ODOO_DATABASE=mydb \
+           -e ODOO_USERNAME=admin \
+           -e ODOO_PASSWORD=secret \
+           -p 8000:8000 \
+           ghcr.io/godoo-dev/godoo-mcp-server:latest
+```
+
+## Configuration
+
+The server resolves Odoo credentials from request headers or environment variables. Headers take precedence over environment variables.
+
+| Credential | Header | Environment Variable |
+|-----------|--------|---------------------|
+| Odoo URL | `X-Odoo-Url` | `ODOO_URL` |
+| Database | `X-Odoo-Database` | `ODOO_DATABASE` |
+| Username | `X-Odoo-Username` | `ODOO_USERNAME` |
+| Password | `X-Odoo-Password` | `ODOO_PASSWORD` |
+
+If neither headers nor environment variables are set, the server returns a credential error.
+
+**Server bind address:** Defaults to `0.0.0.0:8000`. Override with `HOST` and `PORT` environment variables.
+
+> **Note:** If you override `PORT`, you must also update the Docker `HEALTHCHECK` to match the new port.
+
+## Security: Header Trust Model
+
+`godoo-mcp-server` authenticates Odoo users via `X-Odoo-Username` and
+`X-Odoo-Password` request headers (or `ODOO_USERNAME` / `ODOO_PASSWORD`
+environment variables). **This means any caller who can reach the server
+can impersonate any Odoo user by setting these headers.**
+
+This is intentional for self-hosted / trusted-network deployments. In
+production, you MUST deploy a header-stripping reverse proxy in front of
+the server that enforces identity. [`godoo-proxy`](https://github.com/godoo-dev/godoo-proxy)
+is the SaaS-safe gateway for this role — it implements OAuth 2.1 / SSO
+and injects verified per-user credentials before forwarding to
+`godoo-mcp-server`.
+
+If you expose `godoo-mcp-server` directly on a public network without a
+trusted proxy, any network peer gains full Odoo impersonation capability.
+
+## Running E2E tests locally
+
+**Prerequisites:**
+
+- Docker (for the Odoo testcontainer)
+- `claude` CLI on PATH (Claude Code)
+- Claude auth (API key or active OAuth session)
+- Python 3.14 + `uv`
+
+**Command:**
+
+```bash
+uv run pytest -m e2e -s -v
+```
+
+> **Cost warning:** Each run makes a real, billable Claude API call.
+> Keep the suite small and only run when needed.
+
+The test skips automatically when Docker or the `claude` CLI is absent — this is a clean skip, not an error.
+
+The default `uv run pytest` excludes e2e tests automatically via the `not e2e` `addopts` filter.

godoo_mcp_server-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["uv_build>=0.11,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "godoo-mcp-server"
+version = "0.1.0"
+description = "Stateless MCP server for Odoo — raw primitives + skill resources"
+readme = "README.md"
+license = { text = "LGPL-3.0-or-later" }
+requires-python = ">=3.14"
+dependencies = [
+    "fastmcp>=3.3,<4",
+    "godoo-client>=0.2,<0.3",
+    "cachetools>=7,<8",
+]
+
+[project.scripts]
+godoo-mcp-server = "godoo_mcp_server.__main__:main"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.1",
+    "pytest>=9",
+    "pytest-asyncio>=1.4",
+    "pre-commit>=4",
+    "ruff>=0.15",
+    "godoo-testcontainers>=0.2,<0.3",
+]
+
+[tool.ruff]
+target-version = "py314"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "TCH"]
+ignore = []
+
+[tool.mypy]
+python_version = "3.14"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true
+
+[[tool.mypy.overrides]]
+module = "godoo.client.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "godoo.testcontainers.*"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+addopts = "--tb=short -m 'not integration and not e2e'"
+markers = [
+    "integration: marks tests as requiring a live Odoo container (deselect with -m 'not integration')",
+    "e2e: marks tests as requiring Docker + claude CLI + Claude auth (deselect with -m 'not e2e')",
+]
+
+[tool.uv_build]
+include = ["src/godoo_mcp_server/skills/**"]
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true

godoo_mcp_server-0.1.0/src/godoo_mcp_server/__init__.py

@@ -0,0 +1,4 @@
+"""godoo-mcp-server — Stateless MCP server for Odoo."""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

godoo_mcp_server-0.1.0/src/godoo_mcp_server/__main__.py

@@ -0,0 +1,27 @@
+"""godoo-mcp-server CLI entrypoint."""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any
+
+import uvicorn
+
+from godoo_mcp_server import __version__
+from godoo_mcp_server.server import create_app
+
+
+def main() -> None:
+    """Start the MCP server or print version."""
+    if "--version" in sys.argv:
+        print(f"godoo-mcp-server {__version__}")
+        sys.exit(0)
+    app: Any = create_app()
+    host = os.environ.get("HOST", "0.0.0.0")
+    port = int(os.environ.get("PORT", "8000"))
+    uvicorn.run(app, host=host, port=port)  # noqa: S104
+
+
+if __name__ == "__main__":
+    main()

godoo_mcp_server-0.1.0/src/godoo_mcp_server/catalog.py

@@ -0,0 +1,166 @@
+"""Lazy schema-hashed catalog store with in-process LRU+TTL cache.
+
+Cache key: (url, database, schema_hash) — NEVER includes credentials.
+Schema hash: 3 write_date probes on ir.model / ir.model.fields / ir.module.module.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from cachetools import TTLCache
+from godoo.client.client import OdooClient
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_CATALOG_TTL = 3600  # seconds; 1 hour
+_CATALOG_MAXSIZE = 32  # max distinct (url, db, hash) tuples
+
+# ---------------------------------------------------------------------------
+# Types
+# ---------------------------------------------------------------------------
+
+CacheKey = tuple[str, str, str]  # (url, database, schema_hash)
+
+# ---------------------------------------------------------------------------
+# Module-level cache (sync TTLCache — safe to create at module level)
+# asyncio.Lock is NEVER created here — see _get_lock() below (Pitfall 2)
+# ---------------------------------------------------------------------------
+
+_catalog_cache: TTLCache[CacheKey, dict[str, Any]] = TTLCache(
+    maxsize=_CATALOG_MAXSIZE, ttl=_CATALOG_TTL
+)
+
+_catalog_lock: asyncio.Lock | None = None  # created lazily inside the event loop
+
+
+def _get_lock() -> asyncio.Lock:
+    """Return the module-level asyncio.Lock, creating it lazily on first call.
+
+    CRITICAL: Must NOT be called at module import time — asyncio.Lock() must be
+    created inside a running event loop (Python 3.10+ requirement; strict in 3.14).
+    """
+    global _catalog_lock
+    if _catalog_lock is None:
+        _catalog_lock = asyncio.Lock()
+    return _catalog_lock
+
+
+# ---------------------------------------------------------------------------
+# Schema hash computation
+# ---------------------------------------------------------------------------
+
+
+async def compute_schema_hash(client: OdooClient) -> str | None:
+    """Compute a per-target schema generation token from 3 write_date probes.
+
+    Runs 3 parallel search_read calls (ir.model, ir.model.fields,
+    ir.module.module) and joins the most-recent write_date values with "|".
+
+    Returns None on any RPC failure — callers must handle None gracefully.
+    """
+    try:
+        model_rows, field_rows, module_rows = await asyncio.gather(
+            client.search_read(
+                "ir.model",
+                [],
+                fields=["write_date"],
+                order="write_date desc",
+                limit=1,
+            ),
+            client.search_read(
+                "ir.model.fields",
+                [],
+                fields=["write_date"],
+                order="write_date desc",
+                limit=1,
+            ),
+            client.search_read(
+                "ir.module.module",
+                [["state", "=", "installed"]],
+                fields=["write_date"],
+                order="write_date desc",
+                limit=1,
+            ),
+        )
+        model_date = (model_rows[0]["write_date"] or "") if model_rows else ""
+        field_date = (field_rows[0]["write_date"] or "") if field_rows else ""
+        module_date = (module_rows[0]["write_date"] or "") if module_rows else ""
+        return f"{model_date}|{field_date}|{module_date}"
+    except Exception:  # noqa: BLE001
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Snapshot builder (internal)
+# ---------------------------------------------------------------------------
+
+
+async def _build_snapshot(client: OdooClient, schema_hash: str) -> dict[str, Any]:
+    """Build a catalog snapshot for the given schema_hash.
+
+    Lazy: only introspects the core model set on first request to a target.
+    Every other model is introspected on demand (D-10).
+    """
+    _CORE_MODELS = [
+        "mail.message",
+        "res.users",
+        "res.partner",
+        "ir.attachment",
+        "ir.ui.menu",
+    ]
+    model_rows: list[dict[str, Any]] = await client.search_read(
+        "ir.model",
+        [["model", "in", _CORE_MODELS]],
+        fields=["model", "name", "info"],
+    )
+    return {"schema_hash": schema_hash, "models": model_rows}
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+async def get_catalog_snapshot(
+    client: OdooClient, url: str, database: str
+) -> dict[str, Any]:
+    """Get or build a catalog snapshot for the given Odoo target.
+
+    The cache key is (url, database, schema_hash) — credentials are NEVER part
+    of the key (D-12: credential-free cache key; T-04-03-01 mitigation).
+
+    Returns a dict with keys: schema_hash, models, cached.
+    - cached=True  → returned from TTLCache (no Odoo RPC for the snapshot)
+    - cached=False → freshly built and stored in cache
+    """
+    schema_hash = await compute_schema_hash(client)
+    if schema_hash is None:
+        return {"schema_hash": None, "models": [], "cached": False}
+
+    key: CacheKey = (url, database, schema_hash)
+    async with _get_lock():
+        if key in _catalog_cache:
+            return {**_catalog_cache[key], "cached": True}
+        snapshot = await _build_snapshot(client, schema_hash)
+        _catalog_cache[key] = snapshot
+        return {**snapshot, "cached": False}
+
+
+def get_model_entry_from_cache(model_name: str) -> dict[str, Any] | None:
+    """Return the first cached model entry matching model_name, or None.
+
+    Scans all current cache entries without calling Odoo.
+    Returns None if the cache is cold or the model has not been introspected yet.
+
+    Intended for use by resources.py — no OdooClient, no await needed.
+    """
+    for snapshot in _catalog_cache.values():
+        models: list[dict[str, Any]] = snapshot.get("models", [])
+        for entry in models:
+            if entry.get("model") == model_name:
+                return entry
+    return None

godoo_mcp_server-0.1.0/src/godoo_mcp_server/credentials.py

@@ -0,0 +1,114 @@
+"""Odoo credential resolution and per-request ASGI middleware.
+
+Resolves X-Odoo-* request headers with ODOO_* env var fallback.
+Returns HTTP 401 with enumerated missing fields when any credential is absent.
+Injects resolved credentials into scope["state"]["odoo_creds"] for downstream tool handlers.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from starlette.responses import JSONResponse
+
+if TYPE_CHECKING:
+    from starlette.types import ASGIApp, Receive, Scope, Send
+
+
+@dataclass(repr=False)
+class OdooCredentials:
+    """Per-request resolved Odoo credentials.
+
+    repr=False prevents accidental password leakage in logs and tracebacks.
+    """
+
+    url: str
+    database: str
+    username: str
+    password: str
+
+    def __repr__(self) -> str:
+        return (
+            f"OdooCredentials(url={self.url!r}, database={self.database!r}, "
+            f"username={self.username!r}, password=***)"
+        )
+
+
+class CredentialMiddleware:
+    """Pure ASGI middleware: resolves Odoo credentials per-request.
+
+    Precedence: X-Odoo-* headers > ODOO_* env vars.
+    Returns HTTP 401 with enumerated missing fields if any credential is absent.
+    Stores OdooCredentials in scope["state"]["odoo_creds"] for tool handlers.
+
+    Uses pure ASGI (implements __call__ directly) to avoid contextvar propagation issues
+    that affect the MCP SDK's internal request context management.
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        self._app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] != "http":
+            # Pass lifespan and WebSocket events through unchanged
+            await self._app(scope, receive, send)
+            return
+
+        # /healthz is unauthenticated — bypass credential check.
+        # Also used as Docker HEALTHCHECK in Phase 5.
+        if scope.get("path") == "/healthz":
+            await self._app(scope, receive, send)
+            return
+
+        raw_headers: dict[bytes, bytes] = {
+            name.lower(): value for name, value in scope.get("headers", [])
+        }
+
+        def _header(name: str) -> str | None:
+            val = raw_headers.get(name.encode("latin-1"), b"").decode("latin-1")
+            return val or None
+
+        def _env(*names: str) -> str | None:
+            for name in names:
+                val = os.environ.get(name, "")
+                if val:
+                    return val
+            return None
+
+        url = _header("x-odoo-url") or _env("ODOO_URL")
+        database = _header("x-odoo-database") or _env("ODOO_DATABASE", "ODOO_DB")
+        username = _header("x-odoo-username") or _env("ODOO_USERNAME", "ODOO_USER")
+        password = _header("x-odoo-password") or _env("ODOO_PASSWORD")
+
+        missing: list[str] = []
+        if not url:
+            missing.append("X-Odoo-Url (or ODOO_URL)")
+        if not database:
+            missing.append("X-Odoo-Database (or ODOO_DATABASE / ODOO_DB)")
+        if not username:
+            missing.append("X-Odoo-Username (or ODOO_USERNAME / ODOO_USER)")
+        if not password:
+            missing.append("X-Odoo-Password (or ODOO_PASSWORD)")
+
+        if missing:
+            # SECURITY: enumerate missing field NAMES only — never echo supplied credential values
+            response = JSONResponse(
+                {"error": "missing_credentials", "missing": missing},
+                status_code=401,
+            )
+            await response(scope, receive, send)
+            return
+
+        # All four fields resolved — inject into scope["state"] (backs Request.state)
+        scope.setdefault("state", {})
+        # mypy: all values are non-None after the missing check above
+        assert url and database and username and password
+        scope["state"]["odoo_creds"] = OdooCredentials(
+            url=url,
+            database=database,
+            username=username,
+            password=password,
+        )
+        await self._app(scope, receive, send)