odoo-assistant-mcp AGENTS.md

AGENTS.md — odoo-assistant-mcp

MCP server (stdio) that wraps 9 verified Odoo scripts as 19 tools + 8 resources. Shipped and complete; published on PyPI as version 0.1.1 and installable with uvx odoo-assistant.

Read before coding

• docs/PRD.md — the spec: tools (§5B), auth (§6), safety mapping (§7), packaging (§10). Written before the build, so it trails the code: it says 14 tools and two sections are marked superseded. Trust the code first.
• docs/mcp-spec/ — the ENTIRE MCP 2026-07-28 spec, vendored (144 files). Consult it instead of the web.
• docs/RELEASE-CHECKLIST.md — the only work left, and all of it needs a human: PyPI Trusted Publishing, then the tag.
• docs/json2-source/ — the Odoo module behind /json/2. odoo_client.py probes that transport first and falls back to XML-RPC, which Odoo 19 deprecates and 22 removes, so this is the reference for the path that becomes primary.
• references/BUILD-STATE.md — sanity figures for the dev instance

Commands

uv run pytest                       # 225 tests. addopts already excludes live+wheel
uv build && uv run pytest -m wheel  #   3 tests. needs dist/ AND network (uvx)
uv run pytest -m live               #   6 tests. needs the env vars below

Never write -m "not live". A -m on the command line replaces addopts instead of narrowing it, so that spelling silently re-enables the wheel tests and they fail on a clean checkout with no dist/. CI spells it in full: -m "not live and not wheel".

Protocol check: npx @modelcontextprotocol/inspector against the server.

Hard rules

• Never rewrite src/odoo_assistant/odoo_scripts/. Those 9 scripts are verified against a live instance and are the source of truth; the server is a thin wrapper importing them. They came from an agent skill that has been retired, so this repo is the canonical copy — scripts/sync-from-skill.sh has no upstream left and exits 1. Fix a bug there only with a live test proving it; otherwise adapt the wrapper.
• Scripts are flat modules: each does sys.path.insert(0, <own dir>) + from odoo_client import .... Keep that import style working when packaging.
• SDK: from mcp.server import MCPServer (SDK 2.0, pinned mcp[cli]>=2.0.0,<3). MCPServer(...) defaults version to "" — pass it explicitly or every host displays an empty version.
• Module decomposition: server.py stays thin. Tools and resources live in tools_read.py / tools_write.py / tools_collab.py / tools_discuss.py / tools_evolution.py / resources.py, each exposing register(mcp), wired by server._register_all(). Adding a tool means updating the three tests that assert the exact tool set. tools_collab.py notifies ABOUT a record (Inbox bell); tools_discuss.py is user-to-user conversation (chat systray) — "message X" is the second, and its channel_get is the one method the verified safety_layer.py was extended to admit (L1).
• explore_module.REF_DIR redirect needs the package-qualified import (from odoo_assistant.odoo_scripts import explore_module) so the patch is visible to every importer. See tools_evolution.py's docstring.
• Wheel bundles references_public/ only (scrubbed, generic). references/ holds the instance-specific set and is excluded.
• stdio transport: nothing may reach stdout but the JSON-RPC stream. Diagnostics go to stderr.
• Every write passes server_safety.gate() (L0–L5). L4/L5 refuse by default; ODOO_MCP_MAX_LEVEL moves the bar and refuses startup if invalid. Host consent dialogs are untrusted — the gate is the only enforcement point.