mcp-einvoicing-core

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`, `resolve_naptr` (standalone U-NAPTR/SML DNS diagnostic)
`peppol.tools`	`register_peppol_tools` (mountable FastMCP plugin: participant lookup, service endpoint, DNS diagnostic, AS4 send, plus 8 eDEC code list tools), `default_id_adapter`, `IdentifierAdapter` (national identifier adapter contract)
`peppol.codelists`	`CodeList`, `CodelistNotConfiguredError`, `load_codelist` and the eDEC lookup functions (document types, processes, participant ID schemes, transport profiles, SPIS use cases). Requires `EINVOICING_PEPPOL_CODELIST_DIR`, see Configuration below
`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`
`schematron_artifacts`	`en16931_base_schematron_validator` (bundled, compiled CEN EN16931 base Schematron — `BR-*` rules only, no Peppol overlay; optional `[xslt2]` extra)
`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); `extract(filename=None)` tries canonical Factur-X/XRechnung/ZUGFeRD filenames in turn, `identify()` reads XMP to detect a hybrid PDF and its conformance level
`pdf_tools`	`register_pdf_tools` (mountable FastMCP plugin: `identify_and_extract_pdf`), `identify_and_extract_pdf`
`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)

Country packages

Country	Package	Standard	Scope	Coverage status
🇧🇪 Belgium	`mcp-einvoicing-be`	Peppol BIS 3.0 / PINT-BE	B2B, 1 January 2026	Live; Peppol-specific overlay rules not checked (EN 16931 base only)
🇧🇷 Brazil	`mcp-nfe-br`	NF-e / NFC-e (modelo 55/65, schema 4.00) / NFS-e Nacional	B2B (NF-e) + B2C (NFC-e), both mandatory since 2008	Live; IBS/CBS tax reform rollout ongoing through 2033
🇫🇷 France	`mcp-facture-electronique-fr`	NF XP Z12-012 / NF XP Z12-013 / Factur-X / UBL 2.1 / CII	B2B, phased rollout from 1 September 2026	Live
🇩🇪 Germany	`mcp-einvoicing-de`	ZUGFeRD 2.x / XRechnung 3.x	B2B, phased 2025 to 2028	Live
🇮🇹 Italy	`mcp-fattura-elettronica-it`	FatturaPA / SDI	B2G + B2B + B2C, mandatory since 2019 (B2G since 2014)	Live
🇵🇱 Poland	`mcp-ksef-pl`	KSeF FA(3) / FA(2) / Peppol BIS 3.0	B2B, phased February 2026 to January 2027	Live; batch session flow not implemented
🇪🇸 Spain	`mcp-facturacion-electronica-es`	Factura-e / VeriFactu / SII / FACe	Pending Orden Ministerial, targeted 2026-10-01	Live for VeriFactu/SII; B2B format wiring blocked on pending Orden Ministerial

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]

Configuration

Variable	Used by	Purpose
`EINVOICING_PEPPOL_CODELIST_DIR`	`peppol.codelists` (and the `peppol.tools` codelist tools)	Local directory containing your own copy of the OpenPeppol eDEC Code Lists. Not bundled with this package: the eDEC Code Lists carry no confirmed redistribution grant from OpenPeppol, so core ships only the parser and lookup tools, never the data itself. Download the "as GeneriCode" export for each artifact (Document Types, Participant Identifier Schemes, Processes, Transport Profiles, SPIS Use Case) from docs.peppol.eu/edelivery/codelists and point this variable at the directory containing them. Filenames are matched by prefix, so a version bump (e.g. v9.7 to v9.8) needs no code change. Without this set, the codelist tools return a `configured: false` result with setup instructions rather than raising.
`EINVOICING_SMP_ALLOWLIST`	`peppol` (`PeppolSMPClient`, `resolve_naptr`)	Comma-separated hostname suffixes to extend the built-in Peppol Access Point allowlist used when validating a resolved SMP hostname.

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

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

Core also ships its own mountable Peppol tool plugin so country packages stop reimplementing SMP lookup and AS4 send. Supply a national identifier adapter (a small function that normalizes a bare national number, e.g. a VAT number, into a Peppol "<scheme>:<value>" participant ID):

from mcp_einvoicing_core.peppol.tools import register_peppol_tools

def be_id_adapter(identifier: str) -> str:
    if ":" in identifier:
        return identifier
    return f"0208:{normalize_vat_be(identifier)[2:]}"  # KBO/BCE scheme

server.register_plugin(
    lambda m: register_peppol_tools(m, id_adapter=be_id_adapter), "peppol"
)

This registers peppol_lookup_participant, peppol_get_service_endpoint, resolve_peppol_dns, peppol_send, and 8 OpenPeppol eDEC code list tools (see Configuration above for EINVOICING_PEPPOL_CODELIST_DIR, required for the code list tools).

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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mcp_einvoicing_core-1.19.1.tar.gz (3.6 MB view details)

Uploaded Aug 23, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

mcp_einvoicing_core-1.19.1-py3-none-any.whl (228.8 kB view details)

Uploaded Aug 23, 2026 Python 3

File details

Details for the file mcp_einvoicing_core-1.19.1.tar.gz.

File metadata

Download URL: mcp_einvoicing_core-1.19.1.tar.gz
Upload date: Aug 23, 2026
Size: 3.6 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mcp_einvoicing_core-1.19.1.tar.gz
Algorithm	Hash digest
SHA256	`5b146eb2c166cc1a3d5104f191b1d7d88109b5ca7e432d5eda6993e1ba5d6f19`
MD5	`680341ac4f43ac3b2214cc1f309fd68e`
BLAKE2b-256	`b1b9d2f6c42c1b59f978edabf63f01879ab3b6813b8e1744c4e1d7b5db654f54`

See more details on using hashes here.

Provenance

The following attestation bundles were made for mcp_einvoicing_core-1.19.1.tar.gz:

Publisher: publish.yml on cmendezs/mcp-einvoicing-core

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: mcp_einvoicing_core-1.19.1.tar.gz
- Subject digest: 5b146eb2c166cc1a3d5104f191b1d7d88109b5ca7e432d5eda6993e1ba5d6f19
- Sigstore transparency entry: 2569609298
- Sigstore integration time: Aug 23, 2026
Source repository:
- Permalink: cmendezs/mcp-einvoicing-core@2ab55c0f6551eb51d15d815e50a48a805954a814
- Branch / Tag: refs/tags/v1.19.1
- Owner: https://github.com/cmendezs
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@2ab55c0f6551eb51d15d815e50a48a805954a814
- Trigger Event: push