mcp-einvoicing-de 0.1.0__tar.gz

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

@@ -0,0 +1,138 @@
+name: CI / Publish to PyPI
+
+on:
+  push:
+    branches: [main]
+    tags:
+      - "v*"
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  # ── 1. Tests ───────────────────────────────────────────────────────────────
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package + dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check mcp_einvoicing_de/ tests/ audit/
+
+      - name: Type-check with mypy
+        run: mypy mcp_einvoicing_de/
+        continue-on-error: true  # Non-blocking until type stubs are complete
+
+      - name: Run tests
+        run: pytest --tb=short
+
+      - name: Upload coverage report
+        if: matrix.python-version == '3.11'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: htmlcov/
+
+  # ── 2. Pre-publish audit ───────────────────────────────────────────────────
+  audit:
+    name: Pre-publish audit vs mcp-einvoicing-core
+    needs: test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install package + core
+        run: pip install -e ".[dev]"
+
+      - name: Run pre-publish audit
+        # Exit code 2 = blocking failures → job fails → publish is blocked
+        # Exit code 1 = warnings only     → job passes (informational)
+        run: python audit/audit_vs_core.py --output audit/report.json --fail-on blocking
+
+      - name: Upload audit report
+        if: always()   # Upload even on failure so the report is inspectable
+        uses: actions/upload-artifact@v4
+        with:
+          name: audit-report
+          path: audit/report.json
+
+  # ── 3. Build distribution ──────────────────────────────────────────────────
+  build:
+    name: Build distribution packages
+    needs: audit
+    runs-on: ubuntu-latest
+    # Only build on tag pushes
+    if: startsWith(github.ref, 'refs/tags/v')
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Upload distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist-packages
+          path: dist/
+
+  # ── 4. Publish to PyPI ─────────────────────────────────────────────────────
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # Only publish on tag pushes; audit must have passed (via the needs chain)
+    if: startsWith(github.ref, 'refs/tags/v')
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mcp-einvoicing-de
+
+    permissions:
+      id-token: write   # Required for OIDC trusted publisher
+
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: dist-packages
+          path: dist/
+
+      - name: Publish to PyPI via trusted publisher (OIDC)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # No API token needed — uses GitHub OIDC trusted publisher.
+        # Configure the trusted publisher at:
+        # https://pypi.org/manage/project/mcp-einvoicing-de/settings/publishing/

mcp_einvoicing_de-0.1.0/.gitignore

@@ -0,0 +1,74 @@
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+*.DS_Store
+Icon?
+._*
+.Spotlight-V100
+.Trashes
+
+# Credentials & sensitive files
+*.env
+*.key
+*.pem
+cookie.file
+secrets/
+.secret
+*.secret
+wp-config.php
+config.php
+*.credentials
+*.token
+
+# Logs
+*.log
+logs/
+
+# Node
+node_modules/
+npm-debug.log*
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+env/
+dist/
+build/
+*.egg-info/
+.hatch/
+*.whl
+
+# Environnement local (secrets)
+.env
+.env.local
+.env.*.local
+
+# Tests et couverture
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+coverage.xml
+
+# Fichiers de factures de test sensibles
+tests/fixtures/*.xml
+tests/fixtures/*.pdf
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Claude Code (local settings, memory, session data)
+.claude/
+
+# Pre-publish audit output (generated artefacts)
+audit/report.json
+
+# Schematron XSLT resources (downloaded at runtime, not committed)
+mcp_einvoicing_de/resources/

mcp_einvoicing_de-0.1.0/Makefile

@@ -0,0 +1,47 @@
+.PHONY: install dev-install test lint typecheck audit clean build help
+
+PYTHON   := python3
+PKG      := mcp_einvoicing_de
+AUDIT_OUT := audit/report.json
+
+help:          ## Show this help message
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+	  | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-18s\033[0m %s\n", $$1, $$2}'
+
+install:       ## Install the package (production deps only)
+	pip install -e .
+
+dev-install:   ## Install the package with all dev dependencies
+	pip install -e ".[dev]"
+
+test:          ## Run the test suite with coverage
+	pytest --tb=short
+
+lint:          ## Run ruff linter
+	ruff check $(PKG)/ tests/ audit/
+
+lint-fix:      ## Run ruff with auto-fix
+	ruff check --fix $(PKG)/ tests/ audit/
+
+typecheck:     ## Run mypy type checker
+	mypy $(PKG)/
+
+audit:         ## Run pre-publish audit against mcp-einvoicing-core
+	$(PYTHON) audit/audit_vs_core.py --output $(AUDIT_OUT)
+
+audit-strict:  ## Run audit; exit non-zero on any warning
+	$(PYTHON) audit/audit_vs_core.py --output $(AUDIT_OUT) --fail-on warnings
+
+audit-ci:      ## Run audit in CI mode (blocking failures only)
+	$(PYTHON) audit/audit_vs_core.py --output $(AUDIT_OUT) --fail-on blocking
+
+build:         ## Build wheel and sdist
+	$(PYTHON) -m build
+
+clean:         ## Remove build artefacts and caches
+	rm -rf dist/ build/ *.egg-info/ .pytest_cache/ htmlcov/ .coverage coverage.xml
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -name "*.pyc" -delete
+
+run:           ## Start the MCP server (stdio transport)
+	mcp-einvoicing-de

mcp_einvoicing_de-0.1.0/PKG-INFO

@@ -0,0 +1,345 @@
+Metadata-Version: 2.4
+Name: mcp-einvoicing-de
+Version: 0.1.0
+Summary: MCP server for German electronic invoicing (ZUGFeRD 2.x, XRechnung 3.x, EN 16931)
+Project-URL: Homepage, https://github.com/cmendezs/mcp-einvoicing-de
+Project-URL: Repository, https://github.com/cmendezs/mcp-einvoicing-de
+Project-URL: Issues, https://github.com/cmendezs/mcp-einvoicing-de/issues
+Author: cmendezs
+License: Apache-2.0
+Keywords: cii,e-invoicing,einvoicing,en16931,germany,mcp,peppol,ubl,xrechnung,zugferd
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: lxml>=5.0.0
+Requires-Dist: mcp-einvoicing-core<1.0.0,>=0.3.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dateutil>=2.9.0
+Requires-Dist: reportlab>=4.0.0
+Provides-Extra: dev
+Requires-Dist: lxml-stubs>=0.5.0; extra == 'dev'
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Requires-Dist: types-python-dateutil>=2.9.0; extra == 'dev'
+Requires-Dist: types-reportlab>=0.1.0; extra == 'dev'
+Provides-Extra: pdf
+Requires-Dist: pikepdf>=8.0.0; extra == 'pdf'
+Provides-Extra: pymupdf
+Requires-Dist: pymupdf>=1.24.0; extra == 'pymupdf'
+Description-Content-Type: text/markdown
+
+# mcp-einvoicing-de 🇩🇪
+<!-- mcp-name: io.github.cmendezs/mcp-einvoicing-de -->
+
+![License](https://img.shields.io/badge/License-MIT-yellow.svg)
+[![PyPI version](https://img.shields.io/pypi/v/mcp-einvoicing-de.svg)](https://pypi.org/project/mcp-einvoicing-de/)
+[![Python](https://img.shields.io/pypi/pyversions/mcp-einvoicing-de.svg)](https://pypi.org/project/mcp-einvoicing-de/)
+[![mcp-einvoicing-de MCP server](https://glama.ai/mcp/servers/cmendezs/mcp-einvoicing-de/badges/score.svg)](https://glama.ai/mcp/servers/cmendezs/mcp-einvoicing-de)
+
+MCP-Server (Model Context Protocol) in Python für die **deutsche elektronische Rechnung** in den Formaten **ZUGFeRD 2.x** und **XRechnung 3.x** (EN 16931, FeRD, KoSIT). Ermöglicht KI-Agenten (Claude, IDEs) das Erstellen, Validieren, Parsen und Konvertieren von E-Rechnungen, die vollständig dem deutschen B2B-E-Rechnungsmandat (gültig ab 2025, schrittweise Durchsetzung bis 2027–2028) und der europäischen Norm EN 16931 entsprechen.
+
+---
+
+## English summary
+
+This is a **Model Context Protocol (MCP)** server for **German electronic invoicing**. It exposes **6 tools** covering the full lifecycle of a ZUGFeRD or XRechnung invoice: creation (CII/UBL XML), validation against EN 16931 and KoSIT Schematron rules (BR-DE-*), parsing of existing invoice files, profile and syntax conversion, Peppol participant registration lookup (AS4), and German VAT rules (Steuerklassen, §13b UStG reverse charge, exemptions). Supports all ZUGFeRD 2.x profiles (MINIMUM through EXTENDED) and XRechnung 3.x (CII and UBL syntax). Licensed under **MIT**.
+
+## Aufgebaut auf
+
+Dieses Paket basiert auf [**mcp-einvoicing-core**](https://github.com/cmendezs/mcp-einvoicing-core), einer gemeinsamen Basisbibliothek für europäische E-Rechnungs-MCP-Server. Sie stellt gemeinsame Modelle, Validierungsabstraktionen, XML-Hilfsfunktionen und die Ausnahmehierarchie bereit.
+
+`mcp-einvoicing-core` wird automatisch als transitive Abhängigkeit installiert — kein zusätzlicher Schritt erforderlich.
+
+> **Für Entwickler:** `pip install -e ".[dev]"` installiert das Basispaket automatisch aus PyPI.
+
+---
+
+## 🏗️ Architektur
+
+```
+mcp-einvoicing-de (dieses Paket — eigenständiger MCP-Server)
+├── ZUGFeRDInvoice / XRechnungInvoice  ← Pydantic-Modelle (alle Profile)
+├── SchematronValidator                ← EN 16931 + KoSIT BR-DE-* Regeln
+├── KoSITValidator                     ← Remote-Validierungstool (optional)
+└── Tools: create / validate / parse / convert / peppol_check / tax_rules
+
+        ↑ erweitert
+mcp-einvoicing-core (gemeinsame Basis, als Abhängigkeit installiert)
+├── BaseDocumentGenerator / Validator / Parser
+├── BaseInvoice, BaseParty … (Pydantic)
+├── xml_utils, exceptions
+└── EInvoicingMCPServer
+```
+
+---
+
+## 🚀 Installation
+
+### Über PyPI (empfohlen)
+
+```bash
+pip install mcp-einvoicing-de
+```
+
+Ohne vorherige Installation mit `uvx`:
+
+```bash
+uvx mcp-einvoicing-de
+```
+
+### Aus den Quellen
+
+```bash
+git clone https://github.com/cmendezs/mcp-einvoicing-de.git
+cd mcp-einvoicing-de
+
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+
+pip install -e ".[dev]"
+```
+
+---
+
+## ⚙️ Konfiguration
+
+Der Server benötigt in v0.1.0 keine externen Zugangsdaten. Verfügbare Umgebungsvariablen:
+
+| Variable | Beschreibung | Standard |
+|----------|-------------|---------|
+| `EINVOICING_DE_LOG_LEVEL` | Protokollierungsgrad (`DEBUG`, `INFO`, `WARNING`, `ERROR`) | `INFO` |
+| `EINVOICING_DE_KOSIT_VALIDATOR_URL` | URL des KoSIT-Validierungstools (optional, für Remote-Validierung) | — |
+| `EINVOICING_DE_PEPPOL_SMP_URL` | Peppol-SMP-Lookup-URL (optional) | — |
+| `EINVOICING_DE_PDF_ENGINE` | PDF-Generierungsmodul (`reportlab` oder `pymupdf`) | `reportlab` |
+
+### 🤖 Integration Claude Desktop
+
+Eintrag in die Datei `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "einvoicing-de": {
+      "command": "uvx",
+      "args": ["mcp-einvoicing-de"]
+    }
+  }
+}
+```
+
+### ⌨️ Integration Cursor
+
+Konfigurationsdatei (`~/.cursor/mcp.json` oder `.cursor/mcp.json` im Projektverzeichnis):
+
+```json
+{
+  "mcpServers": {
+    "einvoicing-de": {
+      "command": "uvx",
+      "args": ["mcp-einvoicing-de"]
+    }
+  }
+}
+```
+
+### 🪐 Integration Kiro
+
+```json
+{
+  "mcpServers": {
+    "einvoicing-de": {
+      "command": "uvx",
+      "args": ["mcp-einvoicing-de"],
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+---
+
+## 🧰 Verfügbare MCP-Werkzeuge
+
+| Werkzeug | Beschreibung |
+|----------|-------------|
+| `invoice_create` | ZUGFeRD- oder XRechnung-XML (CII oder UBL) erzeugen; PDF/A-3-Hybrid geplant (v0.2.0) |
+| `invoice_validate` | Rechnung gegen EN 16931 und KoSIT-Schematron-Regeln (BR-DE-\*) prüfen |
+| `invoice_parse` | Strukturierte Daten aus einer bestehenden ZUGFeRD- oder XRechnung-Datei extrahieren |
+| `invoice_convert` | Zwischen ZUGFeRD-Profilen oder ZUGFeRD ↔ XRechnung konvertieren |
+| `peppol_check` | Peppol-Teilnehmerregistrierung eines deutschen Unternehmens prüfen (AS4) |
+| `tax_rules` | Deutsche Umsatzsteuerregeln abfragen (Steuerklassen, §13b UStG, Befreiungen) |
+
+---
+
+## Verwendungsbeispiele
+
+### Beispiel 1 — Rechnung validieren
+
+```
+1. invoice_validate(
+     xml_base64="...",   # Base64-kodiertes ZUGFeRD-XML
+     strict=True
+   )
+   → {
+       "is_valid": true,
+       "profile": "EN_16931",
+       "syntax": "CII",
+       "error_count": 0,
+       "warning_count": 2,
+       "errors": [],
+       "warnings": [...],
+       "validator_used": "local_schematron"
+     }
+```
+
+### Beispiel 2 — Deutsche Steuerregeln abfragen
+
+```
+2. tax_rules(query="reverse_charge", context="Bauleistungen")
+   → {
+       "results": [
+         {
+           "paragraph": "§13b Abs. 2 Nr. 5 UStG",
+           "description_en": "Construction services (building contractor rule)",
+           "vatex_code": "VATEX-EU-AE",
+           "invoice_note": "Steuerschuldnerschaft des Leistungsempfängers (§13b UStG)"
+         }
+       ],
+       "legal_disclaimer": "..."
+     }
+```
+
+### Beispiel 3 — Peppol-Registrierung prüfen
+
+```
+3. peppol_check(
+     participant_id="0204:991-1234512345-06",
+     environment="production"
+   )
+   → {
+       "is_registered": true,
+       "participant_id": "0204:991-1234512345-06",
+       "document_type_supported": true,
+       "access_point_url": "https://ap.example.de/as4",
+       "transport_profile": "peppol-transport-as4-v2.0"
+     }
+```
+
+### Beispiel 4 — Rechnungsdaten parsen
+
+```
+4. invoice_parse(xml_base64="...", include_raw_xml=False)
+   → {
+       "profile": "XRECHNUNG",
+       "syntax": "CII",
+       "invoice_number": "RE-2025-001",
+       "invoice_date": "2025-01-15",
+       "seller_name": "Muster GmbH",
+       "buyer_name": "Käufer AG",
+       "tax_inclusive_amount": "119.00",
+       "currency_code": "EUR"
+     }
+```
+
+---
+
+## 📚 Unterstützte Standards
+
+| Standard | Version | Profile / Syntax |
+|----------|---------|-----------------|
+| ZUGFeRD | 2.3 | MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED |
+| XRechnung | 3.x | CII (Cross Industry Invoice), UBL (Universal Business Language) |
+| EN 16931 | — | Europäisches Kerndatenmodell für die elektronische Rechnung |
+| Peppol BIS | 3.0 | Billing 3.0 (DE PINT) |
+
+> **Hinweis:** ZUGFeRD 2.x und XRechnung 3.x teilen auf Profilebene EN 16931 dieselbe CII-XML-Syntax. Eine Konvertierung zwischen beiden Formaten ist daher ohne Datenverlust möglich. Das EXTENDED-Profil ist ZUGFeRD-spezifisch und hat kein XRechnung-Äquivalent.
+
+| Ressource | Link |
+|-----------|------|
+| FeRD ZUGFeRD-Spezifikation | [ferd-net.de](https://www.ferd-net.de) |
+| KoSIT XRechnung | [xeinkauf.de](https://xeinkauf.de/xrechnung/) |
+| KoSIT Validierungstool | [github.com/itplr-kosit/validationtool](https://github.com/itplr-kosit/validationtool) |
+| EN 16931-1:2017 | [CEN](https://www.cen.eu/) |
+| Peppol BIS Billing 3.0 | [docs.peppol.eu](https://docs.peppol.eu/poacc/billing/3.0/) |
+
+---
+
+## 🧪 Tests
+
+```bash
+# Entwicklungsabhängigkeiten installieren
+pip install -e ".[dev]"
+
+# Gesamte Testsuite ausführen
+pytest tests/ -v
+
+# Mit Abdeckungsbericht
+pytest --cov=mcp_einvoicing_de --cov-report=term-missing
+
+# Nur Modell-Tests
+pytest tests/test_models.py -v
+```
+
+---
+
+## Roadmap
+
+| Version | Funktionen |
+|---------|-----------|
+| **v0.1.0** (aktuell) | Werkzeuge: create, validate, parse, convert, peppol_check, tax_rules |
+| **v0.2.0** | PDF/A-3-Einbettung (ZUGFeRD-Hybrid) via `reportlab` / `PyMuPDF` |
+| **v0.3.0** | KoSIT-Online-Validator vollständig integriert |
+| **v0.4.0** | Peppol AS4 Direktübermittlung |
+| **v0.5.0** | DATEV-Exportformat |
+| **v1.0.0** | Produktionsreif, vollständige EN 16931-Abdeckung |
+
+---
+
+## Mitwirken
+
+Beiträge sind willkommen. Bitte öffnen Sie ein Issue, bevor Sie einen Pull Request für wesentliche Änderungen einreichen.
+
+```bash
+git clone https://github.com/cmendezs/mcp-einvoicing-de.git
+cd mcp-einvoicing-de
+pip install -e ".[dev]"
+pytest
+make audit
+```
+
+---
+
+## Other e-invoicing MCP servers
+
+| Country | Server |
+|---------|--------|
+| 🌍 Global | [mcp-einvoicing-core](https://github.com/cmendezs/mcp-einvoicing-core) |
+| 🇧🇪 Belgium | [mcp-einvoicing-be](https://github.com/cmendezs/mcp-einvoicing-be) |
+| 🇫🇷 France | [mcp-facture-electronique-fr](https://github.com/cmendezs/mcp-facture-electronique-fr) |
+| 🇮🇹 Italy | [mcp-fattura-elettronica-it](https://github.com/cmendezs/mcp-fattura-elettronica-it) |
+| 🇩🇪 Germany | [mcp-einvoicing-de](https://github.com/cmendezs/mcp-einvoicing-de) |
+
+---
+
+## 📄 Lizenz
+
+Dieses Projekt steht unter der **MIT-Lizenz**.  
+Einzelheiten finden Sie in der Datei [LICENSE](LICENSE).
+
+Copyright 2026 cmendezs
+
+---
+
+*Projekt gepflegt von [cmendezs](https://github.com/cmendezs). Für Fragen zur Implementierung der ZUGFeRD- oder XRechnung-Spezifikation bitte ein Issue eröffnen.*