Metadata-Version: 2.4
Name: fatturapa-mcp-server
Version: 0.3.0
Summary: MCP server for Italian FatturaPA/SDI e-invoicing
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: lxml>=5.0.0
Requires-Dist: mcp[cli]>=1.0.0
Provides-Extra: dev
Requires-Dist: bandit[toml]==1.9.4; extra == 'dev'
Requires-Dist: lxml-stubs==0.5.1; extra == 'dev'
Requires-Dist: mypy==2.1.0; extra == 'dev'
Requires-Dist: pip-audit==2.10.1; extra == 'dev'
Requires-Dist: pytest-asyncio==1.4.0; extra == 'dev'
Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
Requires-Dist: pytest-httpx==0.36.2; extra == 'dev'
Requires-Dist: pytest==9.1.0; extra == 'dev'
Requires-Dist: ruff==0.15.18; extra == 'dev'
Description-Content-Type: text/markdown

# fatturapa-mcp-server

[![CI](https://github.com/MaurizioLisanti/fatturapa-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/MaurizioLisanti/fatturapa-mcp-server/actions/workflows/ci.yml)
[![Coverage gate](https://img.shields.io/badge/coverage%20gate-80%25%20enforced-brightgreen)](https://github.com/MaurizioLisanti/fatturapa-mcp-server/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

---

# English
## The problem
Every project integrating FatturaPA
reimplements the same validation,
parsing and SDI error handling from scratch.
The result: weeks of repeated work,
hidden bugs and no standardization.

## The solution
Seven production-grade AI tools installable
in one line — official AdE XSD validation,
full document parsing, offline SDI error lookup,
Italian and EU VAT verification via VIES,
anomaly detection and multi-invoice reporting.
## Who is it for
Python developers and AI teams working
on Italian electronic invoicing systems
who want to integrate Claude without
reimplementing FatturaPA compliance
from scratch on every project.
### What is this?

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that gives
AI assistants seven ready-to-use tools for working with Italian electronic invoices
(FatturaPA) and the SDI (Sistema di Interscambio) system — no plumbing required.

### Tools

| Tool | Input | What it does |
|------|-------|--------------|
| `validate_invoice` | `xml_content` | Validates FatturaPA XML against official AdE XSD schemas (v1.2 & v1.3); auto-detects version from namespace |
| `extract_invoice_data` | `xml_content` | Extracts supplier, customer, amounts, line items and metadata from a valid FatturaPA document |
| `lookup_sdi_error` | `error_code` | Returns the official Italian description, category and resolution hint for any SDI error code (offline) |
| `check_piva` | `piva` | Validates an Italian P.IVA (VAT number) using the official MEF checksum algorithm — no network call |
| `verify_piva_vies` | `country_code`, `vat_number` | Verifies any EU VAT number against the live VIES REST API; degrades gracefully when the service is down |
| `find_invoice_anomalies` | `xml_content` | Detects anomalies in a FatturaPA XML document: inconsistent totals, wrong VAT, future dates, invalid P.IVA, missing recipient, incomplete line items, negative amounts, missing payment info |
| `generate_invoice_report` | `xml_contents` | Aggregates multiple FatturaPA XML documents into a single report with statistics, supplier/customer breakdown and anomaly summary |

### Quick start

**Option A — uvx (no install required)**

```bash
uvx fatturapa-mcp-server
```

**Option B — pip**

```bash
pip install fatturapa-mcp-server
fatturapa-mcp-server
```

### Claude Desktop configuration

Add the following block to your Claude Desktop config file:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "fatturapa": {
      "command": "uvx",
      "args": ["fatturapa-mcp-server"]
    }
  }
}
```

After restarting Claude Desktop you will see seven new tools in the tool panel.

> **Note on XSD schemas:** `validate_invoice` requires the official AdE XSD files.
> See [`src/fatturapa_mcp/schemas/README.md`](src/fatturapa_mcp/schemas/README.md)
> for download instructions.

## Changelog / Release history

| Wave | Tools / Features | Release |
|------|-----------------|---------|
| Wave 1 | `validate_invoice`, `extract_invoice_data`, `lookup_sdi_error`, `check_piva`, `verify_piva_vies` | v0.1.0 |
| Wave 2 | PyPI publication, CI/CD, security audit, full coverage | v0.1.0 |
| Wave 3 | Context propagation, structured logging, progress reporting, roots-based secure file access | v0.1.x |
| Wave 4 | `find_invoice_anomalies`, `generate_invoice_report` | v0.2.0 |

**v0.3.0 stats:** 7 tools · 178 tests · 95.6% coverage

## What it demonstrates
- Production-grade MCP server with strict mypy typing
- Automated security audit — bandit + pip-audit
- Guaranteed 80% minimum coverage (currently 95.6% across 178 tests)
- Fail-closed file-system access: reads are refused unless explicitly configured
- Published on PyPI — installable anywhere in one line
- Bilingual IT/EN — built for Italian and international market

### Auditable by design

Every feature in this repository was built through a governed multi-agent
pipeline — planner, executor and reviewer as separate roles, each with declared
authority and hard quality gates between them.

The `coord/` directory is the audit trail. One handoff per task, recording the
files changed and why, the commands run with their PASS/FAIL output, the
assumptions made and how they were verified, and the risks left open. Fifteen
handoffs cover the four development waves listed above.

For regulated work — e-invoicing, tax data, compliance — being able to show
*how* a system was built matters as much as showing that it works. The
methodology is documented separately in
[agentic-dev-pipeline](https://github.com/MaurizioLisanti/agentic-dev-pipeline).

## Production status
Used on real Italian electronic invoicing systems.
Tested with real SDI documents in production environments.
Part of a broader ecosystem: fatturapa-mcp-server → sdi-ops-monitor

### Development setup

```bash
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
```

Individual targets:

```bash
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](https://github.com/modelcontextprotocol/inspector) lets you call
tools interactively from a local web UI — useful during development:

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

### Related projects

- **[sdi-ops-monitor](https://github.com/MaurizioLisanti/sdi-ops-monitor)** — AWS-based
  pipeline that receives, stores and routes FatturaPA files from/to SDI.
  Use together with this MCP server to give Claude end-to-end visibility into
  your Italian e-invoicing operations.

- **[agentic-dev-pipeline](https://github.com/MaurizioLisanti/agentic-dev-pipeline)** —
  The governed multi-agent development pipeline this project was built with.
  The handoffs in `coord/` are its output.

---

# Italiano
## Il problema
Ogni progetto che integra FatturaPA
reimplementa da zero la stessa logica
di validazione, parsing e gestione errori SDI.
Il risultato: settimane di lavoro ripetuto,
bug nascosti e nessuna standardizzazione.
## La soluzione
Sette tool AI production-grade installabili
in una riga — validazione XSD ufficiale AdE,
parsing completo, lookup errori SDI offline,
verifica P.IVA italiana ed europea via VIES,
rilevamento anomalie e report multi-fattura.
## Per chi è
Developer Python e team AI che lavorano
su sistemi di fatturazione elettronica italiana
e vogliono integrare Claude senza reimplementare
la compliance FatturaPA da zero ad ogni progetto.
### Cos'è questo progetto?

Un server [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) che
fornisce agli assistenti AI sette strumenti pronti all'uso per lavorare con le
fatture elettroniche italiane (FatturaPA) e il Sistema di Interscambio (SDI).

### Strumenti disponibili

| Strumento | Input | Cosa fa |
|-----------|-------|---------|
| `validate_invoice` | `xml_content` | Valida un XML FatturaPA contro gli XSD ufficiali AdE (v1.2 e v1.3); rileva automaticamente la versione dal namespace |
| `extract_invoice_data` | `xml_content` | Estrae fornitore, cliente, importi, righe dettaglio e metadati da un documento FatturaPA valido |
| `lookup_sdi_error` | `error_code` | Restituisce la descrizione ufficiale italiana, la categoria e il suggerimento di risoluzione per qualsiasi codice errore SDI (offline) |
| `check_piva` | `piva` | Valida una P.IVA italiana tramite l'algoritmo di checksum ufficiale MEF — nessuna chiamata di rete |
| `verify_piva_vies` | `country_code`, `vat_number` | Verifica qualsiasi partita IVA UE contro l'API REST VIES in tempo reale; risponde in modo degradato se il servizio è irraggiungibile |
| `find_invoice_anomalies` | `xml_content` | Rileva anomalie in un documento FatturaPA XML: totale incoerente, IVA errata, data futura, P.IVA invalida, destinatario mancante, righe incomplete, importo negativo, pagamento mancante |
| `generate_invoice_report` | `xml_contents` | Aggrega più documenti FatturaPA XML in un unico report con statistiche, riepilogo fornitori/clienti e analisi delle anomalie |

### Avvio rapido

**Opzione A — uvx (nessuna installazione necessaria)**

```bash
uvx fatturapa-mcp-server
```

**Opzione B — pip**

```bash
pip install fatturapa-mcp-server
fatturapa-mcp-server
```

### Configurazione Claude Desktop

Aggiungere il seguente blocco al file di configurazione di Claude Desktop:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "fatturapa": {
      "command": "uvx",
      "args": ["fatturapa-mcp-server"]
    }
  }
}
```

Dopo il riavvio di Claude Desktop, i sette strumenti compariranno nel pannello degli strumenti.

> **Nota sugli XSD:** `validate_invoice` richiede i file XSD ufficiali di AdE.
> Vedere [`src/fatturapa_mcp/schemas/README.md`](src/fatturapa_mcp/schemas/README.md)
> per le istruzioni di download.
## Changelog / Storico release

| Wave | Tool / Funzionalità | Release |
|------|---------------------|---------|
| Wave 1 | `validate_invoice`, `extract_invoice_data`, `lookup_sdi_error`, `check_piva`, `verify_piva_vies` | v0.1.0 |
| Wave 2 | Pubblicazione PyPI, CI/CD, security audit, coverage completa | v0.1.0 |
| Wave 3 | Propagazione contesto, logging strutturato, progress reporting, accesso file sicuro via roots | v0.1.x |
| Wave 4 | `find_invoice_anomalies`, `generate_invoice_report` | v0.2.0 |

**Statistiche v0.3.0:** 7 tool · 178 test · 95.6% coverage

## Cosa dimostra tecnicamente
## Cosa dimostra tecnicamente
- MCP server production-grade con strict typing mypy
- Security audit automatico — bandit + pip-audit
- Coverage minima garantita all'80% (attualmente 95.6% su 178 test)
- Accesso al filesystem fail-closed: le letture sono negate salvo configurazione esplicita
- Pubblicato su PyPI — installabile ovunque con una riga
- Bilingue IT/EN — pensato per mercato italiano e internazionale

### Tracciabilita by design

Ogni funzionalita di questo repository e stata costruita con una pipeline
multi-agente governata — planner, executor e reviewer come ruoli distinti,
ciascuno con autorita dichiarata e quality gate obbligatori tra una fase e
l'altra.

La cartella `coord/` e la pista di controllo. Un handoff per task, con i file
modificati e il motivo, i comandi eseguiti con esito PASS/FAIL, le assunzioni
fatte e come sono state verificate, i rischi lasciati aperti. Quindici handoff
coprono le quattro wave di sviluppo elencate sopra.

Nel lavoro su ambiti regolati — fatturazione elettronica, dati fiscali,
compliance — poter mostrare *come* un sistema e stato costruito conta quanto
mostrare che funziona. La metodologia e documentata separatamente in
[agentic-dev-pipeline](https://github.com/MaurizioLisanti/agentic-dev-pipeline).
## In produzione
Usato su sistemi reali di fatturazione elettronica italiana.
Testato con documenti SDI reali in ambiente di produzione.
Parte di un ecosistema più ampio: fatturapa-mcp-server → sdi-ops-monitor

### Setup per lo sviluppo

```bash
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
```

Target individuali:

```bash
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](https://github.com/modelcontextprotocol/inspector) permette di
invocare gli strumenti in modo interattivo da una web UI locale — utile durante lo sviluppo:

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

### Progetti correlati

- **[sdi-ops-monitor](https://github.com/MaurizioLisanti/sdi-ops-monitor)** — Pipeline AWS
  per ricevere, archiviare e instradare i file FatturaPA da/verso il SDI.
  Da usare insieme a questo server MCP per dare a Claude visibilità end-to-end
  sulle operazioni di fatturazione elettronica italiana.

- **[agentic-dev-pipeline](https://github.com/MaurizioLisanti/agentic-dev-pipeline)** —
  La pipeline di sviluppo multi-agente governata con cui questo progetto è stato
  costruito. Gli handoff in `coord/` ne sono l'output.

---

## License / Licenza

[MIT](LICENSE)
