<div align="center">

# 🔌 odoo-mcp

**Pilotez n'importe quelle base Odoo en langage naturel — sans jamais perdre le contrôle.**

Un serveur [MCP](https://modelcontextprotocol.io) qui connecte votre assistant IA
(Claude Code, Antigravity, Gemini CLI, Claude Desktop, Cursor…) à Odoo via XML-RPC.
Lecture instantanée, écriture gardée, import/export Excel, journal d'audit et
rapports présentables au client — le tout depuis une simple conversation.

<br/>

![Version](https://img.shields.io/badge/version-1.10.0-1f6feb?style=flat-square)
![Python](https://img.shields.io/badge/python-3.10+-3776AB?style=flat-square&logo=python&logoColor=white)
![MCP](https://img.shields.io/badge/MCP-compatible-8A2BE2?style=flat-square)
![Outils](https://img.shields.io/badge/outils-37-fb8500?style=flat-square)
![Licence](https://img.shields.io/badge/licence-MIT-2ea043?style=flat-square)

</div>

---

> **En une phrase.** On parle à sa base Odoo comme à un collègue — *« combien de commandes
> en cours ce mois-ci ? »*, *« importe ce catalogue de 1 500 articles »*, *« prépare une
> maquette pour ce prospect »* — et l'outil traduit, exécute, et **rend des comptes** :
> rien ne s'écrit sans garde-fou, et tout ce qui s'écrit est tracé.

## 📑 Sommaire

- [✨ Pourquoi odoo-mcp](#-pourquoi-odoo-mcp)
- [🏗️ Architecture](#-architecture)
- [🔒 Le modèle de sécurité](#-le-modèle-de-sécurité)
- [🚀 Installation](#-installation)
- [💬 Utilisation](#-utilisation)
- [🧰 Les 37 outils](#-les-37-outils)
- [📋 Le rapport d'intervention](#-le-rapport-dintervention)
- [🎬 Le guide de présentation](#-le-guide-de-présentation)
- [📥 Importer un fichier](#-importer-un-fichier)
- [🎭 Préparer une démonstration](#-préparer-une-démonstration)
- [📊 Générer un tableau de bord](#-générer-un-tableau-de-bord)
- [⚡ Économie de contexte](#-économie-de-contexte)
- [🧭 Notes de terrain](#-notes-de-terrain)
- [📄 Licence](#-licence)

## ✨ Pourquoi odoo-mcp

Ce n'est pas un connecteur « boîte noire » de plus. Chaque décision de conception vise le
même objectif : donner de la puissance à l'assistant **sans lui donner les pleins pouvoirs**.

| | |
|---|---|
| 🔐 **Aucun identifiant stocké** | L'assistant demande l'URL, le login et la clé API dans la conversation (`odoo_connect`). Ils ne vivent qu'en mémoire, le temps de la session. |
| 🚫 **Écriture bloquée par défaut** | Elle s'active par un outil dédié (`odoo_enable_write`), que l'assistant n'appelle qu'après accord explicite. Sinon, seules les méthodes de **lecture** sont autorisées (liste blanche) — y compris via l'appel brut `odoo_execute`. |
| 👁️ **Modifications de masse prévisualisées** | `odoo_update_where` montre d'abord combien d'enregistrements sont visés, avec un échantillon avant/après, et n'écrit qu'après confirmation. |
| 📊 **Import/export Excel natif** | Le serveur tourne en local : il lit et écrit les fichiers directement. Un catalogue de 1 500 lignes s'importe sans passer par la conversation. |
| ♻️ **Écritures rejouables** | `odoo_upsert` et l'import par External ID mettent à jour au lieu de dupliquer. |
| 🧾 **Tout est tracé** | Chaque écriture est journalisée avec son état avant/après ; `odoo_journal_report` produit un rapport d'intervention présentable au client. Secrets masqués, binaires résumés, journal lisible par le seul utilisateur (`0600`). |
| 📈 **Tableaux de bord réels** | `odoo_dashboard_create` produit de vrais tableaux de bord Odoo dont les graphiques sont recalculés en direct — pas des captures d'écran. |
| 🎭 **Maquettes de démo sûres** | Un questionnaire de qualification cadre l'avant-vente, et le mode démonstration neutralise **toute** adresse e-mail écrite : aucune fausse facture ne peut partir chez une vraie entreprise. |

## 🏗️ Architecture

Un seul processus local fait le pont entre l'assistant et Odoo. Rien n'est hébergé ailleurs,
aucune donnée ne transite par un tiers.

```mermaid
flowchart LR
    A["🤖 Assistant IA<br/>Claude · Gemini · Cursor…"]
    B["🔌 odoo-mcp<br/>serveur local"]
    C[("🗄️ Base Odoo")]
    D["📁 Fichiers locaux<br/>Excel · rapports · cache"]

    A -->|"protocole MCP"| B
    B -->|"XML-RPC"| C
    B -->|"lit / écrit"| D

    classDef ai fill:#eef2ff,stroke:#6366f1,color:#1e1b4b;
    classDef srv fill:#ecfeff,stroke:#06b6d4,color:#083344;
    classDef odoo fill:#f3e8ff,stroke:#a855f7,color:#3b0764;
    classDef file fill:#fff7ed,stroke:#f97316,color:#431407;
    class A ai; class B srv; class C odoo; class D file;
```

## 🔒 Le modèle de sécurité

Le serveur est le **point de passage obligé** de toute opération. C'est là que sont posés
les garde-fous — donc ils tiennent quel que soit l'outil appelé (création, modification,
upsert, import de fichier, ou appel brut `odoo_execute`).

```mermaid
flowchart TD
    Q["Appel d'un outil d'écriture"] --> R{"Écriture activée ?"}
    R -->|Non| RO["⛔ Refusé<br/>lecture seule (liste blanche)"]
    R -->|Oui| M{"Modification de masse ?"}
    M -->|Oui| P["🔎 Prévisualisation<br/>volume + échantillon avant/après"] --> CF{"Confirmé ?"}
    CF -->|Non| STOP["🚫 Annulé — rien n'est écrit"]
    CF -->|Oui| EX["✍️ Écriture"]
    M -->|Non| EX
    EX --> J[("📓 Journal 0600<br/>secrets masqués · avant→après")]

    classDef gate fill:#fef2f2,stroke:#ef4444,color:#450a0a;
    classDef ok fill:#f0fdf4,stroke:#22c55e,color:#052e16;
    classDef log fill:#f8fafc,stroke:#64748b,color:#0f172a;
    class R,M,CF gate; class EX,P ok; class J log;
```

## 🚀 Installation

> **Prérequis :** [uv](https://docs.astral.sh/uv/getting-started/installation/) —
> `winget install astral-sh.uv` (Windows) · `brew install uv` (macOS) ·
> `curl -LsSf https://astral.sh/uv/install.sh | sh` (Linux).

### En un clic

[![Installer dans Cursor](https://img.shields.io/badge/Cursor-Installer%20en%201%20clic-0098FF?style=for-the-badge&logo=cursor)](cursor://anysphere.cursor-deeplink/mcp/install?name=odoo&config=eyJjb21tYW5kIjogInV2eCIsICJhcmdzIjogWyItLXJlZnJlc2giLCAiLS1mcm9tIiwgImdpdCtodHRwczovL2dpdGh1Yi5jb20vSmFtaVRoZVMvb2Rvby1tY3AiLCAib2Rvby1tY3AiXX0=)
[![Installer dans VS Code](https://img.shields.io/badge/VS%20Code-Installer%20en%201%20clic-007ACC?style=for-the-badge&logo=visualstudiocode)](https://vscode.dev/redirect/mcp/install?name=odoo&config=%7B%22name%22%3A%20%22odoo%22%2C%20%22command%22%3A%20%22uvx%22%2C%20%22args%22%3A%20%5B%22--refresh%22%2C%20%22--from%22%2C%20%22git%2Bhttps%3A//github.com/JamiTheS/odoo-mcp%22%2C%20%22odoo-mcp%22%5D%7D)

Clique le bouton de ton IDE → il ouvre l'éditeur et propose d'ajouter le serveur `odoo`.
Accepte, c'est installé. *(Le bouton Cursor n'ouvre l'IDE que si Cursor est installé.)*

### Par prompt — Claude Code · Gemini · Antigravity

Pas de bouton pour ces clients ? **Copie-colle ce prompt dans le chat de ton assistant** :
il installe le serveur lui-même.

```text
Installe le serveur MCP « odoo » pour moi, puis confirme.

Il se lance avec la commande `uvx` et les arguments :
--refresh --from git+https://github.com/JamiTheS/odoo-mcp odoo-mcp

Procède selon l'outil dans lequel tu tournes :
- Claude Code : exécute
  claude mcp add --scope user odoo -- uvx --refresh --from git+https://github.com/JamiTheS/odoo-mcp odoo-mcp
- Gemini CLI : ajoute une entrée « odoo » sous « mcpServers » dans ~/.gemini/settings.json
- Antigravity ou autre client : ajoute la même entrée « mcpServers.odoo » dans son fichier
  de config MCP.

L'entrée JSON à utiliser (sauf pour la commande Claude Code) :
  "odoo": {
    "command": "uvx",
    "args": ["--refresh", "--from", "git+https://github.com/JamiTheS/odoo-mcp", "odoo-mcp"]
  }

Ne mets aucune clé API ni URL Odoo en dur. Quand c'est fait, dis-moi de redémarrer le
client pour que le serveur « odoo » soit chargé.
```

### En manuel

<details>
<summary><b>Claude Code</b> — une seule commande</summary>

```bash
claude mcp add --scope user odoo -- uvx --refresh --from git+https://github.com/JamiTheS/odoo-mcp odoo-mcp
```
</details>

<details>
<summary><b>Antigravity / Gemini CLI</b> — bloc JSON à coller</summary>

Antigravity : panneau **MCP Servers** → *Manage MCP config*. Gemini CLI : `~/.gemini/settings.json`.

```json
{
  "mcpServers": {
    "odoo": {
      "command": "uvx",
      "args": ["--refresh", "--from", "git+https://github.com/JamiTheS/odoo-mcp", "odoo-mcp"]
    }
  }
}
```
</details>

<details>
<summary><b>Claude Desktop</b></summary>

Paramètres → Développeur → `claude_desktop_config.json` : même bloc JSON que ci-dessus.
</details>

C'est tout : `uvx` télécharge, installe et lance le serveur tout seul au premier démarrage.

> [!IMPORTANT]
> **🔄 Mises à jour automatiques.** Le `--refresh` présent dans toutes les configs est la
> clé : à **chaque démarrage du client**, `uvx` revérifie la dernière version publiée sur
> GitHub et la récupère si du nouveau code a été poussé. Autrement dit, dès qu'un `git push`
> est fait, les utilisateurs sont à jour **au prochain lancement de leur IDE** — sans rien
> réinstaller.
>
> *Contrepartie :* quelques secondes de plus au démarrage et une connexion réseau requise à
> ce moment-là. Pour figer une version, retirer `--refresh` des `args` : la mise à jour
> redevient manuelle.

## 💬 Utilisation

### Au démarrage : deux modes

À l'ouverture d'une session, le serveur se présente (via le champ `instructions` du protocole
MCP) et l'assistant propose de choisir un mode de travail :

- **🧭 Consultant** — intervention sur une base **réelle**. L'assistant ouvre un journal
  d'audit avant d'écrire, garde l'écriture bloquée jusqu'à ton accord, et propose un rapport
  d'intervention en fin de travail.
- **🎭 Avant-vente (Sales)** — construire une **maquette de démonstration**. L'assistant part
  du questionnaire de qualification, active le filet e-mail (`odoo_demo_mode`), puis peuple la
  base avec `odoo_demo_generate`.

> [!NOTE]
> La présentation dépend du client MCP : la plupart injectent ces `instructions` dans le
> contexte de l'assistant, qui t'accueille alors dès ton premier message. L'assistant ne
> choisit pas le mode à ta place — il te pose la question.

### Connexion

Au premier échange, l'assistant demande trois informations :

1. **URL de la base** — ex. `https://acme.odoo.com`
2. **Login** — l'e-mail de connexion
3. **Clé API** — dans Odoo : avatar → *Mon profil* → *Sécurité du compte* → *Nouvelle clé
   API*, en **laissant le champ « Scope » vide** (une clé de scope « MCP » est refusée en
   XML-RPC)

Puis on parle à sa base en langage naturel : *« combien de commandes en cours ? »*,
*« montre les champs de res.partner »*, *« corrige le téléphone de ce contact »*.

### Une session type

Un exemple de bout en bout : importer un catalogue puis préparer une démo. Remarquez
l'étape où l'assistant **s'arrête pour demander l'autorisation** avant la moindre écriture.

```mermaid
sequenceDiagram
    autonumber
    actor U as Vous
    participant A as Assistant IA
    participant M as odoo-mcp
    participant O as Odoo
    U->>A: « importe ce catalogue et prépare une démo »
    A->>M: odoo_connect (URL · login · clé)
    M->>O: authentification XML-RPC
    A->>M: odoo_import_file (mode check)
    M->>O: validation champ par champ
    M-->>A: 0 erreur — prêt à écrire
    A->>U: « je peux activer l'écriture ? »
    U->>A: oui, vas-y
    A->>M: odoo_enable_write + import (mode run)
    M->>O: écriture par lots + journalisation
    M-->>A: 40 articles créés
    A->>U: rapport d'intervention HTML
```

<details>
<summary><b>Base fixe (optionnel)</b></summary>

Pour se connecter automatiquement à une base donnée, ajouter à la déclaration du serveur
(la clé est alors en clair dans le fichier de config du client — à réserver aux bases de test) :

```json
"env": {
  "ODOO_URL": "https://acme.odoo.com",
  "ODOO_USERNAME": "vous@acme.com",
  "ODOO_API_KEY": "votre-clé"
}
```
</details>

## 🧰 Les 37 outils

Huit familles, une progression logique : se connecter → lire → explorer → écrire (sous
garde) → échanger des fichiers → préparer une démo → visualiser → rendre des comptes.

```mermaid
flowchart LR
    R(["🔌 odoo-mcp<br/>37 outils"])
    R --> A["🔌 Connexion · 3"]
    R --> B["📖 Lecture · 7"]
    R --> C["🔎 Schéma · 4"]
    R --> D["✍️ Écriture · 6"]
    R --> E["📁 Fichiers · 3"]
    R --> F["🎭 Démonstration · 4"]
    R --> G["📊 Tableaux de bord · 4"]
    R --> H["🧾 Traçabilité · 6"]

    classDef root fill:#0f2b46,stroke:#0f2b46,color:#fff;
    classDef cat fill:#eef2ff,stroke:#6366f1,color:#1e1b4b;
    class R root; class A,B,C,D,E,F,G,H cat;
```

<table>
<tr><td valign="top" width="50%">

**🔌 Connexion**

| Outil | Rôle |
|---|---|
| `odoo_connect` | Se connecter (URL + login + clé) — en mémoire |
| `odoo_status` | État connexion, version serveur, mode |
| `odoo_enable_write` | Activer/couper l'écriture |

**📖 Lecture**

| Outil | Rôle |
|---|---|
| `odoo_models` | Lister les modèles |
| `odoo_fields` | Décrire les champs (`writable_only`) |
| `odoo_search` | Recherche + lecture (domaine, tri, page) |
| `odoo_count` | Comptage |
| `odoo_read` | Lecture par identifiants |
| `odoo_name_find` | Retrouver un enreg. par son nom |
| `odoo_aggregate` | Sommes/comptes par groupe, par date |

**🔎 Exploration du schéma** *(cache disque)*

| Outil | Rôle |
|---|---|
| `odoo_find_models` | Chercher un modèle par mot-clé |
| `odoo_find_fields` | Chercher un champ par mot-clé |
| `odoo_fields_batch` | Champs de plusieurs modèles d'un coup |
| `odoo_schema_status` | État du cache ; `refresh=true` |

**📁 Fichiers**

| Outil | Rôle |
|---|---|
| `odoo_import_file` | Importer .xlsx/.csv (`inspect`/`check`/`run`) |
| `odoo_export_file` | Exporter vers .xlsx/.csv (`ecraser=True`) |
| `odoo_get_attachment` | Télécharger une pièce jointe |

</td><td valign="top" width="50%">

**✍️ Écriture** *(exige `odoo_enable_write`)*

| Outil | Rôle |
|---|---|
| `odoo_create` | Création |
| `odoo_write` | Modification par identifiants |
| `odoo_update_where` | Modif. de masse **prévisualisée** |
| `odoo_unlink` | Suppression (confirmation > 50) |
| `odoo_upsert` | Créer-ou-mettre-à-jour par External ID |
| `odoo_execute` | Appel brut `execute_kw` (liste blanche) |

**🎭 Démonstration & avant-vente**

| Outil | Rôle |
|---|---|
| `odoo_demo_questionnaire` | Trame de qualification avant démo |
| `odoo_demo_generate` | Générer un jeu de démo depuis une recette compacte |
| `odoo_demo_mode` | Filet : neutralise toute adresse e-mail |
| `odoo_demo_check` | Audite et corrige les adresses réelles |

**📊 Tableaux de bord**

| Outil | Rôle |
|---|---|
| `odoo_dashboard_list` | Inventaire des tableaux de bord |
| `odoo_dashboard_inspect` | Décrire en clair un tableau de bord |
| `odoo_dashboard_create` | Créer un tableau de graphiques live |
| `odoo_saved_analysis` | Enregistrer une analyse réutilisable |

**🧾 Traçabilité & reporting**

| Outil | Rôle |
|---|---|
| `odoo_journal_start` | Ouvrir un journal (titre + objectif) |
| `odoo_journal_chapter` | Ouvrir une étape + sa justification |
| `odoo_journal_note` | Consigner décision / observation / alerte |
| `odoo_journal_report` | Générer le rapport (HTML / Markdown) |
| `odoo_presentation_guide` | Générer le déroulé de démo client |
| `odoo_recent_changes` | Ce qui a bougé (audit natif Odoo) |

</td></tr>
</table>

## 📋 Le rapport d'intervention

Quand c'est l'assistant qui construit un flux entier, retrouver après coup ce qui a été fait
— et l'expliquer à un client — devient vite impossible à partir du seul historique de
conversation. Le serveur étant le point de passage obligé de toute écriture, il journalise
tout automatiquement.

```
odoo_journal_start("Maquette de démonstration", "Traduire le flux affaires dans Odoo")
odoo_journal_chapter("Référentiel articles", "Aucun catalogue n'existait : prérequis
                                              pour bloquer les achats hors contrat")
   → les écritures suivantes sont tracées, avec leur état avant/après
odoo_journal_note("Le stock reste hors périmètre (décision actée en réunion)", "decision")
odoo_journal_report(format="both")
```

Le rapport HTML est autonome (aucune ressource externe), présentable tel quel ou imprimable
en PDF. Il contient la synthèse chiffrée, les volumes par type d'information, le déroulé
chronologique par étape, et pour chaque modification le détail `avant → après`. Les
suppressions y apparaissent avec **le nom de ce qui a disparu** et un marquage
« irréversible ».

> [!TIP]
> **Le rapport parle français, pas Odoo.** Les noms techniques sont traduits en langage
> courant — `res.partner` devient « Contacts (clients, fournisseurs) », `sale.order` devient
> « Devis et commandes clients » — et chaque type d'information est accompagné de l'endroit où
> le trouver dans l'interface. Un dirigeant qui n'a jamais ouvert Odoo comprend le document.

### À quoi ressemble un rapport

> *Extrait reconstitué et anonymisé d'un rapport réel. Le document livré est une page HTML
> autonome et mise en forme (en-tête, cartes de synthèse, code couleur) — voici son contenu.*

<table>
<tr><td>

**RAPPORT D'INTERVENTION ODOO**
### Mise en place d'un jeu de démonstration
Alimenter la base avec un jeu de données de démonstration complet et varié.
`Base ••••••` · `Utilisateur ••••••` · le 27/07/2026

</td></tr>
</table>

**Ce qui a été fait**

| Enregistrements touchés | Opérations | Import de données | Création |
|:---:|:---:|:---:|:---:|
| **325** | **9** | **323** | **2** |

| Ce qui a été touché | Où le trouver | Détail | Total |
|---|---|---|---:|
| Contacts (clients, fournisseurs) | Contacts | import de données | **40** |
| Salariés | Employés → Employés | import de données | **40** |
| Articles | Ventes → Articles → Articles | import de données | **40** |
| Planning des équipes | Planning → Planning | import de données | **195** |
| Taxes | Comptabilité → Configuration → Taxes | création | **1** |

**Déroulé détaillé** *(extrait)*

> `10:36` · **Import de données** — 40 · *Contacts (clients, fournisseurs)*
> *Pourquoi : ajout de personnes physiques avec leurs coordonnées professionnelles (poste, email, téléphone).*
>
> `10:37` · **Import de données** — 40 · *Salariés*
> *Pourquoi : alimenter le module Planning avec les employés, les rôles métier et un planning complet sur 5 jours.*
>
> `10:48` · **Création** — 1 · *Taxes*
> *Pourquoi : appliquer la TVA réduite sur le catalogue et enrichir les descriptions de vente.*

Chaque ligne est passée par le connecteur MCP et a été journalisée automatiquement — rien
n'est saisi à la main dans le rapport.

## 🎬 Le guide de présentation

`odoo_presentation_guide` produit le **déroulé à suivre en réunion client**, écran par écran,
déduit de ce qui a réellement été fait : seules les étapes correspondant aux données mises
en place apparaissent, dans l'ordre naturel du métier (contacts → catalogue → devis →
livraison → facture → rentabilité).

Chaque étape donne le chemin de menu exact, les clics à faire sous forme de **cases à
cocher**, les enregistrements précis à ouvrir, et une phrase d'accroche à dire au client.
Le fichier HTML s'ouvre pendant la réunion : on coche au fur et à mesure, on n'oublie
aucune étape, et on garde le fil du discours.

```
### Étape 3 — Du devis à la commande client

Où aller : Ventes → Commandes → Devis

[ ] Ouvrir un devis de la démonstration
[ ] Montrer les lignes : articles, quantités, prix
[ ] Expliquer le bouton « Confirmer » : le devis devient une commande ferme

> À dire : C'est le point de bascule — un clic sur « Confirmer », et le reste
  de la chaîne se met en route tout seul.
```

Les journaux sont écrits en JSONL dans `~/odoo-mcp-journaux/` (une ligne par opération,
lisible et diffable), et un rapport peut être regénéré plus tard à partir d'un journal
ancien via `journal_path`.

`odoo_recent_changes` complète le dispositif : il interroge les champs d'audit d'Odoo
(`write_date`, `write_uid`), donc il voit aussi les modifications faites directement dans
l'interface par d'autres personnes.

## 📥 Importer un fichier

Trois modes à enchaîner, qui évitent d'écrire n'importe quoi dans la base :

```mermaid
flowchart LR
    F["📄 Fichier<br/>.xlsx / .csv"]
    I["🔍 inspect<br/>structure et doublons<br/>hors ligne"]
    C["✅ check<br/>validation champ par champ<br/>sans écrire"]
    R["🚀 run<br/>import par lots<br/>via load()"]
    O[("🗄️ Odoo")]
    F --> I --> C --> R --> O

    classDef step fill:#f0f9ff,stroke:#0ea5e9,color:#082f49;
    classDef odoo fill:#f3e8ff,stroke:#a855f7,color:#3b0764;
    class F,I,C,R step; class O odoo;
```

1. **`inspect`** — structure du fichier : colonnes, taux de remplissage, valeurs distinctes,
   doublons d'identifiant. Aucune connexion nécessaire.
2. **`check`** — construit les lignes et vérifie chaque champ contre le modèle, sans rien
   écrire.
3. **`run`** — importe par lots via `load()`, l'import natif d'Odoo.

Le `mapping` relie les colonnes du fichier aux champs Odoo. Il est indispensable : les
en-têtes des fichiers exportés depuis Odoo sont des libellés d'interface (`Name*`,
`Sales Price`), jamais des noms de champs.

```json
{
  "_columns": {
    "Code":  "id",
    "Nom":   "name",
    "Pays":  "country_id/id",
    "Notes": null
  },
  "_constants": { "is_company": "True" },
  "_replace":   { "type": { "Goods": "consu" } }
}
```

Mapper une colonne sur `id` (External ID) rend l'import **rejouable** : une seconde exécution
met à jour au lieu de dupliquer. Et `load()` rejette un lot entier en cas d'erreur — un échec
ne laisse jamais de données à moitié écrites.

## 🎭 Préparer une démonstration

Deux usages coexistent dans cet outil. Le **consultant** intervient sur des données
réelles : il lui faut de la traçabilité, d'où le journal et le rapport. L'**avant-vente**
construit des données fictives pour un prospect : il lui faut de la vraisemblance, vite.

Pour ce second cas, `odoo_demo_questionnaire` fournit une trame de qualification en huit
sections — le métier, ce qu'il vend, ses achats, son pilotage, sa facturation, **les
spécificités venant de ses propres clients**, son vocabulaire maison, et le problème qu'il
cherche à résoudre. C'est ce dernier point qui fait la différence entre une démonstration
générique et une démonstration où le prospect se reconnaît.

La composition de la maquette n'est pas codée dans le serveur : c'est l'assistant qui
l'écrit à partir des réponses. Aucun catalogue figé ne produira des noms d'articles et un
vocabulaire aussi justes qu'un modèle de langage — et surtout, cela fonctionne pour un
métier qu'on n'avait pas prévu.

### Peupler sans exploser les tokens

Écrire 40 fiches complètes coûte cher : à chaque ligne, le modèle réécrit l'e-mail, la
référence, la TVA… des champs identiques et sans intérêt métier. `odoo_demo_generate` sépare
les deux : **le modèle fournit le vocabulaire, le serveur déroule la plomberie.**

```json
{
  "model": "product.template",
  "gabarit":  { "type": "consu" },
  "sequence": { "default_code": "ART-{i:03}" },
  "id_prefixe": "art",
  "lignes": [
    { "name": "Article vitrine A", "list_price": 2.90 },
    { "name": "Coffret découverte", "list_price": 15.90 }
  ]
}
```

Le modèle n'écrit que `lignes` (le vocabulaire, spécifique au métier) ; le serveur ajoute les
constantes (`gabarit`), les champs séquentiels (`{i}`, `{i:03}`, `{autre_champ}`), un e-mail
dérivé du nom (`email_depuis`) et un External ID rejouable (`id_prefixe`), puis importe par
lots via `load()`. **~20 lignes de vocabulaire au lieu de ~200 lignes de fiches**, sans perdre
en pertinence — la base reste taillée pour *ce* métier.

> [!NOTE]
> Ce n'est **pas** de la génération de contenu figée : le serveur ne multiplie que les champs
> répétitifs. Deux modes, comme l'import : `check` (valide la recette sans écrire) puis `run`
> (importe ; exige `odoo_enable_write`). Le filet e-mail et le journal s'appliquent
> automatiquement, puisque tout passe par `load()`.

### Le filet e-mail, non négociable

> [!WARNING]
> Une base de démonstration n'est presque jamais neutralisée : Odoo y envoie de vrais
> courriels dès qu'on confirme une commande ou une facture. **Une adresse réelle dans un jeu
> fictif, et une vraie entreprise reçoit une fausse facture.**

```
odoo_demo_mode(actif=true)
```

Une fois activé, **toute** adresse écrite est réécrite vers `example.com` — domaine réservé
par la RFC 2606, qui ne peut appartenir à personne. La garantie est posée au seul endroit
par lequel passent toutes les écritures, elle tient donc quel que soit l'outil utilisé :
création, modification, upsert, import de fichier, ou même appel brut `odoo_execute`. Elle
couvre aussi les lignes imbriquées (commandes one2many/many2many) et les duplications
(`copy`), et **chaque** adresse d'un champ multi-destinataires est vérifiée, pas seulement
la dernière. Le domaine de remplacement n'est pas paramétrable : seuls les domaines réservés
(`example.com` & co.) sont acceptés. La partie gauche de l'adresse est conservée, donc
`jean.dupont@example.com` reste lisible à l'écran pendant la démonstration.

`odoo_demo_check` balaie une base reprise de quelqu'un d'autre et signale — ou corrige — les
adresses qui pourraient encore recevoir du courrier : contacts, employés, pistes
(`crm.lead`) et utilisateurs.

## 📊 Générer un tableau de bord

Les graphiques produits sont **recalculés par Odoo à chaque ouverture** — ce ne sont ni des
images ni des valeurs figées. Chacun porte sa source, son regroupement, sa mesure et son
filtre :

```json
[
  {"titre": "Chiffre d'affaires par mois", "model": "sale.order",
   "groupby": ["date_order:month"], "mesure": "amount_untaxed",
   "type": "line", "domaine": [["state","=","sale"]], "pleine_largeur": true},
  {"titre": "Commandes par vendeur", "model": "sale.order",
   "groupby": ["user_id"], "mesure": "__count", "type": "bar"}
]
```

Trois types : `bar` (comparer), `line` (suivre dans le temps), `pie` (répartition). Sur un
champ date, la granularité s'écrit `champ:month` — aussi `day`, `week`, `quarter`, `year`.
`__count` compte au lieu de sommer.

Le modèle, les champs de regroupement et le type de la mesure sont **vérifiés avant
écriture**, et la vérification fonctionne en lecture seule : on peut valider une maquette
avant de demander l'autorisation d'écrire. C'est important, car un tableau de bord qui
référence un champ inexistant s'ouvre vide, sans message d'erreur.

> [!NOTE]
> **[SPREADSHEETS.md](SPREADSHEETS.md) explique en détail** comment fonctionnent les
> tableurs Odoo : le format o-spreadsheet, les quatre façons de connecter des données et leur
> robustesse respective, le choix de la bonne source (`sale.report` plutôt que `sale.order`…),
> et ce que ce connecteur ne génère volontairement pas.

## ⚡ Économie de contexte

Le serveur régule lui-même ce qu'il renvoie, sans perdre l'accès à la donnée.

**Il rogne, il ne refuse jamais.** Une réponse trop volumineuse est réduite progressivement ;
les lignes rendues restent complètes, les métadonnées sont préservées, et la réponse indique
toujours combien de lignes sur combien et l'`offset` pour la suite. Une troncature silencieuse
mènerait à des conclusions fausses — c'est pire qu'une réponse longue.

**Il dépose l'intégralité sur disque.** Quand un résultat dépasse le plafond, le jeu complet
est écrit dans `~/odoo-mcp-resultats/` et le chemin est renvoyé. L'assistant le relit avec
son propre outil de lecture, sans repasser par Odoo : quelques dizaines de tokens au lieu de
dizaines de milliers. Ces fichiers sont purgés automatiquement (au-delà de 7 jours ou de
50 fichiers).

**Il se resserre à mesure que la session avance.**

| Palier | Déclenché à | Plafond | Champs par défaut | Limite par défaut |
|---|---|---|---|---|
| confort | départ | 60 k car | 12 | 50 |
| économie | 200 k rendus | 30 k | 8 | 30 |
| strict | 500 k | 15 k | 6 | 20 |

**Les défauts sont sobres.** `odoo_search` sans `fields` choisissait autrefois *tous* les
champs — 169 000 tokens pour dix contacts. Il retient désormais une douzaine de champs utiles
et écarte les types lourds. `odoo_fields` renvoie une forme compacte
(`"partner_id":"many2one>res.partner*"`) au lieu de 20 000 tokens de détail.

**Le schéma est mémorisé sur disque.** La première exploration d'une base (liste des modèles,
`fields_get` modèle par modèle) est ce qui coûte le plus cher à chaque session. Modèles et
champs sont donc conservés dans `~/odoo-mcp-cache/`, par base, et remplis à l'usage : un
modèle déjà consulté n'est jamais redemandé à Odoo. Le cache est vérifié une fois par session
(version serveur + modules installés) et invalidé tout seul s'il ne correspond plus ;
`odoo_schema_status(refresh=true)` force le réexamen après une (dés)installation de modules.
Pour chercher sans tout lister : `odoo_find_models` et `odoo_find_fields` filtrent côté
serveur, et `odoo_fields_batch` décrit plusieurs modèles en un seul aller-retour.

L'état de consommation est visible à tout moment dans `odoo_status`. Si le coût permanent des
définitions d'outils gêne, le levier restant est de désactiver dans votre client MCP ceux
dont vous ne vous servez pas.

## 🧭 Notes de terrain

- Inspecter les champs (`odoo_fields`) **avant** d'écrire : les noms changent entre versions
  d'Odoo (en 19, `is_company` existe mais pas `company_type` ; `groups_id` est devenu
  `group_ids` ; le contenu d'une pièce jointe est passé de `datas` à `raw`).
- Préférer `odoo_upsert` à `odoo_create` pour toute donnée de maquette ou d'import.
- Un échec d'écriture sur un champ non fourni (ex. `credit_limit` en créant un contact) est un
  problème de **droits Odoo**, pas de données.
- Les relations one2many (ex. `seller_ids`) **s'accumulent** à chaque écriture au lieu de se
  remplacer — purger avant de rejouer un chargement.
- Archiver (`{"active": false}`) est presque toujours préférable à supprimer : Odoo n'a pas de
  corbeille.

## 📄 Licence

Publié sous licence **MIT** — voir [LICENSE](LICENSE). Auteur : Damien Dechamps.