FatturaPA / SDI

fatturapa-mcp-server

---

英文

问题

每个集成 FatturaPA 的项目 都会从头重新实现相同的验证、 解析和 SDI 错误处理。 结果是：数周的重复工作、 隐藏的错误，以及缺乏标准化。

解决方案

七种可通过一行命令安装的 AI 工具 — 文档解析、接收发票的异常检测、 多发票报告、通过 VIES 验证意大利和欧盟 VAT、XML 结构检查 以及离线查询 SDI 错误。

状态：beta。 在依赖验证结果之前，请参阅已知限制。

适用对象

使用意大利电子发票系统的 Python 开发者和 AI 团队， 他们希望集成 Claude，而不必在每个项目中 从头重新实现 FatturaPA 合规性。

这是什么？

这是一个 MCP（Model Context Protocol） 服务，为 AI 助手提供七种开箱即用的工具，用于处理意大利电子发票（FatturaPA）和 SDI（Sistema di Interscambio）系统 — 无需额外配置。

工具

工具	输入	功能
validate_invoice	xml_content	检查 XML 格式是否正确，以及是否具有 FatturaPA 根结构。⚠️ 尚未进行完整的架构验证 — 请参阅已知限制
extract_invoice_data	xml_content	从有效的 FatturaPA 文档中提取供应商、客户、金额、明细项和元数据
lookup_sdi_error	error_code	返回 SDI 错误代码的描述、类别和解决建议（离线）。⚠️ 错误代码表正在与官方列表重新校准 — 请参阅已知限制
check_piva	piva	使用 MEF 官方校验和算法验证意大利 P.IVA（增值税号）— 无需网络请求
verify_piva_vies	country_code、vat_number	通过实时 VIES REST API 验证任意欧盟增值税号；服务不可用时可平稳降级
find_invoice_anomalies	xml_content	检测 FatturaPA XML 文档中的异常：总额不一致、增值税错误、未来日期、无效 P.IVA、缺少收件人、明细项不完整、金额为负、缺少付款信息
generate_invoice_report	xml_contents	将多个 FatturaPA XML 文档汇总为一份报告，包含统计数据、供应商/客户明细和异常摘要

快速开始

选项 A — uvx（无需安装）

uvx fatturapa-mcp-server

选项 B — pip

pip install fatturapa-mcp-server
fatturapa-mcp-server

Claude Desktop 配置

将以下配置块添加到 Claude Desktop 配置文件中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fatturapa": {
      "command": "uvx",
      "args": ["fatturapa-mcp-server"],
      "env": { "FATTURAPA_ALLOWED_ROOTS": "/path/to/your/invoices" }
    }
  }
}

FATTURAPA_ALLOWED_ROOTS 列出了服务唯一允许读取的文件夹（在 macOS/Linux 上以 : 分隔，在 Windows 上以 ; 分隔）。未设置该变量时，所有 file_path 读取请求都会被拒绝，必须通过 xml_content 传入文档。这是有意为之：该服务由读取不可信文档的 AI Agent 驱动。

重启 Claude Desktop 后，你将在工具面板中看到七种新工具。

已知限制（v0.3.2）

使用合成发票，根据官方 AdE 架构（FatturaPA v1.2.3）进行审计后发现以下问题。这些问题将在后续版本中修复；在此之前：

• validate_invoice 仅进行结构验证。 随附的 XSD 文件是存根：对于未知单据类型（TD99）、无效币种（EURO）或缺少必需区块的发票，都会报告 valid: true。请勿将其用作 SDI 验证的替代方案。
• lookup_sdi_error：部分代码的描述与官方列表不符（例如，00001 的描述是“文件名无效”），并且有些代码缺失。
• 批次（lots）：文件包含多张发票时，只会完整分析第一张。
• 编码：声明为 ISO-8859-1 / windows-1252 的 XML 可能会被错误解码。
• 暂不支持已签名的 .p7m 文件：请先提取 XML。
• 报告：贷项通知单（TD04）会被加上而非减去；不同币种的总额会被相加。
• 金额以浮点数形式返回。

目前可靠的功能：一致性检查（总额、增值税、P.IVA 校验和、日期）、默认拒绝的文件访问、XXE 防护，以及服务不可用时的 VIES 降级处理。

更新日志 / 发布历史

Wave	工具 / 功能	发布版本
Wave 1	validate_invoice、extract_invoice_data、lookup_sdi_error、check_piva、verify_piva_vies	v0.1.0
Wave 2	发布到 PyPI、CI/CD、安全审计、完整覆盖	v0.1.0
Wave 3	上下文传播、结构化日志、进度报告、基于 roots 的安全文件访问	v0.1.x
Wave 4	find_invoice_anomalies、generate_invoice_report	v0.2.0

v0.3.2 统计： 7 个工具 · 181 项测试 · 95% 覆盖率，包括服务启动测试

展示内容

• 采用严格 mypy 类型检查的 MCP 服务，已在 Python 3.11、3.12 和 3.13 上测试
• 自动化安全审计 — bandit + pip-audit
• 保证最低 80% 的覆盖率（目前 181 项测试的覆盖率为 95%）
• 默认拒绝文件系统访问：除非明确配置，否则拒绝读取
• 已发布到 PyPI — 一行命令即可在任何地方安装
• 双语 IT/EN — 面向意大利和国际市场构建

为可审计性而设计

此仓库中的每项功能均通过受治理的多 Agent 流水线构建——规划者、执行者和审查者分别承担独立角色，每个角色都声明了权限，并设有严格的质量门槛。

coord/ 目录记录了完整的审计轨迹。每项任务都有一份交接记录，包含变更的文件及原因、所运行的命令及其 PASS/FAIL 输出、作出的假设及其验证方式，以及尚未解决的风险。上述四个开发阶段共包含十五份交接记录。

对于受监管的工作——电子发票、税务数据、合规事务——能够展示系统是 如何 构建的，与证明系统能够正常运行同样重要。相关方法论单独记录在 agentic-dev-pipeline 中。

项目状态

Beta。 已使用根据官方架构检查过的合成 FatturaPA 单据进行测试；尚未用于生产环境。请参阅已知限制。 属于更广泛生态系统的一部分：fatturapa-mcp-server → sdi-ops-monitor

开发环境设置

git clone https://github.com/MaurizioLisanti/fatturapa-mcp-server
cd fatturapa-mcp-server

# Install the package and all dev dependencies
make install        # pip install -e ".[dev]"

# Run the full quality gate (lint + typecheck + tests + security)
make check

各个目标：

make test           # pytest with coverage (fail-under 80 %)
make lint           # ruff check + ruff format --check
make typecheck      # mypy --strict
make security       # bandit -ll + pip-audit
make format         # auto-fix formatting and imports

MCP Inspector

MCP Inspector 可让你通过本地 Web UI 交互式调用工具，适用于开发期间：

npx @modelcontextprotocol/inspector uvx fatturapa-mcp-server
# Open http://localhost:5173 in your browser

相关项目

• sdi-ops-monitor — 基于 AWS 的流水线，用于接收、存储并将 FatturaPA 文件路由至 SDI 或从 SDI 路由出来。 将其与此 MCP 服务搭配使用，可让 Claude 全面了解你的意大利电子发票运营情况。

• agentic-dev-pipeline — 本项目所采用的受治理多 Agent 开发流水线。 coord/ 中的交接记录即为其产出。

---

意大利语

问题

每个集成 FatturaPA 的项目 都会从头重新实现相同的 SDI 验证、解析和错误处理逻辑。 结果就是：数周重复工作、 隐藏的 Bug，而且没有标准化。

解决方案

七个 AI 工具，一行即可安装 — 解析文档、检测收到的 发票中的异常、生成多发票报告、通过 VIES 验证 意大利和欧洲的 P.IVA、检查 XML 结构，以及离线查询 SDI 错误。

状态：beta。 在依赖验证结果之前，请先阅读已知限制。

适用对象

使用意大利电子发票系统的 Python 开发者和 AI 团队， 希望集成 Claude，而不必在每个项目中 都从头重新实现 FatturaPA 合规逻辑。

这个项目是什么？

这是一个 MCP（Model Context Protocol） 服务，为 AI 助手提供七种开箱即用的工具，用于处理意大利电子发票（FatturaPA）和交换系统（SDI）。

可用工具

工具	输入	功能
validate_invoice	xml_content	检查 XML 格式是否正确，以及根结构是否为 FatturaPA。⚠️ 尚未针对 schema 进行完整验证 — 请参阅“已知限制”
extract_invoice_data	xml_content	从有效的 FatturaPA 文档中提取供应商、客户、金额、明细行和元数据
lookup_sdi_error	error_code	返回 SDI 错误代码的说明、类别和解决建议（离线）。⚠️ 错误表正与官方列表重新校准 — 请参阅“已知限制”
check_piva	piva	通过 MEF 官方校验和算法验证意大利 P.IVA — 不进行网络调用
verify_piva_vies	country_code, vat_number	通过 VIES REST API 实时验证任何欧盟增值税号；服务无法访问时会降级响应
find_invoice_anomalies	xml_content	检测 FatturaPA XML 文档中的异常：总额不一致、增值税错误、未来日期、P.IVA 无效、缺少收件人、明细行不完整、金额为负、缺少付款信息
generate_invoice_report	xml_contents	将多个 FatturaPA XML 文档汇总成一份报告，包含统计信息、供应商/客户摘要和异常分析

快速开始

选项 A — uvx（无需安装）

uvx fatturapa-mcp-server

选项 B — pip

pip install fatturapa-mcp-server
fatturapa-mcp-server

配置 Claude Desktop

将以下代码块添加到 Claude Desktop 配置文件中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fatturapa": {
      "command": "uvx",
      "args": ["fatturapa-mcp-server"],
      "env": { "FATTURAPA_ALLOWED_ROOTS": "C:\\percorso\\delle\\fatture" }
    }
  }
}

FATTURAPA_ALLOWED_ROOTS 指定服务可以读取的文件夹（Windows 上以 ; 分隔，macOS/Linux 上以 : 分隔）。未设置此变量时，所有通过 file_path 读取文件的请求都会被拒绝，发票必须通过 xml_content 传入。这是有意的设计：该服务由 AI Agent 驱动，而 AI Agent 会读取不受信任的文档。

重启 Claude Desktop 后，七种工具就会显示在工具面板中。

已知限制（v0.3.2）

使用合成发票对照 AdE 官方架构（FatturaPA v1.2.3）进行审计后，发现了以下问题，这些问题将在后续版本中修正：

• validate_invoice 仅进行结构验证。 随附的 XSD 是存根：文档类型不存在（TD99）、货币无效（EURO）或缺少必需区块的发票，都会返回 valid: true。它不能替代 SDI 验证。
• lookup_sdi_error：部分描述与官方列表不符（例如，00001 是“文件名无效”），且缺少部分代码。
• 批次：如果文件包含多张发票，则只有第一张会被完整分析。
• 编码：声明为 ISO-8859-1 / windows-1252 的 XML 可能无法正确解码。
• .p7m：目前尚不支持已签名文件；请先提取 XML。
• 报告：贷项通知单（TD04）会被累加而非扣除；不同币种的总额会被相加。
• 金额以 float 形式返回。

目前已具备可靠支持：一致性检查（总额、增值税、P.IVA 校验和、日期）、失败时默认拒绝的文件访问、XXE 防护，以及 VIES 服务无响应时的处理。

更新日志 / 发布历史

Wave	工具 / 功能	发布版本
Wave 1	validate_invoice、extract_invoice_data、lookup_sdi_error、check_piva、verify_piva_vies	v0.1.0
Wave 2	发布到 PyPI、CI/CD、安全审计、完整覆盖率	v0.1.0
Wave 3	上下文传播、结构化日志、进度报告、通过 roots 安全访问文件	v0.1.x
Wave 4	find_invoice_anomalies、generate_invoice_report	v0.2.0

**v0.3.2 统计数据：**7 个工具 · 181 项测试 · 95% 覆盖率，包含服务器启动

技术能力展示

• 使用严格类型检查的 MCP 服务，通过 mypy 验证；已在 Python 3.11、3.12 和 3.13 上测试
• 自动安全审计 — bandit + pip-audit
• 最低覆盖率保证为 80%（目前 181 项测试的覆盖率为 95%）
• 失败时默认拒绝的文件系统访问：除非明确配置，否则禁止读取
• 已发布到 PyPI — 一行命令即可在任何地方安装
• 意大利语/英语双语 — 面向意大利和国际市场

设计即具备可追溯性

此代码库中的每项功能都通过受治理的多 Agent 流水线构建——规划者、执行者和审查者各司其职，每个角色都有明确的权限，并在各阶段之间设置强制质量门禁。

coord/ 文件夹是审计追踪。每项任务都有一份交接记录，其中包含修改的文件及其原因、执行的命令及 PASS/FAIL 结果、所做假设及其验证方式，以及尚未解决的风险。上文列出的四个开发阶段共由 15 份交接记录覆盖。

在电子发票、税务数据和合规等受监管领域，能够展示系统是如何构建的，与展示系统能够正常运行同样重要。相关方法另行记录在 agentic-dev-pipeline 中。

项目状态

Beta。 已使用根据官方架构验证过的 FatturaPA 合成发票进行测试；尚未用于生产环境。请参阅已知限制。 它是更大生态系统的一部分：fatturapa-mcp-server → sdi-ops-monitor

开发环境设置

git clone https://github.com/MaurizioLisanti/fatturapa-mcp-server
cd fatturapa-mcp-server

# Installa il pacchetto e tutte le dipendenze di sviluppo
make install        # pip install -e ".[dev]"

# Esegui il quality gate completo (lint + typecheck + test + security)
make check

单项目标：

make test           # pytest con coverage (fail-under 80 %)
make lint           # ruff check + ruff format --check
make typecheck      # mypy --strict
make security       # bandit -ll + pip-audit
make format         # correzione automatica formattazione e import

MCP Inspector

MCP Inspector 可通过本地 Web UI 交互式调用工具——适用于开发期间：

npx @modelcontextprotocol/inspector uvx fatturapa-mcp-server
# Aprire http://localhost:5173 nel browser

相关项目

• sdi-ops-monitor — AWS 管道， 用于接收、存储和路由发送到 SDI 或来自 SDI 的 FatturaPA 文件。 与此 MCP 服务配合使用，可让 Claude 全面了解意大利电子发票 运营情况。

• agentic-dev-pipeline — 用于构建此项目的多 Agent 治理开发管道。coord/ 中的交接文件 是其输出。

---

许可证 / Licenza

MIT