mcp-einvoicing-core

![License](LICENSE) ![PyPI version](https://pypi.org/project/mcp-einvoicing-core/) ![Python](https://pypi.org/project/mcp-einvoicing-core/)![mcp-einvoicing-core MCP server](https://glama.ai/mcp/servers/cmendezs/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, none), OAuthConfig, OAuthValues, 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 | | 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)
  ├── 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.

MCP E-Invoicing Core