Serveur de validation MCP
Factur-X, ZUGFeRD & XRechnung

1. Aperçu

Le serveur fournit trois outils et une ressource que les agents IA peuvent appeler via le Model Context Protocol.

2. Architecture & flux de données

Déroulement pour validate_invoice

3. Moteurs de validation

Chaque requête est vérifiée par deux moteurs en même temps. Les résultats sont consolidés, dédupliqués, puis renvoyés.

4. Installation & configuration

# Kostenlos registrieren:
https://zugferd-validator.de/portal

npm install -g zugferd-mcp-client

// mcp_config.json (je nach Client abweichender Pfad)
{
  "mcpServers": {
    "zugferd": {
      "command": "zugferd-mcp-client",
      "env": {
        "ZUGFERD_API_KEY": "zv_dein_key_hier"
      }
    }
  }
}

API REST directe

L'API peut aussi être appelée directement, sans client MCP :

# Beispiel: Validierung per curl
curl -X POST https://api.zugferd-validator.de/v1/validate \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: zv_dein_key_hier" \
  -d '{"file_content":"<base64>","file_type":"xml"}'

Variables d'environnement (client MCP)

5. Outils

{
  "valid":    true,
  "format":   "ZUGFeRD 2.x",
  "profile":  "EN16931",
  "summary":  "Keine Probleme gefunden",
  "errors":   [],
  "warnings": [],
  "notices":  [],
  "metadata": {
    "invoice_number": "RE-2026-001",
    "issue_date":     "2026-04-01",
    "seller":         "Musterfirma GmbH",
    "buyer":          "Beispiel AG",
    "total_amount":   "1190.00",
    "currency":       "EUR"
  }
}

{
  "valid":   false,
  "format":  "ZUGFeRD 2.x",
  "profile": "EN16931",
  "summary": "2 Fehler, 1 Warnung gefunden",
  "errors": [
    {
      "severity":       "error",
      "rule_id":        "BR-DE-15",
      "field":          "BT-10",
      "message":        "Die Käuferreferenz / Leitweg-ID (BT-10) muss übermittelt werden.",
      "fix_suggestion": "Füge die Käuferreferenz / Leitweg-ID (BT-10) in 'ram:ApplicableHeaderTradeAgreement/ram:BuyerReference' ein.",
      "xpath":          "//ram:ApplicableHeaderTradeAgreement/ram:BuyerReference"
    }
  ],
  "warnings": [
    {
      "severity":       "warning",
      "rule_id":        "BR-CL-10",
      "field":          "BT-81",
      "message":        "Zahlungsmittelcode muss aus UNTDID 4461 stammen.",
      "fix_suggestion": "Verwende z.B. '58' für SEPA-Überweisung oder '59' für SEPA-Lastschrift.",
      "xpath":          "//ram:SpecifiedTradeSettlementPaymentMeans/ram:TypeCode"
    }
  ]
}

{
  "xml_content": "<?xml version='1.0' encoding='UTF-8'?>\n<rsm:CrossIndustryInvoice ...>...</rsm:CrossIndustryInvoice>",
  "format":      "ZUGFeRD 2.x",
  "profile":     "EN16931"
}

{
  "consistent":    true,
  "discrepancies": []
}

{
  "consistent":    false,
  "discrepancies": [
    {
      "field":     "total_amount",
      "pdf_value": "1190.00",
      "xml_value": "1180.00",
      "message":   "Gesamtbetrag im PDF ('1190.00') unterscheidet sich von dem im XML ('1180.00')."
    }
  ]
}

{
  "format":     "zugferd",
  "profile":    "EN16931",
  "pdf_base64": "JVBERi0xLjc…",
  "xml":        "<?xml version=\"1.0\"…",
  "branding":   "free_footer"
}

6. Ressource : validation_rules

Renvoie l'ensemble de règles actuel du serveur : formats et profils pris en charge, ainsi que le moteur de validation utilisé.

URI : validation://rules

{
  "supported_formats": [
    "ZUGFeRD 1.0", "ZUGFeRD 2.0", "ZUGFeRD 2.1", "ZUGFeRD 2.2",
    "ZUGFeRD 2.3", "ZUGFeRD 2.x / Factur-X 1.0x",
    "XRechnung 1.2", "XRechnung 2.0", "XRechnung 2.3", "XRechnung 3.0"
  ],
  "supported_profiles": [
    "minimum", "basic_wl", "basic", "en16931", "extended", "xrechnung"
  ],
  "validation_engines": [
    "Mustang Project v2.22.0",
    "KoSIT Validierungstool v1.6.2 (XRechnung 3.0.2 + EN 16931 CII)"
  ],
  "last_updated":      "2026-04-08"
}

7. Gestion des erreurs

En cas d'erreur, tous les outils renvoient un objet JSON avec un champ error. Il n'y a jamais de sortie d'erreur non structurée.

{
  "error":   "Kurze Fehlerkategorie",
  "details": "Ausführliche Beschreibung mit konkretem Hinweis zur Behebung."
}

8. Types de données communs

ValidationIssue

Utilisé dans les tableaux errors, warnings et notices de validate_invoice.

InvoiceMetadata

Champ optionnel dans le résultat de validate_invoice (uniquement pour file_type: "xml").

9. Formats & profils pris en charge

Formats

Profils (ZUGFeRD/Factur-X)

10. Règles & suggestions de correction

Le serveur contient une base de suggestions de correction pour 63 catégories de règles. Les erreurs des deux moteurs de validation (Mustang + KoSIT) sont consolidées — lorsqu'une ID de règle connue est trouvée, la suggestion de correction est ajoutée automatiquement.

11. Exemples d'utilisation

Exemple 1 : valider un XML XRechnung

{
  "tool": "validate_invoice",
  "arguments": {
    "file_content": "PD94bWwgdmVyc2lvbj0iMS4wIj8+...",
    "file_type":   "xml",
    "profile":     "xrechnung"
  }
}

{
  "valid":   true,
  "format":  "XRechnung 3.0",
  "profile": "XRECHNUNG",
  "summary": "Keine Probleme gefunden",
  "errors":  [],
  "warnings": [],
  "metadata": {
    "invoice_number": "INV-2026-0042",
    "issue_date":     "2026-04-07",
    "seller":         "Tech GmbH",
    "buyer":          "Bundesbehörde X",
    "total_amount":   "5950.00",
    "currency":       "EUR"
  }
}

Exemple 2 : facture erronée avec suggestion de correction

{
  "tool": "validate_invoice",
  "arguments": {
    "file_content": "JVBERi0xLjQK...",
    "file_type":   "pdf"
  }
}

{
  "valid":   false,
  "format":  "ZUGFeRD 2.x",
  "profile": "EN16931",
  "summary": "1 Fehler gefunden",
  "errors": [{
    "severity":       "error",
    "rule_id":        "BR-DE-23",
    "field":          "BT-10",
    "message":        "Käuferreferenz (BT-10) muss für XRechnung angegeben werden.",
    "fix_suggestion": "Füge 'ram:BuyerReference' hinzu, z.B. '04011000-1234-34' für Behörden.",
    "xpath":          "//ram:ApplicableHeaderTradeAgreement/ram:BuyerReference"
  }],
  "warnings": []
}

Exemple 3 : extraire et valider le XML

// Schritt 1 — XML aus PDF extrahieren
{ "tool": "extract_xml", "arguments": { "pdf_content": "JVBERi0x..." } }

// Schritt 2 — Extrahiertes XML validieren (base64-kodiert übergeben)
{ "tool": "validate_invoice", "arguments": { "file_content": "<base64 des xml_content>", "file_type": "xml" } }

Exemple 4 : contrôle de cohérence

{
  "tool": "check_consistency",
  "arguments": { "pdf_content": "JVBERi0xLjQK..." }
}

{
  "consistent":    false,
  "discrepancies": [{
    "field":     "total_amount",
    "pdf_value": "1190.00",
    "xml_value": "1180.00",
    "message":   "Gesamtbetrag im PDF ('1190.00') unterscheidet sich von dem im XML ('1180.00')."
  }]
}

12. Limites & restrictions connues

13. Journal des modifications