Skip to content

Contributing and license

Thank you for helping to improve MCP-Odoo-Tools.

New in v1.6.0

  • Each command on its surface: in the repository's guides, a /plugin command goes in a text block (it is typed inside Claude Code) and never in a terminal block, and claude plugin goes in the terminal. A test checks it (server/tests/test_install_surfaces.py).
  • CLAUDE.md lives in .claude/CLAUDE.md, so claude plugin validate --strict passes without a warning.

New in v1.5.1

  • Product rules: read docs/product-rules.md before a change that affects where the plugin installs, what it says on a surface where its tools cannot run, credentials or diagnostics.
  • This manual: every pull request says what changes here, or why nothing does.

New in v1.5.0

  • Scope: a generic, declarative permission policy is part of the public core.
  • New tools: each one must declare what it touches for the permission policy, with its internal calls and a test row (see Server below).

New in v1.4.1

The clean-room rule now also covers proprietary Odoo modules (Odoo Proprietary License, OPL-1) and any code whose license does not allow redistribution under MIT, and a test checks that no file in the repository declares a license that MIT cannot absorb.

Ground rules

  • License: contributions are accepted under the MIT license.
  • Clean-room: do not copy code from AGPL-licensed Odoo MCP projects, nor from proprietary ones: Odoo Apps modules under the Odoo Proprietary License (OPL-1), or any code whose license does not allow redistribution under MIT. Such projects may inform ideas, read from their public documentation; never their code, tests, prompts or tool descriptions. Interoperate with them only over the network. Rely only on Odoo's public XML-RPC/JSON-RPC/JSON-2 interfaces and on the public model/field names.
  • Product rules: read docs/product-rules.md before a change that affects where the plugin installs, what it says on a surface where its tools cannot run, credentials or diagnostics. The plugin installs on every surface Anthropic allows and is never blocked on one.
  • Scope: this repository is the public generic core. A generic, declarative permission policy is part of the public core; approval workflows, localization engines (CFDI and the like), backups and other client-specific engines are not, and live elsewhere.

Server (Python)

cd server
python3 -m venv .venv && . .venv/bin/activate
pip install -e ".[dev,cache]"
ruff check src tests
pytest -q -m "not live"
  • No runtime dependencies (dependencies = []): the plugin runs the source as-is with python3 and installs nothing, so a mandatory import of a third-party package would break its start. Optional capabilities must degrade gracefully, like the existing extras. The code must stay compatible with Python 3.9 (CI tests 3.9, 3.11, 3.12 and 3.13; ruff targets py39), and run_stdio.py must stay readable by older interpreters so it can show its version error. The dev extra includes the official mcp SDK (Python ≥ 3.10) only for an interoperability test; the server never imports it.
  • Tests marked live (-m live) run against a real Odoo sandbox and are optional.
  • tests/test_license_hygiene.py fails CI if a file in the repository, tracked or not, declares a license that MIT cannot absorb (for example an OPL-1 or (L/A)GPL license in an Odoo manifest, the OPL-1 or AGPL title in a file that is not Markdown, or an SPDX expression with such an id). Mentions in Markdown documentation stay allowed.
  • Changing a cross-version behavior? Edit src/odoo_mcp/compat/deltas.py (data) and add a row to tests/test_compat_resolve.py. The boundaries you cannot verify live are commented as "best-effort".
  • New tool? Register it in src/odoo_mcp/tools/ with the registry decorator and route the model/field names through compat before the ORM. Since v1.5.0 it must pass access= (what it touches, for the permission policy), declare its internal calls with predicates (registry.Internal(model, methods, check=..., reason=...), with one positive and one negative test) and add a GOLDEN row to tests/test_policy_mapping.py; the mapping and coverage tests explain what is missing when they fail. A write tool also states destructive=. Then refresh the tables of docs/policy.md with python3 scripts/policy_docs.py --write (CI checks them). See Tool mapping.

CLI (TypeScript)

cd cli && npm install && npm run build

Pull requests

  • Keep changes focused; include tests for the logic.
  • Say in the pull request what changes in the manual at docs.transgenia.org, or why nothing does (product rule 8). Transgenia's maintainers update the manual in Spanish, English and Chinese in the same release.
  • Update docs/compat-matrix.md when the delta map changes.
  • Note any new Odoo version/edition you have verified against.

License

MIT © Transgenia (Centrum Transgenia SAS). See LICENSE and NOTICE for the third-party attributions.

Attributions

  • odoo-agent (MIT): by Francisco Ramírez. The TypeScript XML-RPC CLI (cli/), the generic Odoo agent definition (agents/odoo.md, adapted), the domain-knowledge context and the SessionStart hook pattern (adapted) are reused.

Clean-room declaration

The Python MCP server (server/) is an original, independent implementation. It does not copy or adapt code from any AGPL-licensed Odoo MCP project (or its forks), nor from any proprietary Odoo module, including modules distributed under the Odoo Proprietary License (OPL-1) on Odoo Apps (which are not part of Odoo). Where it works with such a module, it does so only over the network, as a client. It relies solely on Odoo's publicly documented XML-RPC/JSON-RPC/JSON-2 interfaces and on the public model/field nomenclature, which are not subject to copyright. Any similarity in behavior reflects those public interfaces, not shared code.

Odoo trademark

"Odoo" is a registered trademark of Odoo S.A. This project is an independent, community-oriented tool, not affiliated with or endorsed by Odoo S.A.