# statisticheisa-cli

CLI e server MCP per le statistiche ISA (Indici Sintetici di Affidabilità) dell'Agenzia delle Entrate italiana.

## 📋 Caratteristiche

- **Ricerca codici ISA** per descrizione o alias colloquiali (es. "tassisti" → DG72U)
- **Dati nazionali**: reddito medio, ricavi, componenti per codice ISA
- **Dati regionali**: dettaglio per regione
- **Elenco anni** disponibili
- **Catalogo sezioni** ISA per anno
- **Alias integrati** per ricerche naturali (ristoranti, idraulici, commercianti, ecc.)
- **Output flessibile**: JSON, tabella, CSV, plain text
- **Filtraggio campi** con notazione dot-path (es. `totale.redditoMedio`)
- **Parsing numeri italiani** (es. "39.917" → 39917)

## 🚀 Installazione

```bash
# Da sorgente (richiede Go 1.21+)
git clone https://github.com/your-repo/statisticheisa-cli
cd statisticheisa-cli
go build -o statisticheisa-cli .

# Oppure scarica il binario precompilato dalle releases
```

## 📖 Uso CLI

### Comandi principali

```bash
# Mostra aiuto
statisticheisa-cli --help

# Cerca codice ISA per parola chiave
statisticheisa-cli cerca tassisti
statisticheisa-cli cerca "trasporto passeggeri" --anno 2024 --format table

# Elenco anni disponibili
statisticheisa-cli elenco-anni

# Tutti i dati ISA per un anno
statisticheisa-cli dati 2024

# Dati nazionali per un codice ISA
statisticheisa-cli nazionali 2024 DG72U
statisticheisa-cli nazionali 2024 DG72U --field totale.redditoMedio --format plain
statisticheisa-cli nazionali --anno 2024 --codisa DG72U --field totalePersoneFisiche.redditoMedio --format json

# Dati regionali
statisticheisa-cli regionali 2024 DG72U

# Lista codici ISA (con filtro opzionale)
statisticheisa-cli lista 2024 --cerca trasporto --format table

# Macroaree per un codice
statisticheisa-cli macroaree 2024 DG72U

# Dati multi-anno
statisticheisa-cli nazionali-multi 2024 DG72U Servizi U
statisticheisa-cli regionali-multi 2024 DG72U Servizi

# Grafici
statisticheisa-cli grafico-barre 2024 1 DG72U Servizi redditoMedio
statisticheisa-cli grafico-regioni 2024 1 DG72U Servizi

# Info endpoint e alias
statisticheisa-cli info
```

### Flag globali

| Flag | Descrizione |
|------|-------------|
| `--field <path>` | Proietta solo campi specifici (dot-separated, comma-separated) |
| `--format <json\|table\|csv\|plain>` | Formato output (default: json) |
| `--parse-numbers` | Converte numeri formato italiano "39.917" → 39917 |
| `--raw` | Dump bytes grezzi API |
| `--output <file>, -o <file>` | Scrive su file invece di stdout |
| `--cerca <query>` | Filtra lista per query |
| `--anno <year>` | Override anno |
| `--codisa <code>` | Override codIsa (stile flag) |
| `--macroarea <area>` | Override macroarea |

### Alias supportati

Il CLI risolve automaticamente alias comuni:

```bash
# Questi sono equivalenti:
statisticheisa-cli nazionali 2024 tassisti
statisticheisa-cli nazionali 2024 DG72U

# Altri alias: ristoranti, bar, pizzerie, idraulici, elettricisti,
# parrucchieri, commercianti, agenti-immobiliari, medici, dentisti,
# avvocati, commercialisti, architetti, ingegneri, ...
```

Vedi tutti con: `statisticheisa-cli info`

## 🔌 Server MCP

Il progetto include due server MCP (Model Context Protocol) per integrazione con agenti AI (OpenCode, Claude, ecc.).

### 1. Server stdio (locale)

Per uso diretto con agenti che supportano MCP su stdio.

```bash
# Avvia server
statisticheisa-cli mcp

# Configurazione OpenCode (opencode.json)
{
  "mcp": {
    "servers": {
      "statisticheisa-local": {
        "type": "local",
        "command": ["go", "run", ".", "mcp"],
        "environment": {}
      }
    }
  }
}
```

### 2. Server HTTP (remote)

Per connessione remota via HTTP.

```bash
# Avvia server su porta 8080
statisticheisa-cli mcp-http

# Oppure specifica indirizzo
statisticheisa-cli mcp-http :9090

# Configurazione OpenCode (opencode.json)
{
  "mcp": {
    "servers": {
      "statisticheisa-http": {
        "type": "remote",
        "url": "http://localhost:8080/mcp"
      }
    }
  }
}
```

### Endpoint HTTP

- `POST /mcp` - Endpoint MCP JSON-RPC 2.0
- `GET /health` - Health check

### Strumenti MCP disponibili

| Tool | Descrizione | Parametri |
|------|-------------|-----------|
| `cerca` | Cerca codice ISA per query | `query` (string), `anno` (int, default 2024) |
| `lista` | Lista codici ISA per anno | `anno` (int, default 2024), `cerca` (string, opzionale) |
| `elenco_anni` | Anni disponibili | `anno` (int, default 2024) |
| `dati` | Catalogo sezioni ISA | `anno` (int, required) |
| `nazionali` | Dati nazionali per codice | `anno` (int), `codIsa` (string), `macroarea` (string, default "Servizi"), `field` (string, opzionale) |
| `regionali` | Dati regionali per codice | `anno` (int), `codIsa` (string), `macroarea` (string, default "Servizi") |
| `info` | Info endpoint e alias | (nessuno) |

### Esempi uso MCP

```json
// Inizializzazione
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}

// Lista strumenti
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

// Cerca "tassisti"
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"cerca","arguments":{"query":"tassisti","anno":2024}}}

// Dati nazionali per DG72U (tassisti)
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"nazionali","arguments":{"anno":2024,"codIsa":"DG72U","field":"totale.redditoMedio"}}}
```

## 🏗️ Architettura

```
statisticheisa-cli/
├── main.go                    # Entry point CLI
├── internal/
│   ├── aliases/aliases.go     # Risoluzione alias colloquiali
│   ├── client/client.go       # Client HTTP per API Agenzia Entrate
│   ├── client/testdata/       # Golden files per test
│   ├── format/numbers.go      # Parsing numeri italiani
│   ├── mcp/
│   │   ├── server.go          # Server MCP stdio
│   │   └── http_server.go     # Server MCP HTTP (Gin)
│   ├── output/output.go       # Formattazione output (JSON, table, CSV, plain)
│   └── search/search.go       # Ricerca fuzzy codici ISA
├── explore/                   # Script di esplorazione API (non per produzione)
├── go.mod / go.sum
└── opencode.json              # Configurazione MCP per OpenCode
```

## 🔧 Sviluppo

```bash
# Test
go test ./...

# Build
go build -o statisticheisa-cli .

# Lint
golangci-lint run

# Esegui server HTTP in background per test
./statisticheisa-cli mcp-http &
curl -X POST http://localhost:8080/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
```

## 📡 API Sorgente

I dati provengono dalle API pubbliche dell'Agenzia delle Entrate:
- Base URL: `https://www.agenziaentrate.gov.it/portale/`
- Endpoint ISA: `/portale/it/servizi/indici-sintetici-affidabilita`

## ⚠️ Note

- Il server HTTP MCP usa protocollo **2024-11-05** (compatibile OpenCode)
- I dati sono soggetti a disponibilità API Agenzia Entrate
- Gli alias sono mantenuti manualmente in `internal/aliases/aliases.go`
- Per contributi: apri issue o PR

## 📄 Licenza

MIT License - vedi LICENSE per dettagli.