odoo-mcp-19: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

odoo-mcp-19 — Standalone MCP server for Odoo 19+ using the v2 JSON-2 API (POST /json/2/{model}/{method}, Bearer token auth, named args only). No v1 fallback.

• Version: 1.18.0 · Python: 3.10+ · MCP: 2025-11-25 (FastMCP >=3.4.6,<4; cryptography>=42 is a direct dependency of token_crypto, not just a transitive Authlib one; anyio>=4 is a direct dependency of the event-loop offload in server.py / resources.py)
• The <4 ceiling is deliberate. FastMCP 4.x targets MCP spec 2026-07-28 and is not a drop-in — see docs/mcp-2026-07-28-migration.md and tests/test_dependency_pins.py, which fails the build if the bound is widened or the environment drifts. uv.lock is gitignored (.gitignore: "project uses pip + pyproject.toml") — it pins only your local .venv, never the documented pip install git+… path, so pyproject.toml is the only thing between a fresh install and FastMCP 4.x. Do not relax the ceiling on the strength of the lockfile.
• Surface: 5 tools, 38 odoo:// resources, 19 prompts (12 generic + 7 cyanview-* workflow skill prompts)
• Discovery is via resources, action is via tools — there is no list_models tool, agents read odoo://models instead.
• Two deployment shapes: single-user (STDIO or HTTP with one static MCP_API_KEY) and multi-user HTTP (per-user cv_odoo_… keys from the CLORAG-managed registry, personal Odoo clients, per-user skill visibility — see "Multi-user mode" below).

Development commands

# Install (local workflow — uv-managed .venv; uv.lock is deliberately gitignored, the project ships via pip + pyproject.toml)
uv sync --extra dev
# then prefix commands with `uv run`, e.g.:
uv run pytest tests/test_safety.py
# pip equivalent: pip install -e ".[dev]"

# Install as a package (installs the `odoo-mcp-19` console entry point) — deliberately NOT on PyPI
pip install git+https://github.com/AlanOgic/odoo-mcp-19.git

# Run server — STDIO (default); loads .env from cwd
python -m odoo_mcp

# Run server — HTTP (requires MCP_API_KEY *or* USERS_DB_PATH, else sys.exit(1))
MCP_TRANSPORT=streamable-http MCP_API_KEY=<token> python -m odoo_mcp

# Interactive setup wizard — generates .env, Docker cmd, Claude Desktop config
python -m odoo_mcp --setup

# Tests — unit (no Odoo needed)
uv run pytest tests/ --ignore=tests/live
uv run pytest tests/test_safety.py::TestClassifyOperation::test_safe_methods_are_safe   # single test
# Note: bare `pytest tests/` collects NO live tests (they are __main__-guarded scripts with no test_* functions),
# but it does *import* them, and their module-level load_dotenv() pushes real .env credentials into os.environ
# for the whole session. Always --ignore=tests/live.

# Tests — live (requires .env with real Odoo creds; script-style runners)
python tests/live/test_safety_live.py
python tests/live/test_v1110_live.py
python tests/live/test_locked_mode_live.py

# Format + lint + typecheck
black . && isort .   # both clean; isort has skip_gitignore=true so it skips venvs like black does
ruff check .         # known baseline: 26 errors (20 E501, 6 E402) — see below
mypy src/odoo_mcp    # known baseline: 51 errors, mostly [index]/[assignment] in resources.py + server.py

# If `uv run pytest` reports ModuleNotFoundError: No module named 'odoo_mcp' (17 collection
# errors), the dev extras are not installed — run `uv sync --extra dev` first. uv also ignores a
# VIRTUAL_ENV pointing anywhere other than ./.venv (it warns and uses .venv regardless), so an
# activated sibling venv silently gives you a system pytest/ruff/mypy or none at all.

# Docker
docker build -t odoo-mcp-19 .
docker compose up -d           # uses .env, requires MCP_API_KEY
# Multi-user overlay (on the clorag host — registry mounted read-only)
docker compose -f docker-compose.yml -f docker-compose.multiuser.yml up -d