🌉 Invoice Bridge MCP

Ein robuster, produktionsreifer Model Context Protocol (MCP) Server zur automatisierten Extraktion, Analyse und Konformitätsprüfung von hybriden elektronischen Rechnungen (ZUGFeRD / Factur-X) und § 14 UStG Pflichtangaben für KI-Assistenten (z. B. Claude Desktop, Antigravity, Cursor, Cline).

📋 Inhaltsverzeichnis

• Überblick

• Funktionsumfang

• Architektur

• Installation & Schnellstart

• MCP Konfiguration

  • Claude Desktop / Cline / Antigravity

  • Umgebungsvariablen

• MCP Schnittstellen (Tools & Resources)

  • Resources

  • Tools

• Validierte Regeln & Standards

• Projektstruktur

• Entwicklung & Tests

• Roadmap & Geplante Features

• Lizenz

Related MCP server: Scribo MCP Server

💡 Überblick

Ab dem 01.01.2025 gilt in Deutschland die gesetzliche Verpflichtung zum Empfang elektronischer Rechnungen (E-Rechnung) im B2B-Bereich. Invoice Bridge MCP schließt die Lücke zwischen Dokumenten-Eingangsverzeichnissen, hybriden PDF/A-3-Rechnungsdateien und LLM-basierten Agenten.

Der MCP-Server ermöglicht KI-Assistenten:

1. Rechnungsdokumente im Eingangsordner aufzufinden (invoices://list).

2. Eingebettete XML-Rechnungsdaten aus PDF/A-3-Dateien verlustfrei zu extrahieren (parse_invoice).

3. XML-Rechnungen auf steuerrechtliche (§ 14 UStG) und EN 16931 Konformität zu prüfen (validate_compliance).

4. PDF-Rechnungen in einem Schritt direkt zu prüfen (validate_invoice_pdf).

✨ Funktionsumfang

• 📄 PDF/A-3 Extraktion: Erkennt und extrahiert eingebettete Factur-X / ZUGFeRD-Anhänge (factur-x.xml, zugferd-invoice.xml, xrechnung.xml).

• ⚡ 1-Step PDF Validierung: Direkte Prüfung von PDF-Rechnungen ohne Zwischendatei.

• 🛡️ Sicherheit & Resilienz: Integrierte Path-Traversal-Absicherung (.. Erkennung) und sicheres Fehlerhandling bei defektem XML.

• ⚖️ § 14 UStG & Schematron-Validierung:

  • Rechnungsnummer, Ausstellungsdatum (Format 102 / YYYYMMDD), Rechnungstyp-Codes.

  • Vollständigkeit von Rechnungssteller und Leistungsempfänger.

  • Prüfung der Steuernummer und USt-IdNr. (Format & ISO-Ländercode-Prefix).

  • Währungscodes (ISO 4217) & Ländercodes (ISO 3166-1).

• 🧮 Mathematische Konsistenzprüfung:

  • Exakte Cent-genaue Prüfung mit Decimal: Netto + USt == Brutto.

  • Prüfung der maximalen Nachkommastellen (BR-DEC-Regeln).

• 🔌 Standardkonformes MCP: Basiert auf FastMCP mit automatischer Tool- und Ressourcen-Registrierung.

🏗️ Architektur

flowchart LR
    A[KI-Agent / LLM] <-->|MCP Protocol| B[Invoice Bridge MCP Server]
    B --> C[parser.py\nPDF/A-3 Extractor]
    B --> D[validator.py\nFacturXValidator]
    B --> E[(input/ Ordner)]
    C -->|Liest PDF & Schreibt XML| E
    D -->|Liest XML & Prüft Daten| E

🚀 Installation & Schnellstart

Voraussetzungen

• Python >= 3.10

• Virtuelle Umgebung empfohlen

1. Repository klonen & Virtual Environment erstellen

git clone https://github.com/Winterholdt/invoice-bridge-mcp.git
cd invoice-bridge-mcp

# Virtual Environment anlegen
python -m venv .venv

# Aktivieren (Windows PowerShell)
.venv\Scripts\Activate.ps1

# Aktivieren (Linux/macOS)
source .venv/bin/activate

2. Paket installieren

pip install -e .

⚙️ MCP Konfiguration

Claude Desktop / Cline / Antigravity

Trage den MCP Server in deine Konfigurationsdatei (z. B. claude_desktop_config.json) ein:

{
  "mcpServers": {
    "invoice-bridge": {
      "command": "c:/your/path/invoice-bridge-mcp/.venv/Scripts/python.exe",
      "args": [
        "c:/your/path/invoice-bridge-mcp/src/invoice_bridge/server.py"
      ],
      "env": {
        "INVOICE_INPUT_DIR": "c:/your/path/invoice-bridge-mcp/input"
      }
    }
  }
}

Umgebungsvariablen

🛠️ MCP Schnittstellen (Tools & Resources)

Resources

Tools

1. validate_invoice_pdf (Empfohlen für PDFs)

Direkte Prüfung einer PDF-Rechnung in einem Schritt: Extrahiert eingebettete ZUGFeRD/Factur-X XML-Daten und validiert die Konformität nach § 14 UStG.

• Eingabe-Parameter:

  • invoice_pdf_name (string, erforderlich): Dateiname der PDF im Ordner input/ (z. B. test.pdf).

• Rückgabe-Beispiel:

  {
    "status": "success",
    "invoice_id": "RE-2026-001",
    "compliance_checks": {
      "is_valid": true,
      "total_checks": 14,
      "passed": 14,
      "failed": 0,
      "failed_details": []
    },
    "approved_for_payment": true
  }

2. parse_invoice

Extrahiert die eingebettete ZUGFeRD/Factur-X XML-Datei aus einer PDF-Rechnung und speichert sie als .xml im Eingangsordner.

• Eingabe-Parameter:

  • invoice_pdf_name (string, erforderlich): Dateiname der PDF im Ordner input/ (z. B. test.pdf).

• Rückgabe-Beispiel:

  {
    "status": "success",
    "xml_file": "test.xml"
  }

3. validate_compliance

Prüft eine vorhandene ZUGFeRD/Factur-X XML-Datei auf formale, strukturelle und rechnerische Konformität nach § 14 UStG und EN 16931 / Factur-X Profilen.

• Eingabe-Parameter:

  • invoice_xml_name (string, erforderlich): Dateiname der XML im Ordner input/ (z. B. test.xml).

• Rückgabe-Beispiel:

  {
    "status": "success",
    "invoice_id": "INV-2026-001",
    "compliance_checks": {
      "is_valid": true,
      "total_checks": 14,
      "passed": 14,
      "failed": 0,
      "failed_details": []
    },
    "approved_for_payment": true
  }

📜 Validierte Regeln & Standards

📁 Projektstruktur

invoice-bridge-mcp/
├── .github/
│   └── workflows/
│       └── ci.yml                # GitHub Actions CI Workflow (Python 3.10 - 3.12)
├── config/
│   └── mcp_config.example.json   # Vorlage für MCP-Client-Konfiguration
├── input/                        # Verzeichnis für Eingangsrechnungen (PDF/XML)
│   └── test.pdf
├── src/
│   └── invoice_bridge/           # Hauptpaket (Single Source of Truth)
│       ├── __init__.py
│       ├── parser.py             # PDF/A-3 Extractor mit robuster Fehlerbehandlung
│       ├── server.py             # FastMCP Server mit Path-Traversal-Schutz
│       └── validator.py          # FacturX / ZUGFeRD / § 14 UStG Prüflogik
├── test_invoices/                # Testrechnungen
│   ├── fail-xml-invalid.pdf
│   └── test.pdf
├── tests/                        # Vollständige Pytest-Suite
│   ├── test_parser.py
│   ├── test_server.py
│   └── test_validator.py
├── .gitignore
├── pyproject.toml                # Projekt-Metadaten, Entrypoints & Linter-Settings
└── README.md

🧪 Entwicklung & Tests

# Entwicklungsumgebung inkl. Test-Tools installieren
pip install -e .[dev]

# Linter ausführen
ruff check .

# Test-Suite ausführen
pytest -v

📄 Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert. Weitere Details in der LICENSE-Datei.