{"id":49039376,"url":"https://github.com/cmendezs/mcp-einvoicing-core","last_synced_at":"2026-06-14T22:02:18.295Z","repository":{"id":352367545,"uuid":"1214880201","full_name":"cmendezs/mcp-einvoicing-core","owner":"cmendezs","description":"Base library for building MCP e-invoicing servers: abstract base classes, shared Pydantic models, XML utilities, and OAuth2-capable async HTTP client.","archived":false,"fork":false,"pushed_at":"2026-06-10T11:50:53.000Z","size":2503,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T13:21:29.935Z","etag":null,"topics":["base-library","e-invoicing","electronic-invoicing","european-invoicing","fastmcp","mcp","mcp-server","peppol","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cmendezs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-19T07:09:46.000Z","updated_at":"2026-06-10T11:51:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cmendezs/mcp-einvoicing-core","commit_stats":null,"previous_names":["cmendezs/mcp-einvoicing-core"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/cmendezs/mcp-einvoicing-core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmendezs%2Fmcp-einvoicing-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmendezs%2Fmcp-einvoicing-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmendezs%2Fmcp-einvoicing-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmendezs%2Fmcp-einvoicing-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cmendezs","download_url":"https://codeload.github.com/cmendezs/mcp-einvoicing-core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmendezs%2Fmcp-einvoicing-core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34339195,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["base-library","e-invoicing","electronic-invoicing","european-invoicing","fastmcp","mcp","mcp-server","peppol","python"],"created_at":"2026-04-19T14:09:36.149Z","updated_at":"2026-06-14T22:02:18.289Z","avatar_url":"https://github.com/cmendezs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mcp-einvoicing-core\n\n\u003c!-- mcp-name: io.github.cmendezs/mcp-einvoicing-core --\u003e\n\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n[![PyPI version](https://img.shields.io/pypi/v/mcp-einvoicing-core.svg)](https://pypi.org/project/mcp-einvoicing-core/)\n[![Python](https://img.shields.io/pypi/pyversions/mcp-einvoicing-core.svg)](https://pypi.org/project/mcp-einvoicing-core/)[![mcp-einvoicing-core MCP server](https://glama.ai/mcp/servers/cmendezs/mcp-einvoicing-core/badges/score.svg)](https://glama.ai/mcp/servers/cmendezs/mcp-einvoicing-core)\n\n**Topics:** `mcp` `mcp-server` `e-invoicing` `electronic-invoicing` `european-invoicing` `python` `fastmcp` `peppol` `en16931` `ubl` `fatturapa` `xp-z12-013` `xml` `base-library`\n\nBase package for European electronic invoicing MCP servers.\n\nProvides abstract base classes, shared Pydantic models, XML utilities, and an HTTP client\nso country-specific packages (`mcp-facture-electronique-fr`, `mcp-fattura-elettronica-it`, …)\nshare a common foundation without duplicating code.\n\n---\n\n## What this package provides\n\n| Module | Contents | Used by |\n|--------|----------|---------|\n| `models.py` | `InvoiceParty`, `InvoiceLineItem`, `VATSummary`, `PaymentTerms`, `InvoiceDocument`, `DocumentValidationResult` | IT (structured invoice generation), future BE/PL/DE/ES |\n| `base_server.py` | `BaseDocumentGenerator`, `BaseDocumentValidator`, `BaseDocumentParser`, `BaseLifecycleManager`, `BasePartyValidator`, `EInvoicingMCPServer` | All country adapters |\n| `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 |\n| `http_client.py` | `TokenCache`, `OAuthConfig`, `BaseEInvoicingClient` (OAuth2 + no-auth) | FR (extracted verbatim), future API-based countries |\n| `exceptions.py` | `EInvoicingError`, `ValidationError`, `PartyValidationError`, `XSDValidationError`, `DocumentGenerationError`, `AuthenticationError`, `PlatformError` | All country adapters |\n| `logging_utils.py` | `setup_logging`, `get_logger` | All country adapters |\n\n## Installation\n\n```bash\npip install mcp-einvoicing-core\n```\n\nThis package has **no country-specific dependencies**. `lxml` (needed for XSD validation\nin IT and future countries) is declared by each country package individually.\n\n## Architecture\n\n```\nmcp-einvoicing-core           ← this package\n  ├── BaseDocumentGenerator   ← abstract: generate(InvoiceDocument) → str\n  ├── BaseDocumentValidator   ← abstract: validate(xml) → DocumentValidationResult\n  ├── BaseDocumentParser      ← abstract: parse(xml) → dict\n  ├── BaseLifecycleManager    ← abstract: submit/search/get_status (async HTTP)\n  ├── BasePartyValidator      ← abstract: validate_seller/buyer/tax_id\n  ├── BaseEInvoicingClient    ← concrete: async HTTP + OAuth2/no-auth/token\n  ├── InvoiceDocument (Pydantic)  ← shared data model\n  └── EInvoicingMCPServer     ← plugin registry wrapping FastMCP\n\nmcp-facture-electronique-fr   ← country adapter (FR)\n  ├── PAConfig(OAuthConfig)\n  ├── FlowClient(BaseEInvoicingClient)      ← OAuth2, XP Z12-013 Annex A\n  ├── DirectoryClient(BaseEInvoicingClient) ← OAuth2, XP Z12-013 Annex B\n  └── FrLifecycleManager(BaseLifecycleManager)\n\nmcp-fattura-elettronica-it    ← country adapter (IT)\n  ├── ItalyPartyValidator(BasePartyValidator)   ← Partita IVA modulo-10\n  ├── FatturaGenerator(BaseDocumentGenerator)   ← FatturaPA XML v1.6.1\n  ├── FatturaValidator(BaseDocumentValidator)   ← lxml XSD v1.6.1\n  └── FatturaParser(BaseDocumentParser)         ← lxml xpath\n```\n\n## Plugin registration pattern\n\nCountry packages register their tools on a shared or standalone FastMCP instance:\n\n```python\n# Standalone (existing server.py — no changes required)\nfrom fastmcp import FastMCP\nmcp = FastMCP(name=\"mcp-fattura-elettronica-it\", instructions=\"…\")\nregister_header_tools(mcp)\nregister_body_tools(mcp)\nregister_global_tools(mcp)\n\n# Multi-country (optional EInvoicingMCPServer)\nfrom mcp_einvoicing_core import EInvoicingMCPServer\nserver = EInvoicingMCPServer(name=\"mcp-einvoicing-eu\", instructions=\"…\")\nserver.register_plugin(register_header_tools, \"it-header\")\nserver.register_plugin(register_flow_tools, \"fr-flow\")\nserver.run()\n```\n\n## Claude Desktop / Cursor / Kiro compatibility\n\nExisting configurations for `mcp-facture-electronique-fr` and `mcp-fattura-elettronica-it`\nrequire **no changes**: tool names, signatures, environment variables, and entry points\n(`server:main`) are fully preserved.\n\n## Roadmap compatibility\n\n| Country | Status | Standard | Transport | Inherits | Overrides | Known gaps |\n|---------|--------|----------|-----------|----------|-----------|------------|\n| [🇧🇪 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 |\n| [🇫🇷 FR](https://github.com/cmendezs/mcp-facture-electronique-fr) | ✅ Done | XP Z12-013 | Hybrid / PPF hub | `BaseEInvoicingClient`, `BaseLifecycleManager` | `submit_lifecycle_status`, `healthcheck` | None |\n| [🇩🇪 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 |\n| [🇮🇹 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 |\n| [🇵🇱 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 |\n| [🇪🇸 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 |\n| 🇷🇴 RO | 📋 Backlog | RO-UBL (EN 16931) | Direct API / clearance | `BaseDocumentGenerator`, `BaseLifecycleManager` | ANAF clearance flow | `BaseSchematronValidator` variant needed |\n| 🇬🇷 GR | 📋 Backlog | myDATA XML | Direct API / reporting | `BaseEInvoicingClient`, `BaseLifecycleManager` | myDATA auth + reporting flow | myDATA API client not yet designed |\n| 🇳🇱🇸🇪🇩🇰🇳🇴 Nordics/NL | 📋 Backlog | Peppol BIS 3.0 / UBL | AS4 / Peppol | all base classes | `generate()` → UBL 2.1, `validate()` → Schematron | Reuses BE AS4 transport layer |\n| 🇵🇹 PT | 📋 Backlog | CIUS-PT + QR Code | Signature / direct | `BaseDocumentGenerator`, `BaseDocumentValidator` | Qualified signature + QR injection | Qualified signature integration not designed |\n\n## Architectural notes\n\n### Transport interface\n\nAs the adapter count grows, a `TransportInterface` abstraction in core will prevent duplication across countries that share the same transport layer:\n\n| Transport | Countries |\n|-----------|-----------|\n| **Direct API** (clearance / reporting) | FR, RO, GR, HU |\n| **AS4 / Peppol network** | BE, DE, Nordics/NL |\n| **Hybrid / hub** | FR (PPF/PDP dual path) |\n\n### Germany: 80% reuse from FR\n\nGermany'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.\n\n### ViDA / DRR (2030)\n\nBy 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.\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmendezs%2Fmcp-einvoicing-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcmendezs%2Fmcp-einvoicing-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmendezs%2Fmcp-einvoicing-core/lists"}