内容
# 电子发票工具
[English](README.md) | [简体中文](README.zh-CN.md)
<!-- mcp-name: io.github.cmendezs/mcp-fattura-elettronica-it -->
[](https://pypi.org/project/mcp-fattura-elettronica-it/)
[](https://pypi.org/project/mcp-fattura-elettronica-it/) [](https://glama.ai/mcp/servers/cmendezs/mcp-fattura-elettronica-it)
一个Python MCP服务器，用于生成、验证和分析符合**FatturaPA XML**格式（SDI / Agenzia delle Entrate标准，版本1.2.3）的**意大利电子发票**。它使AI代理（Claude，IDE）能够生成、验证和分析直接符合Sistema di Interscambio（SDI）技术规范的B2B、B2G和跨境电子发票。
这是一个**Model Context Protocol（MCP）**服务器，暴露了**42种工具**，涵盖了FatturaPA XML文档的整个生命周期：传输头构造、卖方/买方验证、文档类型代码（TD01-TD28）、行项目、增值税汇总计算、付款条件、XSD验证（官方Agenzia delle Entrate模式，v1.2.3）、XML生成、解析、JSON导出、SDI文件名生成、预扣税（ritenuta d'acconto）计算、数字签名（XAdES-BES和CAdES-BES）、通过SDICoop SOAP直接传输SDI、SDI通知解析和conservazione sostitutiva（依法存档，符合AgID规定）。遵循**Apache 2.0**许可。
---
## 🚀 安装
### 通过PyPI（推荐）
```bash
pip install mcp-fattura-elettronica-it
```
`mcp-einvoicing-core`将自动作为依赖项安装。
`lxml`也需要并已包含，因此无需额外步骤。
无需预先安装，使用`uvx`：
```bash
uvx mcp-fattura-elettronica-it
```
### 从源码
```bash
git clone https://github.com/cmendezs/mcp-fattura-elettronica-it.git
cd mcp-fattura-elettronica-it
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env
```
---
## ⚙️ 配置
可用的环境变量：
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `LOG_LEVEL` | 日志级别（`DEBUG`、`INFO`、`WARNING`、`ERROR`） | `INFO` |
| `FATTURA_XSD_PATH` | FatturaPA XSD文件路径 | `schemas/FatturaPA_v1.2.3.xsd` |
| `SDI_ENVIRONMENT` | SDI环境：`test`或`production` | `test` |
| `SDI_CERT_PATH` | SDI的PKCS#12 mTLS证书路径 | （无） |
| `SDI_CERT_PASSWORD` | PKCS#12文件的密码 | （无） |
| `SDI_ENDPOINT_URL` | SDICoop端点URL覆盖 | （自动从环境中） |
| `SDI_CHANNEL_ID` | 认证过程中分配的通道ID | （无） |
| `EINVOICING_SIGNER_SOCKET` | 签名微服务的Unix套接字 | （无） |
| `EINVOICING_SIGNER_TOKEN` | 签名微服务的身份验证令牌 | （无） |
| `CONSERVAZIONE_STORAGE_PATH` | 本地存档存储路径（仅限开发） | `.conservazione/` |
### 🤖 Claude Desktop集成
将以下内容添加到`claude_desktop_config.json`文件中：
```json
{
"mcpServers": {
"fattura-elettronica-it": {
"command": "uvx",
"args": ["mcp-fattura-elettronica-it"]
}
}
}
```
### ⌨️ Cursor集成
配置文件（`~/.cursor/mcp.json`或项目文件夹中的`.cursor/mcp.json`）：
```json
{
"mcpServers": {
"fattura-elettronica-it": {
"command": "uvx",
"args": ["mcp-fattura-elettronica-it"]
}
}
}
```
### 🪐 Kiro集成
```json
{
"mcpServers": {
"fattura-elettronica-it": {
"command": "uvx",
"args": ["mcp-fattura-elettronica-it"],
"disabled": false,
"autoApprove": []
}
}
}
```
---
## 🧰 可用MCP工具
### 头部：FatturaElettronicaHeader（7种工具）
| 工具 | 描述 |
|------|-------------|
| `build_transmission_header` | 构建DatiTrasmissione块：ProgressivoInvio、CodiceDestinatario、PECDestinatario |
| `validate_cedente_prestatore` | 验证卖方块：IdFiscaleIVA、Anagrafica、Sede、RegimeFiscale代码 |
| `validate_cessionario` | 验证买方块：IdFiscaleIVA或CodiceFiscale、Sede |
| `get_regime_fiscale_codes` | 返回所有有效的RegimeFiscale代码及其描述（RF01-RF19） |
| `validate_partita_iva` | 验证意大利增值税号码（Partita IVA）格式和校验和（11位） |
| `generate_progressivo_invio` | 生成唯一的ProgressivoInvio标识符（最多10个字母数字字符） |
| `lookup_codice_destinatario` | 返回有关CodiceDestinatario（6字符SDI代码）或PEC地址的信息 |
### 正文：FatturaElettronicaBody（7种工具）
| 工具 | 描述 |
|------|-------------|
| `build_dati_generali` | 构建DatiGenerali块：TipoDocumento、Divisa、Data、Numero、Causale |
| `get_tipo_documento_codes` | 返回所有TD01-TD28代码及其描述和使用情况（包括跨境） |
| `add_linea_dettaglio` | 添加DettaglioLinee条目：NumeroLinea、Descrizione、Quantita、PrezzoUnitario |
| `compute_totali` | 计算DatiRiepilogo：imponibile、imposta、AliquotaIVA从行项目 |
| `get_natura_codes` | 返回所有Natura代码（N1-N7和子代码）及其增值税豁免的法律参考 |
| `build_dati_pagamento` | 构建DatiPagamento：CondizioniPagamento（TP01/02/03）、ModalitaPagamento（MP01-MP23） |
| `add_allegato` | 将base64编码的文档附加到Allegati块中，包含名称和格式 |
### 全局：生成和验证（7种工具）
| 工具 | 描述 |
|------|-------------|
| `generate_fattura_xml` | 从结构化输入数据生成完整的FatturaPA XML文件 |
| `validate_fattura_xsd` | 验证FatturaPA XML字符串是否符合官方XSD模式v1.2.3 |
| `parse_fattura_xml` | 解析现有的FatturaPA XML字符串并返回结构化的JSON字典 |
| `export_to_json` | 将解析的FatturaPA结构导出为干净的JSON格式 |
| `validate_partita_iva_format` | 验证Partita IVA格式和Luhn校验和（11位意大利增值税） |
| `get_sdi_filename` | 生成官方SDI文件名：IT{PartitaIVA}_{ProgressivoInvio}.xml |
| `check_ritenuta_acconto` | 检查和计算专业发票的预扣税（withholding tax） |
### 简化发票：FatturaSemplificata VFSM10（3种工具）
| 工具 | 描述 |
|------|-------------|
| `generate_fattura_semplificata` | 使用VFSM10格式生成简化发票XML（TD07/TD08/TD09） |
| `validate_fattura_semplificata_xsd` | 验证简化发票XML是否符合VFSM10 XSD v1.0.2 |
| `parse_fattura_semplificata_xml` | 将简化发票XML解析为结构化字典 |
简化发票（art. 21-bis DPR 633/72）适用于交易额不超过EUR 400（含税）的交易。
它们使用比普通FatturaPA更扁平的结构：没有每行的增值税明细，没有DatiRiepilogo。
每个`DatiBeniServizi`条目都有自己的`Descrizione`、`Importo`和`DatiIVA`。
VFSM10格式使用命名空间`v1.0`，与普通发票使用的EN 16931 CIUS不同。
### 数字签名（2种工具）
| 工具 | 描述 |
|------|-------------|
| `sign_fattura_xades` | 应用XAdES-BES enveloped XML签名（.xml）。需要PKCS#12证书。 |
| `sign_fattura_cades` | 应用CAdES-BES CMS/PKCS#7 attached签名（.xml.p7m）。需要PKCS#12证书。 |
两种签名格式均被SDI接受（Specifiche tecniche SDI v1.8.4，第2.1节）。
支持双模式：签名微服务（将密钥保持在MCP进程之外）或直接PKCS#12加载。
需要`cryptography>=42.0.0`（通过`mcp-einvoicing-core`上的`[xml-sign]`额外功能安装）。
### SDI集成（5种工具）
| 工具 | 描述 |
|------|-------------|
| `submit_to_sdi` | 通过SDICoop SOAP（mTLS）将签名发票提交给SDI |
| `check_sdi_status` | 通过IdentificativoSDI检查提交状态 |
| `parse_sdi_notification` | 解析SDI通知XML（RC/NS/MC/NE/EC/SE/DT/MT/AT） |
| `send_esito_committente` | 向SDI发送接受（EC01）或拒绝（EC02） |
| `get_sdi_channel_info` | 显示当前SDI通道配置 |
生产使用需要AdE认证。配置环境变量`SDI_CERT_PATH`、`SDI_CERT_PASSWORD`、`SDI_ENVIRONMENT`（测试/生产）和`SDI_ENDPOINT_URL`（覆盖）。
### 保管存档 / 存档（5种工具）
| 工具 | 描述 |
|------|-------------|
| `archive_invoice` | 使用SHA-256哈希和10年保留期存档签名发票 |
| `retrieve_archived_invoice` | 通过ID检索存档文档 |
| `verify_archive_integrity` | 验证存档文档的SHA-256哈希完整性 |
| `list_archived_invoices` | 列出所有存档发票 |
| `build_pacchetto_versamento` | 为转移到AgID认证的保管员构建PdV ZIP存档 |
根据AgID circolare 65/2014和DM 17/06/2014，电子发票必须存档至少10年。
本地文件系统后端仅用于开发；生产需要与AgID认证的conservazione提供商集成。
---
## 用例
### 示例1：生成完整的B2B发票
```
1. validate_partita_iva_format("01234567897")
→ { "valid": true }
2. generate_progressivo_invio(sequence=1)
→ { "progressivo_invio": "00001" }
3. build_transmission_header(id_paese="IT", id_codice="01234567897",
progressivo_invio="00001", formato_trasmissione="FPR12",
codice_destinatario="ABC123")
4. validate_cedente_prestatore(id_paese="IT", id_codice="01234567897",
denominazione="ACME Srl", regime_fiscale="RF01",
indirizzo="Via Roma 1", cap="00100", comune="Roma", nazione="IT")
5. validate_cessionario(denominazione="Buyer Srl",
id_paese="IT", id_codice="98765432109",
indirizzo="Via Verdi 2", cap="20100", comune="Milano")
6. build_dati_generali(tipo_documento="TD01", data="2026-01-15",
numero="2026/001", divisa="EUR")
7. add_linea_dettaglio(numero_linea=1, descrizione="Consulenza informatica",
quantita=8, unita_misura="ORE", prezzo_unitario=100.0,
prezzo_totale=800.0, aliquota_iva=22.0)
8. compute_totali(linee=[{"prezzo_totale": 800.0, "aliquota_iva": 22.0}])
→ { "totale_fattura": "976.00" }
9. build_dati_pagamento(condizioni_pagamento="TP02", modalita_pagamento="MP05",
importo_pagamento=976.0, iban="IT60X0542811101000000123456")
10. generate_fattura_xml(...all previous blocks...)
→ { "xml": "<?xml ...", "filename": "IT01234567897_00001.xml" }
11. validate_fattura_xsd(xml_string=...)
→ { "valid": true }
```
### 示例2：专业发票与预扣税
```
check_ritenuta_acconto(imponibile=1000.0, tipo_ritenuta="RT02",
causale_pagamento="A")
→ {
"DatiRitenuta": {
"TipoRitenuta": "RT02",
"ImportoRitenuta": "200.00",
"AliquotaRitenuta": "20.00",
"CausalePagamento": "A"
},
"importo_ritenuta": "200.00"
}
```
### 示例3：查找增值税豁免代码
```
get_natura_codes()
→ codes: [
{ "code": "N3.1", "description": "Non imponibili — esportazioni",
"legal_ref": "Art. 8 DPR 633/72" },
{ "code": "N6.1", "description": "Inversione contabile — rottami",
"legal_ref": "Art. 74 c. 7-8 DPR 633/72" },
...
]
```
---
## 架构
```
mcp-fattura-elettronica-it (此包，独立MCP服务器)
├── ItalyPartyValidator(BasePartyValidator) ← Partita IVA modulo-10
├── FatturaGenerator(BaseDocumentGenerator) ← FatturaPA XML v1.2.3
├── FatturaValidator(BaseDocumentValidator) ← lxml XSD v1.2.3
└── FatturaParser(BaseDocumentParser) ← lxml xpath
↑ extends
mcp-einvoicing-core (共享基础，作为依赖项安装)
├── BaseDocumentGenerator / Validator / Parser / PartyValidator
├── InvoiceDocument, InvoiceParty, InvoiceLineItem … (Pydantic)
├── xml_utils, logging_utils, exceptions
└── EInvoicingMCPServer (可选的多国聚合器)
```
---
## 📚 参考标准
| 资源 | 链接 |
|----------|------|
| FatturaPA规格 | [fatturapa.gov.it](https://www.fatturapa.gov.it) |
| 官方XSD v1.2.3 | [Schema v1.2.2, Agenzia delle Entrate](https://www.fatturapa.gov.it/it/norme-e-aggiornamenti/documentazione-fatturapa/) |
| XML命名空间 | `http://ivaservizi.agenziaentrate.gov.it/docs/xsd/fatture/v1.2` |
| SDI, Sistema di Interscambio | [Agenzia delle Entrate](https://www.agenziaentrate.gov.it/portale/web/guest/aree-tematiche/fatturazione-elettronica) |
| 预扣税（withholding tax） | Art. 25 DPR 600/73, Modello 770 |
---
## 🧪 测试
```bash
# 安装开发依赖
pip install -e ".[dev]"
# 运行所有测试
pytest tests/ -v
# 仅运行MCP集成测试
pytest tests/test_mcp_integration.py -v
---
## 路线图
| 版本 | 功能 |
|---------|----------|
| **v0.1.0** | XML生成，XSD验证，解析，21种MCP工具，预扣税 |
| **v0.2.0** | 简化发票（TD07/TD08/TD09），FPA12批量发票，增值税率警告，30种MCP工具 |
| **v0.3.0** | SdI生命周期范围边界文档，传输字段默认值移除 |
| **v0.5.0** （当前） | XAdES-BES和CAdES-BES数字签名，直接SDI集成（SDICoop SOAP），保管存档（AgID存档），42种MCP工具 |
| **v0.6.0** | SFTP通道，AgID认证提供商API集成 |
---
## 其他电子发票MCP服务器
| 国家 | 服务器 |
|---------|--------|
| 🌍 全球 | [mcp-einvoicing-core](https://github.com/cmendezs/mcp-einvoicing-core) |
| 🇧🇪 比利时 | [mcp-einvoicing-be](https://github.com/cmendezs/mcp-einvoicing-be) |
| 🇧🇷 巴西 | [mcp-nfe-br](https://github.com/cmendezs/mcp-nfe-br) |
| 🇫🇷 法国 | [mcp-facture-electronique-fr](https://github.com/cmendezs/mcp-facture-electronique-fr) |
| 🇩🇪 德国 | [mcp-einvoicing-de](https://github.com/cmendezs/mcp-einvoicing-de) |
| 🇮🇹 意大利 | [mcp-fattura-elettronica-it](https://github.com/cmendezs/mcp-fattura-elettronica-it) |
| 🇵🇱 波兰 | [mcp-ksef-pl](https://github.com/cmendezs/mcp-ksef-pl) |
| 🇪🇸 西班牙 | [mcp-facturacion-electronica-es](https://github.com/cmendezs/mcp-facturacion-electronica-es) |
---
## 📄 许可
此项目遵循 **Apache 2.0** 许可协议。
详见 [LICENSE](LICENSE) 文件。
版权所有 2026 cmendezs
---
*项目由 [cmendezs](https://github.com/cmendezs) 维护。对于FatturaPA规格实施的疑问，请提交问题。*
```
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器