@gabrielerandelli/minus-tracker 0.7.0 → 0.8.0

package/README.md

@@ -16,10 +16,22 @@ 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 a due categorie** (Bucket A/B) degli strumenti finanziari — azioni, ETF, titoli
+  di stato, derivati — con classificazione automatica via 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 in agenti/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 +97,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` | Aggiorna i tassi BCE automaticamente se la snapshot ha più di 7 giorni; 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 +141,7 @@ npm install @gabrielerandelli/minus-tracker
 import {
   DEGIROParser,
   Calculator,
+  Classifier,
   ParseError,
   CalculationError,
 } from "@gabrielerandelli/minus-tracker";
@@ -140,19 +154,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; omettilo per la 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 +197,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`   | Effettua il parsing di un CSV DEGIRO in `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 su più chiamate, mantenendo lo stato lato client.
+
 ### Domande frequenti
 
 **Il CSV viene rifiutato con "colonna mancante" o "CSV non valido"**
@@ -251,10 +311,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 +393,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` | Auto-fetches ECB rates if snapshot is more than 7 days old; 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 +437,7 @@ npm install @gabrielerandelli/minus-tracker
 import {
   DEGIROParser,
   Calculator,
+  Classifier,
   ParseError,
   CalculationError,
 } from "@gabrielerandelli/minus-tracker";
@@ -376,19 +450,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 +491,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"**

package/dist/cli/index.js

@@ -1246,7 +1246,7 @@ function classifyByType(isin, securityType, product, warnings) {
     };
   }
   warnings.push(
-    `Unrecognized type: ${securityType}. Please classify manually.`
+    `Unrecognized type for ${isin}: ${securityType}. Please classify manually.`
   );
   return {
     product,
@@ -1259,6 +1259,84 @@ function classifyByType(isin, securityType, product, warnings) {
     source: "user"
   };
 }
+var ASSET_CLASS_DEFAULTS = {
+  ETF: {
+    assetClass: "ETF",
+    bucketGain: "A",
+    bucketLoss: "B",
+    taxRate: 0.26,
+    whiteListed: null
+  },
+  Stock: {
+    assetClass: "Stock",
+    bucketGain: "B",
+    bucketLoss: "B",
+    taxRate: 0,
+    whiteListed: null
+  },
+  ETC: {
+    assetClass: "ETC",
+    bucketGain: "B",
+    bucketLoss: "B",
+    taxRate: 0,
+    whiteListed: null
+  },
+  GovtBondWL: {
+    assetClass: "GovtBondWL",
+    bucketGain: "A",
+    bucketLoss: "B",
+    taxRate: 0.125,
+    whiteListed: true
+  },
+  GovtBondOther: {
+    assetClass: "GovtBondOther",
+    bucketGain: "A",
+    bucketLoss: "B",
+    taxRate: 0.26,
+    whiteListed: false
+  },
+  CorpBond: {
+    assetClass: "CorpBond",
+    bucketGain: "B",
+    bucketLoss: "B",
+    taxRate: 0,
+    whiteListed: null
+  },
+  Derivative: {
+    assetClass: "Derivative",
+    bucketGain: "B",
+    bucketLoss: "B",
+    taxRate: 0,
+    whiteListed: null
+  },
+  LeverageCert: {
+    assetClass: "LeverageCert",
+    bucketGain: "B",
+    bucketLoss: "B",
+    taxRate: 0,
+    whiteListed: null
+  },
+  CapProtectedCert: {
+    assetClass: "CapProtectedCert",
+    bucketGain: "A",
+    bucketLoss: "B",
+    taxRate: 0.26,
+    whiteListed: null
+  }
+};
+function buildEntryFromAssetClass(assetClass, product) {
+  const mapped = ASSET_CLASS_DEFAULTS[assetClass];
+  return {
+    product,
+    assetClass: mapped.assetClass,
+    bucketGain: mapped.bucketGain,
+    bucketLoss: mapped.bucketLoss,
+    taxRate: mapped.taxRate,
+    whiteListed: mapped.whiteListed,
+    confirmedByUser: true,
+    source: "user"
+  };
+}
 var Classifier = class {
   interactive;
   constructor(options) {
@@ -1280,7 +1358,7 @@ var Classifier = class {
     }
     return parsed.classifications;
   }
-  async classify(transactions, sidecarPath, _httpPost = httpsPost) {
+  async classify(transactions, sidecarPath, options, _httpPost = httpsPost) {
     const isinToProduct = /* @__PURE__ */ new Map();
     for (const tx of transactions) {
       if (tx.isin && !isinToProduct.has(tx.isin)) {
@@ -1288,13 +1366,21 @@ var Classifier = class {
       }
     }
     const confirmed = {};
-    if (fs3.existsSync(sidecarPath)) {
-      const existingMap = await this.load(sidecarPath);
-      for (const [isin, entry] of Object.entries(existingMap)) {
-        if (entry.confirmedByUser) {
-          confirmed[isin] = entry;
+    if (sidecarPath !== void 0) {
+      if (fs3.existsSync(sidecarPath)) {
+        const existingMap = await this.load(sidecarPath);
+        for (const [isin, entry] of Object.entries(existingMap)) {
+          if (entry.confirmedByUser) {
+            confirmed[isin] = entry;
+          }
         }
       }
+    } else if (options?.existingClassification) {
+      Object.assign(confirmed, options.existingClassification);
+    }
+    for (const [isin, assetClass] of Object.entries(options?.overrides ?? {})) {
+      const product = isinToProduct.get(isin) ?? isin;
+      confirmed[isin] = buildEntryFromAssetClass(assetClass, product);
     }
     const toProcess = [];
     for (const isin of isinToProduct.keys()) {
@@ -1304,76 +1390,100 @@ var Classifier = class {
     }
     const warnings = [];
     const newEntries = {};
-    const BATCH_SIZE = 10;
-    for (let i = 0; i < toProcess.length; i += BATCH_SIZE) {
-      if (i > 0) {
-        await new Promise((resolve2) => setTimeout(resolve2, 6e3));
+    if (options?.offline) {
+      for (const isin of toProcess) {
+        const product = isinToProduct.get(isin) ?? isin;
+        warnings.push(
+          `Unrecognized type for ${isin}: unknown. Please classify manually.`
+        );
+        newEntries[isin] = {
+          product,
+          assetClass: "Stock",
+          bucketGain: "B",
+          bucketLoss: "B",
+          taxRate: 0,
+          whiteListed: null,
+          confirmedByUser: false,
+          source: "user"
+        };
       }
-      const batch = toProcess.slice(i, i + BATCH_SIZE);
-      const requestBody = JSON.stringify(
-        batch.map((isin) => ({ idType: "ID_ISIN", idValue: isin }))
-      );
-      let response = null;
-      for (let attempt = 0; attempt < 2; attempt++) {
-        try {
-          const r = await _httpPost(
-            "https://api.openfigi.com/v3/mapping",
-            requestBody,
-            1e4
-          );
-          if (r.status < 500) {
-            response = r;
-            break;
+    } else {
+      const BATCH_SIZE = 10;
+      const totalBatches = Math.ceil(toProcess.length / BATCH_SIZE);
+      for (let i = 0; i < toProcess.length; i += BATCH_SIZE) {
+        if (i > 0) {
+          await new Promise((resolve2) => setTimeout(resolve2, 6e3));
+        }
+        const batch = toProcess.slice(i, i + BATCH_SIZE);
+        const requestBody = JSON.stringify(
+          batch.map((isin) => ({ idType: "ID_ISIN", idValue: isin }))
+        );
+        let response = null;
+        for (let attempt = 0; attempt < 2; attempt++) {
+          try {
+            const r = await _httpPost(
+              "https://api.openfigi.com/v3/mapping",
+              requestBody,
+              1e4
+            );
+            if (r.status < 500) {
+              response = r;
+              break;
+            }
+          } catch {
+            throw new ClassificationError("NETWORK_ERROR");
           }
-        } catch {
+        }
+        if (response === null) {
           throw new ClassificationError("NETWORK_ERROR");
         }
-      }
-      if (response === null) {
-        throw new ClassificationError("NETWORK_ERROR");
-      }
-      const results = JSON.parse(response.data);
-      for (let j = 0; j < batch.length; j++) {
-        const isin = batch[j];
-        const result = results[j];
-        const product = isinToProduct.get(isin) ?? isin;
-        if (!result || result.error || !result.data || result.data.length === 0) {
-          warnings.push(
-            `Unrecognized type: unknown. Please classify manually.`
-          );
-          newEntries[isin] = {
-            product,
-            assetClass: "Stock",
-            bucketGain: "B",
-            bucketLoss: "B",
-            taxRate: 0,
-            whiteListed: null,
-            confirmedByUser: false,
-            source: "user"
-          };
-          continue;
+        const results = JSON.parse(response.data);
+        for (let j = 0; j < batch.length; j++) {
+          const isin = batch[j];
+          const result = results[j];
+          const product = isinToProduct.get(isin) ?? isin;
+          if (!result || result.error || !result.data || result.data.length === 0) {
+            warnings.push(
+              `Unrecognized type for ${isin}: unknown. Please classify manually.`
+            );
+            newEntries[isin] = {
+              product,
+              assetClass: "Stock",
+              bucketGain: "B",
+              bucketLoss: "B",
+              taxRate: 0,
+              whiteListed: null,
+              confirmedByUser: false,
+              source: "user"
+            };
+            continue;
+          }
+          const st = result.data[0]?.securityType;
+          const st2 = result.data[0]?.securityType2;
+          const typeToUse = st && isKnownType(st) ? st : st2 && isKnownType(st2) ? st2 : st ?? st2 ?? "Unknown";
+          newEntries[isin] = classifyByType(isin, typeToUse, product, warnings);
         }
-        const st = result.data[0]?.securityType;
-        const st2 = result.data[0]?.securityType2;
-        const typeToUse = st && isKnownType(st) ? st : st2 && isKnownType(st2) ? st2 : st ?? st2 ?? "Unknown";
-        newEntries[isin] = classifyByType(isin, typeToUse, product, warnings);
+        const batchIndex = i / BATCH_SIZE;
+        options?.onBatchProgress?.(batchIndex + 1, totalBatches);
       }
     }
     const mergedMap = { ...newEntries, ...confirmed };
-    const sidecarContent = JSON.stringify(
-      {
-        version: 1,
-        generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-        classifications: mergedMap,
-        warnings
-      },
-      null,
-      2
-    );
-    try {
-      fs3.writeFileSync(sidecarPath, sidecarContent, "utf-8");
-    } catch {
-      throw new ClassificationError("WRITE_ERROR");
+    if (sidecarPath !== void 0) {
+      const sidecarContent = JSON.stringify(
+        {
+          version: 1,
+          generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          classifications: mergedMap,
+          warnings
+        },
+        null,
+        2
+      );
+      try {
+        fs3.writeFileSync(sidecarPath, sidecarContent, "utf-8");
+      } catch {
+        throw new ClassificationError("WRITE_ERROR");
+      }
     }
     return mergedMap;
   }