# LibreLink MCP Server - Fixed for API v4.16.0

🇬🇧 [English](README.en.md) | 🇮🇹 [Italiano](README.md)

🩸 Server MCP per accedere ai dati glicemici FreeStyle Libre tramite Claude Desktop.

**Questa è una versione corretta** che supporta le modifiche API introdotte l'8 ottobre 2025:
- ✅ Supporto per la versione API 4.16.0+
- ✅ Header `Account-Id` obbligatorio (SHA256 hash dell'userId)
- ✅ Gestione automatica del redirect regionale
- ✅ Refresh automatico del token
- ✅ Storage sicuro delle credenziali con crittografia AES-256-GCM
- ✅ Chiavi di crittografia salvate nel keychain del sistema operativo (Keytar)
- ✅ Fallback automatico a file `.encryption.key` se Keytar non disponibile
- ✅ Persistenza sicura dei token JWT
- ✅ **v1.3.0**: Supporto completo per tutte le 13 regioni LibreLinkUp
- ✅ **v1.4.0**: Aggiornamento dipendenze di sicurezza (13 vulnerabilità risolte), MCP SDK 1.29.0, richiede Node.js 20+
- ✅ **v1.5.0**: 8 vulnerabilità risolte, MCP SDK 1.30.0, richiede Node.js 22+
- ✅ **v1.5.1**: 5 vulnerabilità risolte (hono, qs), axios 1.20.0
- ✅ **v1.6.0**: `get_glucose_stats` riporta la finestra temporale effettivamente coperta (`data_coverage`), manifest del bundle completo, bundle senza devDependencies

## 📋 Prerequisiti

- **Node.js**: Versione 22.0.0 o superiore
- **Account LibreLinkUp**: Account attivo con dati condivisi
- **Sensore**: FreeStyle Libre 2 o 3 attivo
- **Claude Desktop**: Per l'integrazione MCP

## 🚀 Installazione Rapida (Bundle Precompilato)

### Passaggi:

### 1. Installa Keytar (Raccomandato per sicurezza massima)

Per utilizzare il vault nativo del sistema operativo (Windows Credential Manager, macOS Keychain, Linux Secret Service), installa `keytar`:

```bash
npm install keytar
```

> **Nota:** Se `keytar` non può essere installato, il sistema userà automaticamente un file criptato come fallback.

### 2. Scarica il bundle

Usa il browser oppure:

```bash
wget https://github.com/sedoglia/librelink-mcp-server/releases/download/v1.6.0/librelink-mcp-server.mcpb
```

### 3. Verifica l'integrità

Verifica l'integrità (opzionale ma consigliato):

```bash
wget https://github.com/sedoglia/librelink-mcp-server/releases/download/v1.6.0/librelink-mcp-server.mcpb.sha256
sha256sum -c librelink-mcp-server.mcpb.sha256
```

### 4. Installa l'estensione in Claude Desktop (Metodo Consigliato)

**Installazione tramite Custom Desktop Extensions:**

1. Apri **Claude Desktop**
2. Vai su **Impostazioni** (Settings)
3. Seleziona la scheda **Estensioni** (Extensions)
4. Clicca su **Impostazioni Avanzate** (Advanced settings) e trova la sezione **Extension Developer**
5. Clicca su **"Installa Estensione..."** (Install Extension…)
6. Seleziona il file `.mcpb` (`librelink-mcp-server.mcpb` scaricato al passaggio 1)
7. Segui le indicazioni a schermo per completare l'installazione

> **Nota:** Questo è il metodo più semplice e consigliato. L'estensione sarà automaticamente integrata in Claude Desktop senza necessità di configurazione manuale.

---

### 5. Configura le Credenziali LibreLink (Metodo Sicuro - Raccomandato)

Apri una **nuova chat su Claude Desktop** e scrivi il seguente prompt:

```
Configura le credenziali di accesso per LibreLink
```

Rispondi al messaggio fornendo:
- **Utente:** la tua email LibreLink
- **Password:** la tua password LibreLink

L'estensione provvederà automaticamente a criptare e salvare le credenziali in modo sicuro nel vault nativo del sistema operativo (Windows Credential Manager, macOS Keychain, Linux Secret Service).

> **Nota:** Le credenziali NON verranno salvate in file di testo. Saranno sempre crittografate e gestite dal vault nativo del SO.


### 6. Riavvia Claude Desktop

- Chiudi completamente l'applicazione
- Riapri Claude Desktop
- Verifica in Impostazioni → Sviluppatore lo stato della connessione ✅


## 🚀 Installazione (clonando il repository con GIT)

### 1. Clona il Repository

```bash
# Clona il repository
git clone https://github.com/sedoglia/librelink-mcp-server.git
cd librelink-mcp-server
```

### 2. Installa le Dipendenze

```bash
# Installa dipendenze
npm install
```

### 3. Installa Keytar

Keytar richiede alcune dipendenze di sistema per funzionare:

**Windows**: Nessuna dipendenza aggiuntiva richiesta (usa Windows Credential Manager)

**macOS**: Nessuna dipendenza aggiuntiva richiesta (usa Keychain)

**Linux** (Debian/Ubuntu):
```bash
sudo apt-get install libsecret-1-dev gnome-keyring
```

**Linux** (Fedora/RHEL):
```bash
sudo dnf install libsecret-devel gnome-keyring
```

```bash
# Installa Keytar
npm install keytar
```

### 4. Compila il Progetto

```bash
# Compila TypeScript
npm run build
```

### 5. Configura le credenziali

```bash
npm run configure
```

Ti verrà chiesto:
- **Email**: Email del tuo account LibreLinkUp
- **Password**: Password del tuo account
- **Regione**: Una delle 13 regioni supportate (vedi sotto)
- **Range target**: Valori glicemici target (default: 70-180 mg/dL)

### Regioni Supportate

| Codice | Regione |
|--------|---------|
| AE | Emirati Arabi Uniti |
| AP | Asia Pacifico |
| AU | Australia |
| CA | Canada |
| CN | Cina |
| DE | Germania |
| EU | Europa (default) |
| EU2 | Europa 2 |
| FR | Francia |
| JP | Giappone |
| LA | America Latina |
| RU | Russia |
| US | Stati Uniti |

Le credenziali vengono salvate in modo sicuro:
- **Crittografia**: AES-256-GCM con salt e IV casuali
- **Chiave di crittografia**: Salvata nel keychain del sistema operativo
- **Token JWT**: Persistito in modo sicuro per evitare login ripetuti

### 6. Testa la connessione

```bash
npm run test:connection
```

### 7. Configura Claude Desktop

Aggiungi al file di configurazione di Claude Desktop:

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

```json
{
  "mcpServers": {
    "librelink": {
      "command": "node",
      "args": ["C:/percorso/librelink-mcp-server/dist/index.js"]
    }
  }
}
```

### 8. Riavvia Claude Desktop

Riavvia Claude Desktop per caricare il server MCP.

## 🛠 Strumenti MCP Disponibili

| Strumento | Descrizione |
|-----------|-------------|
| `get_current_glucose` | Lettura glicemica attuale con trend |
| `get_glucose_history` | Storico glicemico (default: 24 ore) |
| `get_glucose_stats` | Statistiche: media, GMI, time-in-range |
| `get_glucose_trends` | Analisi pattern: dawn phenomenon, stabilità |
| `get_sensor_info` | Info sensore attivo |
| `configure_credentials` | Configura credenziali LibreLinkUp |
| `configure_ranges` | Imposta range target personalizzati |
| `validate_connection` | Testa la connessione |
| `get_session_status` | Stato della sessione di autenticazione |
| `clear_session` | Pulisce la sessione e forza re-autenticazione |

## 💬 Esempi di Utilizzo

Una volta integrato con Claude Desktop, puoi chiedere:

- *"Qual è la mia glicemia attuale?"*
- *"Mostrami lo storico glicemico delle ultime 6 ore"*
- *"Calcola il mio time-in-range di questa settimana"*
- *"Analizza i miei pattern glicemici"*
- *"Ho il fenomeno dell'alba?"*

## 📊 Output di Esempio

### Lettura Attuale

```json
{
  "current_glucose": 105,
  "timestamp": "2025-12-06T16:30:00.000Z",
  "trend": "Flat",
  "status": "Normal",
  "color": "green"
}
```

### Statistiche

```json
{
  "analysis_period_days": 7,
  "data_coverage": {
    "from": "2026-09-12T10:46:28.000Z",
    "to": "2026-09-12T22:01:32.000Z",
    "hours_covered": 11.3,
    "hours_requested": 168,
    "note": "Only 11.3 of the requested 168 hours are available: LibreLinkUp returns roughly the last 12 hours of readings. Statistics below describe that window only."
  },
  "average_glucose": 112.5,
  "glucose_management_indicator": 5.94,
  "time_in_range": {
    "target_70_180": 85.2,
    "below_70": 2.1,
    "above_180": 12.7
  },
  "variability": {
    "standard_deviation": 28.4,
    "coefficient_of_variation": 25.2
  }
}
```

Il blocco `data_coverage` indica la finestra temporale realmente coperta dalle letture: LibreLinkUp restituisce solo le ultime ~12 ore, quindi le statistiche descrivono quella finestra anche quando si richiedono più giorni.

## 🔒 Sicurezza e Privacy

### Posizioni di Storage

I file di configurazione sono salvati in posizioni specifiche per ogni sistema operativo:

| Sistema | Percorso |
|---------|----------|
| Windows | `%LOCALAPPDATA%\librelink-mcp\` |
| macOS | `~/Library/Application Support/librelink-mcp/` |
| Linux | `~/.config/librelink-mcp/` |

### Architettura di Sicurezza

```
┌─────────────────────────────────────────────────────────────┐
│              Storage Chiave di Crittografia                 │
│  ┌─────────────────────────────────────────────────────────┐│
│  │  OPZIONE 1 (Preferita): OS Keychain via Keytar          ││
│  │  - Windows: Credential Manager                          ││
│  │  - macOS: Keychain                                      ││
│  │  - Linux: Secret Service (libsecret)                    ││
│  ├─────────────────────────────────────────────────────────┤│
│  │  OPZIONE 2 (Fallback): File .encryption.key             ││
│  │  - Permessi 0o600 (solo proprietario)                   ││
│  │  - Usato se Keytar non disponibile                      ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│         [Percorso specifico per OS]/librelink-mcp/          │
│  ┌───────────────────┐  ┌────────────────────┐              │
│  │ credentials.enc   │  │ token.enc          │              │
│  │ (AES-256-GCM)     │  │ (AES-256-GCM)      │              │
│  │ - email           │  │ - JWT token        │              │
│  │ - password        │  │ - expiration       │              │
│  └───────────────────┘  │ - userId           │              │
│                         │ - accountId        │              │
│  ┌───────────────────┐  └────────────────────┘              │
│  │ config.json       │                                      │
│  │ (non sensibile)   │  ┌────────────────────┐              │
│  │ - region          │  │ .encryption.key    │              │
│  │ - targetLow/High  │  │ (fallback, 0o600)  │              │
│  └───────────────────┘  └────────────────────┘              │
└─────────────────────────────────────────────────────────────┘
```

### Caratteristiche di Sicurezza

- **Crittografia AES-256-GCM**: Le credenziali sono crittografate con algoritmo AES-256 in modalità GCM con authentication tag
- **Salt e IV casuali**: Ogni operazione di crittografia usa salt e IV unici
- **Chiavi nel Keychain (preferito)**: La chiave master è salvata nel keychain del sistema operativo:
  - Windows: Credential Manager
  - macOS: Keychain
  - Linux: Secret Service (libsecret)
- **Fallback file-based**: Se Keytar non è disponibile (es. LM Studio, ambienti senza moduli nativi), la chiave viene salvata in `.encryption.key` con permessi restrittivi (0o600)
- **Token persistenti**: I JWT token sono salvati crittografati per evitare login ripetuti
- **Migrazione automatica**: Le credenziali dalla vecchia versione vengono migrate automaticamente e le password in chiaro eliminate
- **Permessi file**: Automaticamente impostati a 600 (solo utente)
- **Nessun tracking**: Zero telemetria
- **Elaborazione locale**: Nessun dato inviato a server esterni

## 🧾 SBOM (Software Bill of Materials)

Il progetto pubblica un [SBOM](https://github.com/resources/articles/what-is-an-sbom-software-bill-of-materials) in formato [CycloneDX](https://cyclonedx.org/) 1.6: l'inventario completo, leggibile da macchina, di tutto il codice di terze parti che gira sul tuo dispositivo quando usi il server.

- **File**: [`sbom.cdx.json`](sbom.cdx.json) nella radice del repository; è incluso anche dentro il bundle `.mcpb` e allegato a ogni [release GitHub](https://github.com/sedoglia/librelink-mcp-server/releases).
- **Contenuto**: le sole dipendenze di produzione (quelle che finiscono nel bundle), dirette e transitive, con versione, licenza, [Package URL](https://github.com/package-url/purl-spec), hash SHA-512 del tarball npm e grafo delle dipendenze. Le devDependencies (`typescript`, `@types/*`) sono escluse perché non vengono distribuite.
- **Generazione**: prodotto da [`@cyclonedx/cyclonedx-npm`](https://github.com/CycloneDX/cyclonedx-node-npm) a partire dal solo `package-lock.json`, in modalità riproducibile (senza timestamp né numero di serie): lo stesso lockfile produce sempre lo stesso inventario, quindi un diff sull'SBOM segnala esclusivamente un cambio di dipendenze.
- **Allineamento garantito**: la CI rigenera l'SBOM a ogni push e PR (`npm run sbom:check`) e fallisce se non coincide con quello committato, così il file su `main` descrive sempre il lockfile corrente. Chi aggiorna una dipendenza deve quindi rilanciare `npm run sbom` e committare il risultato insieme a `package-lock.json`; sulle PR di Dependabot lo fa in automatico il workflow `dependabot-sbom.yml`.

Per rigenerarlo o per usarlo con uno scanner di vulnerabilità (es. [Grype](https://github.com/anchore/grype), [OSV-Scanner](https://github.com/google/osv-scanner), [Dependency-Track](https://dependencytrack.org/)):

```bash
npm run sbom
grype sbom:sbom.cdx.json
```

## ⚠️ Fix API v4.16.0 (Ottobre 2025)

### Il Problema

L'8 ottobre 2025, Abbott ha reso obbligatori:
1. Header `version` con valore minimo `4.16.0`
2. Header `Account-Id` contenente l'hash SHA256 dell'userId

### La Soluzione

Questo fork genera automaticamente l'`Account-Id` dopo il login:

```typescript
import { createHash } from 'crypto';

// L'userId viene dalla risposta del login
const userId = loginResponse.data.user.id;
const accountId = createHash('sha256').update(userId).digest('hex');

// L'header viene aggiunto a tutte le richieste autenticate
headers['Account-Id'] = accountId;
```

## 🐛 Troubleshooting

### Errore 403 con `minimumVersion`

```json
{"data":{"minimumVersion":"4.16.0"},"status":920}
```

**Soluzione:** Stai usando una versione vecchia. Usa questo fork aggiornato.

### Errore `RequiredHeaderMissing`

**Soluzione:** L'header `Account-Id` non viene inviato. Usa questo fork che lo include automaticamente.

### Nessuna connessione trovata

**Soluzioni:**
1. Apri l'app LibreLinkUp e accetta i nuovi Termini e Condizioni
2. Verifica che qualcuno stia condividendo i dati con te
3. Controlla di usare le credenziali LibreLinkUp (non LibreLink)

### Errore di autenticazione

**Soluzioni:**
1. Verifica email e password
2. Prova ad accedere dall'app ufficiale LibreLinkUp
3. Controlla la regione (EU vs US, ecc.)

### Errore Keytar/Keychain

Se riscontri errori con il keychain:
1. Assicurati che il servizio keychain del sistema sia attivo
2. Su Linux, installa `libsecret-1-dev` e `gnome-keyring`
3. Se Keytar non è disponibile, il sistema userà automaticamente il fallback file-based (`.encryption.key` nella directory dati)
4. Il fallback è completamente trasparente e le credenziali rimangono crittografate con AES-256-GCM

## 📁 Struttura Progetto

```
librelink-mcp-server/
├── src/
│   ├── index.ts              # Server MCP principale
│   ├── librelink-client.ts   # Client API con fix v4.16.0
│   ├── glucose-analytics.ts  # Analisi e statistiche
│   ├── config.ts             # Gestione configurazione
│   ├── configure.ts          # Tool CLI configurazione
│   ├── secure-storage.ts     # Storage sicuro con Keytar
│   └── types.ts              # Definizioni TypeScript
├── scripts/
│   ├── smoke-test.mjs        # Smoke test MCP senza credenziali (CI)
│   ├── sbom-check.mjs        # Verifica che l'SBOM coincida col lockfile (CI)
│   └── pack.mjs              # Build del bundle .mcpb di release
├── manifest.json             # Manifest del bundle .mcpb
├── sbom.cdx.json             # SBOM CycloneDX delle dipendenze di produzione
├── test-real-connection.js   # Test connessione
├── test-secure-storage.js    # Test modulo sicurezza
├── package.json
├── tsconfig.json
└── README.md
```

## 📦 Pubblicare una release (per i maintainer)

Il numero di versione è dichiarato in sei file, che devono cambiare insieme: `package.json`, `package-lock.json`, `manifest.json` (il bundle `.mcpb`), `src/index.ts` (costruttore `Server` e banner di avvio) e i due README (riga di changelog + URL di download del bundle).

1. **Branch e bump**
   ```bash
   git checkout -b release/X.Y.Z
   npm version X.Y.Z --no-git-tag-version   # package.json + package-lock.json
   ```
   Poi aggiorna a mano `manifest.json`, `src/index.ts`, `README.md` e `README.en.md`.

2. **Verifica**
   ```bash
   npm run typecheck && npm run build
   npm run pack
   npm audit --audit-level=moderate
   ```
   `npm run pack` compila, reinstalla le sole dipendenze di produzione, esegue lo smoke test su quell'albero (che controlla anche che la versione riportata via MCP coincida con `package.json`), rigenera `sbom.cdx.json`, impacchetta `releases/librelink-mcp-server.mcpb` con il relativo `.sha256` e infine ripristina le devDependencies. Così il bundle non contiene mai `typescript` o `@types/*`, e l'SBOM (che riporta la nuova versione e le dipendenze aggiornate) va committato insieme al bump.

3. **Pull request** con il template dedicato (le PR ordinarie e quelle di Dependabot non lo usano):
   ```bash
   gh pr create --template release.md
   ```
   Il merge su `main` richiede la CI verde.

4. **Tag e release** dopo il merge:
   ```bash
   git checkout main && git pull --ff-only
   git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z
   npm run pack
   gh release create vX.Y.Z releases/librelink-mcp-server.mcpb releases/librelink-mcp-server.mcpb.sha256 sbom.cdx.json \
     --title "LibreLink MCP Server vX.Y.Z" --latest --notes-file NOTE.md
   ```

5. **Controllo finale**: scarica gli asset pubblicati e verifica il checksum, esattamente come farà un utente.
   ```bash
   gh release download vX.Y.Z -p 'librelink-mcp-server.mcpb*'
   sha256sum -c librelink-mcp-server.mcpb.sha256
   ```

## 🔐 Privacy Policy

Questo server MCP rispetta la tua privacy. Ecco un riepilogo:

- **Elaborazione locale**: Tutti i dati vengono elaborati esclusivamente sul tuo dispositivo
- **Crittografia**: Credenziali protette con AES-256-GCM, chiavi nel keychain OS
- **Nessun tracking**: Zero telemetria, analytics o condivisione con terze parti
- **Comunicazione sicura**: Solo con API LibreLinkUp ufficiali di Abbott

📄 **[Leggi la Privacy Policy completa](PRIVACY_POLICY.md)**

## 📜 Licenza

MIT License

## 🙏 Crediti

- Fork originale: [amansk/librelink-mcp-server](https://github.com/amansk/librelink-mcp-server)
- Documentazione API: [khskekec/libre-link-up-http-dump](https://gist.github.com/khskekec/6c13ba01b10d3018d816706a32ae8ab2)
- MCP Protocol: [Anthropic](https://modelcontextprotocol.io)
- Secure Storage: [Keytar](https://github.com/atom/node-keytar)

## ☕ Supporta il Progetto

Se questo progetto ti è utile, considera di fare una donazione per supportarne lo sviluppo:

[![PayPal](https://img.shields.io/badge/PayPal-Dona-blue?style=for-the-badge&logo=paypal)](https://paypal.me/sedoglia)

---

**Disclaimer**: Questo è un progetto non ufficiale, non affiliato con Abbott o FreeStyle Libre. Usalo responsabilmente e consulta sempre i professionisti sanitari per decisioni mediche.