aruba-fatture-mcp

<p align="center"> <img src="assets/banner.svg" alt="Aruba Fatture MCP — Fatturazione Elettronica Aruba per qualsiasi client MCP" width="100%"> </p> <p align="center"> <a href="https://modelcontextprotocol.io"><img alt="MCP server" src="https://img.shields.io/badge/MCP-server-FF7A4D"></a> <img alt="Node 18+" src="https://img.shields.io/badge/Node-18%2B-3C873A"> <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-strict-3178C6"> <img alt="License MIT" src="https://img.shields.io/badge/license-MIT-22B8E6"> <img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-38E1C4"> </p> <h1 align="center">Aruba Fatture MCP</h1> <p align="center"> <b>Fatturazione Elettronica Aruba per qualsiasi client MCP.</b><br> Fatture inviate e ricevute, clienti e fornitori, statistiche IVA e creazione fatture — in tempo reale, anche senza utenza Premium. </p>

Server Model Context Protocol che porta la Fatturazione Elettronica di Aruba dentro qualsiasi client MCP — Claude (Code e Desktop), Cursor, Cline, Zed e gli altri. Interroghi e crei fatture elettroniche (FatturaPA / SDI) in linguaggio naturale: «quanto ho fatturato quest'anno?», «prospetto IVA del trimestre», «chi sono i miei fornitori principali?», «genera la fattura per questo cliente».

Documentazione API ufficiali Aruba: https://fatturazioneelettronica.aruba.it/apidoc/v2/docs.html

Il server ha tre sorgenti dati indipendenti:

• Pannello web (live) — legge le fatture direttamente dal pannello Aruba in tempo reale, senza utenza Premium. È la sorgente consigliata per liste, clienti/fornitori, IVA e statistiche;
• API Aruba ufficiali — dati in tempo reale dal web service, ma richiedono un'utenza Premium (o delegata da una Premium);
• archivio locale — analisi sugli XML/ZIP esportati a mano, utile offline o come backup.

In tutte le sorgenti, fatture inviate (ciclo attivo) e ricevute (ciclo passivo) sono sempre tenute separate: nessun tool le somma o le mischia.

Tool sul pannello web (live, nessuna utenza Premium)

Accedono al pannello con le stesse credenziali del login web, replicandone l'API interna. Non serve esportare nulla: i dati sono sempre aggiornati.

| Tool | Descrizione | |---|---| | panel_list_invoices | Elenco fatture di un ciclo (inviate o ricevute), con filtri per periodo e controparte e i totali | | panel_invoice_detail | Dettaglio di una singola fattura (metadati + righe + riepilogo IVA); può salvare XML e PDF su disco | | panel_counterparties | Clienti (dalle inviate) o fornitori (dalle ricevute), con totali e periodo di attività | | panel_registry | Registro anagrafico salvato in Aruba: clienti o fornitori, con P.IVA, codice fiscale, codice destinatario e indirizzo | | panel_vat_report | Totali IVA dell'anno: IVA vendite e IVA acquisti separate, con il saldo | | panel_revenue_trend | Andamento per mese/trimestre/anno, inviate e ricevute in due serie distinte | | panel_create_invoice_xml | Genera l'XML di una nuova fattura scegliendo il cliente dal registro Aruba; calcola i totali. Non invia | | panel_upload_invoice | Carica un XML nel pannello creando una bozza pronta da rivedere e inviare. Non invia a SDI |

Ogni tool di elenco/anagrafica richiede il parametro ciclo (o tipo) proprio per non mescolare mai i due flussi. I dati dell'anno vengono scaricati una volta e messi in cache; ricarica: true forza il riscaricamento.

Creare e inviare una fattura

Il flusso è pensato per essere sicuro rispetto all'unica azione irreversibile — l'invio a SDI:

1. panel_registry con tipo: "clienti" per trovare il destinatario (o si conosce già la sua P.IVA);
2. panel_create_invoice_xml genera l'XML: i dati del mittente sono riusati da una fattura già emessa (sempre corretti), il destinatario dal registro Aruba, e i totali IVA sono calcolati dalle righe. Restituisce il file e i totali da verificare;
3. panel_upload_invoice carica l'XML nel pannello come bozza.

L'invio a SDI non è automatizzato di proposito. È un'azione irreversibile e, su questo account, Aruba richiede un OTP via SMS per completarla (jsAbilitaOtpCaricaFattura). Dopo l'upload, la bozza va rivista e inviata dal pannello web. È una tutela voluta: nessun tool può far partire una fattura reale senza un passaggio umano.

Questi tool usano l'API privata del pannello, non documentata da Aruba: è più comoda (nessun requisito di utenza) ma può cambiare senza preavviso. Per l'accesso ufficiale e stabile restano i tool «API Aruba» qui sotto, che però richiedono un'utenza Premium.

Tool sulle API Aruba

| Tool | Descrizione | Utenza richiesta | |---|---|---| | get_user_info | Informazioni account (P.IVA, stato servizio, spazio conservazione) | base | | get_invoice_notifications | Notifiche SDI di una fattura per nome file (consegna, scarto, esiti) | base¹ | | send_invoice | Invia una fattura XML a SDI — di default dryRun=true (solo validazione) | Premium | | search_invoices | Ricerca fatture inviate o ricevute per periodo, stato, controparte | Premium | | get_invoice_detail | Metadati completi di una fattura (per id, filename o idSdi) | Premium | | download_invoice | Salva su disco XML, PDF, ZIP (fattura + notifiche) o PDD | Premium |

Le utenze base standalone non hanno le deleghe API (FAW-*): ricerca e dettaglio rispondono 401 (delega FAW-R non presente per le inviate, FAW-IN per le ricevute), l'upload risponde 0093 Errore deleghe — ma solo dopo aver superato la validazione XSD, quindi un errore 0092 su upload non implica che l'invio sia abilitato. ¹L'endpoint notifiche risponde a livello dati con utenza base (verificato con errorCode 0002), ma non è stato possibile verificarlo con una fattura esistente.

Attenzione: il controllo delle deleghe avviene dopo la validazione dei parametri. Una richiesta con una finestra date superiore a 10 giorni risponde 400 anche a un'utenza senza deleghe: per sapere se le deleghe ci sono, interrogare con una finestra valida.

Tool sull'archivio locale

Funzionano su una cartella di fatture esportate dal pannello Aruba (o da qualunque altro portale SDI) e non richiedono utenza Premium. Formati riconosciuti, anche in sottocartelle: .xml, .p7m (firmate CAdES) e .zip che li contengono. I duplicati — stesso emittente, numero e data — vengono unificati.

| Tool | Descrizione | |---|---| | list_invoices | Elenco fatture filtrabile per direzione, periodo, controparte, tipo documento e importo, con i totali del sottoinsieme | | list_counterparties | Anagrafica clienti e fornitori ricostruita dalle fatture, con numero documenti, totali e periodo di attività | | vat_report | Prospetto IVA del periodo: imponibile e imposta per aliquota e natura, separando vendite e acquisti, con il saldo | | revenue_trend | Andamento di fatturato e acquisti per mese, trimestre o anno |

La direzione (emessa/ricevuta) è determinata confrontando il cedente della fattura con la partita IVA e il codice fiscale del titolare, letti automaticamente da get_user_info (con fallback a ARUBA_VAT_CODE / ARUBA_FISCAL_CODE se l'account non è raggiungibile).

vat_report è un prospetto contabile di supporto, non una liquidazione IVA: non tiene conto di detraibilità parziale, reverse charge, split payment o crediti pregressi.

Requisiti

• Node.js ≥ 18
• Credenziali del servizio Aruba Fatturazione Elettronica

Installazione

npm install
npm run build

Configurazione

| Variabile | Descrizione | |---|---| | ARUBA_USERNAME | Username del servizio Fatturazione Elettronica | | ARUBA_PASSWORD | Password del servizio | | ARUBA_ENVIRONMENT | demo (default) oppure production | | ARUBA_ARCHIVE_DIR | Cartella con gli XML/ZIP delle fatture, usata dai tool di analisi quando non si passa archivePath | | ARUBA_VAT_CODE | Facoltativa: P.IVA del titolare, solo come fallback se get_user_info non è raggiungibile | | ARUBA_FISCAL_CODE | Facoltativa: codice fiscale del titolare, stesso scopo |

Le credenziali non vanno messe in file versionati: .env è già in .gitignore.

L'ambiente demo usa i server di test Aruba (demoauth/demows): consigliato per le prime prove.

Collegare il server a un client MCP

Il server parla stdio ed è compatibile con qualunque client MCP. La configurazione è sempre la stessa — comando node <percorso>/dist/index.js con le variabili d'ambiente qui sopra. Sotto due esempi (Claude Code e Claude Desktop); per Cursor, Cline, Zed e gli altri vale lo stesso schema command/args/env nel rispettivo file di configurazione MCP.

Claude Code

claude mcp add aruba-fatture ^
  -e ARUBA_USERNAME=tuo_username ^
  -e ARUBA_PASSWORD=tua_password ^
  -e ARUBA_ENVIRONMENT=demo ^
  -- node <percorso-del-progetto>\dist\index.js

Claude Desktop

In claude_desktop_config.json (o nel file MCP equivalente di Cursor/Cline/Zed):

{
  "mcpServers": {
    "aruba-fatture": {
      "command": "node",
      "args": ["<percorso-del-progetto>\\dist\\index.js"],
      "env": {
        "ARUBA_USERNAME": "tuo_username",
        "ARUBA_PASSWORD": "tua_password",
        "ARUBA_ENVIRONMENT": "demo"
      }
    }
  }
}

Note operative

• Invio a SDI: send_invoice per default esegue solo la validazione (dryRun=true). L'invio reale avviene solo chiedendo esplicitamente di impostare dryRun=false.
• Trasmittente: le fatture inviate tramite Aruba devono riportare l'intermediario Aruba nell'IdTrasmittente (P.IVA 01879020517).
• Codice destinatario per ricevere fatture su Aruba: KRRH6B9.
• Rate limit Aruba: 12 richieste/minuto per le ricerche, 30/minuto per gli upload; oltre soglia il server restituisce HTTP 429. Anche l'endpoint di autenticazione è soggetto a rate limit severi: il client serializza i login e riusa i token proprio per questo — in caso di 429 sull'autenticazione attendere qualche minuto.
• I contenuti base64 (XML/PDF) vengono omessi dalle risposte testuali per non saturare il contesto: usare download_invoice per salvarli su file.
• I token di accesso (30 min) e di refresh (60 min) sono gestiti automaticamente.

Architettura

<p align="center"> <img src="assets/architecture.svg" alt="Tre sorgenti dati (pannello web live, API ufficiali, archivio locale) verso un unico server MCP e qualsiasi client MCP" width="100%"> </p>

Il codice è organizzato per sorgente dati, in modo che i tre canali restino indipendenti.

| File | Ruolo | |---|---| | src/index.ts | Server MCP: registra tutti i tool e li instrada alla sorgente giusta | | src/panel-client.ts | Login headless al pannello (OpenID Connect) e chiamate all'API interna /services/* | | src/panel.ts | Normalizzazione e aggregazione dei dati del pannello (inviate/ricevute separate) | | src/aruba-client.ts | Client delle API ufficiali (OAuth2 password/refresh, gestione token) | | src/archivio.ts | Lettura di un archivio locale di .xml/.p7m/.zip, con classificazione emesse/ricevute | | src/fatturapa.ts | Parser FatturaPA v1.2.x da XML a struttura tipizzata | | src/analisi.ts | Aggregazioni sull'archivio locale (liste, controparti, IVA per aliquota, andamento) |

Come funziona la modalità pannello (live)

Il pannello web di Aruba non espone API documentate, ma la sua interfaccia parla con un backend REST interno (/services/*) dietro un login OpenID Connect (Keycloak). Il client replica il flusso di login del browser senza browser:

1. GET /api/oauth2/authorization/gateway → il gateway reindirizza a Keycloak e imposta il cookie di sessione;
2. si legge la pagina di login Keycloak e se ne estrae l'action del form;
3. POST di username e password all'action → risposta con l'authorization code (il reCAPTCHA della pagina non è imposto lato server);
4. il ritorno del code al gateway stabilisce la sessione ap