mcp-einvoicing-core
English | Francais | Deutsch | Italiano | Espanol | Portugues (Brasil) | العربية
Topics: mcp mcp-server e-invoicing electronic-invoicing python fastmcp peppol en16931 ubl fatturapa xp-z12-013 nfe xml base-library
Base package for electronic invoicing MCP servers.
Provides shared Pydantic models, EN 16931 invoice tree, UBL/CII wire format serializers, an OAuth2 HTTP client, Peppol SMP lookup, digital signature primitives, and a compliance audit framework so country-specific packages share a common foundation without duplicating code.
What this package provides
| Module | Contents |
|---|---|
models | InvoiceDocument, InvoiceParty, InvoiceLineItem, PartyAddress, VATSummary, PaymentTerms, DocumentValidationResult, TaxIdentifier (per-country tax ID validators: IT, FR, DE, BE, ES, PL, BR), TaxIdValidationResult |
en16931 | EN16931Invoice, EN16931Party, EN16931LineItem, EN16931Address, EN16931Tax, EN16931AllowanceCharge, EN16931PaymentMeans |
credit_note | EN16931CreditNote (type codes 381/383/384/385), BillingReference |
wire_formats | EN16931UBLSerializer, EN16931UBLParser, EN16931CIISerializer, EN16931CIIParser, UBL_NSMAP, CII_NSMAP |
convert | Syntax (UBL, CII), convert_wire_format (auto-detect source, serialize to target) |
base_server | EInvoicingMCPServer, BaseDocumentGenerator, BaseDocumentValidator, BaseDocumentParser, BaseLifecycleManager, BasePartyValidator, SubmitResult, assert_not_read_only, scrub |
http_client | BaseEInvoicingClient (OAuth2, mTLS, bearer, API key, JWS, none), OAuthConfig, OAuthValues, JWSConfig, TokenCache, AuthMode |
peppol | PeppolSMPClient, PeppolParticipantId, PeppolServiceInfo, PeppolLookupResult, PeppolEnvironment, PEPPOL_BIS_BILLING_30 |
peppol.transport | AS4MessageEnvelope, AS4TransportClient, AS4ReceiptHandler, PeppolTransmitter, AS4Receipt, AS4Credentials (Peppol AS4 outbound transmission) |
schematron | SchematronValidator (XSLT 1.0), SaxonSchematronValidator (XSLT 2.0/3.0, optional [xslt2] extra), load_schematron_validator (auto-dispatch factory), get_xslt_version, BaseStructuredValidator, BaseXSDValidator, BaseJSONValidator, ValidationMessage, ValidationResult |
digital_signature | BaseDocumentSigner, XAdESEPESSigner, XAdESSignerConfig, XMLDSigSigner, XMLDSigSignerConfig, load_certificate_der |
endpoints | BaseEnvironmentEndpoints, EndpointSet, EndpointEnvironment (sandbox/production URL routing) |
routing | RoutingIdentifier (static validators: validate_de_leitweg), RoutingIdValidationResult |
profile_registry | ProfileEntry, ProfileRegistry, profile_registry, set_profile_registry |
pdf | PDFEmbedder (PDF/A-3 XML embedding) |
qr | generate_qr_png_base64 |
xml_utils | format_amount, format_quantity, xml_element, xml_optional, validate_date_iso, validate_iban, resolve_xml_input, mark_untrusted, mark_untrusted_fields, filter_empty_values, format_error |
download_rules | DownloadSpec, download_artefacts |
testing | InvoiceFixtureFactory (shared pytest fixtures) |
audit_log | AuditLog, AuditAction, get_audit_log |
confirmation | ConfirmationGate, ConfirmationStore (human-in-the-loop gate) |
exceptions | EInvoicingError, ValidationError, PartyValidationError, XSDValidationError, SchematronValidationError, DocumentGenerationError, AuthenticationError, PlatformError |
logging_utils | setup_logging, get_logger |
audit | Compliance audit framework: AuditReport, CheckResult, CheckFinding, severity constants, make_report, render_summary_table, parse_audit_args, run_check_core_coverage, run_check_version_compatibility, run_check_known_shared_helpers, TaxRate, load_rates (optional [audit] extra) |
Installation
pip install mcp-einvoicing-core
For the compliance audit framework (used by country package CI):
pip install mcp-einvoicing-core[audit]
For XSLT 2.0/3.0 Schematron validation (SaxonSchematronValidator — needed for Schematron
rule sets using XPath 2.0+ constructs, e.g. FNFE-MPE Factur-X 1.08 / ZUGFeRD):
pip install mcp-einvoicing-core[xslt2]
Architecture
Country packages subclass the core abstractions and register their tools on a shared or standalone MCP server:
mcp-einvoicing-core
├── EN16931Invoice / InvoiceDocument ← canonical invoice models
├── EN16931CreditNote ← credit note (type codes 381/383/384/385)
├── EN16931UBL/CII Serializer/Parser ← wire format round-trip
├── convert_wire_format ← CII ↔ UBL conversion
├── BaseDocumentGenerator/Validator/Parser/LifecycleManager
├── BaseEInvoicingClient ← async HTTP (OAuth2/mTLS/bearer/API key/JWS)
├── PeppolSMPClient ← participant lookup via SMP/SML
├── PeppolTransmitter ← AS4 outbound transmission
├── BaseDocumentSigner ← XAdES-EPES / XMLDSig
├── BaseEnvironmentEndpoints ← sandbox/production URL routing
├── RoutingIdentifier ← country-specific routing ID validation
├── EInvoicingMCPServer ← plugin registry wrapping FastMCP
└── Audit framework ← per-package compliance checks
Country packages
| Country | Package | Standard |
|---|---|---|
| France | mcp-facture-electronique-fr | NF XP Z12-012 / NF XP Z12-013 / Factur-X / UBL 2.1 / CII |
| Germany | mcp-einvoicing-de | ZUGFeRD 2.x / XRechnung 3.x |
| Belgium | mcp-einvoicing-be | Peppol BIS 3.0 / PINT-BE |
| Italy | mcp-fattura-elettronica-it | FatturaPA / SDI |
| Poland | mcp-ksef-pl | KSeF FA(3) / FA(2) / Peppol BIS 3.0 |
| Spain | mcp-facturacion-electronica-es | Factura-e / VeriFactu / SII / FACe |
| Brazil | mcp-nfe-br | NF-e / NFC-e (modelo 55/65, schema 4.00) / NFS-e Nacional |
Plugin registration pattern
Country packages register their tools on a shared or standalone FastMCP instance:
# Standalone
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 country packages require no changes: tool names,
signatures, environment variables, and entry points (server:main) are fully preserved.
License
Apache 2.0 -- see LICENSE.