Aller au contenu
mcp-einvoicing-be

mcp-einvoicing-be 🇧đŸ‡Ș

English | Français | Nederlands

PyPI version Python License mcp-einvoicing-be MCP server

Introduction

mcp-einvoicing-be est un serveur MCP (Model Context Protocol) qui expose des outils pour la facturation electronique en Belgique. Il couvre l’ensemble de l’ecosysteme belge de facturation electronique : Peppol BIS Billing 3.0, UBL 2.1, et le reseau Mercurius pour la facturation du secteur public. Ce serveur fait partie de la famille mcp-einvoicing-* de serveurs specifiques a chaque pays, tous construits sur mcp-einvoicing-core, qui fournit le moteur de validation partage, les abstractions UBL et les utilitaires reseau Peppol.

Installation

Prérequis

  • Python ≄ 3.11
  • mcp-einvoicing-core (installĂ© automatiquement en tant que dĂ©pendance)

Avec uv (recommandé)

Terminal window
uv add mcp-einvoicing-be

Avec pip

Terminal window
pip install mcp-einvoicing-be

Depuis les sources

Terminal window
git clone https://github.com/cmendezs/mcp-einvoicing-be.git
cd mcp-einvoicing-be
uv sync --all-extras

Configuration

Variables d’environnement

Variable Description Par défaut
BCE_API_KEY ClĂ© API pour la base de donnĂ©es d’entreprises belge BCE/KBO -
PEPPOL_ENV Environnement Peppol : production ou test production
PEPPOL_SML_URL Remplacer l’URL de recherche SML (auto)
EINVOICING_PEPPOL_CODELIST_DIR RĂ©pertoire local contenant votre propre copie des listes de codes eDEC OpenPeppol, requis par les outils de listes de codes (non fourni avec ce paquet ; voir le README de mcp-einvoicing-core) —
EINVOICING_EN16931_CODELIST_DIR RĂ©pertoire local contenant votre propre copie des listes de codes sĂ©mantiques EN 16931 du CEF « Digital Building Blocks », requis par les outils de listes de codes EN 16931 (non fourni ; voir le README de mcp-einvoicing-core) —
LOG_LEVEL Niveau de journalisation : DEBUG, INFO, WARNING, ERROR INFO

Les outils de rapport EUSR/TSR et MLS nĂ©cessitent en plus l’extra [xslt2] (pip install "mcp-einvoicing-be[xslt2]") pour la validation Schematron.

Intégration Claude Desktop

Pour utiliser ce serveur avec Claude, ajoutez cette configuration dans votre fichier claude_desktop_config.json :

{
  "mcpServers": {
    "einvoicing-be": {
      "command": "uvx",
      "args": ["mcp-einvoicing-be"],
      "env": {
        "BCE_API_KEY": "votre-cle-api-bce",
        "PEPPOL_ENV": "production"
      }
    }
  }
}

Pour une installation de développement locale :

{
  "mcpServers": {
    "einvoicing-be": {
      "command": "uv",
      "args": ["run", "mcp-einvoicing-be"],
      "cwd": "/path/to/mcp-einvoicing-be"
    }
  }
}

Intégration Cursor

Cursor prend en charge les serveurs MCP en stdio. Ajoutez la configuration dans :

  • Global (tous les projets) : ~/.cursor/mcp.json
  • Projet (ce dĂ©pĂŽt uniquement) : .cursor/mcp.json
{
  "mcpServers": {
    "einvoicing-be": {
      "command": "uvx",
      "args": ["mcp-einvoicing-be"],
      "env": {
        "BCE_API_KEY": "votre-cle-api-bce",
        "PEPPOL_ENV": "production"
      }
    }
  }
}

Rechargez la fenĂȘtre Cursor (Ctrl+Shift+P puis Reload Window) pour prendre en compte les changements.

Intégration Kiro

Kiro prend en charge les serveurs MCP via son fichier de configuration dédié. Deux niveaux sont disponibles :

  • Global (tous les projets) : ~/.kiro/settings/mcp.json
  • Workspace (ce dĂ©pĂŽt uniquement) : .kiro/settings/mcp.json
{
  "mcpServers": {
    "einvoicing-be": {
      "command": "uvx",
      "args": ["mcp-einvoicing-be"],
      "env": {
        "BCE_API_KEY": "votre-cle-api-bce",
        "PEPPOL_ENV": "production"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Le fichier est rechargé automatiquement à la sauvegarde. Vous pouvez également ouvrir la configuration via la palette de commandes (Cmd+Shift+P / Ctrl+Shift+P) puis MCP.

Conseil sĂ©curitĂ© Kiro : plutĂŽt que d’écrire les secrets en clair, utilisez la syntaxe "BCE_API_KEY": "${BCE_API_KEY}", Kiro rĂ©sout les variables d’environnement shell au dĂ©marrage.

Outils disponibles

validate_invoice_be

Valide une facture XML UBL 2.1. Les profils peppol-bis-3/pint-eu executent une validation Schematron reelle sur les regles de base CEN EN 16931 (~50 regles structurelles/arithmetiques BR-*, via le Schematron de base fourni par mcp-einvoicing-core — voir CHANGELOG.md v0.8.0). Cela ne verifie pas les regles de la couche specifique Peppol (aucun droit de redistribution confirme aupres d’OpenPeppol) ; les resultats portent un avertissement explicite de portee en16931-base-only et ne doivent pas etre lus comme une conformite Peppol BIS3 complete. Le profil mercurius applique la couche specifique Mercurius (schema de point de terminaison, reference de bon de commande) mais ne verifie pas la conformite EN 16931/Peppol BIS 3.0 de base.

Parametre Type Requis Description
xml string oui Contenu XML UBL 2.1 brut
profile string non peppol-bis-3 (par defaut) ou mercurius

Retourne un ValidationResult avec valid, errors et warnings (chacun portant l’identifiant de la rĂšgle Ă©chouĂ©e et un message lisible).

generate_invoice_be

GénÚre un document XML de facture électronique belge UBL 2.1 valide à partir de données structurées.

ParamĂštre Type Requis Description
invoice_data object oui Champs de la facture (voir le schéma InvoiceInput ci-dessous)
profile string non peppol-bis-3 (par defaut)

L’objet InvoiceInput prend en charge :

{
  "invoice_number": "INV-2024-001",
  "issue_date": "2024-01-15",
  "due_date": "2024-02-14",
  "currency_code": "EUR",
  "supplier": { "name": "...", "vat_number": "BE0428759497", "address": {...} },
  "customer": { "name": "...", "vat_number": "BE0403170701", "address": {...} },
  "lines": [{ "description": "...", "quantity": 1, "unit_price": 100.00, "vat_rate": 21.0 }]
}

Retourne une chaĂźne XML UBL 2.1.

transform_to_ubl

Convertit une charge utile JSON de facture structurée en XML UBL 2.1 sans validation complÚte. Utile comme premiÚre étape avant la validation.

ParamĂštre Type Requis Description
data object oui DonnĂ©es de facture source (mĂȘme format que InvoiceInput)

lookup_vat_be

Recherche un numĂ©ro d’entreprise belge (numĂ©ro de TVA) dans la base de donnĂ©es publique BCE/KBO.

ParamĂštre Type Requis Description
vat_number string oui Numéro de TVA/entreprise belge, par ex. BE0428759497 ou 0123456789

Retourne le nom de l’entreprise, l’adresse enregistrĂ©e, le statut juridique et les codes d’activitĂ© NACE.

Outils du réseau Peppol

La recherche de participant Peppol, la recherche de point de service, un diagnostic DNS seul, l’envoi AS4, la recherche dans l’annuaire Peppol et les outils de listes de codes eDEC OpenPeppol sont fournis par le plugin d’outils Peppol partagĂ© du core (mcp_einvoicing_core.peppol.tools.register_peppol_tools), montĂ© dans server.py avec un adaptateur d’identifiant spĂ©cifique Ă  la Belgique : un numĂ©ro de TVA belge simple (par ex. 0428759497 ou BE0428759497) est normalisĂ© vers le schĂ©ma Peppol 0208:<chiffres> (numĂ©ro d’entreprise KBO/BCE) ; un identifiant dĂ©jĂ  qualifiĂ© par schĂ©ma (par ex. 0208:0428759497) passe inchangĂ©.

peppol_send signe dĂ©sormais les messages sortants avec une vĂ©ritable signature wsse:Security depuis mcp-einvoicing-core v1.20.0 (auparavant calculĂ©e puis ignorĂ©e — voir CHANGELOG.md v0.10.0).

Outil Description
peppol_lookup_participant VĂ©rifie si une entreprise est enregistrĂ©e sur le rĂ©seau Peppol ; retourne le statut d’enregistrement et les types de documents pris en charge
peppol_get_service_endpoint RĂ©cupĂšre le point de terminaison AS4 pour le type de document d’un participant
resolve_peppol_dns Diagnostic DNS seul (SML), indĂ©pendant de l’accessibilitĂ© SMP
peppol_send Transmet une facture UBL/CII via AS4
peppol_directory_search Recherche dans l’annuaire public Peppol par participant, nom, pays ou type de document
list_participant_id_schemes, list_document_type_ids, list_process_ids, list_spis_use_case_ids Recherches dans les listes de codes eDEC OpenPeppol (nécessitent EINVOICING_PEPPOL_CODELIST_DIR)
check_document_type_id_in_codelist, check_process_id_in_codelist, check_participant_id_scheme_in_codelist, get_peppol_codelist_version VĂ©rifications de listes de codes eDEC OpenPeppol et rapport de version

Voir le README de mcp-einvoicing-core pour la documentation complĂšte des paramĂštres de ces outils.

Outils de rapport et de statut Peppol

AjoutĂ©s en v0.10.0 via trois plugins core optionnels, montĂ©s inconditionnellement dans server.py. Chacun renvoie une erreur claire Ă  l’appel (pas Ă  l’enregistrement) si son extra ou son rĂ©pertoire de donnĂ©es est manquant.

Outil Plugin Description
validate_eusr_report register_peppol_reporting_tools Valide un End User Statistics Report (XSD, puis Schematron). NĂ©cessite l’extra [xslt2].
validate_tsr_report register_peppol_reporting_tools Valide un Transaction Statistics Report (XSD, puis Schematron). NĂ©cessite l’extra [xslt2].
validate_mls_message register_peppol_mls_tools Valide un document Message Level Status (sous-ensemble UBL ApplicationResponse-2). NĂ©cessite l’extra [xslt2].
build_mls_message register_peppol_mls_tools Construit une rĂ©ponse MLS au niveau du document. NĂ©cessite l’extra [xslt2].
13 paires list_*/check_*, get_en16931_codelist_version register_en16931_codelist_tools Recherches/vérifications des listes de codes sémantiques EN 16931 (unités, catégories de TVA, etc.). Nécessitent EINVOICING_EN16931_CODELIST_DIR.

Voir le README de mcp-einvoicing-core pour la documentation complĂšte des paramĂštres de ces outils.

parse_ubl_invoice_be

Analyse une facture XML UBL 2.1 (Peppol BIS 3.0) en un dictionnaire structure. Repond a l’obligation de reception obligatoire de l’Art. 13quater de l’AR no. 1.

Parametre Type Requis Description
xml_content string oui Contenu XML UBL 2.1 brut de la facture

Retourne {"success": true, "invoice": {...}, "warnings": []} en cas de succes, ou {"success": false, "error": "..."} en cas d’echec.

get_invoice_types_be

Retourne la liste des types de documents de facture electronique belges pris en charge (facture, note de credit, note de debit) avec leurs valeurs customizationID et profileID UBL pour chaque profil.

Aucun parametre d’entree requis.

B2G via Mercurius

Mercurius est la plateforme belge de facturation electronique pour le secteur public federal. Elle fonctionne comme un recepteur du reseau Peppol, et non comme une API separee. Les factures B2G sont soumises via le reseau Peppol standard en utilisant l’identifiant de participant de l’autorite dans le schema 0208 (numero d’entreprise KBO/BCE a 10 chiffres). Le Point d’Acces achemine automatiquement la facture vers Mercurius. Aucun point de soumission specifique a Mercurius ni cle API n’est requis.

Architecture

mcp-einvoicing-be/
├── src/
│   └── mcp_einvoicing_be/
│       ├── __init__.py
│       ├── server.py              # Point d'entrĂ©e du serveur MCP et enregistrement des outils
│       ├── tools/
│       │   ├── __init__.py
│       │   ├── validation.py      # validate_invoice_be
│       │   ├── generation.py      # generate_invoice_be
│       │   ├── transformation.py  # transform_to_ubl
│       │   ├── parsing.py         # parse_ubl_invoice_be
│       │   └── lookup.py          # lookup_vat_be, get_invoice_types_be
│       ├── models/
│       │   ├── __init__.py
│       │   ├── invoice.py         # InvoiceInput, InvoiceLine, ValidationResult
│       │   └── party.py           # Supplier, Customer, Address
│       ├── standards/
│       │   ├── __init__.py
│       │   ├── peppol_bis_3.py    # Rùgles et ID de personnalisation Peppol BIS Billing 3.0
│       │   ├── ubl.py             # Constantes de namespace UBL 2.1 et utilitaires XML
│       │   ├── pint_be.py         # PINT-BE placeholder (supprime en v0.4.0)
│       │   └── mercurius.py       # Configuration rĂ©seau Mercurius et rĂšgles de couche
│       └── utils/
│           ├── __init__.py
│           └── helpers.py         # Normalisation de numĂ©ro de TVA, formatage de dates, etc.
├── tests/
│   ├── __init__.py
│   ├── conftest.py
│   ├── test_tools/
│   │   ├── __init__.py
│   │   ├── test_validation.py
│   │   ├── test_generation.py
│   │   └── test_transformation.py
│   └── fixtures/
│       ├── invoice_valid_peppol.xml
│       ├── invoice_valid_pint_be.xml
│       └── invoice_invalid.xml
├── .github/
│   └── workflows/
│       ├── ci.yml
│       └── publish.yml
├── pyproject.toml
├── CHANGELOG.md
├── CONTRIBUTING.md
└── LICENSE

Relation avec mcp-einvoicing-core

mcp-einvoicing-core fournit :

  • Utilitaires partagĂ©s d’analyse et de sĂ©rialisation XML UBL 2.1/2.3
  • RĂšgles de validation de base EN 16931 (syntaxe + sĂ©mantique)
  • Client rĂ©seau Peppol (recherche SMP, rĂ©solution SML)
  • ModĂšles de base Pydantic communs (BaseInvoice, BaseParty, BaseValidationResult)

mcp-einvoicing-be ajoute la logique specifique a la Belgique :

  • Validation des regles de couche Mercurius (basee sur XPath) pour la facturation B2G
  • Integration de la base de donnees d’entreprises BCE/KBO
  • Normalisation des numeros de TVA belges (format BTW/TVA) et validation des digits de controle OGM/VCS
  • Analyse de factures UBL 2.1 pour la reception obligatoire (Art. 13quater)
  • Valeurs customizationID et profileID specifiques au coin belge de Peppol

Contribuer

Les contributions sont les bienvenues. Veuillez ouvrir un ticket (issue) pour discuter des changements significatifs avant de soumettre une pull request.

Terminal window
git clone https://github.com/cmendezs/mcp-einvoicing-be.git
cd mcp-einvoicing-be
uv sync --all-extras
uv run pytest
uv run ruff check src tests
uv run mypy src

Toutes les pull requests doivent :

  • Passer l’ensemble de la suite de tests (pytest)
  • Passer le linting (ruff check)
  • Passer la vĂ©rification de types (mypy)
  • Inclure ou mettre Ă  jour les tests pour tout comportement modifiĂ©
  • Faire rĂ©fĂ©rence aux identifiants de rĂšgle concernĂ©s lors de la correction d’un problĂšme de validation

Consultez CONTRIBUTING.md pour les directives complĂštes.

Autres serveurs MCP de facturation Ă©lectronique

Pays Serveur
🌍 Global mcp-einvoicing-core
🇧đŸ‡Ș Belgique mcp-einvoicing-be
đŸ‡§đŸ‡· BrĂ©sil mcp-nfe-br
đŸ‡«đŸ‡· France mcp-facture-electronique-fr
đŸ‡©đŸ‡Ș Allemagne mcp-einvoicing-de
🇼đŸ‡č Italie mcp-fattura-elettronica-it
đŸ‡ČđŸ‡œ Mexique mcp-cfdi-mx
đŸ‡”đŸ‡± Pologne mcp-ksef-pl
🇾🇬 Singapour mcp-invoicenow-sg
đŸ‡Ș🇾 Espagne mcp-facturacion-electronica-es
🇩đŸ‡Ș Émirats arabes unis mcp-einvoicing-ae

Licence

Ce projet est sous licence Apache 2.0. Consultez LICENSE pour plus de dĂ©tails. Pour l’historique complet des versions, voir CHANGELOG.md.