MCP E-Invoicing Core

mcp-einvoicing-core

English | 法语 | 德语 | 意大利语 | 西班牙语 | 巴西葡萄牙语 | 阿拉伯语

主题： 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（各国税号验证器：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 订购、司法管辖区扩展）的共享信封；明确位于 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、bearer、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 发送、目录搜索，以及 8 个 eDEC 代码列表工具）、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（Peppol AS4 出站传输，现已支持真实的 WS-Security 消息签名）；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 消息级状态（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（人机交互确认关卡）
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 e-invoicing / FORM GST INV-01 schema v1.1 / IRP-IRN (INV + CRN + DBN)	B2B + B2G；根据 CGST Rule 48(4)，自 2023 年 8 月 1 日起，AATO 超过 ₹5 crore 的纳税人必须使用	预发布（v0.1.0，未发布）；仅阶段 A（构建 + 离线验证 + QR 渲染）——实时 IRP 提交功能待 NIC API 规范发布
🇮🇹 意大利	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，2026 年 4 月起 GST 注册企业必须使用	已上线；验证范围仅限 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 (billing + self-billing) / 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 代码列表副本的本地目录。此软件包不附带这些数据：OpenPeppol 尚未确认授予 eDEC 代码列表的再分发许可，因此核心包仅提供解析器和查询工具，不包含数据本身。请从 docs.peppol.eu/edelivery/codelists 下载每项内容（文档类型、参与方标识符方案、流程、传输配置文件、SPIS 用例）的“As GeneriCode”导出文件，并将此变量指向包含这些文件的目录。文件名按前缀匹配，因此升级版本（例如从 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	本地目录，包含 test/ 和 prod/ 子目录，其中存放 PEM 编码的 OpenPeppol PKI 根 CA/中间 CA 证书，用于验证 AS4 消息签名和 SMP 响应签名链。OpenPeppol 尚未在任何位置发布可供打包的数据——在设置此变量前，信任功能会报告 trust_anchors_configured: false。
EINVOICING_SMP_ALLOWLIST	peppol（PeppolSMPClient、resolve_naptr）	以逗号分隔的主机名后缀，用于扩展内置的 Peppol 接入点允许列表，该列表用于验证解析出的 SMP 主机名。
EINVOICING_CERT_PINS	http_client（BaseEInvoicingClient）和 peppol.transport.client（AS4TransportClient）	以逗号分隔的 host:sha256hex 配对，用于对出站 HTTP 请求启用 SHA-256 证书固定。若未设置此变量，则不会强制执行证书固定。

架构

各国家/地区的软件包继承核心抽象类，并在共享或独立的 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 支持以下三种方式，各国家/地区软件包则会实现其司法管辖区所采用的方式：

• 直接连接税务机关。 法律不要求中介；软件包使用你自己的认证信息与政府端点通信。（意大利、波兰、巴西、西班牙）
• 可替换的中介。 必须使用中介，但其 API 已标准化，因此更换服务提供商只需修改配置，无需修改代码。（法国依据 XP Z12-013 标准的 PDP；比利时、新加坡、阿联酋的 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()

核心也提供了自己的可挂载 Peppol 工具插件，这样国家级软件包就不必再重复实现 SMP 查询和 AS4 发送功能。提供一个国家标识符适配器（一个小型函数，用于将裸国家编号（例如增值税号）规范化为 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。