odoo-assistant 0.1.0__tar.gz

odoo_assistant-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+dist/
+__pycache__/
+*.pyc
+.pytest_cache/
+.omo/
+.codegraph
+.DS_Store
+/tmp-install/
+.env*
+*.local
+.vscode/
+# carries a real API key for local MCP testing
+.opencode/opencode.json

odoo_assistant-0.1.0/.gitleaks.toml

@@ -0,0 +1,6 @@
+[allowlist]
+description = "Allow documented example credentials in vendored documentation"
+paths = [
+  '''docs/json2-source/docs/SPA_AUTH_GUIDE\.md$''',
+  '''docs/mcp-spec/docs/2026-07-28/tutorials/security/authorization\.md$''',
+]

odoo_assistant-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,5 @@
+repos:
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.24.2
+    hooks:
+      - id: gitleaks

odoo_assistant-0.1.0/AGENTS.md

@@ -0,0 +1,81 @@
+# 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.0 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
+
+```bash
+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**.
+
+## Where guidance actually lands (measured)
+
+Two controlled runs of a fresh host session showed the `odoo://skill` resource
+being read **zero** times, and removing the equivalent global skill changed no
+answer. What routed behaviour both times was a **tool docstring** — it becomes
+the tool description, which every host puts in context unconditionally.
+
+So a rule an agent must follow belongs in the tool's docstring, not in a
+resource and not in a reference file. Structural guards in `safety_layer.py`
+are the only thing stronger, because they refuse instead of advise.
+
+## Odoo landmines (silent wrong results, not errors)
+
+Full list: `references/SKILL.md` (8 rules) + `references/writing.md` (12 patterns).
+
+- Odoo commits **before** serialising the response: an exception can mean "committed but unserializable" (`OdooExecutedButUnserializable`). **Never retry** — re-read. Blind retries once created duplicate invoices. Seen live: `crm.lead.action_set_lost` takes this path.
+- A returned dict carrying `res_model` is a wizard to follow, not a result.
+- `account.move` / `account.move.line` without `move_type` mixes invoices, bills and journal entries (3.613 vs 373). `check_guards()` blocks it structurally.
+- Sum `*_signed` fields, never `amount_total` (multi-currency once inflated a total 11,9×).
+- Multi-company: pass `context={"allowed_company_ids": [...]}` or you report one company as the whole business.
+- **`default_get` is where records go missing.** `crm.lead.type` defaults to `'lead'` on an instance whose pipeline is opportunities; `account.move.move_type` defaults to `'entry'`, so a "new invoice" is a raw journal entry. The `required_fields` tool exists to surface this — call it before a create.
+- **Archiving reads like deletion.** `action_set_lost` sets `active=False`; a later plain search returns `[]`. Add `["active", "in", [true, false]]` before concluding a record is gone.
+- **`phone_sanitized` is one value per record**, computed from `mobile` first and `phone` second — not per field. It stays `False`, with no error, when the number has no `+` prefix and the record no `country_id`. Write E.164 yourself.
+- Wrong `ODOO_USER` makes `authenticate()` return `False` rather than raise — it reads like a permission error. Omitting it entirely is supported and takes the discovery path (up to 59 probes, fails at uid >= 60).
+- `create()` returns a list, not an int. Methods starting with `_` are always rejected.
+- Idempotency: `Writer.create(..., unique_on=[...])`, chains via `Writer.step()`. A write is done only when a re-read proves it.
+
+## Live and local testing
+
+- Env: required are `ODOO_BASE_URL` (no trailing slash) and `ODOO_API_KEY` only. `ODOO_DB` is discovered (mandatory only when the instance serves several — the error names them), `ODOO_USER` is discovered from the key. **API key only** — passwords were removed deliberately.
+- Write scenarios need `ODOO_MCP_ALLOW_LIVE_WRITE=1`; that variable is test-suite-only and must never appear in host config.
+- Dev instance `persevida_dev18` (Odoo 18 Enterprise, companies ES+CZ, XML-RPC, destructive tests allowed). `odoo_client.py` refuses writes to hosts listed in `ODOO_MCP_PROTECTED_HOSTS` (env, empty by default — no host is hardcoded).
+- Cleanup archives rather than deletes — `Writer.can()` refuses partner unlink — so `MCP Test %` residue on the dev instance is expected.
+- Local host config lives in `.opencode/opencode.json`, **gitignored because it holds a real API key**. It runs the server from source (`uv run --directory <repo> odoo-assistant`) for development convenience, and raises `timeout` from opencode's 5000 ms default, which `instance_overview` exceeds.
+- Smoke-test a script directly: `python3 src/odoo_assistant/odoo_scripts/query.py --url http://host:8069 --key <API_KEY>`
+
+## references/
+
+Generated by `explore_module.py`, never hand-written. Everything above
+`## NOTES` is rebuilt on each run — hand-edit only the `## NOTES` section.
+Served as MCP resources (`odoo://skill`, `odoo://ref/*`).

odoo_assistant-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-08-18
+
+This is the first published release of the Odoo Assistant MCP Server.
+
+### Added
+- **MCP Server Core**: Implemented `MCPServer` skeleton with environment credentials validation and stderr logging.
+- **Safety Layer**: Dynamic classification gate (L0 to L5) with configurable `ODOO_MCP_MAX_LEVEL` ceiling.
+- **Error Handling**: Custom error models, `OdooExecutedButUnserializable` handling, and output truncation strategy.
+- **Read Tools**: Implemented `search_read`, `read_record`, `count_records`, and `instance_overview` with company context and caps.
+- **Write Tools**: Implemented `create_record`, `write_record`, `run_action`, and `cancel_record` with idempotency and verification.
+- **Collaboration & Document Tools**: Implemented `notify_user`, `create_activity`, `download_docs`, and `generate_pdf` with audience guards.
+- **Discuss Tools**: Implemented `list_message_targets`, `read_conversation`, `send_direct_message`, and `send_channel_message` to support user-to-user messaging.
+- **Evolution Tools**: Implemented `explore_module` with persistence redirect and `list_known_modules`.
+- **Resources**: Exposed `odoo://skill` and `odoo://ref/*` from the bundled reference set.
+- **Testing**: Added mock-based unit tests, scripted MCP Inspector suite, and opt-in live integration suite with cancel-based cleanup.
+- **CI/CD**: Configured tag-triggered sequential PyPI and MCP Registry publishing pipeline using GitHub OIDC.
+- **Documentation**: Added PyPI README, host configuration examples, security policy, and developer guidelines.
+- **Credentials**: Only `ODOO_BASE_URL` and `ODOO_API_KEY` are required; the database and the login are discovered from the key.
+- **Paths**: A single per-OS data directory for caching and persistence, with `ODOO_MCP_DATA_DIR` to override it.
+- **Notifications**: `notify_user` offers three subtypes — `note` (internal, visible in the chatter), `inbox` (notification only, invisible on the record) and `comment` (emails every follower).

odoo_assistant-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to Odoo Assistant MCP Server
+
+Thank you for contributing to the Odoo Assistant MCP Server. Please follow these guidelines to set up your development environment, run tests, and submit changes.
+
+## Development Environment Setup
+
+This project uses `uv` for Python package management.
+
+1. **Install uv**:
+   Follow the instructions at [astral.sh/setup-uv](https://astral.sh/setup-uv) to install `uv`.
+
+2. **Clone the repository**:
+   ```bash
+   git clone https://github.com/singleflo/odoo-assistant-mcp.git
+   cd odoo-assistant-mcp
+   ```
+
+3. **Sync dependencies**:
+   ```bash
+   uv sync
+   ```
+
+## Hard Rules for Code Changes
+
+* **Treat `src/odoo_assistant/odoo_scripts/` as verified code, not as your working surface.** These 9 scripts are verified against a live Odoo instance and are the source of truth; the MCP server is a thin wrapper importing them. They came from an agent skill that has since been retired, so this repository is now the canonical copy — there is no upstream to sync from. Fix a bug here only with a live-instance test proving it, and never refactor them to suit the wrapper: adapt the wrapper instead.
+* **Keep server.py thin.** Tools and resources must live in their respective modules (`tools_read.py`, `tools_write.py`, `tools_collab.py`, `tools_evolution.py`, `resources.py`) and expose a `register(mcp)` function.
+* **No stdout printing.** The stdio transport uses stdout for JSON-RPC communication. Any diagnostic prints must go to stderr.
+
+## Running Tests
+
+We use `pytest` for testing.
+
+### Non-Live Tests (Default)
+To run the unit tests and mock-based integration tests:
+```bash
+uv run pytest tests/ -m "not live"
+```
+
+### Live Tests
+To run tests against a live Odoo instance, you must opt-in by providing the connection details and setting the appropriate environment variables:
+
+1. **Read-only live tests**:
+   ```bash
+   export ODOO_BASE_URL="https://your-odoo-instance.com"
+   export ODOO_API_KEY="your-api-key"
+   export ODOO_DB="your-db"
+    export ODOO_USER="your-user" # Optional: omitted, the login is discovered from the key
+   uv run pytest tests/
+   ```
+
+2. **Write live tests**:
+   By default, live tests that perform write operations are skipped to prevent accidental modifications to your instance. To enable them, set `ODOO_MCP_ALLOW_LIVE_WRITE=1`:
+   ```bash
+   export ODOO_MCP_ALLOW_LIVE_WRITE=1
+   uv run pytest tests/
+   ```
+
+## Commit Conventions
+
+We follow standard git commit message conventions. Please write concise, descriptive commit messages matching the repository style. Stage only intended files and never commit secrets.

odoo_assistant-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roberto Crotti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

odoo_assistant-0.1.0/PKG-INFO

@@ -0,0 +1,304 @@
+Metadata-Version: 2.5
+Name: odoo-assistant
+Version: 0.1.0
+Summary: An Odoo virtual employee via MCP: query, create, modify records, run workflows
+Project-URL: Homepage, https://github.com/singleflo/odoo-assistant-mcp
+Project-URL: Repository, https://github.com/singleflo/odoo-assistant-mcp
+Project-URL: Issues, https://github.com/singleflo/odoo-assistant-mcp/issues
+Project-URL: MCPRegistry, https://registry.modelcontextprotocol.io/servers/io.github.singleflo/odoo-assistant
+Author-email: Roberto Crotti <bo@fl1.cz>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,claude,erp,mcp,model-context-protocol,odoo
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]<3,>=2.0.0
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.singleflo/odoo-assistant -->
+# Odoo Assistant MCP Server
+
+An Odoo virtual employee via the Model Context Protocol (MCP). This server exposes Odoo's business logic, records, and workflows to LLMs, allowing them to query, create, update, and act on Odoo data safely.
+
+## Quickstart
+
+### 1. Install
+
+Run the server directly:
+
+```bash
+uvx odoo-assistant
+```
+
+Or install it into your environment:
+
+```bash
+uv pip install odoo-assistant
+```
+
+Installing from source for development remains possible:
+
+```bash
+uv pip install git+https://github.com/singleflo/odoo-assistant-mcp
+```
+
+### 2. Configure Environment Variables
+Two variables are required; everything else is discovered or has a default:
+
+* `ODOO_BASE_URL`: The base URL of your Odoo instance (e.g., `https://mycompany.odoo.com`).
+* `ODOO_API_KEY`: The Odoo API key (Odoo 14+, generate under Settings > Users > API Keys > New). An account password is not accepted: a key is per-user, scoped and revocable on its own.
+
+Optional configuration:
+* `ODOO_DB`: The database name. Discovered automatically when the instance serves exactly one database; required when it serves several — the error names them all.
+* `ODOO_USER`: The login. Discovered from the key at the cost of up to 59 extra round trips; discovery fails if the key owner's uid is 60 or higher. Setting it saves the probe.
+* `ODOO_MCP_MAX_LEVEL`: The highest safety level this server may execute, `0` to `4` (default: `3`). This is how you make the server read-only or let it delete — see [Choosing the ceiling](#choosing-the-ceiling).
+* `ODOO_MCP_PROTECTED_HOSTS`: Comma-separated hosts this server refuses to *write* to (empty by default — no host is baked into the package). A listed host still allows reads; writing needs `ODOO_ALLOW_PROD_WRITE=yes` as a deliberate override.
+
+## Safety Layer
+
+Every write and action passes through a dynamic safety classifier before reaching Odoo. Operations are classified into levels L0 to L5:
+
+| Level | Name | Description | Default Status |
+|---|---|---|---|
+| **L0** | `L0_READ` | Read-only queries (`search_read`, `read`, `search_count`). | Allowed |
+| **L1** | `L1_WRITE` | Single record writes and creations. | Allowed |
+| **L2** | `L2_BATCH` | Batch writes affecting multiple records. | Allowed |
+| **L3** | `L3_STATE_CHANGE` | Workflow state transitions (e.g., confirming orders, posting invoices). | Allowed |
+| **L4** | `L4_DESTRUCTIVE` | Destructive operations (e.g., `unlink`, `action_cancel`, archiving). | Blocked |
+| **L5** | `L5_PRIVATE` / `L5_UNKNOWN` | Private methods or unknown operations. | Blocked |
+
+### Choosing the ceiling
+
+`ODOO_MCP_MAX_LEVEL` sets the highest level this server may execute. Each value
+is cumulative — it permits its own level and everything below:
+
+| Value | What it permits |
+|---|---|
+| `0` | Reads only. |
+| `1` | + single-record writes and creations. |
+| `2` | + batches above 5 records. |
+| `3` | **Default.** + confirming orders, posting invoices, sending mail. |
+| `4` | + `unlink`, `action_cancel`, archiving. |
+| `5` | Accepted, but identical to `4` in effect — see below. |
+
+Two behaviours are worth knowing before you pick a number:
+
+* **`5` does not unlock L5.** Both L5 variants are refused before the ceiling is
+  ever read. `L5_PRIVATE` is refused because Odoo itself rejects every method
+  starting with `_`, so no ceiling could deliver it; `L5_UNKNOWN` is refused
+  because a method nobody classified has, by definition, unreviewed effects. The
+  way to allow such a method is to add it to `WRITE_L1`/`L3`/`L4` in
+  `safety_layer.py` — in code, reviewed — never through configuration.
+* **An invalid value refuses startup.** `ODOO_MCP_MAX_LEVEL="O"` raises rather
+  than falling back to the default, because the fallback is write-capable: a
+  typo must not hand you a writing server you believed was read-only.
+
+The ceiling is set out of band, by a human, and read from the process
+environment at startup. The model running against this server cannot raise it;
+when a call exceeds the ceiling the refusal names the level required, so the
+agent can explain what the operation would change and leave the decision to you.
+
+Note that this is the authority of *this server*, not of the account. An agent
+with shell access can always bypass an MCP server by invoking Odoo directly. A
+limit that must hold regardless of the client belongs in the Odoo access rights
+of the user the API key belongs to, where the Odoo server enforces it.
+
+## Odoo Version Support
+
+Odoo 14.0 is the absolute minimum supported version because this server authenticates using API keys only, which do not exist in Odoo 13 or earlier.
+
+| Odoo Version | API Keys | XML-RPC | Officially Maintained (Aug 2026) | Support Level / Notes |
+|---|---|---|---|---|
+| **≤ 13.0** | **No** | Yes | No | **Unsupported**. Cannot authenticate with this server. |
+| **14.0** | **Yes** | Yes | No | Protocol-compatible. Untested against a live instance. |
+| **15.0** | Yes | Yes | No | Protocol-compatible. Untested against a live instance. |
+| **16.0** | Yes | Yes | No | Protocol-compatible. Untested against a live instance. |
+| **17.0** | Yes | Yes | **Yes** (until Sep 2026) | Protocol-compatible. Untested against a live instance. |
+| **18.0** | Yes | Yes | **Yes** (until Sep 2027) | **Primary target**. Verified and fully supported against a live instance. |
+| **19.0** | Yes | Yes | **Yes** (until Sep 2028) | Protocol-compatible. Untested against a live instance. API keys require description and expiry (max 3 months). |
+
+### API Key Generation Path
+To generate an API key, log in to your Odoo instance and navigate to:
+**Preferences / My Profile → Account Security → New API Key**
+
+### Transport & Deprecation Note
+The client automatically detects if the native JSON-2 API is available at `/json/2/<model>/<method>` (which uses `Authorization: bearer <API_KEY>`) and falls back to XML-RPC if it is not. Please note that XML-RPC and JSON-RPC are deprecated in Odoo 19 and scheduled for removal in Odoo 22.
+
+### Sources
+- [Odoo 14.0 External API Documentation](https://www.odoo.com/documentation/14.0/developer/reference/external_api.html) (API keys introduction)
+- [Odoo 19.0 External API Documentation](https://www.odoo.com/documentation/19.0/developer/reference/external_api.html) (JSON-2)
+- [Odoo 19.0 External RPC API Documentation](https://www.odoo.com/documentation/19.0/developer/reference/external_rpc_api.html) (XML-RPC deprecation)
+- [Odoo Standard & Extended Support Policy](https://www.odoo.com/documentation/19.0/administration/standard_extended_support.html) (Support timelines)
+
+## Tools and Resources
+
+The server exposes 19 tools and 2 resource types:
+
+### Tools
+
+1. `search_read`: Search and read records in one call (Odoo `search_read`).
+2. `read_record`: Read one record by id, always with named fields.
+3. `count_records`: Count the records matching a domain (Odoo `search_count`).
+4. `instance_overview`: Summarise the connected instance: version, companies, volumes per area, in-house modules, anomalies.
+5. `required_fields`: List what Odoo demands before a `create` on a model, the default it would apply, and how existing records actually use it.
+6. `create_record`: Create a record, reusing an existing match when `unique_on` is given.
+7. `write_record`: Write field values to one record and report what actually changed.
+8. `run_action`: Run a workflow method and report the state it left behind.
+9. `cancel_record`: Cancel a record through `action_cancel`, following the wizard it returns.
+10. `notify_user`: Notify users on a record's chatter. Internal by default.
+11. `create_activity`: Schedule an activity: the only notification that carries a deadline.
+12. `download_docs`: Save every document of a record to disk, chatter files included.
+13. `generate_pdf`: Render the PDF of a record and return where it was saved.
+14. `list_message_targets`: List who can be messaged and where — internal users with presence (online/away/offline) and the caller's open conversations. Ask this before sending.
+15. `read_conversation`: Read a Discuss conversation, newest first.
+16. `send_direct_message`: Send a 1-to-1 Discuss message that appears in the user's chat systray in real time — no email, reaches them whatever their notification setting says.
+17. `send_channel_message`: Post to an existing Discuss channel, refusing a room that holds a non-employee.
+18. `explore_module`: Discover a module's structure by interrogating the live instance.
+19. `list_known_modules`: List the modules this server has learned: name, generation date, records.
+
+Tools 10-11 (`notify_user`, `create_activity`) notify ABOUT a record and land
+in the Inbox bell; tools 14-17 are Discuss conversations that land in the chat
+systray. "Message user X" is the second kind — `send_direct_message`, not
+`notify_user`.
+
+### Resources
+
+* `odoo://skill`: Access the Odoo assistant skill instructions.
+* `odoo://ref/*`: Access generated reference documentation for explored modules.
+
+## Host Configuration Examples
+
+Every example below carries only what matters: the two required variables, and
+the ceiling — the one setting that decides whether this server can write, made
+visible in the file the human owns. The database and the login are discovered,
+and `3` is the ceiling's default. Note the **quotes**: environment values are
+strings.
+
+### Claude Desktop
+Add this to your `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "odoo-assistant": {
+      "command": "uvx",
+      "args": [
+        "odoo-assistant"
+      ],
+      "env": {
+        "ODOO_BASE_URL": "https://mycompany.odoo.com",
+        "ODOO_API_KEY": "your-api-key-here",
+        "ODOO_MCP_MAX_LEVEL": "3"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+Add this to your `.cursor/mcp.json` or configure it in the Cursor settings UI:
+```json
+{
+  "mcpServers": {
+    "odoo-assistant": {
+      "command": "uvx",
+      "args": [
+        "odoo-assistant"
+      ],
+      "env": {
+        "ODOO_BASE_URL": "https://mycompany.odoo.com",
+        "ODOO_API_KEY": "your-api-key-here",
+        "ODOO_MCP_MAX_LEVEL": "3"
+      }
+    }
+  }
+}
+```
+
+### VS Code Copilot
+Add this to your VS Code `settings.json`:
+```json
+{
+  "mcp.servers": {
+    "odoo-assistant": {
+      "command": "uvx",
+      "args": [
+        "odoo-assistant"
+      ],
+      "env": {
+        "ODOO_BASE_URL": "https://mycompany.odoo.com",
+        "ODOO_API_KEY": "your-api-key-here",
+        "ODOO_MCP_MAX_LEVEL": "3"
+      }
+    }
+  }
+}
+```
+
+### opencode
+Add this to `opencode.json` or `.opencode/opencode.json` in your project, or to
+`~/.config/opencode/opencode.json` to make the server available everywhere:
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "odoo-assistant": {
+      "type": "local",
+      "enabled": true,
+      "command": [
+        "uvx",
+        "odoo-assistant"
+      ],
+      "timeout": 120000,
+      "environment": {
+        "ODOO_BASE_URL": "https://mycompany.odoo.com",
+        "ODOO_API_KEY": "your-api-key-here",
+        "ODOO_MCP_MAX_LEVEL": "3"
+      }
+    }
+  }
+}
+```
+
+opencode's shape differs from the hosts above in ways it rejects outright: the
+key is `mcp` (not `mcpServers`), `type` is required, `command` is a single array
+holding the program *and* its arguments (there is no separate `args`), and the
+environment block is `environment` (not `env`).
+
+Set `timeout` deliberately. It defaults to **5000 ms**, and the first call of a
+session pays for authentication plus, for `instance_overview`, dozens of XML-RPC
+round trips — comfortably past five seconds against a real instance.
+
+opencode reads its config once at startup and does not hot-reload it, so **quit
+and restart** after editing. Anything you change here — the ceiling included —
+takes effect only on the next launch.
+
+### ChatGPT (Custom Connectors)
+To connect this server to ChatGPT via Custom Connectors:
+1. Go to Settings → Connectors → Add Connector.
+2. Enter the server URL or select from the Registry.
+3. Enter your Odoo credentials when prompted.
+
+### Hermes
+Add the server using the Hermes CLI:
+```bash
+hermes mcp add odoo-assistant \
+  --env ODOO_BASE_URL=https://mycompany.odoo.com \
+  --env ODOO_API_KEY=your-api-key-here \
+  --env ODOO_MCP_MAX_LEVEL=3 \
+  --args run odoo-assistant
+```
+
+The examples omit the optional variables. Set `ODOO_DB` when the instance serves several databases, `ODOO_USER` to skip the uid probe, and `ODOO_MCP_MAX_LEVEL` to change the ceiling from its default of `3`.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+