@gabrielerandelli/minus-tracker 0.7.0 → 0.8.1

package/README.md

@@ -2,6 +2,21 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 [![npm version](https://img.shields.io/npm/v/@gabrielerandelli/minus-tracker.svg)](https://www.npmjs.com/package/@gabrielerandelli/minus-tracker)
+[![npm downloads](https://img.shields.io/npm/dm/@gabrielerandelli/minus-tracker.svg)](https://www.npmjs.com/package/@gabrielerandelli/minus-tracker)
+[![Node](https://img.shields.io/badge/node-%3E%3D24-brightgreen.svg)](https://nodejs.org)
+[![MCP](https://img.shields.io/badge/MCP-server-blueviolet.svg)](https://modelcontextprotocol.io)
+
+⚠️ **Ausilio al calcolo, non consulenza fiscale** — vedi l'[Avvertenza](#avvertenza).
+⚠️ **Calculation aid only, not tax advice** — see the [Disclaimer](#disclaimer).
+
+🤖 **Novità: server MCP** — qualsiasi agente AI può calcolare plusvalenze/minusvalenze italiane direttamente, senza passare dalla CLI.
+🤖 **New: MCP server** — any AI agent can compute Italian capital gains/losses directly, no CLI required.
+
+✅ Validato su tutti i 12 scenari FAQ dell'Agenzia delle Entrate · 120 test automatici · zero dipendenze runtime nella libreria core.
+✅ Validated against all 12 Agenzia delle Entrate FAQ scenarios · 120 automated tests · zero runtime dependencies in the core library.
+
+_L'unico tool open-source che trasforma un export DEGIRO grezzo direttamente in plusvalenze/minusvalenze corrette secondo l'Agenzia delle Entrate — come CLI, libreria, o strumento MCP richiamabile dal tuo agente AI._
+_The only open-source tool that turns a raw DEGIRO export directly into Agenzia-Entrate-correct capital gains/losses — as a CLI, a library, or an MCP tool your AI agent can call._
 
 ---
 
@@ -16,10 +31,23 @@ Il tool elabora i dati partendo direttamente dal formato CSV esportato da DEGIRO
 - Calcolo di plusvalenze e minusvalenze con gestione dei lotti via **LIFO o FIFO** (configurabile)
 - **Parser integrato** per i file CSV di DEGIRO
 - Gestione **multivaluta** con tassi storici BCE (EUR, USD, GBP, CHF)
+- **Classificazione fiscale degli strumenti finanziari in due categorie** (Bucket A/B) — azioni,
+  ETF, titoli di stato, derivati — con classificazione automatica tramite OpenFIGI e sidecar JSON
+  persistente
+- **Modello Redditi PF**: genera Quadro RT (redditi diversi) e Quadro RM (redditi di capitale) a
+  partire dai lotti calcolati, con riporto delle minusvalenze pregresse (regola dei 4 anni)
 - Suite di test allineata alle **FAQ dell'Agenzia delle Entrate**
 - Output disponibile in **italiano** (default) o **inglese** (`--lang en`)
 - Disponibile come pacchetto NPM con supporto CLI
 
+**Novità in v0.8.0:**
+
+- **Modalità stateless per `Classifier`**: `classify()` può ora funzionare senza alcun accesso al
+  filesystem (nessun sidecar), utile per l'integrazione con agenti e automazioni
+- **Server MCP** (`minus-tracker-mcp`): espone `parse_transactions`, `classify_instruments` e
+  `calculate_gains` come tool MCP su stdio, per l'uso diretto da parte di agenti AI — vedi la
+  sezione [Server MCP](#server-mcp) più sotto
+
 ### Avvio rapido
 
 Se non hai ancora un export di DEGIRO a disposizione, puoi testare il tool con il file di esempio incluso nel pacchetto.
@@ -85,15 +113,16 @@ npx @gabrielerandelli/minus-tracker calc trades.csv
 
 ### Utilizzo CLI
 
-| Comando                | Flag principali                                                  | Note                                                                   |
-| ---------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| `calc <file.csv>`      | `--method LIFO\|FIFO` (default: LIFO), `--lang it\|en`, `--json` | Aggiorna i tassi BCE automaticamente se la snapshot ha più di 7 giorni |
-| `validate <file.csv>`  | `--lang it\|en`                                                  | Exit 0 con avvisi; exit 1 in caso di errori bloccanti                  |
-| `rates --check`        | —                                                                | Mostra la copertura della snapshot BCE in locale                       |
-| `rates --update`       | —                                                                | Scarica i tassi aggiornati dall'API BCE                                |
-| `config --lang it\|en` | —                                                                | Salva la lingua preferita                                              |
-| `config --show`        | —                                                                | Mostra la lingua correntemente impostata                               |
-| `stress-test`          | `--range N-M`, `--keep`, `--json`, `--output-dir`                | Documentato in fondo                                                   |
+| Comando                | Flag principali                                                                                                      | Note                                                                                                                    |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `calc <file.csv>`      | `--method LIFO\|FIFO` (default: LIFO), `--lang it\|en`, `--json`, `--export-dichiarazione [path]`, `--carry-forward` | Non aggiorna mai i tassi BCE da solo — esegui `rates --update` periodicamente; usa il sidecar di `classify` se presente |
+| `classify <file.csv>`  | `--offline`                                                                                                          | Classifica gli strumenti (Bucket A/B) e crea/aggiorna il sidecar `*.classify.json`                                      |
+| `validate <file.csv>`  | `--lang it\|en`                                                                                                      | Exit 0 con avvisi; exit 1 in caso di errori bloccanti                                                                   |
+| `rates --check`        | —                                                                                                                    | Mostra la copertura della snapshot BCE in locale                                                                        |
+| `rates --update`       | —                                                                                                                    | Scarica i tassi aggiornati dall'API BCE                                                                                 |
+| `config --lang it\|en` | —                                                                                                                    | Salva la lingua preferita                                                                                               |
+| `config --show`        | —                                                                                                                    | Mostra la lingua correntemente impostata                                                                                |
+| `stress-test`          | `--range N-M`, `--keep`, `--json`, `--output-dir`                                                                    | Documentato in fondo                                                                                                    |
 
 Precedenza lingua: `--lang` > lingua salvata > italiano (default).
 
@@ -128,6 +157,7 @@ npm install @gabrielerandelli/minus-tracker
 import {
   DEGIROParser,
   Calculator,
+  Classifier,
   ParseError,
   CalculationError,
 } from "@gabrielerandelli/minus-tracker";
@@ -140,19 +170,25 @@ if (parser.warnings.length > 0) {
   console.warn("Righe saltate:", parser.warnings);
 }
 
-// 2. Calcolo
-const method: LotMethod = "LIFO"; // oppure "FIFO"
-const report: GainsReport = new Calculator(
+// 2. Classificazione (Bucket A/B) — facoltativa, abilita Quadro RT/RM nel report
+const classification = await new Classifier().classify(
   transactions,
-  parser.warnings,
-).calculateGains(method);
+  "trades.classify.json", // sidecar persistente; assente in modalità stateless
+);
+
+// 3. Calcolo
+const method: LotMethod = "LIFO"; // oppure "FIFO"
+const report: GainsReport = new Calculator(transactions, parser.warnings, {
+  classification,
+}).calculateGains(method);
 
 console.log(report.plusvalenze); // numero in EUR
 console.log(report.minusvalenze); // numero in EUR (valore assoluto)
 console.log(report.netResult); // plusvalenze - minusvalenze
 console.log(report.lots); // MatchedLot[] — dettaglio per lotto
+console.log(report.dichiarazione); // Quadro RT/RM, se classification è stata passata
 
-// 3. Gestione errori
+// 4. Gestione errori
 try {
   const txs = parser.parse(csvString);
   const r = new Calculator(txs, parser.warnings).calculateGains("LIFO");
@@ -177,6 +213,46 @@ try {
 
 **Prerequisiti:** Node.js ≥ 24 ([nodejs.org](https://nodejs.org))
 
+### Server MCP
+
+A partire dalla v0.8.0, minus-tracker include un binario `minus-tracker-mcp` che espone un
+[server MCP](https://modelcontextprotocol.io) su stdio, pensato per l'uso diretto da parte di
+agenti AI (senza passare dalla CLI):
+
+```bash
+npx -p @gabrielerandelli/minus-tracker minus-tracker-mcp
+```
+
+Configurazione tipica per un client MCP (es. Claude Desktop, `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "minus-tracker": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "-p",
+        "@gabrielerandelli/minus-tracker",
+        "minus-tracker-mcp"
+      ]
+    }
+  }
+}
+```
+
+Il server espone 3 tool:
+
+| Tool                   | Descrizione                                                                            |
+| ---------------------- | -------------------------------------------------------------------------------------- |
+| `parse_transactions`   | Esegue il parsing di un CSV DEGIRO, restituendo `transactions`/`warnings`/`incomeRows` |
+| `classify_instruments` | Classifica gli ISIN in Bucket A/B (modalità stateless — nessun sidecar)                |
+| `calculate_gains`      | Calcola plusvalenze/minusvalenze (LIFO/FIFO) e, se disponibile, Quadro RT/RM           |
+
+`classify_instruments` supporta `existingClassification`, `overrides` e `offline: true` per
+funzionare senza rete e senza accesso al filesystem — pensato per essere invocato ripetutamente
+da un agente in chiamate successive, mantenendo lo stato lato client.
+
 ### Domande frequenti
 
 **Il CSV viene rifiutato con "colonna mancante" o "CSV non valido"**
@@ -189,7 +265,7 @@ Le righe vengono saltate (senza bloccare il calcolo) quando: l'ISIN è vuoto, la
 Il CSV contiene una vendita per un titolo senza un acquisto precedente nel file. L'acquisto potrebbe essere in un export di un anno precedente non incluso. Usa `validate` per esaminare le transazioni parsate.
 
 **I tassi BCE sono scaduti**
-Esegui `minus-tracker rates --update`. Il comando `calc` esegue l'aggiornamento automaticamente se la snapshot ha più di 7 giorni.
+Esegui `minus-tracker rates --update`. Il comando `calc` non aggiorna mai i tassi da solo: l'aggiornamento è sempre un'azione esplicita.
 
 **LIFO o FIFO?**
 Il Regime Dichiarativo utilizza il LIFO come metodo predefinito ai sensi della normativa fiscale italiana. Il FIFO è disponibile per confronto. Consulta il tuo commercialista per conferma.
@@ -251,10 +327,22 @@ It loads data following the CSV format used by DEGIRO.
 - Capital-gains/loss calculation with configurable **LIFO and FIFO** lot matching
 - **DEGIRO CSV parser**
 - **Multi-currency** handling with historical ECB rates (EUR, USD, GBP, CHF)
+- **Two-bucket classification** (Bucket A/B) of financial instruments — stocks, ETFs, government
+  bonds, derivatives — with automatic OpenFIGI-backed classification and a persistent JSON sidecar
+- **Modello Redditi PF** generation: Quadro RT (capital gains) and Quadro RM (capital income) built
+  from the calculated lots, with prior-year loss carryforward (4-year rule)
 - Test suite based on **Agenzia Entrate FAQ**
 - Output in **Italian** (default) or **English** (`--lang en`)
 - minus-tracker is an NPM package with CLI support
 
+**New in v0.8.0:**
+
+- **Stateless mode for `Classifier`**: `classify()` can now run with zero filesystem access (no
+  sidecar file), useful for embedding in agents/automations
+- **MCP server** (`minus-tracker-mcp`): exposes `parse_transactions`, `classify_instruments`, and
+  `calculate_gains` as MCP tools over stdio, for direct use by AI agents — see the
+  [MCP Server](#mcp-server) section below
+
 ### Quick Start
 
 Don't have a DEGIRO export yet? Use the sample file bundled with the package.
@@ -321,15 +409,16 @@ npx @gabrielerandelli/minus-tracker calc trades.csv
 
 ### CLI Usage
 
-| Command                | Key flags                                                        | Notes                                                      |
-| ---------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------- |
-| `calc <file.csv>`      | `--method LIFO\|FIFO` (default: LIFO), `--lang it\|en`, `--json` | Auto-fetches ECB rates if snapshot is more than 7 days old |
-| `validate <file.csv>`  | `--lang it\|en`                                                  | Exit 0 with warnings; exit 1 on hard errors                |
-| `rates --check`        | —                                                                | Shows bundled ECB snapshot coverage                        |
-| `rates --update`       | —                                                                | Fetches fresh rates from the ECB API                       |
-| `config --lang it\|en` | —                                                                | Saves language preference                                  |
-| `config --show`        | —                                                                | Shows current language setting                             |
-| `stress-test`          | `--range N-M`, `--keep`, `--json`, `--output-dir`                | Documented below                                           |
+| Command                | Key flags                                                                                                            | Notes                                                                                                          |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `calc <file.csv>`      | `--method LIFO\|FIFO` (default: LIFO), `--lang it\|en`, `--json`, `--export-dichiarazione [path]`, `--carry-forward` | Never fetches ECB rates on its own — run `rates --update` periodically; uses `classify`'s sidecar when present |
+| `classify <file.csv>`  | `--offline`                                                                                                          | Classifies instruments (Bucket A/B) and creates/updates the `*.classify.json` sidecar                          |
+| `validate <file.csv>`  | `--lang it\|en`                                                                                                      | Exit 0 with warnings; exit 1 on hard errors                                                                    |
+| `rates --check`        | —                                                                                                                    | Shows bundled ECB snapshot coverage                                                                            |
+| `rates --update`       | —                                                                                                                    | Fetches fresh rates from the ECB API                                                                           |
+| `config --lang it\|en` | —                                                                                                                    | Saves language preference                                                                                      |
+| `config --show`        | —                                                                                                                    | Shows current language setting                                                                                 |
+| `stress-test`          | `--range N-M`, `--keep`, `--json`, `--output-dir`                                                                    | Documented below                                                                                               |
 
 Language precedence: `--lang` flag > saved config > Italian (default).
 
@@ -364,6 +453,7 @@ npm install @gabrielerandelli/minus-tracker
 import {
   DEGIROParser,
   Calculator,
+  Classifier,
   ParseError,
   CalculationError,
 } from "@gabrielerandelli/minus-tracker";
@@ -376,19 +466,25 @@ if (parser.warnings.length > 0) {
   console.warn("Skipped rows:", parser.warnings);
 }
 
-// 2. Calculate
-const method: LotMethod = "LIFO"; // or "FIFO"
-const report: GainsReport = new Calculator(
+// 2. Classify (Bucket A/B) — optional, enables Quadro RT/RM in the report
+const classification = await new Classifier().classify(
   transactions,
-  parser.warnings,
-).calculateGains(method);
+  "trades.classify.json", // persistent sidecar; omit for stateless mode
+);
+
+// 3. Calculate
+const method: LotMethod = "LIFO"; // or "FIFO"
+const report: GainsReport = new Calculator(transactions, parser.warnings, {
+  classification,
+}).calculateGains(method);
 
 console.log(report.plusvalenze); // EUR capital gains (number)
 console.log(report.minusvalenze); // EUR capital losses (number, absolute value)
 console.log(report.netResult); // plusvalenze - minusvalenze
 console.log(report.lots); // MatchedLot[] — per-lot breakdown
+console.log(report.dichiarazione); // Quadro RT/RM, when classification was passed
 
-// 3. Error handling
+// 4. Error handling
 try {
   const txs = parser.parse(csvString);
   const r = new Calculator(txs, parser.warnings).calculateGains("LIFO");
@@ -411,6 +507,46 @@ minus-tracker is **pure tax math** — no UI, auth, database, or PDF.
 
 **Prerequisites:** Node.js ≥ 24 ([nodejs.org](https://nodejs.org))
 
+### MCP Server
+
+As of v0.8.0, minus-tracker ships a `minus-tracker-mcp` binary exposing an
+[MCP server](https://modelcontextprotocol.io) over stdio, for direct use by AI agents (no need to
+go through the CLI):
+
+```bash
+npx -p @gabrielerandelli/minus-tracker minus-tracker-mcp
+```
+
+Typical MCP client configuration (e.g. Claude Desktop, `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "minus-tracker": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "-p",
+        "@gabrielerandelli/minus-tracker",
+        "minus-tracker-mcp"
+      ]
+    }
+  }
+}
+```
+
+The server exposes 3 tools:
+
+| Tool                   | Description                                                           |
+| ---------------------- | --------------------------------------------------------------------- |
+| `parse_transactions`   | Parses a DEGIRO CSV into `transactions`/`warnings`/`incomeRows`       |
+| `classify_instruments` | Classifies ISINs into Bucket A/B (stateless mode — no sidecar file)   |
+| `calculate_gains`      | Calculates gains/losses (LIFO/FIFO) and, when available, Quadro RT/RM |
+
+`classify_instruments` supports `existingClassification`, `overrides`, and `offline: true` to run
+without network access or filesystem access — designed to be called repeatedly by an agent across
+multiple calls, with state kept client-side.
+
 ### FAQ / Troubleshooting
 
 **My CSV is rejected with "missing column" or "invalid CSV"**
@@ -423,7 +559,7 @@ Rows are skipped (without aborting the calculation) when: the ISIN is empty, the
 The CSV contains a SELL for a position that has no prior BUY in the same file. The BUY may be in a prior year's export that was not included. Use `validate` to inspect the parsed transactions.
 
 **ECB rates are outdated**
-Run `minus-tracker rates --update`. The `calc` command also auto-updates if the snapshot is more than 7 days old.
+Run `minus-tracker rates --update`. The `calc` command never fetches rates on its own — refreshing is always an explicit, user-invoked action.
 
 **LIFO or FIFO?**
 LIFO is the standard lot-matching method under Italian tax law for the Regime Dichiarativo. FIFO is available for comparison or other jurisdictions. Consult your tax advisor for confirmation.