Facture Électronique France

mcp-facture-electronique-fr 🇫🇷

English | Français

一个 Python MCP 服务，提供法国电子发票改革（自 2026 年 9 月 1 日起生效）所采用的标准化 AFNOR XP Z12-013 API。该项目使 AI Agent（Claude、IDE）能够以原生方式与作为兼容解决方案（SC）的获批平台（PA/PDP）生态系统交互。

---

简介

此软件包基于 mcp-einvoicing-core 构建。这是一个供欧洲电子发票 MCP 服务共用的基础库，提供本软件包使用的 OAuth2 HTTP 客户端、令牌缓存、共享模型、日志工具和异常层级。

mcp-einvoicing-core 会作为传递依赖自动安装，无需额外操作。

贡献者须知： pip install -e ".[dev]" 会自动从 PyPI 安装基础软件包。

此服务以法国电子发票改革所定义的**兼容解决方案（CS）**模式运行。CS 充当企业信息系统与获批平台（AP/PDP）之间的中介。这意味着：

• 不验证调用方提供的负载是否符合配置文件。 服务会按原样传输发票文件（Factur-X PDF/A-3、UBL 2.1 或 CII XML）。结构和业务规则验证（NF XP Z12-012 配置文件、Schematron 规则）由接收方获批平台执行，而非本服务。
• 电子报告负载仅进行 XSD 架构级验证。 调用 validate_ereporting_xml 时，会根据 DGFiP v3.2 XSD 架构验证交易报告（Flux 10.1/10.3）和付款报告（Flux 10.2/10.4），但更深入的业务规则检查（例如，声明金额与发票总额之间的一致性）由 AP 负责。
• 不生成 PDF/A-3 封装文件。 调用方必须生成符合要求且内嵌 CII XML 的 Factur-X PDF/A-3 文件。本服务负责传输生成完毕的二进制文件。

获批平台会执行最终验证，并可能以错误代码和消息拒绝不合规的提交。

安装

通过 PyPI 安装（推荐）

pip install mcp-facture-electronique-fr

也可以使用 uvx，无需预先安装：

uvx mcp-facture-electronique-fr

如需进行 Factur-X Schematron 验证（validate_facturx，需要 XSLT 2.0 / Saxon-HE 后端——请参阅下文「可用工具」中的 FR-XSLT2-1）：

pip install mcp-facture-electronique-fr[xslt2]

从源代码安装

# Clone the repository
git clone https://github.com/cmendezs/mcp-facture-electronique-fr.git
cd mcp-facture-electronique-fr

# Create the virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in editable mode
pip install -e ".[dev]"

# Initial configuration
cp .env.example .env
# Edit .env with the credentials provided by your PA/PDP

配置（.env）

服务需要以下变量，以便通过获批平台（PA）进行身份验证：

变量	描述
PA_BASE_URL_FLOW	PA Flow Service 的基础 URL
PA_BASE_URL_DIRECTORY	已弃用——不再读取；请参阅 PPF_ANNUAIRE_BASE_URL
PPF_ANNUAIRE_BASE_URL	PPF Annuaire 服务的基础 URL（默认为生产环境 swagger servers URL；沙盒测试时可覆盖）
PA_CLIENT_ID	OAuth2 客户端 ID
PA_CLIENT_SECRET	OAuth2 客户端密钥
PA_TOKEN_URL	身份验证服务器 URL
PA_ORGANIZATION_ID	多租户 AP 的组织标识符（可选）
HTTP_TIMEOUT	请求超时时间（默认值：30s）
PPF_GLOBAL_ID	用于 CDAR 第二个 RecipientTradeParty 的 PPF 参与方 GlobalID（可选，默认未设置；请参阅 submit_lifecycle_status）
PPF_SCHEME_ID	PPF_GLOBAL_ID 的 schemeID（默认值 0238）
PPF_NAME	PPF RecipientTradeParty 的名称（默认值 PPF）
PPF_ROLE_CODE	PPF RecipientTradeParty 的 RoleCode（默认值 DFH）

Claude Desktop 集成

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

{
  "mcpServers": {
    "facture-electronique-fr": {
      "command": "uvx",
      "args": ["mcp-facture-electronique-fr"],
      "env": {
        "PA_BASE_URL_FLOW": "https://api.votre-pdp.fr/flow",
        "PPF_ANNUAIRE_BASE_URL": "https://aife.economie.gouv.fr/ppf/annuaire-public/v1",
        "PA_CLIENT_ID": "votre-id",
        "PA_CLIENT_SECRET": "votre-secret",
        "PA_TOKEN_URL": "https://auth.votre-pdp.fr/oauth/token"
      }
    }
  }
}

Cursor 集成

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

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

{
  "mcpServers": {
    "facture-electronique-fr": {
      "command": "uvx",
      "args": ["mcp-facture-electronique-fr"],
      "env": {
        "PA_BASE_URL_FLOW": "https://api.votre-pdp.fr/flow",
        "PPF_ANNUAIRE_BASE_URL": "https://aife.economie.gouv.fr/ppf/annuaire-public/v1",
        "PA_CLIENT_ID": "votre-id",
        "PA_CLIENT_SECRET": "votre-secret",
        "PA_TOKEN_URL": "https://auth.votre-pdp.fr/oauth/token"
      }
    }
  }
}

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

Kiro 集成

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

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

{
  "mcpServers": {
    "facture-electronique-fr": {
      "command": "uvx",
      "args": ["mcp-facture-electronique-fr"],
      "env": {
        "PA_BASE_URL_FLOW": "https://api.votre-pdp.fr/flow",
        "PPF_ANNUAIRE_BASE_URL": "https://aife.economie.gouv.fr/ppf/annuaire-public/v1",
        "PA_CLIENT_ID": "votre-id",
        "PA_CLIENT_SECRET": "votre-secret",
        "PA_TOKEN_URL": "https://auth.votre-pdp.fr/oauth/token"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

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

Kiro 安全提示：不要以纯文本形式写入密钥，而应使用语法 "PA_CLIENT_SECRET": "${PA_CLIENT_SECRET}"；Kiro 会在启动时解析 shell 环境变量。

可用工具

服务	领域	标准	MCP 工具
Flow Service	发票流和电子报告	Annex A，v1.2.0	5 个工具
PPF Annuaire（目录）	中央目录（SIREN/SIRET/路由/寻址）	PPF swagger v1.11.0	20 个工具
Webhook Service	事件通知订阅	Annex A，v1.2.0	5 个工具
Factur-X Service	CII XML 验证（Schematron）	Factur-X 1.09.2	1 个工具

文本已更新至 2026 年 6 月（当前 swagger 版本为 v1.2.0）——AFNOR 于 2026 年 6 月重新提供了 XP Z12-013 的叙述性文本，但未更新 swagger；该服务继续实现 v1.2.0 线协议。

**注意（FR-XSLT2-1，已解决）：**随附的 Factur-X 1.09.2 Schematron 样式表需要 XSLT 2.0，而 lxml/libxslt（仅支持 XSLT 1.0）无法编译这些样式表——根本原因与 ZUGFeRD 的 DE-XSLT2-1 问题相同。 validate_facturx 现在通过 Saxon-HE 执行真正的 Schematron 验证。要使用此功能，请安装可选的 xslt2 扩展： pip install mcp-facture-electronique-fr[xslt2]。若未安装，该工具会平稳降级为 level="unavailable"。

**注意（FR-FLUX11-2026-06，PPF Annuaire）：**目录工具直接基于随附的 PPF-platform swagger ppf-openapi-annuaire-api-public-1.11.0-openapi.json 接入——这是 PPF-platform 专用接口，并非与 PDP 无关的 Annex B 抽象。 根据 swagger 自身的说明，这些端点可能发生变化，使用前必须先发布 PISTE 应用。

Flow Service（流管理）

• submit_flow：提交发票（Factur-X、UBL、CII）或电子报告数据。
• search_flows：使用标准筛选条件，对已发送或已接收的流进行多条件搜索。
• submit_lifecycle_status：更新生命周期状态（例如：已开放、已收集、争议）。
• get_flow：检索特定流的完整详情和附件。
• healthcheck_flow：测试 PA Flow API 的连接性和可用性。

PPF Annuaire（目录）

直接基于随附的 PPF-platform swagger ppf-openapi-annuaire-api-public-1.11.0-openapi.json 构建 — 请参阅上文说明。

• search_company / get_company_by_siren / get_company_by_id_instance：查询法人单位（SIREN）。
• search_establishment / get_establishment_by_siret / get_establishment_by_id_instance：查询营业场所（SIRET）。
• search_routing_code / get_routing_code_by_siret_and_code / get_routing_code_by_id_instance / create_routing_code / update_routing_code / replace_routing_code：管理路由代码（code-routage）。
• search_directory_line / get_directory_line_by_code / get_directory_line / create_directory_line / update_directory_line / replace_directory_line / delete_directory_line：管理目录条目（ligne-annuaire），即电子发票接收地址。
• check_ppf_annuaire_health：检查 PPF Annuaire 服务的可用性。

Webhook 服务（Webhook 管理）

• list_webhooks：列出当前令牌持有者的所有 Webhook 订阅 ID。
• get_webhook：获取 Webhook 订阅的完整详情。
• create_webhook：订阅流事件通知（按流类型、方向和处理规则筛选）。
• update_webhook：更新 Webhook 的技术参数（身份验证、签名）。
• delete_webhook：取消 Webhook 订阅。

架构

该服务充当 AI Agent 与改革相关技术基础设施之间的智能通信接口：

[ ERP / Business IS ] <--> [ MCP Server ] <--> [ Approved Platform (PA/PDP) ]
          ^                        |
          |                        v
   [ AI Agent (Claude) ] <--- (XP Z12-013 Standard)

供应商中立性

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

法律要求使用 PDP（Plateforme de Dématérialisation Partenaire），但其 API 已根据 XP Z12-013 标准化，因此更换服务商只需修改配置，无需更改代码。

支持的标准

• AFNOR XP Z12-012：发票消息格式、配置文件和生命周期状态（v1.4，2026 年 6 月版）。
• AFNOR XP Z12-013：服务接口规范（2026 年 6 月版；v1.2.0 线路契约）。
• AFNOR XP Z12-014：业务用例技术实施指南（v1.4，2026 年 6 月版）。
• 法国 B2B 改革：强制实施时间表（2024-2026）。

测试

# Run the unit and integration test suite
pytest tests/ -v

贡献

欢迎贡献 — 请参阅 CONTRIBUTING.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。