Skip to main content
Glama
deenesjakoruzh
cmendezs

mcp-einvoicing-core

by cmendezs
OverviewSchemaSourceRelated ServersDiscussionsAdmin

mcp-einvoicing-core

License PyPI version Python

Themen: mcp mcp-server e-invoicing electronic-invoicing european-invoicing python fastmcp peppol en16931 ubl fatturapa xp-z12-013 xml base-library

Basispaket für europäische elektronische Rechnungsstellungs-MCP-Server.

Stellt abstrakte Basisklassen, gemeinsame Pydantic-Modelle, XML-Dienstprogramme und einen HTTP-Client bereit, damit länderspezifische Pakete (mcp-facture-electronique-fr, mcp-fattura-elettronica-it, …) eine gemeinsame Grundlage nutzen können, ohne Code zu duplizieren.

Was dieses Paket bietet

Modul

Inhalt

Verwendet von

models.py

InvoiceParty, InvoiceLineItem, VATSummary, PaymentTerms, InvoiceDocument, DocumentValidationResult

IT (strukturierte Rechnungserstellung), zukünftig BE/PL/DE/ES

base_server.py

BaseDocumentGenerator, BaseDocumentValidator, BaseDocumentParser, BaseLifecycleManager, BasePartyValidator, EInvoicingMCPServer

Alle Länder-Adapter

xml_utils.py

format_amount, format_quantity, validate_date_iso, validate_iban, xml_element, xml_optional, format_error, filter_empty_values

IT (wortwörtlich übernommen), zukünftige XML-basierte Formate

http_client.py

TokenCache, OAuthConfig, BaseEInvoicingClient (OAuth2 + no-auth)

FR (wortwörtlich übernommen), zukünftige API-basierte Länder

exceptions.py

EInvoicingError, ValidationError, PartyValidationError, XSDValidationError, DocumentGenerationError, AuthenticationError, PlatformError

Alle Länder-Adapter

logging_utils.py

setup_logging, get_logger

Alle Länder-Adapter

Related MCP server: mcp-facture-electronique-fr

Installation

pip install mcp-einvoicing-core

Dieses Paket hat keine länderspezifischen Abhängigkeiten. lxml (benötigt für XSD-Validierung in IT und zukünftigen Ländern) wird von jedem Länderpaket individuell deklariert.

Architektur

mcp-einvoicing-core           ← this package
  ├── BaseDocumentGenerator   ← abstract: generate(InvoiceDocument) → str
  ├── BaseDocumentValidator   ← abstract: validate(xml) → DocumentValidationResult
  ├── BaseDocumentParser      ← abstract: parse(xml) → dict
  ├── BaseLifecycleManager    ← abstract: submit/search/get_status (async HTTP)
  ├── BasePartyValidator      ← abstract: validate_seller/buyer/tax_id
  ├── BaseEInvoicingClient    ← concrete: async HTTP + OAuth2/no-auth/token
  ├── InvoiceDocument (Pydantic)  ← shared data model
  └── EInvoicingMCPServer     ← plugin registry wrapping FastMCP

mcp-facture-electronique-fr   ← country adapter (FR)
  ├── PAConfig(OAuthConfig)
  ├── FlowClient(BaseEInvoicingClient)      ← OAuth2, XP Z12-013 Annex A
  ├── DirectoryClient(BaseEInvoicingClient) ← OAuth2, XP Z12-013 Annex B
  └── FrLifecycleManager(BaseLifecycleManager)

mcp-fattura-elettronica-it    ← country adapter (IT)
  ├── ItalyPartyValidator(BasePartyValidator)   ← Partita IVA modulo-10
  ├── FatturaGenerator(BaseDocumentGenerator)   ← FatturaPA XML v1.6.1
  ├── FatturaValidator(BaseDocumentValidator)   ← lxml XSD v1.6.1
  └── FatturaParser(BaseDocumentParser)         ← lxml xpath

Plugin-Registrierungsmuster

Länderpakete registrieren ihre Tools auf einer gemeinsamen oder eigenständigen FastMCP-Instanz:

# Standalone (existing server.py — no changes required)
from fastmcp import FastMCP
mcp = FastMCP(name="mcp-fattura-elettronica-it", instructions="…")
register_header_tools(mcp)
register_body_tools(mcp)
register_global_tools(mcp)

# Multi-country (optional EInvoicingMCPServer)
from mcp_einvoicing_core import EInvoicingMCPServer
server = EInvoicingMCPServer(name="mcp-einvoicing-eu", instructions="…")
server.register_plugin(register_header_tools, "it-header")
server.register_plugin(register_flow_tools, "fr-flow")
server.run()

Kompatibilität mit Claude Desktop / Cursor / Kiro

Bestehende Konfigurationen für mcp-facture-electronique-fr und mcp-fattura-elettronica-it erfordern keine Änderungen: Tool-Namen, Signaturen, Umgebungsvariablen und Einstiegspunkte (server:main) bleiben vollständig erhalten.

Roadmap-Kompatibilität

Land

Status

Standard

Transport

Erbt von

Überschreibt

Bekannte Lücken

🇫🇷 FR

✅ Erledigt

XP Z12-013

Hybrid / PPF-Hub

BaseEInvoicingClient, BaseLifecycleManager

submit_lifecycle_status, healthcheck

Keine

🇮🇹 IT

✅ Erledigt

FatturaPA v1.6.1

Direkt / SDI

BaseDocumentGenerator, BaseDocumentValidator, BaseDocumentParser, BasePartyValidator

alle abstrakten Methoden

to_invoice_document() noch nicht implementiert

🇧🇪 BE

✅ Erledigt

Peppol BIS 3.0

AS4 / Peppol

alle Basisklassen

generate() → UBL 2.1, validate() → Schematron EN16931

Keine

🇵🇱 PL

🔄 In Arbeit

KSeF FA(2)

Direkt-API

BaseDocumentGenerator, BaseDocumentValidator, BaseLifecycleManager

KSeF-Sitzungs-Auth-Flow

MTLS-Auth-Modus noch nicht implementiert

🇩🇪 DE

🔄 In Arbeit

ZUGFeRD / XRechnung

AS4 / Peppol

alle Basisklassen

generate() gibt PDF-Bytes zurück (base64)

generate() Rückgabetyp: Mehrdeutigkeit zwischen str und bytes

🇪🇸 ES

🔄 In Arbeit

FACeB2B / FacturaE

Direkt-API

alle Basisklassen

mTLS-Auth

MTLS-Auth-Modus noch nicht implementiert

🇷🇴 RO

📋 Backlog

RO-UBL (EN 16931)

Direkt-API / Clearance

BaseDocumentGenerator, BaseLifecycleManager

ANAF-Clearance-Flow

BaseSchematronValidator-Variante erforderlich

🇬🇷 GR

📋 Backlog

myDATA XML

Direkt-API / Reporting

BaseEInvoicingClient, BaseLifecycleManager

myDATA-Auth + Reporting-Flow

myDATA-API-Client noch nicht entworfen

🇳🇱🇸🇪🇩🇰🇳🇴 Nordics/NL

📋 Backlog

Peppol BIS 3.0 / UBL

AS4 / Peppol

alle Basisklassen

generate() → UBL 2.1, validate() → Schematron

Nutzt BE AS4-Transportschicht wieder

🇵🇹 PT

📋 Backlog

CIUS-PT + QR-Code

Signatur / direkt

BaseDocumentGenerator, BaseDocumentValidator

Qualifizierte Signatur + QR-Injektion

Integration qualifizierter Signaturen nicht entworfen

Architektonische Hinweise

Transport-Schnittstelle

Da die Anzahl der Adapter wächst, wird eine TransportInterface-Abstraktion im Core Duplikate über Länder hinweg verhindern, die dieselbe Transportschicht nutzen:

Transport

Länder

Direkt-API (Clearance / Reporting)

FR, RO, GR, HU

AS4 / Peppol-Netzwerk

BE, DE, Nordics/NL

Hybrid / Hub

FR (PPF/PDP dualer Pfad)

Deutschland: 80% Wiederverwendung von FR

Das deutsche Mandat (aktiv seit Jan 2025 für B2B-Empfang) bevorzugt stark ZUGFeRD/Factur-X — dasselbe in PDF eingebettete XML-Modell wie das französische Factur-X-Profil. Die XML-Generierungs- und Validierungslogik von mcp-facture-electronique-fr kann mit minimalen Änderungen wiederverwendet werden, was DE zum nächsten Adapter mit dem geringsten Aufwand nach BE macht.

ViDA / DRR (2030)

Bis Juli 2030 müssen sich alle nationalen Systeme an die EU-Vorgaben zur digitalen Berichterstattung (Digital Reporting Requirement) für grenzüberschreitende Transaktionen anpassen. Die Verwendung von EN 16931 als internes InvoiceDocument-Datenmodell in diesem Kernpaket macht das Projekt bereits zukunftssicher: Länder-Adapter übersetzen EN 16931 → lokales Format, nicht umgekehrt.

Lizenz

Apache 2.0 — siehe LICENSE.

Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • einvoice-mcp

    makririch
    A
    license
    A
    quality
    D
    maintenance
    MCP server for DACH e-invoicing. Create XRechnung (UBL) and ZUGFeRD 2.3 (Factur-X CII) invoices, validate against EN 16931 rules, extract data from XML, and convert between UBL, CII and JSON formats.
    6
    49 npm
    2
    MIT

  • mcp-facture-electronique-fr

    cmendezs
    A
    license
    A
    quality
    A
    maintenance
    Model Context Protocol (MCP) server for French Electronic Invoicing (NF XP Z12-013). Provide tools to validate, generate, and explore API specifications for PDP/OD interoperability.
    2
    34
    Apache 2.0

  • mcp-fattura-elettronica-it

    cmendezs
    A
    license
    A
    quality
    A
    maintenance
    Model Context Protocol (MCP) server for Italian Electronic Invoicing (FatturaPA / SDI). Provide tools to validate, generate, and explore API specifications for Sistema di Interscambio (SDI) interoperability.
    43
    110 PyPI
    1
    Apache 2.0

  • mcp-einvoicing-be

    cmendezs
    A
    license
    A
    quality
    A
    maintenance
    Model Context Protocol (MCP) server for Belgian Electronic Invoicing (Peppol BIS 3.0 / PINT-BE / Mercurius). Provides tools to validate, generate, and transform UBL 2.1 e-invoices, and look up BCE/KBO enterprise data and Peppol participants.
    50
    Apache 2.0