# Facturolia MCP

Serveur MCP qui permet à un assistant IA (Claude, ou tout client compatible
[Model Context Protocol](https://modelcontextprotocol.io)) de **lire et vérifier
des factures électroniques** : Factur-X, ZUGFeRD, XRechnung, UBL, CII.

Vous demandez « cette facture est-elle correcte ? » en pointant un fichier ;
l'assistant répond avec le contenu en clair et le contrôle EN 16931.

## Outils exposés

| Outil | Ce qu'il fait |
|---|---|
| `read_invoice` | Contenu complet : parties, dates, lignes, TVA, totaux + contrôle EN 16931 |
| `check_invoice` | Uniquement le verdict de conformité et les anomalies |

## Installation

Aucune dépendance : Python 3.10+ et la bibliothèque standard suffisent.

1. Récupérez `facturolia_mcp.py`.
2. Obtenez une clé API sur <https://facturolia.fr/tarifs> (palier gratuit
   disponible : 10 requêtes/minute, 100/jour).
3. Déclarez le serveur dans votre client MCP.

### Claude Desktop

Dans `claude_desktop_config.json` :

```json
{
  "mcpServers": {
    "facturolia": {
      "command": "python",
      "args": ["/chemin/absolu/vers/facturolia_mcp.py"],
      "env": {
        "FACTUROLIA_API_KEY": "votre-cle-api"
      }
    }
  }
}
```

Redémarrez le client. Les deux outils apparaissent alors dans la liste.

## Variables d'environnement

| Variable | Rôle | Défaut |
|---|---|---|
| `FACTUROLIA_API_KEY` | Votre clé API (**obligatoire**) | — |
| `FACTUROLIA_BASE_URL` | Utile pour tester contre une autre instance | `https://facturolia.fr` |

## Exemples de demandes

- « Lis la facture `~/Téléchargements/FA-2026-0042.pdf` »
- « Cette facture respecte-t-elle la norme EN 16931 ? »
- « Quel est le total TTC et l'échéance de ce fichier ? »
- « Compare les montants du PDF et du XML embarqué »

## Confidentialité — à lire avant usage

Ce serveur **envoie le fichier** à l'API Facturolia pour analyse. Comme dans
l'outil web, la facture est analysée en mémoire, jamais écrite sur disque, et
supprimée dès la réponse envoyée ; aucun service tiers n'est appelé et les
serveurs sont dans l'Union européenne.

Ce n'est cependant **pas** un traitement local : si votre politique interne
interdit la sortie des factures de votre réseau, n'utilisez pas ce serveur —
l'API peut être auto-hébergée, ou l'outil web reste disponible.

## Limites

- Formats acceptés : `.pdf` (Factur-X/ZUGFeRD) et `.xml` (UBL, CII, XRechnung).
- Taille maximale : 10 Mo par fichier.
- Le débit dépend de votre palier (voir `/tarifs`).
- Facturolia **lit et vérifie** ; ce n'est pas une Plateforme Agréée et il ne
  transmet aucune facture.

## Dépannage

| Message | Cause probable |
|---|---|
| `FACTUROLIA_API_KEY n'est pas défini` | La clé manque dans le bloc `env` de la configuration |
| `api_key_invalid` | Clé inconnue ou révoquée |
| `api_rate_limited` | Palier dépassé ; attendez ou changez de palier |
| `Fichier introuvable` | Donnez un chemin **absolu** ; l'assistant n'a pas le même dossier courant que vous |
| `pdf_no_xml` | PDF ordinaire sans données structurées : ce n'est pas une facture électronique |

## Licence et support

Publié avec Facturolia — <https://facturolia.fr> · info@facturolia.fr

## Langue des réponses

Par défaut les réponses sont en **anglais**, comme l'API `/v1`. Pour les
recevoir en français, ajoutez la variable dans le champ `env` :

```json
"env": { "FACTUROLIA_API_KEY": "votre-cle", "FACTUROLIA_LANG": "fr" }
```

Les descriptions des outils restent en anglais, car c'est l'assistant qui les
lit et l'écosystème MCP est anglophone.

## Code source

Le serveur est aussi publié seul, avec sa licence MIT :
https://github.com/toomasgutman-blip/facturolia-mcp