mcp-einvoicing-core

License PyPI version Python mcp-einvoicing-core MCP server

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

Base package for European electronic invoicing MCP servers.

Provides abstract base classes, shared Pydantic models, XML utilities, and an HTTP client so country-specific packages (mcp-facture-electronique-fr, mcp-fattura-elettronica-it, …) share a common foundation without duplicating code.

What this package provides

Module	Contents	Used by
`models.py`	`InvoiceParty`, `InvoiceLineItem`, `VATSummary`, `PaymentTerms`, `InvoiceDocument`, `DocumentValidationResult`	IT (structured invoice generation), future BE/PL/DE/ES
`base_server.py`	`BaseDocumentGenerator`, `BaseDocumentValidator`, `BaseDocumentParser`, `BaseLifecycleManager`, `BasePartyValidator`, `EInvoicingMCPServer`	All country adapters
`xml_utils.py`	`format_amount`, `format_quantity`, `validate_date_iso`, `validate_iban`, `xml_element`, `xml_optional`, `format_error`, `filter_empty_values`	IT (extracted verbatim), future XML-based formats
`http_client.py`	`TokenCache`, `OAuthConfig`, `BaseEInvoicingClient` (OAuth2 + no-auth)	FR (extracted verbatim), future API-based countries
`exceptions.py`	`EInvoicingError`, `ValidationError`, `PartyValidationError`, `XSDValidationError`, `DocumentGenerationError`, `AuthenticationError`, `PlatformError`	All country adapters
`logging_utils.py`	`setup_logging`, `get_logger`	All country adapters

Installation

pip install mcp-einvoicing-core

This package has no country-specific dependencies. lxml (needed for XSD validation in IT and future countries) is declared by each country package individually.

Architecture

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 registration pattern

Country packages register their tools on a shared or standalone FastMCP instance:

# 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()

Claude Desktop / Cursor / Kiro compatibility

Existing configurations for mcp-facture-electronique-fr and mcp-fattura-elettronica-it require no changes: tool names, signatures, environment variables, and entry points (server:main) are fully preserved.

Roadmap compatibility

Country	Status	Standard	Transport	Inherits	Overrides	Known gaps
🇧🇪 BE	✅ Done	Peppol BIS 3.0	AS4 / Peppol	all base classes	`generate()` → UBL 2.1, `validate()` → Schematron EN16931	None
🇫🇷 FR	✅ Done	XP Z12-013	Hybrid / PPF hub	`BaseEInvoicingClient`, `BaseLifecycleManager`	`submit_lifecycle_status`, `healthcheck`	None
🇩🇪 DE	✅ Done	ZUGFeRD / XRechnung	AS4 / Peppol	all base classes	`generate()` returns PDF bytes (base64)	`generate()` return type: `str` vs `bytes` ambiguity
🇮🇹 IT	✅ Done	FatturaPA v1.6.1	Direct / SDI	`BaseDocumentGenerator`, `BaseDocumentValidator`, `BaseDocumentParser`, `BasePartyValidator`	all abstract methods	`to_invoice_document()` not yet implemented
🇵🇱 PL	✅ Done	KSeF FA(2)	Direct API	`BaseDocumentGenerator`, `BaseDocumentValidator`, `BaseLifecycleManager`	KSeF session auth flow	`MTLS` auth mode not yet implemented
🇪🇸 ES	✅ Done	FACeB2B / FacturaE	Direct API	all base classes	mTLS auth	`MTLS` auth mode not yet implemented
🇷🇴 RO	📋 Backlog	RO-UBL (EN 16931)	Direct API / clearance	`BaseDocumentGenerator`, `BaseLifecycleManager`	ANAF clearance flow	`BaseSchematronValidator` variant needed
🇬🇷 GR	📋 Backlog	myDATA XML	Direct API / reporting	`BaseEInvoicingClient`, `BaseLifecycleManager`	myDATA auth + reporting flow	myDATA API client not yet designed
🇳🇱🇸🇪🇩🇰🇳🇴 Nordics/NL	📋 Backlog	Peppol BIS 3.0 / UBL	AS4 / Peppol	all base classes	`generate()` → UBL 2.1, `validate()` → Schematron	Reuses BE AS4 transport layer
🇵🇹 PT	📋 Backlog	CIUS-PT + QR Code	Signature / direct	`BaseDocumentGenerator`, `BaseDocumentValidator`	Qualified signature + QR injection	Qualified signature integration not designed

Architectural notes

Transport interface

As the adapter count grows, a TransportInterface abstraction in core will prevent duplication across countries that share the same transport layer:

Transport	Countries
Direct API (clearance / reporting)	FR, RO, GR, HU
AS4 / Peppol network	BE, DE, Nordics/NL
Hybrid / hub	FR (PPF/PDP dual path)

Germany: 80% reuse from FR

Germany's mandate (active since Jan 2025 for B2B receiving) heavily favors ZUGFeRD/Factur-X — the same PDF-embedded XML model as the French Factur-X profile. The mcp-facture-electronique-fr XML generation and validation logic can be reused with minimal changes, making DE the lowest-effort next adapter after BE.

ViDA / DRR (2030)

By July 2030, all national systems must align with the EU Digital Reporting Requirement for cross-border transactions. Using EN 16931 as the internal InvoiceDocument data model in this core package already future-proofs the project: country adapters translate EN 16931 → local format, not the other way around.

License

Apache 2.0 — see LICENSE.

mcp-einvoicing-core

mcp-einvoicing-core

What this package provides

Installation

Architecture

Plugin registration pattern

Claude Desktop / Cursor / Kiro compatibility

Roadmap compatibility

Architectural notes

Transport interface

Germany: 80% reuse from FR

ViDA / DRR (2030)

License

Maintenance

Resources

Latest Blog Posts

MCP directory API