MCP E-Invoicing Core

mcp-einvoicing-core

English | Français | Deutsch | Italiano | Español | Português (Brasil) | العربية

トピック： mcp mcp-server e-invoicing electronic-invoicing python fastmcp peppol en16931 ubl fatturapa xp-z12-013 nfe xml base-library

電子請求書 MCP サーバー向けの基盤パッケージです。

共通の Pydantic モデル、EN 16931 請求書ツリー、UBL/CII ワイヤーフォーマットシリアライザー、 OAuth2 HTTP クライアント、Peppol SMP ルックアップ、デジタル署名の基盤機能、コンプライアンス 監査フレームワークを提供します。これにより、国別のパッケージはコードを重複させずに共通の基盤を共有できます。

---

このパッケージが提供するもの

モジュール	内容
models	InvoiceDocument、InvoiceParty、InvoiceLineItem、PartyAddress、VATSummary、PaymentTerms、DocumentValidationResult、TaxIdentifier（国別の税務 ID バリデーター：IT、FR、DE、BE、ES、PL、BR、AE、SG、MX、IN）、TaxIdValidationResult
en16931	EN16931Invoice、EN16931Party、EN16931LineItem、EN16931Address、EN16931Tax、EN16931AllowanceCharge、EN16931PaymentMeans
credit_note	EN16931CreditNote（タイプコード 381/383/384/385）、BillingReference
ubl_documents	BaseUBLDocument — 請求書以外の UBL/Peppol 文書ファミリー向け共通エンベロープ（Peppol Ordering、管轄区域の拡張）。InvoiceDocument/EN16931Invoice ツリーの対象外であることが明示されています
wire_formats	EN16931UBLSerializer、EN16931UBLParser、EN16931CIISerializer、EN16931CIIParser、UBL_NSMAP、CII_NSMAP
convert	Syntax（UBL、CII）、convert_wire_format（ソースを自動検出し、ターゲット形式にシリアライズ）
base_server	EInvoicingMCPServer、BaseDocumentGenerator、BaseDocumentValidator、BaseDocumentParser、BaseLifecycleManager、BasePartyValidator、BaseScopeInfo、SubmissionMetadata、SearchCriteria、SubmitResult、assert_not_read_only、scrub
http_client	BaseEInvoicingClient（OAuth2、mTLS、ベアラー、API キー、JWS、認証なし）、OAuthConfig、OAuthValues、JWSConfig、APIKeyConfig、TokenCache、AuthMode
peppol	PeppolSMPClient、PeppolParticipantId、PeppolServiceInfo、PeppolLookupResult、PeppolEnvironment、PEPPOL_BIS_BILLING_30、resolve_naptr（単独で使える U-NAPTR/SML DNS 診断機能）
peppol.tools	register_peppol_tools（マウント可能な FastMCP プラグイン：参加者検索、サービスエンドポイント、DNS 診断、AS4 送信、Directory 検索、eDEC コードリストツール 8 種）、default_id_adapter、IdentifierAdapter（国別識別子アダプターの契約）
peppol.codelists	CodeList、CodelistNotConfiguredError、load_codelist と eDEC 検索関数（文書タイプ、プロセス、参加者 ID スキーム、トランスポートプロファイル、SPIS ユースケース）。EINVOICING_PEPPOL_CODELIST_DIR が必要です。下記の「設定」を参照してください
genericode	parse_genericode、CodeList、CodelistNotConfiguredError — 共通 OASIS Genericode 1.0 パーサー（peppol.codelists と en16931_codelists で使用）
en16931_codelists	en16931_codelist_tools.register_en16931_codelist_tools（マウント可能な FastMCP プラグイン：国、通貨、ICD、UNCL1001/1153/4461/5305、値引き／品目／料金の理由、MIME、EAS、VATEX の検索）。EINVOICING_EN16931_CODELIST_DIR が必要です。下記の「設定」を参照してください
peppol.directory	PeppolDirectoryClient（認証不要の公開 Peppol Directory REST 検索）、PeppolDirectorySearchResult、PeppolBusinessCard、PeppolBusinessEntity
peppol.transport	AS4MessageEnvelope、AS4TransportClient、AS4ReceiptHandler、PeppolTransmitter、AS4Receipt、AS4Credentials（実際の WS-Security メッセージ署名に対応した Peppol AS4 送信）；AS4InboundHandler、AS4InboundMessage、AS4InboundError、StandardBusinessDocumentHeader（AS4 受信側、C3 ロール）；sign_as4_message、verify_as4_signature（WS-Security プリミティブ）
peppol.trust	PeppolTrustStore、validate_certificate_chain、check_revocation、verify_smp_signature — OpenPeppol PKI のチェーン／失効／署名検証。EINVOICING_PEPPOL_PKI_DIR が必要です（このリリース時点で OpenPeppol はルート証明書をまだ公開していないため、証明書が提供されるまではロジックのみです）
peppol.reporting	parse_eusr、parse_tsr、validate_eusr、validate_tsr — Peppol EUSR/TSR サービスプロバイダー統計レポートのモデルと検証（XSD と Schematron を同梱、[xslt2] エクストラは任意）
peppol.mls	parse_mls、validate_mls、build_mls — Peppol Message Level Status（MLS）のモデルと検証（Schematron を同梱、[xslt2] エクストラは任意）
schematron	SchematronValidator（XSLT 1.0）、SaxonSchematronValidator（XSLT 2.0/3.0、[xslt2] エクストラは任意）、load_schematron_validator（自動ディスパッチファクトリー）、get_xslt_version、BaseStructuredValidator、BaseXSDValidator、XSDValidator（汎用具象 XSD バリデーター）、BaseJSONValidator、ValidationMessage、ValidationResult
schematron_artifacts	en16931_base_schematron_validator（同梱のコンパイル済み CEN EN16931 基本 Schematron — BR-* ルールのみで、Peppol オーバーレイなし。[xslt2] エクストラは任意）
digital_signature	BaseDocumentSigner、XAdESEPESSigner、XAdESSignerConfig、XMLDSigSigner、XMLDSigSignerConfig、CAdESSigner、CAdESSignerConfig、SelloDigitalSigner、SelloDigitalSignerConfig、load_certificate_der
endpoints	BaseEnvironmentEndpoints、EndpointSet、EndpointEnvironment（サンドボックス／本番 URL のルーティング）
routing	RoutingIdentifier（静的バリデーター：validate_de_leitweg）、RoutingIdValidationResult
profile_registry	ProfileEntry、ProfileRegistry、profile_registry、set_profile_registry
pdf	PDFEmbedder（PDF/A-3 XML 埋め込み）；extract(filename=None) は正規の Factur-X/XRechnung/ZUGFeRD ファイル名を順に試し、identify() は XMP を読み取ってハイブリッド PDF とその適合レベルを検出します
pdf_tools	register_pdf_tools（マウント可能な FastMCP プラグイン：identify_and_extract_pdf）、identify_and_extract_pdf
qr	generate_qr_png_base64
xml_utils	format_amount、format_quantity、xml_element、xml_optional、validate_date_iso、validate_iban、resolve_xml_input、mark_untrusted、mark_untrusted_fields、filter_empty_values、format_error
download_rules	DownloadSpec、download_artefacts
testing	InvoiceFixtureFactory（共有 pytest フィクスチャ）
audit_log	AuditLog、AuditAction、get_audit_log
confirmation	ConfirmationGate、ConfirmationStore（human-in-the-loop ゲート）
exceptions	EInvoicingError、ValidationError、PartyValidationError、XSDValidationError、SchematronValidationError、DocumentGenerationError、AuthenticationError、PlatformError
logging_utils	setup_logging、get_logger
audit	コンプライアンス監査フレームワーク：AuditReport、CheckResult、CheckFinding、重大度定数、make_report、render_summary_table、parse_audit_args、run_check_core_coverage、run_check_version_compatibility、run_check_known_shared_helpers、run_check_resource_paths、TaxRate、load_rates（[audit] エクストラは任意）

国別パッケージ

国	パッケージ	標準	対象範囲	対応状況
🇧🇪 ベルギー	mcp-einvoicing-be	Peppol BIS 3.0 / PINT-BE	B2B、2026年1月1日	稼働中。Peppol 固有のオーバーレイルールは未確認（EN 16931 の基本部分のみ）
🇧🇷 ブラジル	mcp-nfe-br	NF-e / NFC-e（modelo 55/65、schema 4.00）/ NFS-e Nacional	B2B（NF-e）+ B2C（NFC-e）、どちらも2008年から義務化	稼働中。IBS/CBS 税制改革の導入は2033年まで継続
🇫🇷 フランス	mcp-facture-electronique-fr	NF XP Z12-012 / NF XP Z12-013 / Factur-X / UBL 2.1 / CII	B2B、2026年9月1日から段階的に導入	稼働中
🇩🇪 ドイツ	mcp-einvoicing-de	ZUGFeRD 2.x / XRechnung 3.x	B2B、2025年から2028年にかけて段階的に導入	稼働中
🇮🇳 インド	mcp-einvoicing-in	GST 電子インボイス / FORM GST INV-01 schema v1.1 / IRP-IRN（INV + CRN + DBN）	B2B + B2G、2023年8月1日以降、AATO が ₹5 crore を超える納税者に CGST Rule 48(4) に基づき義務化	プレリリース（v0.1.0、未公開）。Phase A のみ（構築 + オフライン検証 + QR レンダリング）— NIC API 仕様待ちのため、稼働中の IRP への送信は未対応
🇮🇹 イタリア	mcp-fattura-elettronica-it	FatturaPA / SDI	B2G + B2B + B2C、2019年から義務化（B2G は2014年から）	稼働中
🇲🇽 メキシコ	mcp-cfdi-mx	CFDI 4.0 / Complemento de Pagos 2.0	B2B + B2G、全国で義務化	稼働中。PAC 送信トランスポートは未対応
🇵🇱 ポーランド	mcp-ksef-pl	KSeF FA(3) / FA(2) / Peppol BIS 3.0	B2B、2026年2月から2027年1月にかけて段階的に導入	稼働中。一括セッションフローは未実装
🇸🇬 シンガポール	mcp-invoicenow-sg	PINT-SG v1.4.1 / SG Peppol BIS Billing 3.0	B2B、GST 登録事業者に2026年4月から義務化	稼働中。検証範囲は IRAS C5 の受け入れチェックに限定。PINT-SG の管轄別 Schematron と EN 16931 の基本検証は未接続
🇪🇸 スペイン	mcp-facturacion-electronica-es	Factura-e / VeriFactu / SII / FACe	Orden Ministerial の発行待ち、目標日2026-10-01	VeriFactu/SII は稼働中。B2B 形式の接続は Orden Ministerial の発行待ちで保留
🇦🇪 アラブ首長国連邦	mcp-einvoicing-ae	PINT AE（請求 + セルフビリング）/ Peppol AE TDD	B2B + B2G、2026年7月から任意参加のパイロット、2027年1月から大規模納税者に義務化	稼働中。CEN EN16931 の基本 Schematron のみを検証。PINT AE の管轄別オーバーレイと TDD 検証は未対応

インストール

pip install mcp-einvoicing-core

コンプライアンス監査フレームワーク（各国パッケージの CI で使用）の場合：

pip install mcp-einvoicing-core[audit]

XSLT 2.0/3.0 Schematron 検証（SaxonSchematronValidator — XPath 2.0 以降の構文を使用する Schematron ルールセットに必要。例：FNFE-MPE Factur-X 1.08 / ZUGFeRD）の場合：

pip install mcp-einvoicing-core[xslt2]

設定

変数	使用元	用途
EINVOICING_PEPPOL_CODELIST_DIR	peppol.codelists（および peppol.tools のコードリストツール）	OpenPeppol eDEC コードリストの独自コピーを格納するローカルディレクトリです。このパッケージには同梱されていません。eDEC コードリストについては、OpenPeppol から再配布の許可が確認できていないため、コアにはパーサーと検索ツールのみが含まれ、データ自体は含まれません。各アーティファクト（文書タイプ、参加者識別子スキーム、プロセス、トランスポートプロファイル、SPIS ユースケース）の「as GeneriCode」エクスポートをdocs.peppol.eu/edelivery/codelistsからダウンロードし、それらを格納したディレクトリをこの変数に指定してください。ファイル名はプレフィックスで照合されるため、バージョンが更新されても（例：v9.7 から v9.8）、コードを変更する必要はありません。設定されていない場合、コードリストツールは例外を発生させず、セットアップ手順とともに configured: false の結果を返します。
EINVOICING_EN16931_CODELIST_DIR	en16931_codelists（およびその FastMCP ツール）	CEF EN 16931 セマンティックコードリスト（国、通貨、ICD、UNCL1001/1153/4461/5305、値引き／項目／料金の理由、MIME、EAS、VATEX）の独自コピーを格納するローカルディレクトリです。上記の eDEC リストと同様、同梱されていません。CEF EN 16931 コードリストのページから「as GeneriCode」エクスポートバンドルをダウンロードしてください。ファイル名は完全一致で照合されます（バージョンプレフィックス付きの名前ではなく Country.gc）。設定されていない場合、ツールは configured: false を返します。
EINVOICING_PEPPOL_PKI_DIR	peppol.trust	AS4 メッセージ署名および SMP レスポンス署名チェーンの検証に使用する、PEM 形式の OpenPeppol PKI ルート／中間 CA 証明書を格納した test/ および prod/ サブディレクトリを含むローカルディレクトリです。OpenPeppol は、現時点でこれらを同梱データとして公開していません。この変数を設定するまで、信頼機能は trust_anchors_configured: false を返します。
EINVOICING_SMP_ALLOWLIST	peppol（PeppolSMPClient、resolve_naptr）	SMP ホスト名を解決した際の検証に使用する、組み込みの Peppol アクセスポイント許可リストに追加するホスト名サフィックスを、カンマ区切りで指定します。
EINVOICING_CERT_PINS	http_client（BaseEInvoicingClient）および peppol.transport.client（AS4TransportClient）	外部への HTTP リクエストで SHA-256 証明書ピンニングを有効にする host:sha256hex の組を、カンマ区切りで指定します。設定されていない場合、ピンニングは適用されません。

アーキテクチャ

国別パッケージはコア抽象クラスをサブクラス化し、共有またはスタンドアロンの MCP サーバーにツールを登録します。

mcp-einvoicing-core
  ├── EN16931Invoice / InvoiceDocument  ← canonical invoice models
  ├── EN16931CreditNote                 ← credit note (type codes 381/383/384/385)
  ├── EN16931UBL/CII Serializer/Parser  ← wire format round-trip
  ├── convert_wire_format               ← CII ↔ UBL conversion
  ├── BaseDocumentGenerator/Validator/Parser/LifecycleManager
  ├── BaseEInvoicingClient              ← async HTTP (OAuth2/mTLS/bearer/API key/JWS)
  ├── PeppolSMPClient                   ← participant lookup via SMP/SML
  ├── PeppolTransmitter                 ← AS4 outbound transmission
  ├── BaseDocumentSigner                ← XAdES-EPES / XMLDSig
  ├── BaseEnvironmentEndpoints          ← sandbox/production URL routing
  ├── RoutingIdentifier                 ← country-specific routing ID validation
  ├── EInvoicingMCPServer               ← plugin registry wrapping FastMCP
  └── Audit framework                   ← per-package compliance checks

ベンダー中立性

このファミリーの各サーバーは、標準そのものを実装しています。文書の作成、検証、署名はローカルで行われ、署名鍵はお客様のインフラストラクチャ内に保持されます。これらのパッケージはいずれも商用の請求プラットフォームのクライアントではなく、実行にベンダーアカウントは必要ありません。

国によって異なるのは、最後の接続部分、つまり税務当局との間に仲介者を置く必要があるかどうかです。mcp-einvoicing-core は次の3つの方式すべてに対応しており、各国別パッケージはその管轄区域で採用されている方式を実装します。

• 税務当局への直接接続。 法的に仲介者は不要です。パッケージはお客様自身の認定資格を使用して政府のエンドポイントに接続します。(イタリア、ポーランド、ブラジル、スペイン)
• 交換可能な仲介者。 仲介者は必要ですが、その API は標準化されているため、プロバイダーの変更はコードではなく設定の変更で対応できます。(XP Z12-013 に基づくフランスの PDP、ベルギー、シンガポール、UAE の Peppol アクセスポイント)
• ベンダーごとのアダプターを使用する仲介者。 仲介者が必要で、各ベンダーの API は異なります。文書と鍵は引き続きお客様が保持し、トランスポートアダプターのみがベンダー固有となります。(メキシコの PAC、インドの GSP)

いずれの方式でも、コンプライアンスロジックと秘密鍵はお客様が保持します。

プラグイン登録パターン

国別パッケージは、共有またはスタンドアロンの FastMCP インスタンスにツールを登録します。

# Standalone
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()

コアには、国別パッケージが SMP ルックアップと AS4 送信を再実装せずに済むよう、マウント可能な Peppol ツールプラグインも含まれています。国別識別子アダプター（国別番号のみの値（VAT 番号など）を Peppol の "<scheme>:<value>" 参加者 ID に正規化する小さな関数）を指定してください。

from mcp_einvoicing_core.peppol.tools import register_peppol_tools

def be_id_adapter(identifier: str) -> str:
    if ":" in identifier:
        return identifier
    return f"0208:{normalize_vat_be(identifier)[2:]}"  # KBO/BCE scheme

server.register_plugin(
    lambda m: register_peppol_tools(m, id_adapter=be_id_adapter), "peppol"
)

これにより、peppol_lookup_participant、peppol_get_service_endpoint、resolve_peppol_dns、 peppol_send、peppol_directory_search、および 8 つの OpenPeppol eDEC コードリストツールが登録されます（コードリストツールに必要な EINVOICING_PEPPOL_CODELIST_DIR については、上記の設定を参照してください）。EN 16931 セマンティックコードリスト（en16931_codelist_tools.register_en16931_codelist_tools）、Peppol レポート（peppol.reporting_tools.register_peppol_reporting_tools）、および MLS（peppol.mls_tools.register_peppol_mls_tools）には、それぞれ別のマウント可能なプラグインが用意されています。

Claude Desktop / Cursor / Kiro との互換性

国別パッケージの既存の設定を変更する必要はありません。ツール名、シグネチャ、環境変数、エントリーポイント（server:main）はすべてそのまま維持されます。

ライセンス

Apache 2.0 — LICENSE を参照してください。