mcp-einvoicing-core 0.1.0__tar.gz

mcp_einvoicing_core-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,69 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Hatch
+        run: pip install hatch
+
+      - name: Build package
+        run: hatch build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for trusted publishing (no API key needed)
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  create-release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

mcp_einvoicing_core-0.1.0/.gitignore

@@ -0,0 +1,58 @@
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+*.DS_Store
+Icon?
+._*
+.Spotlight-V100
+.Trashes
+
+# Credentials & sensitive files
+*.env
+*.key
+*.pem
+cookie.file
+secrets/
+.secret
+*.secret
+*.credentials
+*.token
+
+# Logs
+*.log
+logs/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+env/
+dist/
+build/
+*.egg-info/
+.hatch/
+*.whl
+
+# Environment locals (secrets)
+.env
+.env.local
+.env.*.local
+
+# Tests & coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+coverage.xml
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Claude Code (local settings, memory, session data)
+.claude/

mcp_einvoicing_core-0.1.0/LICENSE

@@ -0,0 +1,191 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other transformations
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "contribution" means any work of authorship,
+      including the original version of the Work and any modifications or
+      additions to that Work or Derivative Works of the Work.
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent contributions
+      Licensable by such Contributor that are necessarily infringed by
+      their Contribution(s) alone or by the combination of their
+      Contribution(s) with the Work to which such Contribution(s) was
+      submitted. If You institute patent litigation against any entity
+      (including a cross-claim or counterclaim in a lawsuit) alleging that
+      the Work or any Work embodied within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or in addition to the
+          NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the
+      Contributions, either on an original or modified basis, or to
+      grant a third-party the rights to do so, provided you meet the
+      terms of this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may include an offer,
+      accepting, as described in Sections 1 and 2 above, for additional
+      warranty or additional liability obligations consistent with the
+      License. However, in accepting such obligations, You may offer only
+      on Your own behalf and on Your behalf of all other Contributors, and
+      only if You agree to indemnify, defend, and hold each Contributor
+      harmless for any liability incurred by, or claims asserted against,
+      such Contributor by reason of your accepting any such warranty or
+      additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the format in question; however, since the
+      file itself may be readable as a machine, you may not include
+      the brackets!  This is just an example notice; replace the text
+      according to your actual work.
+
+   Copyright 2026 Christophe Mendez
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

mcp_einvoicing_core-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: mcp-einvoicing-core
+Version: 0.1.0
+Summary: Base package for European electronic invoicing MCP servers
+Author: Christophe Mendez
+License: Apache-2.0
+License-File: LICENSE
+Keywords: b2b,e-invoicing,einvoicing,europe,mcp,peppol,ubl
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic-settings>=2.3.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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 | Standard | Inherits | Overrides | Known gaps |
+|---------|----------|----------|-----------|------------|
+| 🇫🇷 FR (existing) | XP Z12-013 | `BaseEInvoicingClient`, `BaseLifecycleManager` | `submit_lifecycle_status`, `healthcheck` | None |
+| 🇮🇹 IT (existing) | FatturaPA v1.6.1 | `BaseDocumentGenerator`, `BaseDocumentValidator`, `BaseDocumentParser`, `BasePartyValidator` | all abstract methods | `to_invoice_document()` not yet implemented |
+| 🇧🇪 BE 2026 | Peppol BIS 3.0 | all base classes | `generate()` → UBL 2.1, `validate()` → Schematron EN16931 | Need `BaseSchematronValidator` variant |
+| 🇵🇱 PL 2026 | KSeF FA(2) | `BaseDocumentGenerator`, `BaseDocumentValidator`, `BaseLifecycleManager` | KSeF session auth flow | `MTLS` auth mode not yet implemented |
+| 🇩🇪 DE | ZUGFeRD / XRechnung | all base classes | `generate()` returns PDF bytes (base64) | `generate()` return type: `str` vs `bytes` ambiguity |
+| 🇪🇸 ES | FACeB2B / FacturaE | all base classes | mTLS auth | `MTLS` auth mode not yet implemented |
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

mcp_einvoicing_core-0.1.0/README.md

@@ -0,0 +1,98 @@
+# 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 | Standard | Inherits | Overrides | Known gaps |
+|---------|----------|----------|-----------|------------|
+| 🇫🇷 FR (existing) | XP Z12-013 | `BaseEInvoicingClient`, `BaseLifecycleManager` | `submit_lifecycle_status`, `healthcheck` | None |
+| 🇮🇹 IT (existing) | FatturaPA v1.6.1 | `BaseDocumentGenerator`, `BaseDocumentValidator`, `BaseDocumentParser`, `BasePartyValidator` | all abstract methods | `to_invoice_document()` not yet implemented |
+| 🇧🇪 BE 2026 | Peppol BIS 3.0 | all base classes | `generate()` → UBL 2.1, `validate()` → Schematron EN16931 | Need `BaseSchematronValidator` variant |
+| 🇵🇱 PL 2026 | KSeF FA(2) | `BaseDocumentGenerator`, `BaseDocumentValidator`, `BaseLifecycleManager` | KSeF session auth flow | `MTLS` auth mode not yet implemented |
+| 🇩🇪 DE | ZUGFeRD / XRechnung | all base classes | `generate()` returns PDF bytes (base64) | `generate()` return type: `str` vs `bytes` ambiguity |
+| 🇪🇸 ES | FACeB2B / FacturaE | all base classes | mTLS auth | `MTLS` auth mode not yet implemented |
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

mcp_einvoicing_core-0.1.0/RELEASE.md

@@ -0,0 +1,48 @@
+# Release Notes
+
+## v0.1.0 — 2026-04-18
+
+Initial public release.
+
+### What's included
+
+**Abstract base classes** (`base_server.py`):
+- `BaseDocumentGenerator` — generate e-invoice documents from `InvoiceDocument`
+- `BaseDocumentValidator` — validate documents against a schema, returning `DocumentValidationResult`
+- `BaseDocumentParser` — parse raw XML/bytes into structured dicts or `InvoiceDocument`
+- `BaseLifecycleManager` — async submit, status, search, and lifecycle-event operations
+- `BasePartyValidator` — validate seller/buyer parties and tax identifiers
+- `EInvoicingMCPServer` — thin wrapper around `FastMCP` with plugin registration
+
+**Shared Pydantic v2 models** (`models.py`):
+- `TaxIdentifier`, `PartyAddress`, `InvoiceParty`, `InvoiceLineItem`
+- `VATSummary`, `PaymentTerms`, `InvoiceDocument`, `DocumentValidationResult`
+
+**XML utilities** (`xml_utils.py`):
+- `format_amount`, `format_quantity` — Decimal-safe monetary/quantity formatting
+- `validate_date_iso`, `validate_iban` — format validators
+- `xml_element`, `xml_optional`, `xml_escape` — XML building helpers
+- `format_error`, `filter_empty_values` — dict/response helpers
+
+**HTTP client** (`http_client.py`):
+- `BaseEInvoicingClient` — async httpx client with OAuth2 client_credentials, Bearer token, or no-auth modes; automatic token refresh and 401-retry
+- `TokenCache` — in-memory token cache with configurable expiry margin
+- `AuthMode` — enum (OAUTH2_CLIENT_CREDENTIALS, BEARER_TOKEN, NONE, MTLS†, API_KEY†)
+- `OAuthConfig`, `BaseEInvoicingConfig` — pydantic-settings base configs
+
+**Logging utilities** (`logging_utils.py`):
+- `setup_logging`, `get_logger` — stderr-based structured logging
+
+### Country packages using this base
+
+| Package | Version | Country |
+|---------|---------|---------|
+| `mcp-facture-electronique-fr` | v0.2.0 | 🇫🇷 France (AFNOR XP Z12-013) |
+| `mcp-fattura-elettronica-it` | v0.2.0 | 🇮🇹 Italy (FatturaPA v1.6.1 / SDI) |
+
+### Known limitations
+
+- MTLS and API_KEY auth modes are stubs (raise `NotImplementedError`)
+- `BaseDocumentParser.to_invoice_document()` raises `NotImplementedError` by default
+- `BaseLifecycleManager.submit_lifecycle_status()` and `healthcheck()` are stubs
+- `lxml` is intentionally excluded — country packages that need XSD validation must declare it as their own dependency

mcp_einvoicing_core-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-einvoicing-core"
+version = "0.1.0"
+description = "Base package for European electronic invoicing MCP servers"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Christophe Mendez" }]
+keywords = ["mcp", "einvoicing", "e-invoicing", "europe", "b2b", "peppol", "ubl"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: Apache Software License",
+    "Topic :: Office/Business :: Financial :: Accounting",
+]
+
+# [DECISION: minimal deps] Only include what is strictly needed by every country adapter.
+# lxml is deliberately excluded — only countries that need XSD/XML validation (IT, DE, BE...)
+# include it in their own pyproject.toml.  pydantic-settings is included because every
+# country needs some form of env-var config, even if minimal.
+dependencies = [
+    "fastmcp>=2.0.0",
+    "httpx>=0.27.0",
+    "pydantic>=2.7.0",
+    "pydantic-settings>=2.3.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-httpx>=0.30.0",
+    "mypy>=1.10.0",
+    "ruff>=0.4.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_einvoicing_core"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "tests/",
+    ".env*",
+    ".DS_Store",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true