https://github.com/cmendezs/mcp-einvoicing-core
Base library for building MCP e-invoicing servers: abstract base classes, shared Pydantic models, XML utilities, and OAuth2-capable async HTTP client.
https://github.com/cmendezs/mcp-einvoicing-core
base-library e-invoicing electronic-invoicing european-invoicing fastmcp mcp mcp-server peppol python
Last synced: about 23 hours ago
JSON representation
Base library for building MCP e-invoicing servers: abstract base classes, shared Pydantic models, XML utilities, and OAuth2-capable async HTTP client.
- Host: GitHub
- URL: https://github.com/cmendezs/mcp-einvoicing-core
- Owner: cmendezs
- License: apache-2.0
- Created: 2026-04-19T07:09:46.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-10T11:50:53.000Z (5 days ago)
- Last Synced: 2026-06-10T13:21:29.935Z (5 days ago)
- Topics: base-library, e-invoicing, electronic-invoicing, european-invoicing, fastmcp, mcp, mcp-server, peppol, python
- Language: Python
- Homepage:
- Size: 2.39 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# mcp-einvoicing-core
[](LICENSE)
[](https://pypi.org/project/mcp-einvoicing-core/)
[](https://pypi.org/project/mcp-einvoicing-core/)[](https://glama.ai/mcp/servers/cmendezs/mcp-einvoicing-core)
**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
```bash
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:
```python
# 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](https://github.com/cmendezs/mcp-einvoicing-be) | ✅ Done | Peppol BIS 3.0 | AS4 / Peppol | all base classes | `generate()` → UBL 2.1, `validate()` → Schematron EN16931 | None |
| [🇫🇷 FR](https://github.com/cmendezs/mcp-facture-electronique-fr) | ✅ Done | XP Z12-013 | Hybrid / PPF hub | `BaseEInvoicingClient`, `BaseLifecycleManager` | `submit_lifecycle_status`, `healthcheck` | None |
| [🇩🇪 DE](https://github.com/cmendezs/mcp-einvoicing-de) | ✅ Done | ZUGFeRD / XRechnung | AS4 / Peppol | all base classes | `generate()` returns PDF bytes (base64) | `generate()` return type: `str` vs `bytes` ambiguity |
| [🇮🇹 IT](https://github.com/cmendezs/mcp-fattura-elettronica-it) | ✅ Done | FatturaPA v1.6.1 | Direct / SDI | `BaseDocumentGenerator`, `BaseDocumentValidator`, `BaseDocumentParser`, `BasePartyValidator` | all abstract methods | `to_invoice_document()` not yet implemented |
| [🇵🇱 PL](https://github.com/cmendezs/mcp-ksef-pl) | ✅ Done | KSeF FA(2) | Direct API | `BaseDocumentGenerator`, `BaseDocumentValidator`, `BaseLifecycleManager` | KSeF session auth flow | `MTLS` auth mode not yet implemented |
| [🇪🇸 ES](https://github.com/cmendezs/mcp-facturacion-electronica-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](LICENSE).