# 🚀 mcp-dolibarr

Serveur MCP (**Model Context Protocol**) hautement performant, optimisé et sécurisé basé sur **FastMCP**, permettant à n'importe quel assistant IA (Claude Desktop, Claude Web via Connecteur, Cursor, AI Agents) d'interagir nativement avec l'ERP/CRM **Dolibarr** via son API REST officielle.

---

## 🏗️ ARCHITECTURE MCP DOLIBARR – RÔLE DE CHAQUE COMPOSANT

### 📐 Schéma d'Architecture Globale (11 Composants)

```mermaid
flowchart LR
    subgraph Client_Side ["Côté Client IA"]
        U["1. USER<br/>(Utilisateur)"] --> CD["2. CLAUDE DESKTOP<br/>(Assistant IA)"]
        CD --> MH["3. MCP HOST<br/>(Application Hôte)"]
        MH --> MC["4. MCP CLIENT<br/>(Client Protocol)"]
    end

    subgraph Server_Side ["Serveur MCP (Python + FastMCP)"]
        MC -- "MCP / JSON-RPC<br/>(stdio | http)" --> MS["5. MCP SERVER<br/>(Python + FastMCP)"]
        MS --> MT["6. MCP TOOLS<br/>(tools/thirdparties, products...)"]
        MT --> SL["7. SERVICE LAYER<br/>(Logique métier)"]
        SL --> DAC["8. DOLIBARR API CLIENT<br/>(Client HTTP httpx)"]
    end

    subgraph Dolibarr_Side ["ERP / CRM & Base de Données"]
        DAC -- "9. HTTP / REST<br/>+ DOLAPIKEY" --> DAPI["10. DOLIBARR<br/>(REST API)"]
        DAPI <--> DB[("11. MYSQL<br/>(Base de Données)")]
    end
```

---

### 🧩 Rôle Détaillé des 11 Composants de l'Architecture

1. **1. USER (Utilisateur)** : L'utilisateur pose une question ou donne une instruction en langage naturel (ex: *"Donne-moi les 5 derniers clients."*).
2. **2. CLAUDE DESKTOP (Assistant IA)** : Claude comprend la demande et décide d'utiliser un outil MCP approprié (ex: `get_thirdparties`).
3. **3. MCP HOST (Application Hôte)** : L'application hôte (Claude Desktop / Cursor / Agent) gère la connexion avec le serveur MCP configuré.
4. **4. MCP CLIENT** : Le client MCP communique avec le serveur MCP via le protocole MCP standard (JSON-RPC sur `stdio` ou Streamable HTTP).
5. **5. MCP SERVER (Python + FastMCP)** : Le serveur MCP expose les outils, gère la découverte (`tools/list`), l'exécution (`tools/call`) et le protocole MCP.
6. **6. MCP TOOLS** : Ensemble des outils disponibles pour Claude, organisés par domaine (`thirdparties`, `products`, `proposals`, `invoices`, `orders`, `stocks`).
7. **7. SERVICE LAYER** : Contient la logique métier. Sépare la déclaration des outils MCP de la communication effective avec Dolibarr.
8. **8. DOLIBARR API CLIENT** : Client HTTP (basé sur `httpx`) qui appelle l'API REST de Dolibarr avec la clé d'authentification `DOLAPIKEY`.
9. **9. HTTP / REST + DOLAPIKEY** : Requêtes HTTP/REST sécurisées et authentifiées avec l'en-tête de clé API.
10. **10. DOLIBARR (REST API)** : Dolibarr ERP/CRM reçoit la requête HTTP, valide les permissions et traite l'opération demandée.
11. **11. MYSQL (BASE DE DONNÉES)** : Dolibarr lit ou écrit les données dans sa base de données relationnelle MySQL.

---

## 🔍 MCP TOOLS : `tools/list` vs `tools/call`

```mermaid
flowchart LR
    subgraph Discovery ["Découverte - tools/list"]
        D1["1. Client -> tools/list"] --> D2["2. Serveur répertorie les outils:<br/>• get_thirdparty<br/>• create_thirdparty<br/>• get_product<br/>• get_invoice"]
    end

    subgraph Execution ["Exécution - tools/call"]
        E1["1. Client -> tools/call (id: 25)"] --> E2["2. Serveur exécute l'outil,<br/>interroge Dolibarr REST<br/>et renvoie le résultat."]
    end
```

- **🔍 `tools/list` (DÉCOUVERTE)** : Permet au client IA d'explorer au démarrage l'ensemble des fonctions exposées par le serveur MCP ainsi que leur schéma d'arguments.
- **▶️ `tools/call` (EXÉCUTION)** : Déclenche l'exécution d'un outil spécifique avec des paramètres précis fournis par l'assistant IA.

---

## 🔄 EXEMPLE COMPLET DE FLUX : *"Donne-moi les 5 derniers clients."*

```mermaid
sequenceDiagram
    autonumber
    actor U as 1. Utilisateur
    participant C as 2. Claude
    participant MC as 3. MCP Client
    participant MS as 4. MCP Server
    participant MT as 5. MCP Tool
    participant SL as 6. Service Layer
    participant DAC as 7. Dolibarr API Client
    participant D as 8. Dolibarr ERP/CRM
    participant DB as 9. MySQL (BDD)

    U->>C: 1. Donne la demande: "Donne-moi les 5 derniers clients."
    C->>MC: 2. Comprend la demande & choisit l'outil get_thirdparties
    MC->>MS: 3. Communication MCP: 1) tools/list (découverte) | 2) tools/call (exécution)
    MS->>MT: 4. Reçoit la requête & exécute get_thirdparties(limit=5)
    MT->>SL: 5. Appelle le Service Layer pour récupérer les données
    SL->>DAC: 6. Utilise le Dolibarr API Client pour appeler l'API REST
    DAC->>D: 7. Envoie la requête HTTP GET /thirdparties?limit=5 + DOLAPIKEY
    D->>DB: 8. Récupère les 5 derniers clients dans la base de données MySQL
    DB-->>D: Restitution des enregistrements SQL
    D-->>DAC: Envoi de la réponse JSON REST
    DAC-->>SL: Traitement HTTP
    SL-->>MT: Données métiers
    MT-->>MS: Nettoyage & formatage pour LLM
    MS-->>MC: Protocol Response (JSON-RPC)
    MC-->>C: Transfert au moteur de réponse
    C-->>U: 9. La réponse suit le chemin inverse et Claude affiche les 5 clients.
```

### Détail des 9 Étapes de l'Exemple :
1. **Utilisateur** : Donne la demande à Claude (*"Donne-moi les 5 derniers clients."*).
2. **Claude** : Comprend la demande et choisit l'outil approprié (`get_thirdparties`).
3. **MCP Client** : Exécute `tools/list` (découverte), puis `tools/call` (exécution).
4. **MCP Server** : Reçoit la requête, exécute l'outil `get_thirdparties(limit=5)`.
5. **MCP Tool** : Appelle le Service Layer pour récupérer les données.
6. **Service Layer** : Utilise le Dolibarr API Client pour appeler l'API REST.
7. **Dolibarr API** : Envoie une requête `HTTP GET /thirdparties?limit=5` authentifiée par `DOLAPIKEY`.
8. **Dolibarr** : Récupère les clients enregistrés dans la base de données MySQL.
9. **Réponse** : La réponse suit le chemin inverse et Claude affiche les 5 clients à l'utilisateur.

---

## ⚖️ COMPARAISON ARCHITECTURALE & OPTIMISATION DES TOKENS

### ❌ 1. Architecture MCP Classique / Basique (Explosion de Tokens)

Dans les passerelles MCP basiques ou génériques pour Dolibarr, **chaque petite sous-action génère un appel HTTP distinct qui passe par la fenêtre de contexte du LLM** :

```mermaid
sequenceDiagram
    autonumber
    actor LLM as 🤖 LLM / Claude
    participant API as 🌐 API REST Dolibarr (ERP/CRM)

    LLM->>API: 1. HTTP GET /thirdparties (Recherche Tiers)
    API-->>LLM: Reçoit JSON brut (+50 champs internes inutiles)
    LLM->>API: 2. HTTP POST /proposals (Création Devis)
    API-->>LLM: Reçoit JSON brut (+50 champs internes inutiles)
    LLM->>API: 3. HTTP POST /proposals/line (Ajout Ligne)
    API-->>LLM: Reçoit JSON brut (+50 champs internes inutiles)
    LLM->>API: 4. HTTP PUT /proposals/validate (Validation Devis)
    API-->>LLM: Reçoit JSON brut (+50 champs internes inutiles)
    LLM->>API: 5. HTTP POST /orders (Génération Commande)
    API-->>LLM: Reçoit JSON brut (+50 champs internes inutiles)
    LLM->>API: 6. HTTP POST /invoices (Création Facture)
    API-->>LLM: Reçoit JSON brut (+50 champs internes inutiles)
    Note over LLM,API: 🔴 Total : 6 allers-retours LLM • ~15 000 à 30 000 tokens consommés !
```

**Bilan de l'Architecture Classique :**
- 🔴 **6 à 10 allers-retours LLM successifs** pour un seul workflow métier.
- 🔴 **Consommation massive : ~15 000 à 30 000 tokens** gaspillés pour transmettre des métadonnées système JSON inutiles (`import_key`, `array_options`, `fk_user_author`, `user_creation_id`, etc.).
- 🔴 **Risque d'échec très élevé** : Plus le nombre d'appels LLM successifs augmente, plus le risque d'hallucination ou d'oubli de contexte augmente.

---

### ✅ 2. Notre Architecture Multicouche `mcp-dolibarr` (Réduction de 80% à 90% des Tokens)

Grâce au découplage en couches (`tools/`, `utils/formatters.py`, `dolibarr/client.py`), l'ensemble de la logique métier et du nettoyage est exécuté **localement côté serveur Python** :

```mermaid
sequenceDiagram
    autonumber
    actor LLM as 🤖 LLM / Claude
    participant Server as ⚡ Serveur MCP Python (mcp-dolibarr)
    participant API as 🏢 API REST Dolibarr (ERP/CRM)

    LLM->>Server: 1. Un seul appel MCP Orchestrateur (ex: convert_proposal_to_invoice)
    Note over Server: Exécution interne locale en Python:<br/>• Valide le devis<br/>• Génère la commande client<br/>• Crée et valide la facture
    Server->>API: Exécute les requêtes REST HTTP en local (sans repasser par le LLM)
    API-->>Server: Données brutes de Dolibarr
    Note over Server: formatters.py : Nettoie et filtre les 50+ champs inutiles
    Server-->>LLM: 2. Résumé Markdown concis et épuré
    Note over LLM,API: 🟢 Total : 1 seul aller-retour LLM • ~500 à 1 500 tokens seulement !
```

**Bilan de Notre Architecture Multicouche :**
- 🟢 **1 seul aller-retour LLM** pour exécuter la totalité du workflow complexe.
- 🟢 **Consommation minimale : ~500 à 1 500 tokens seulement**.
- 🟢 **Gain d'efficacité : Réduction de 80% à 90% des tokens consommés**, offrant une exécution ultra-rapide et économique.

---

### 🛠️ Comment Cette Architecture Réduit-elle Concrètement les Tokens ?

1. **⚡ Orchestration Serveur (Workflows Multi-Étapes en 1 Tour)** :
   Au lieu de demander au LLM d'exécuter 6 requêtes réseau successives, des outils orchestrateurs dédiés (comme `convert_proposal_to_invoice`) exécutent la séquence complète en local dans le code Python et ne renvoient au LLM que le résultat final.

2. **🎯 Nettoyage et Filtrage Dynamique des JSON (`utils/formatters.py`)** :
   L'API REST native de Dolibarr renvoie par défaut plus de 50 champs d'audit et métadonnées système par objet (ex: `import_key`, `array_options`, `fk_user_author`, `user_creation_id`, `fk_statut`, `extrafields`, etc.). `formatters.py` intercepte et détruit ces champs superflus pour ne restituer que les données métiers essentielles (ID, Référence, Raison Sociale, Montant HT/TTC, Statut).

3. **🛡️ Validation Stricte en Amont (`utils/validators.py`)** :
   Toutes les données saisies par l'utilisateur (emails, montants positifs, identifiants) sont vérifiées en amont avant l'émission de la requête HTTP. Cela empêche Dolibarr de renvoyer des erreurs HTTP 400/422 et évite au LLM de consommer des tokens dans des boucles de réécriture et de correction d'erreurs.

4. **📄 Formatage Markdown Synthétique** :
   Les réponses retournées au LLM sont directement formatées sous forme de texte brut ou Markdown compact, éliminant tout le superflu syntaxique des structures JSON verbeuses.

---

## 📌 RÉSUMÉ & LÉGENDE

- 📌 **MCP (Model Context Protocol)** : Protocole standardisé permettant de connecter de façon sécurisée des assistants IA (Claude) à des outils et systèmes externes.
- 🔌 **Serveur MCP** : Agit comme un pont intermédiaire entre Claude et l'ERP Dolibarr.
- 🛠️ **MCP Tools** : Ensemble des fonctions exposées au client IA pour réaliser des actions de lecture, création ou modification sur Dolibarr.
- 🌐 **Dolibarr REST API** : L'ERP Dolibarr est accessible uniquement via son API REST officielle (garantissant sécurité, isolation et respect des règles de gestion).

**Légende des flux :**
- `──>` : Flux de la requête (Aller)
- `<──` : Flux de la réponse (Retour)
- `<──>` : Communication bidirectionnelle (MCP stdio/http ou HTTP REST)

---

## ✨ Fonctionnalités & Description Détaillée des Outils MCP

Le serveur MCP couvre l'ensemble des besoins de gestion d'entreprise sur Dolibarr à travers **plus de 30 outils dédiés** répartis dans 12 modules thématiques :

### 🏢 1. Tiers & Sociétés (`tools/thirdparties.py`)
- `list_thirdparties` : Recherche plein-texte et listing filtré des fiches clients, prospects ou fournisseurs.
- `get_thirdparty` : Consultation complète et détaillée d'un tiers à partir de son identifiant unique (ID).
- `create_thirdparty` : Création d'une nouvelle fiche entreprise (Raison sociale, Code client, SIREN/TVA, Email, Téléphone, Adresse).
- `update_thirdparty` : Modification granulaire des coordonnées et des informations d'un tiers existant.

### 👤 2. Contacts & Intervenants (`tools/contacts.py`)
- `list_contacts` : Recherche et extraction des personnes physiques (interlocuteurs) rattachés à une entreprise client.
- `create_contact` : Création et rattachement d'un nouveau contact (Nom, Prénom, Poste, Email, Téléphone direct).

### 📦 3. Produits & Services (`tools/products.py`)
- `list_products` : Consultation du catalogue d'articles physiquement stockables et de prestations de service.
- `get_product` : Fiche technique complète d'un produit par son ID ou par sa Référence unique.
- `create_product` : Création d'un article ou d'un service (Référence, Libellé, Prix de vente HT, Taux de TVA, Description).
- `update_product` : Mise à jour des tarifs HT, libellés ou caractéristiques d'un produit.

### 📄 4. Devis & Propositions Commerciales (`tools/proposals.py`)
- `list_proposals` : Consultation et suivi des devis (filtrage par tiers ou par statut commercial).
- `create_proposal` : Génération d'un devis commercial multi-lignes pour un tiers.
- `add_proposal_line` : Ajout d'une ligne d'article ou de service avec quantité, prix unitaire HT et remise.
- `update_proposal_line` : Ajustement de la quantité ou du prix d'une ligne de devis existante.
- `delete_proposal_line` : Suppression d'une ligne d'un devis en cours.
- `validate_proposal` : Validation officielle attribuant le numéro de devis définitif.
- `convert_proposal_to_invoice` : **Orchestrateur intelligent** qui enchaîne automatiquement la validation du devis, la création de la commande et la génération de la facture finale en un seul appel.

### 🛒 5. Commandes Clients (`tools/orders.py`)
- `list_orders` : Listing et suivi des commandes d'achats enregistrées.
- `create_order` : Création d'une commande client liée à une société.
- `add_order_line` : Ajout d'un produit ou d'un service sur une commande.
- `update_order_line` : Modification de quantité ou de tarif unitaire d'une ligne de commande.
- `delete_order_line` : Suppression d'une ligne de commande.

### 💳 6. Factures Clients & Règlements (`tools/invoices.py`)
- `list_invoices` : Consultation des factures avec état des règlements (Reste à payer, Payée, Impayée).
- `create_invoice` : Création d'une facture directe ou depuis une commande client.
- `add_invoice_line` : Ajout d'une ligne d'article ou de prestation sur la facture.
- `update_invoice_line` : Édition et ajustement des lignes de facturation.
- `delete_invoice_line` : Suppression d'une ligne de facture en brouillon.
- `validate_invoice` : Validation finale attribuant la référence légale de facture (ex: `FA2608-0001`).

### 📊 7. Gestion des Stocks par Entrepôt (`tools/stocks.py`)
- `get_product_stock` : Consultation détaillée du niveau de stock réel d'un article, entrepôt par entrepôt.

### 📁 8. Fiches Projets (`tools/projects.py`)
- `list_projects` : Consultation des projets de gestion et suivi d'affaires.
- `create_project` : Création d'un projet et rattachement à une fiche client.

### 📜 9. Contrats de Service (`tools/contracts.py`)
- `list_contracts` : Suivi des contrats de prestation récurrents souscrits par les clients.
- `create_contract` : Enregistrement d'un nouveau contrat de service pour un tiers.

### 🛠️ 10. Fiches d'Intervention Technique (`tools/interventions.py`)
- `list_interventions` : Suivi et historique des fiches d'intervention terrain.
- `create_intervention` : Création d'une fiche d'intervention technique (Date, Durée, Description d'intervention).

### 📑 11. Documents & Génération PDF (`tools/documents.py`)
- `generate_document` : Déclenchement de la génération automatique du PDF officiel de Dolibarr (modèles Azur, Crabe, etc.).
- `get_document_base64` : Téléchargement et encodage du fichier PDF en Base64 pour analyse directe par l'assistant IA.

### 🔌 12. Mode Secours API REST Brute (`tools/raw.py`)
- `call_dolibarr_api` : Outil de secours permettant d'exécuter n'importe quelle méthode HTTP (`GET`, `POST`, `PUT`, `DELETE`) sur n'importe quel endpoint REST de Dolibarr non couvert par les outils standard.

---

## ⚙️ Configuration du Fichier `.env.example`

Le projet utilise un fichier `.env` pour configurer le comportement et les accès. Copiez le modèle `.env.example` fourni :

```bash
cp .env.example .env
```

Contenu standard du fichier `.env.example` :

```env
# --- Dolibarr REST API ---
DOLIBARR_URL=http://localhost:8080/api/index.php
DOLIBARR_API_KEY=change-me

# --- Logging ---
LOG_LEVEL=INFO

# --- Transport MCP (stdio | http) ---
MCP_TRANSPORT=stdio
MCP_HOST=0.0.0.0
MCP_PORT=8000

# --- Timeout HTTP (secondes) ---
HTTP_TIMEOUT=30
```

---

## 🏃 Comment Lancer et Exécuter le Serveur MCP

### 1. Préparation de l'environnement

```bash
# 1. Créer l'environnement virtuel Python
python -m venv .venv

# 2. Activer l'environnement
# Linux / macOS / Git Bash :
source .venv/bin/activate
# Windows PowerShell :
# .venv\Scripts\Activate.ps1

# 3. Installer les dépendances
pip install -r requirements.txt
```

### 2. Modes de Démarrage

#### A. Mode Local `stdio` (Claude Desktop / Cursor)

Par défaut (`MCP_TRANSPORT=stdio`), le serveur communique via l'entrée/sortie standard.

```bash
python server.py
```

##### 💻 Configuration pour Claude Desktop (`claude_desktop_config.json`)

Fichier de configuration situé à l'emplacement suivant :
- **Windows** : `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS** : `~/Library/Application Support/Claude/claude_desktop_config.json`

**Exemple de configuration générique pour Windows** :
```json
{
  "mcpServers": {
    "dolibarr": {
      "command": "C:\\chemin\\vers\\mcp-dolibarr\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\chemin\\vers\\mcp-dolibarr\\server.py"
      ],
      "env": {
        "DOLIBARR_URL": "http://localhost:8080/dolibarr/api/index.php",
        "DOLIBARR_API_KEY": "votre_cle_api_dolibarr",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}
```

**Exemple de configuration générique pour Linux / macOS** :
```json
{
  "mcpServers": {
    "dolibarr": {
      "command": "/chemin/vers/mcp-dolibarr/.venv/bin/python",
      "args": [
        "/chemin/vers/mcp-dolibarr/server.py"
      ],
      "env": {
        "DOLIBARR_URL": "http://localhost:8080/dolibarr/api/index.php",
        "DOLIBARR_API_KEY": "votre_cle_api_dolibarr",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}
```

#### B. Mode Serveur Distant / Streamable HTTP (`http`)

Pour exposer le serveur MCP en réseau local ou distant via le mode **Streamable HTTP** :

```bash
MCP_TRANSPORT=http MCP_PORT=8000 python server.py
```

Le serveur sera démarré sur `http://0.0.0.0:8000` et exposera les endpoints `/mcp`, `/sse` et `/health`.

---

## 🌐 Connexion de Claude au Serveur MCP Distant (Railway via Add Connector)

Le serveur MCP `mcp-dolibarr` est déployé et directement disponible en production sur **Railway** via le mode Streamable HTTP.

Pour connecter **Claude** à ce serveur MCP distant, utilisez la fonctionnalité **Add Connector** (Ajouter un connecteur MCP) avec les informations suivantes :

- **Nom du connecteur** : `mcp-dolibarr`
- **Lien / URL du serveur** : `https://mcp-dolibarr-production-d091.up.railway.app/mcp`

### Étapes d'ajout dans Claude :
1. Ouvrez l'interface Claude et accédez au menu des connecteurs (**Add Connector / Ajouter un connecteur**).
2. Entrez le nom du connecteur : `mcp-dolibarr`
3. Collez le lien du serveur : `https://mcp-dolibarr-production-d091.up.railway.app/mcp`
4. Validez la connexion. Claude peut maintenant interagir directement avec votre ERP Dolibarr !

---

## 🧪 Test et Débogage avec MCP Inspector

Vous pouvez tester et inspecter interactivement tous les outils du serveur en local grâce à l'outil officiel **MCP Inspector** (`npx @modelcontextprotocol/inspector`).

### 1. Test en Mode Local `stdio`
```bash
npx @modelcontextprotocol/inspector python server.py
```

### 2. Test en Mode Streamable HTTP (Local)
Démarrez d'abord le serveur en mode HTTP (`MCP_TRANSPORT=http python server.py`), puis lancez l'inspector sur l'URL locale :
```bash
npx @modelcontextprotocol/inspector http://localhost:8000/mcp
```

---

## 🐋 Exécution avec Docker

### Via Docker Compose (Recommandé)
```bash
docker-compose up -d --build
```

### Via Docker CLI
```bash
docker build -t mcp-dolibarr .
docker run -d -p 8000:8000 --env-file .env mcp-dolibarr
```

---

## 🧪 Exécution des Tests Unitaires

La suite de tests unitaires valide le comportement du client et des outils à l'aide de `pytest` et du mock HTTP `respx` (aucun appel réseau réel ni modification sur votre Dolibarr) :

```bash
pytest
```

---

## 📁 Architecture et Structure du Projet

```text
mcp-dolibarr/
├── app.py                # Initialisation de l'instance FastMCP & endpoints de contrôle (/health, /mcp)
├── server.py             # Point d'entrée principal (Transports stdio/http & Logging)
├── config/
│   └── settings.py       # Centralisation et validation des paramètres d'environnement (.env)
├── dolibarr/
│   ├── client.py         # Client HTTP asynchrone httpx connecté à l'API REST Dolibarr
│   ├── auth.py           # Authentification HTTP via le header DOLAPIKEY
│   └── exceptions.py     # Hiérarchie des erreurs et exceptions métier
├── tools/                # 12 modules d'outils MCP exposés aux assistants IA
│   ├── thirdparties.py   # Gestion des tiers et sociétés clients/prospects
│   ├── contacts.py       # Gestion des contacts personnes physiques
│   ├── products.py       # Catalogue produits et services
│   ├── proposals.py      # Devis & Orchestrateur de conversion devis->facture
│   ├── orders.py         # Commandes clients et gestion de leurs lignes
│   ├── invoices.py       # Facturation, validation et paiements
│   ├── stocks.py         # Suivi des niveaux de stock par entrepôt
│   ├── projects.py       # Fiches projets
│   ├── contracts.py      # Suivi des contrats clients
│   ├── interventions.py  # Fiches d'intervention technique
│   ├── documents.py      # Génération & téléchargement de PDF
│   └── raw.py            # Outil de secours API REST brute
├── utils/
│   ├── formatters.py     # Nettoyage et mise en forme des réponses JSON pour optimiser les tokens LLM
│   └── validators.py     # Validation stricte des entrées utilisateur
├── tests/                # Tests unitaires automatisés (pytest + respx)
├── Dockerfile            # Image Docker du serveur MCP
├── docker-compose.yml    # Fichier Docker Compose
├── requirements.txt      # Liste des dépendances Python
├── .env.example          # Modèle de variables d'environnement
└── README.md             # Documentation complète du projet
```