mcp-einvoicing-de 🇩🇪

Name: mcp-einvoicing-de
Author: cmendezs

License PyPI version Python mcp-einvoicing-de MCP server

MCP-сервер (Model Context Protocol) на Python для немецких электронных счетов-фактур в форматах ZUGFeRD 2.x и XRechnung 3.x (EN 16931, FeRD, KoSIT). Позволяет ИИ-агентам (Claude, IDE) создавать, проверять, анализировать и конвертировать электронные счета, полностью соответствующие немецкому мандату B2B (действует с 2025 года, поэтапное внедрение до 2027–2028 годов) и европейскому стандарту EN 16931.

Резюме на английском

Это сервер Model Context Protocol (MCP) для немецкого электронного документооборота. Он предоставляет 6 инструментов, охватывающих полный жизненный цикл счета ZUGFeRD или XRechnung: создание (CII/UBL XML), проверку на соответствие правилам EN 16931 и KoSIT Schematron (BR-DE-*), анализ существующих файлов счетов, конвертацию профилей и синтаксиса, поиск регистрации участников Peppol (AS4) и правила немецкого НДС (налоговые классы, §13b UStG reverse charge, исключения). Поддерживает все профили ZUGFeRD 2.x (от MINIMUM до EXTENDED) и XRechnung 3.x (синтаксис CII и UBL). Лицензировано под Apache 2.0.

Основано на

Этот пакет основан на mcp-einvoicing-core, общей базовой библиотеке для европейских MCP-серверов электронных счетов. Она предоставляет общие модели, абстракции проверки, вспомогательные функции XML и иерархию исключений.

mcp-einvoicing-core устанавливается автоматически как транзитивная зависимость — никаких дополнительных шагов не требуется.

Для разработчиков: pip install -e ".[dev]" автоматически устанавливает базовый пакет из PyPI.

🏗️ Архитектура

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

🚀 Установка

Через PyPI (рекомендуется)

pip install mcp-einvoicing-de

Без предварительной установки с помощью uvx:

uvx mcp-einvoicing-de

Из исходного кода

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]"

⚙️ Конфигурация

Серверу в версии v0.1.0 не требуются внешние учетные данные. Доступные переменные окружения:

Переменная	Описание	По умолчанию
`EINVOICING_DE_LOG_LEVEL`	Уровень логирования (`DEBUG`, `INFO`, `WARNING`, `ERROR`)	`INFO`
`EINVOICING_DE_KOSIT_VALIDATOR_URL`	URL инструмента проверки KoSIT (опционально, для удаленной проверки)	—
`EINVOICING_DE_PEPPOL_SMP_URL`	URL поиска Peppol SMP (опционально)	—
`EINVOICING_DE_PDF_ENGINE`	Модуль генерации PDF (`reportlab` или `pymupdf`)	`reportlab`

🤖 Интеграция с Claude Desktop

Запись в файле claude_desktop_config.json:

{
  "mcpServers": {
    "einvoicing-de": {
      "command": "uvx",
      "args": ["mcp-einvoicing-de"]
    }
  }
}

⌨️ Интеграция с Cursor

Файл конфигурации (~/.cursor/mcp.json или .cursor/mcp.json в директории проекта):

{
  "mcpServers": {
    "einvoicing-de": {
      "command": "uvx",
      "args": ["mcp-einvoicing-de"]
    }
  }
}

🪐 Интеграция с Kiro

{
  "mcpServers": {
    "einvoicing-de": {
      "command": "uvx",
      "args": ["mcp-einvoicing-de"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

🧰 Доступные инструменты MCP

Инструмент	Описание
`invoice_create`	Создание XML ZUGFeRD или XRechnung (CII или UBL); гибрид PDF/A-3 запланирован (v0.2.0)
`invoice_validate`	Проверка счета на соответствие EN 16931 и правилам KoSIT-Schematron (BR-DE-*)
`invoice_parse`	Извлечение структурированных данных из существующего файла ZUGFeRD или XRechnung
`invoice_convert`	Конвертация между профилями ZUGFeRD или ZUGFeRD ↔ XRechnung
`peppol_check`	Проверка регистрации участника Peppol немецкой компании (AS4)
`tax_rules`	Запрос правил немецкого НДС (налоговые классы, §13b UStG, исключения)

Примеры использования

Пример 1 — Проверка счета

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"
     }

Пример 2 — Запрос немецких налоговых правил

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": "..."
     }

Пример 3 — Проверка регистрации Peppol

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"
     }

Пример 4 — Анализ данных счета

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"
     }

📚 Поддерживаемые стандарты

Стандарт	Версия	Профили / Синтаксис
ZUGFeRD	2.3	MINIMUM, BASIC WL, BASIC, EN 16931, EXTENDED
XRechnung	3.x	CII (Cross Industry Invoice), UBL (Universal Business Language)
EN 16931	—	Европейская модель основных данных для электронных счетов
Peppol BIS	3.0	Billing 3.0 (DE PINT)

Примечание: ZUGFeRD 2.x и XRechnung 3.x используют один и тот же синтаксис CII-XML на уровне профиля EN 16931. Поэтому конвертация между обоими форматами возможна без потери данных. Профиль EXTENDED является специфичным для ZUGFeRD и не имеет эквивалента в XRechnung.

Ресурс	Ссылка
Спецификация FeRD ZUGFeRD	ferd-net.de
KoSIT XRechnung	xeinkauf.de
Инструмент проверки KoSIT	github.com/itplr-kosit/validationtool
EN 16931-1:2017	CEN
Peppol BIS Billing 3.0	docs.peppol.eu

🧪 Тесты

# 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

Дорожная карта

Версия	Функции
v0.1.0 (текущая)	Инструменты: create, validate, parse, convert, peppol_check, tax_rules
v0.2.0	Внедрение PDF/A-3 (ZUGFeRD-Hybrid) через `reportlab` / `PyMuPDF`
v0.3.0	Полная интеграция онлайн-валидатора KoSIT
v0.4.0	Прямая передача Peppol AS4
v0.5.0	Формат экспорта DATEV
v1.0.0	Готовность к производству, полное покрытие EN 16931

Участие в разработке

Вклад приветствуется. Пожалуйста, откройте Issue, прежде чем отправлять Pull Request для существенных изменений.

git clone https://github.com/cmendezs/mcp-einvoicing-de.git
cd mcp-einvoicing-de
pip install -e ".[dev]"
pytest
make audit

Другие MCP-серверы электронных счетов

Страна	Сервер
🌍 Глобальный	mcp-einvoicing-core
🇧🇪 Бельгия	mcp-einvoicing-be
🇫🇷 Франция	mcp-facture-electronique-fr
🇮🇹 Италия	mcp-fattura-elettronica-it
🇩🇪 Германия	mcp-einvoicing-de

📄 Лицензия

Этот проект распространяется под лицензией Apache-2.0. Подробности см. в файле LICENSE.

Проект поддерживается cmendezs. По вопросам реализации спецификации ZUGFeRD или XRechnung, пожалуйста, откройте Issue.

mcp-einvoicing-de