mcp-einvoicing-ae

mcp-einvoicing-ae 🇦🇪

English | العربية

---

简介

mcp-einvoicing-ae 是一个 MCP（模型上下文协议） 服务， 提供阿联酋电子发票相关工具。它属于 mcp-einvoicing-* 国家/地区专用服务系列，均基于 mcp-einvoicing-core 构建，后者提供 共享验证引擎、EN 16931 抽象和 Peppol 网络实用工具。

生成的 PINT AE 发票在结构上符合规范：会生成 cbc:UUID、cbc:ProfileExecutionID、 每行对应的 cac:ItemPriceExtension 和 trade_license_number，并可通过 parse_invoice_ae 完成往返解析。模型验证器会强制执行 5.00% 的标准增值税税率，并提供 Peppol 参与方查询工具。 validate_invoice_ae 仅检查 core 共享的 CEN EN16931 基础 Schematron，不检查 PINT AE 司法辖区扩展； validate_tdd_ae 目前报告“不可用”——请参阅下文的支持的标准和 可用工具。

阿联酋 Peppol 管理机构的 PINT AE（账单）专业规范状态为 Status: Final，版本为 1.0.4（2026-06-02）；Peppol AE 税务数据文档（TDD）状态为 Status: Final，版本为 1.0.4 （2026-07-23）。完整引用信息请见：specs/README.md。

支持的标准

• PINT AE（账单） — UBL 2.1，CustomizationID: urn:peppol:pint:billing-1@ae-1， ProfileID: urn:peppol:bis:billing。版本 1.0.4（2026-06-02）。
• PINT AE（自开票） — CustomizationID: urn:peppol:pint:selfbilling-1@ae-1， ProfileID: urn:peppol:bis:selfbilling。
• Peppol AE TDD（税务数据文档）— 发送给 FTA 的第 5 方报告文档；它使用自己的 XML 命名空间（urn:peppol:schema:taxdata:1.0），并非 UBL 发票。版本 1.0.4 （2026-07-23）。

阿联酋计划采用经认证服务提供商路由的去中心化 Peppol 五方模式，除该系列其他地区采用的四方交换外，还增加了向税务机关报告的环节（即上述 TDD）。发票树路径已确认为 EN16931Invoice（PINT AE 是 EN 16931-1:2017 的 UBL 2.1 CIUS）——在所提供的规范中未找到 JSON 绑定。

AEInvoice 通过 mcp_einvoicing_ae.wire_formats.AEUBLSerializer 序列化；该序列化器在核心的 EN16931UBLSerializer 之上叠加 AE 专属元素（cbc:ProfileExecutionID、带有 schemeAgencyID="TL" 的 PartyLegalEntity/CompanyID，用于 trade_license_number）——后者现在原生输出 cbc:UUID（来源为 document_uuid）和每行的 cac:ItemPriceExtension（mcp-einvoicing-core v1.25.0），因为 profile/business_process 已保存实际的 Peppol URN。AEParty.vat_id 保存 15 位 TRN，并通过 TaxIdentifier.validate_ae_trn()（核心 v1.22.0）进行格式验证；Peppol 参与方 ID（TIN）会自动取其前 10 位生成。AETaxDataDocument 对 TDD 的必填字段进行建模，但它不是 UBL 发票，也不基于 AEInvoice 构建。parse_invoice_ae 会从原始 XML 中重新提取 AE 专属元素，并将结果重新验证为 AEInvoice，因此解析时会重新执行与新建对象相同的 TRN 和税率检查——详见可用工具，了解支持和不支持的内容。TDD 传输通道（与发票使用同一 AS4 通道，还是单独通道）仍是一个尚待文档说明的问题，并非代码缺口。完整详情： specs/README.md。

验证范围，截至 v0.2.0： validate_invoice_ae 仅检查 CEN EN16931 基础 Schematron（结构和算术/总额规则，与 mcp-einvoicing-be/mcp-ksef-pl 共用）——不检查 PINT AE 管辖区覆盖规则（ibr-*-ae 规则）。由于阿联酋 TRN 不带国家前缀，预计每张真实 AE 发票都会触发 BR-CO-09（VAT 标识符必须带 ISO 3166-1 alpha-2 前缀）；每个结果中都会说明这一点，这并非数据缺陷。validate_tdd_ae 目前完全没有可用的验证功能。v0.1.0 曾捆绑 5 个自行编译的文件，这些文件源自 OpenPeppol 的 PINT AE 和 TDD Schematron/XSD 源码，但没有确认重新分发权利——已在 v0.2.0 中移除。详见 CHANGELOG.md。

安装

要求

• Python ≥ 3.11
• mcp-einvoicing-core（作为依赖项自动安装）

使用 uvx（推荐）

uvx mcp-einvoicing-ae

使用 uv

uv add mcp-einvoicing-ae

从源代码安装

git clone https://github.com/cmendezs/mcp-einvoicing-ae.git
cd mcp-einvoicing-ae
uv sync --all-extras

配置

环境变量

变量	必需	默认值	描述
LOG_LEVEL	否	INFO	日志级别：DEBUG、INFO、WARNING 或 ERROR

国家/地区专属变量（传输端点、凭据、环境切换项）将在规范文档明确说明后添加。参见 .env.example。目前运行此服务无需凭据。

Claude Desktop 集成

要将此服务与 Claude 配合使用，请将以下配置添加到 claude_desktop_config.json 文件中：

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

Cursor 集成

Cursor 通过 stdio 支持 MCP 服务。请在以下位置添加配置：

• 全局（所有项目）：~/.cursor/mcp.json
• 项目（仅此代码库）：.cursor/mcp.json

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

重新加载 Cursor 窗口（按 Ctrl+Shift+P，然后选择 Reload Window）以应用更改。

Kiro 集成

Kiro 通过专用配置文件支持 MCP 服务。可选择两个级别：

• 全局（所有项目）：~/.kiro/settings/mcp.json
• 工作区（仅此仓库）：.kiro/settings/mcp.json

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

保存后会自动重新加载文件。你也可以通过命令面板（Cmd+Shift+P / Ctrl+Shift+P）打开配置，然后选择 MCP。

可用工具

工具	描述
generate_invoice_ae	通过 AEUBLSerializer，根据结构化数据生成 PINT AE UBL 2.1 发票 XML（账单或自开票）。生成所有无条件必需的 PINT AE 元素：cbc:UUID、cbc:ProfileExecutionID、每个行项目的 cac:ItemPriceExtension，以及 PartyLegalEntity/CompanyID（设置了 trade_license_number 时）。
validate_invoice_ae	根据 core 共享的 CEN EN16931 基础 Schematron 校验 PINT AE UBL 2.1 发票（仅结构和算术／总计规则，不包括 PINT AE 管辖区覆盖规则）。需要 xslt2 extra。
validate_tdd_ae	始终返回明确的“不可用”结果——目前没有适用于 Peppol AE Tax Data Document（TDD）的授权校验资源。
parse_invoice_ae	将 PINT AE UBL 2.1 发票 XML 解析为结构化字典。从原始 XML 中重新提取 document_uuid、profile_execution_id 和 trade_license_number，并将结果重新校验为 AEInvoice——会对解析后的内容重新应用 TRN 格式和税率／类别检查，而不只是对新构造的内容进行检查。

Peppol 参与方查询（core 的 register_peppol_tools 插件，基于 TIN 的 ID 适配器——方案 0235，TRN 的前 10 位数字）：

工具	描述
peppol_lookup_participant	检查企业是否已在 Peppol 网络注册；返回注册状态和支持的文档类型
peppol_get_service_endpoint	获取参与方对应文档类型的 AS4 端点
resolve_peppol_dns	仅限 DNS（SML）的诊断，不依赖 SMP 可达性
peppol_send	通过 AS4 传输 UBL/CII 发票

generate_invoice_ae/validate_invoice_ae/parse_invoice_ae 需要 mcp-einvoicing-ae[xslt2] （包含 saxonche），以加载基础 Schematron 校验器；如果未安装，该校验器不会静默通过，而是由 validate_invoice_ae 返回明确的“不可用”结果。

docs/TOOLS.md 中的工具参考文档由正在运行的服务生成：

uv run python scripts/gen_tool_reference.py

供应商中立性

此服务直接实现标准：在本地构建、校验并签署文档。它不是商业开票平台的客户端，你的签名密钥和凭据绝不会离开自己的基础设施。

PINT AE / Peppol AE TDD 需要 Peppol 接入点，但任何经过认证的接入点都使用相同的 AS4 配置，因此切换供应商只需更改配置，无需更改代码。

贡献

开发环境设置、测试和 lint 命令以及拉取请求检查清单，请参阅 CONTRIBUTING.md。安全问题请按照 SECURITY.md 中的私密披露流程处理。

其他电子发票 MCP 服务

国家/地区	服务
🌍 全球	mcp-einvoicing-core
🇧🇪 比利时	mcp-einvoicing-be
🇧🇷 巴西	mcp-nfe-br
🇫🇷 法国	mcp-facture-electronique-fr
🇩🇪 德国	mcp-einvoicing-de
🇮🇳 印度	mcp-einvoicing-in
🇮🇹 意大利	mcp-fattura-elettronica-it
🇲🇽 墨西哥	mcp-cfdi-mx
🇵🇱 波兰	mcp-ksef-pl
🇸🇬 新加坡	mcp-invoicenow-sg
🇪🇸 西班牙	mcp-facturacion-electronica-es
🇦🇪 阿联酋	mcp-einvoicing-ae

许可证

本项目采用 Apache 2.0 许可证，详情请参阅 LICENSE。完整的版本历史请参阅 CHANGELOG.md。