v1.5.0 Stable

ClasseViva MCP v1.5.0 — Stable

Il registro elettronico ClasseViva dentro il tuo assistente AI: voti, compiti, assenze, circolari, materiali didattici e Google Classroom, in locale sul tuo computer. Da questa versione è usabile anche dal telefono (app Claude e ChatGPT), restando completamente self-hosted.

Installazione rapida

uvx classeviva-mcp login

Per un avvio più veloce e un percorso fisso:

uv tool install classeviva-mcp
classeviva-mcp login

Collega il server

Copia il JSON stampato da login e incollalo:

• nella configurazione MCP del tuo client (Claude, Cursor, Codex, Antigravity, OpenCode, ...);
• oppure nella chat del tuo agente AI, chiedendogli di configurarlo per te.

Puoi ristamparlo in qualsiasi momento, anche nel formato nativo del tuo client:

classeviva-mcp config --client opencode   # oppure: generic, vscode, codex, claude-code

Novità v1.5.0 — Accesso dal telefono, senza servizi esterni

Le app Claude (web, desktop, mobile) e ChatGPT si collegano al tuo server tramite OAuth 2.1, gestito dal server stesso: niente account di terze parti, niente costi, le credenziali ClasseViva non lasciano il tuo PC.

classeviva-mcp remote-setup          # scegli la passphrase del proprietario
tailscale funnel --bg 8765           # HTTPS gratuito con indirizzo fisso
classeviva-mcp serve --transport streamable-http --public-url https://<pc>.<tailnet>.ts.net

Poi in Claude: Impostazioni → Connettori → Aggiungi connettore personalizzato → https://<pc>.<tailnet>.ts.net/mcp, approva con la passphrase e funziona anche dall'app sul telefono.

• 🔒 PKCE, token a scadenza breve con rotazione, revoca con classeviva-mcp remote-revoke
• 🔒 Su disco solo hash: mai token o passphrase in chiaro
• 🔧 Server HTTP ora funzionante dietro tunnel; token bearer stabile tra un riavvio e l'altro

Computer di scuola o condivisi

Il server è pensato per un solo account su un dispositivo personale. Su un PC con account condiviso chiunque usi quell'account può aprire il Keyring, e due studenti che fanno login si sovrascrivono a vicenda.

Prima di lasciare un computer non tuo:

classeviva-mcp logout --purge

Non servono privilegi di amministratore. Dettagli in SECURITY.md.

What's Changed

• fix: config MCP stabile con uvx, supporto reti scolastiche, errori di login chiari (v1.3.0) by @NihaoBoo in #5
• feat: self-hosted OAuth remote access for mobile apps (v1.5.0) by @NihaoBoo in #6
• fix: print only fixed messages when validating the owner passphrase by @NihaoBoo in #7

Full Changelog: v1.4.0...v1.5.0

Documentazione

• README — guida passo-passo
• CHANGELOG — tutte le modifiche
• SECURITY — policy di sicurezza
• PRIVACY — informativa privacy
• PyPI — pacchetto ufficiale

v1.4.0 Stable

Added

• Didattica / Materiali-Compiti: list_didactics (cartelle, materia, docente, file, con filtri)
  e download_didactics_item (scarica un file con permessi 0o600 ed estrae il testo da
  PDF/DOCX/XLSX/TXT/CSV). Tollera il refuso upstream didacticts.
• get_calendar: giorni di vacanza, festività, patrono e ponti deliberati dalla scuola
  (giorni HD) nei prossimi giorni, più i periodi dell'anno scolastico.
• get_notes: note disciplinari, richiami e sanzioni (NTTE, NTCL, NTWN, NTST) con
  testo completo.
• get_documents: elenco di pagelle e documenti ufficiali di scrutinio.
• get_schoolbooks: libri adottati con ISBN, autori, editore, prezzo e obbligatorio/consigliato.
• Prompt MCP recap-settimanale e piano-recupero-materie.
• get_snapshot include ora prossimi giorni di vacanza/ponti e novità in Didattica.
  Le note disciplinari restano escluse di proposito.
• README: tabella tool aggiornata e guida al collaudo live sul proprio account.

Changed

• read_notice_pdf: se l'allegato è bloccato perché la circolare non è mai stata aperta,
  con allow_mark_as_read=True la circolare viene segnata come letta, l'allegato scaricato e
  la risposta riporta notice_marked_as_read: true. Senza consenso esplicito non cambia nulla.
• Tutti i nuovi tool dati personali non vengono registrati in CLASSEVIVA_READ_ONLY_MODE.

Note complete: CHANGELOG.md

v1.3.0 Stable

Installazione rapida:

uvx classeviva-mcp login

Collega il server

Copia il JSON stampato da login e incollalo in uno dei due modi:

• nella configurazione MCP del tuo client (Claude, Cursor, Codex, Antigravity, OpenCode, ...);
• oppure nella chat del tuo agente AI, chiedendogli di configurarlo per te.

Novità v1.3.0: su client come OpenCode, puoi generare direttamente il blocco nativo con:

classeviva-mcp config --client opencode

Note complete: CHANGELOG.md

Novità principali v1.3.0

• JSON MCP stabile con uvx: non punta più al percorso temporaneo nella cache di uv (...\uv\cache\archive-v0\...), ma usa uvx classeviva-mcp (oppure lo shim stabile se installato via uv tool install).
• Supporto reti scolastiche: rispetto automatico del proxy di sistema e verifica certificati con lo store TLS di Windows (truststore), con opt-out CLASSEVIVA_PROXY=off e CLASSEVIVA_TLS=certifi.
• Messaggi di errore di login chiari e azionabili: spiegazione chiara per credenziali rifiutate (es. codice 251), rilevamento caratteri di controllo (^V) incollati nella console, indicazione dell'uso del codice studente S... al posto dell'email.
• Protezione da blocco account Spaggiari: cooldown di 10 minuti dopo una password errata per impedire che chiamate a ripetizione dell'agente blocchino temporaneamente l'accesso al registro.
• Nuovo comando config: classeviva-mcp config --client generic|opencode|vscode|codex|claude-code per stampare la configurazione corretta in qualsiasi momento senza dover ripetere il login.
• doctor potenziato: diagnostica approfondita su versione, proxy/TLS attivi, tipo di credenziale salvata (email o codice) e consigli sull'avvio.

Computer di scuola o condivisi

Il server è pensato per un solo account su un dispositivo personale. Su un PC con account condiviso chiunque usi quell'account può aprire il Keyring, e due studenti che fanno login si sovrascrivono a vicenda.

Prima di lasciare un computer non tuo:

classeviva-mcp logout --purge

Non servono privilegi di amministratore. Dettagli in SECURITY.md.

Documentazione

• README — guida passo-passo
• CHANGELOG — tutte le modifiche
• SECURITY — policy di sicurezza
• PRIVACY — informativa privacy
• PyPI — pacchetto ufficiale

v1.2.1 Stable

Installazione rapida:

uvx classeviva-mcp login

Collega il server

Copia il JSON stampato da login e incollalo in uno dei due modi:

• nella configurazione MCP del tuo client (Claude, Cursor, Codex, Antigravity, Opencode, ...);
• oppure nella chat del tuo agente AI, chiedendogli di configurarlo per te.

Il JSON contiene il percorso assoluto dell'installazione su quel computer, quindi cambia da macchina a macchina.

Note complete: CHANGELOG.md

Computer di scuola o condivisi

Il server è pensato per un solo account su un dispositivo personale. Su un PC con account condiviso chiunque usi quell'account può aprire il Keyring, e due studenti che fanno login si sovrascrivono a vicenda._

Prima di lasciare un computer non tuo:

classeviva-mcp logout --purge

Non servono privilegi di amministratore. Dettagli in SECURITY.md.

Documentazione

• README — guida passo-passo
• CHANGELOG — tutte le modifiche
• SECURITY — policy di sicurezza
• PRIVACY — informativa privacy
• PyPI — pacchetto ufficiale

v1.2.0 Stable

Workflow avanzati: un solo tool per l'intero stato dello studente, risorse MCP indirizzate da URI e un trasporto HTTP protetto da token per l'uso da VPS, telefono o bot.

Installazione rapida

Serve solo uv. Apri il terminale ed esegui:

uvx classeviva-mcp login

Oppure, se preferisci la versione dal repository:

uvx --from git+https://github.com/NihaoBoo/classeviva-mcp@stable classeviva-mcp login

Il comando verifica le credenziali contro Spaggiari, le salva nel Keyring di sistema e stampa un blocco JSON già pronto per il client MCP.

Vuoi bloccare questa versione esatta? Sostituisci @stable con @v1.2.0.

Collega il server

Copia il JSON stampato da login e incollalo in uno dei due modi:

• nella configurazione MCP del tuo client (Claude, Cursor, Codex, Antigravity, Opencode, ...);
• oppure nella chat del tuo agente AI, chiedendogli di configurarlo per te.

Il JSON contiene il percorso assoluto dell'installazione su quel computer, quindi cambia da macchina a macchina.

Cosa c'è di nuovo

get_snapshot: tutto in una chiamata

Profilo, contesto, materie, orario, voti con medie, assenze da giustificare, compiti e agenda in un solo tool. Le cinque richieste di rete partono in parallelo: un brief + un piano di recupero passano da 6-8 round-trip a 1.

Risorse MCP

Dataset in sola lettura indirizzati da URI, che il client può scaricare una volta e riusare:

classeviva://profile · //subjects · //notices · //grades · //absences · //homework/{days} · //agenda/{start}/{end} · //lessons/{start}/{end}

Trasporto HTTP con token (opzionale)

classeviva-mcp serve --transport streamable-http --port 8765

Per usarlo da un VPS, dal telefono o da un bot. Il server richiede sempre un bearer token: senza header Authorization risponde 401 Unauthorized e non esegue nulla. Di default ascolta solo su 127.0.0.1; se lo esponi su un indirizzo raggiungibile ti avvisa che il traffico non è cifrato (usalo solo su rete privata o dietro un tunnel).

Il default resta stdio: nessuna porta aperta, il server vive e muore con il tuo client.

Computer di scuola o condivisi

Il server è pensato per un solo account su un dispositivo personale. Su un PC con account condiviso chiunque usi quell'account può aprire il Keyring, e due studenti che fanno login si sovrascrivono a vicenda.

Prima di lasciare un computer non tuo:

classeviva-mcp logout --purge

Non servono privilegi di amministratore. Dettagli in SECURITY.md.

Documentazione

• README — guida passo-passo
• CHANGELOG — tutte le modifiche
• SECURITY — policy di sicurezza
• PRIVACY — informativa privacy
• PyPI — pacchetto ufficiale

v1.1.3 Stable

Correzioni di sicurezza: lo stato di lettura delle circolari non può più essere aggirato e le credenziali vengono verificate prima di essere salvate. Più connessione HTTP riutilizzata e cache breve per i workflow avanzati. Tutte le modifiche sono nel CHANGELOG.

Installazione rapida

Serve solo uv. Apri il terminale ed esegui:

uvx --from git+https://github.com/NihaoBoo/classeviva-mcp@stable classeviva-mcp login

Il comando verifica le credenziali contro Spaggiari, le salva nel Keyring di sistema e stampa un blocco JSON già pronto per il client MCP.

Vuoi bloccare questa versione esatta? Sostituisci @stable con @v1.1.3.

Collega il server

Copia il JSON stampato da login e incollalo in uno dei due modi:

• nella configurazione MCP del tuo client (Claude, Cursor, Codex, Antigravity, Opencode, ...);
• oppure nella chat del tuo agente AI, chiedendogli di configurarlo per te.

Il JSON contiene il percorso assoluto dell'installazione su quel computer, quindi cambia da macchina a macchina. Ecco la struttura di riferimento:

{
  "mcpServers": {
    "classeviva": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/NihaoBoo/classeviva-mcp@stable",
        "classeviva-mcp"
      ]
    }
  }
}

Se il client non riesce a trovare uvx, sostituisci "command" con il percorso assoluto mostrato da login.

Cosa è cambiato

• Nessuna circolare viene più segnata come letta senza consenso. Se non è
  possibile verificare se la circolare è già stata aperta, il server fallisce
  chiuso: solo metadati, nessuna ricevuta di lettura, nessun download.
• Le password non verificate non finiscono più nel Keyring. login
  controlla le credenziali con Spaggiari prima di salvare; se sono sbagliate
  non resta nulla memorizzato.
• Più veloce nei workflow lunghi. Connessione HTTP riutilizzata tra le
  chiamate e cache di 60 secondi sugli endpoint di sola lettura: un brief, un
  piano di recupero e i voti non interrogano più il registro tre volte per gli
  stessi dati.

Google Classroom

Se hai saltato il link .ics durante il login:

# Se usi uvx (senza installazione permanente)
uvx --from git+https://github.com/NihaoBoo/classeviva-mcp@stable classeviva-mcp set-classroom-url

# Se hai installato stabilmente con uv tool install
classeviva-mcp set-classroom-url

Il link viene chiesto con input nascosto. Evita di passarlo come argomento: resterebbe nella cronologia del terminale.

Computer di scuola o condivisi

Il server è pensato per un solo account su un dispositivo personale. Su un PC con account condiviso chiunque usi quell'account può aprire il Keyring, e due studenti che fanno login si sovrascrivono a vicenda.

Prima di lasciare un computer non tuo:

# Se usi uvx
uvx --from git+https://github.com/NihaoBoo/classeviva-mcp@stable classeviva-mcp logout --purge

# Se hai installato con uv tool install
classeviva-mcp logout --purge

Non servono privilegi di amministratore. Cancellare a mano solo le voci del Keyring non basta: session_cache.json contiene il token di sessione e resta fino a logout. Dettagli in SECURITY.md.

Documentazione

• README — guida passo-passo
• CHANGELOG — tutte le modifiche
• SECURITY — policy di sicurezza
• PRIVACY — informativa privacy
• NOTICE — disclaimer

v1.1.2 Stable

Download in streaming, conferma prima di segnare una circolare come letta e indicazioni chiare per l'uso su computer scolastici o condivisi. Tutte le modifiche sono nel CHANGELOG.

Installazione rapida

Serve solo uv. Apri il terminale ed esegui:

uvx --from git+https://github.com/NihaoBoo/classeviva-mcp@stable classeviva-mcp login

Il comando salva le credenziali sul tuo computer e stampa un blocco JSON già pronto per il client MCP.

Vuoi bloccare questa versione esatta? Sostituisci @stable con @v1.1.2.

Collega il server

Copia il JSON stampato da login e incollalo in uno dei due modi:

• nella configurazione MCP del tuo client (Claude, Cursor, Codex, Antigravity, Opencode, ...);
• oppure nella chat del tuo agente AI, chiedendogli di configurarlo per te.

Il JSON contiene il percorso assoluto dell'installazione su quel computer, quindi cambia da macchina a macchina. Ecco la struttura di riferimento:

{
  "mcpServers": {
    "classeviva": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/NihaoBoo/classeviva-mcp@stable",
        "classeviva-mcp"
      ]
    }
  }
}

Se il client non riesce a trovare uvx, sostituisci "command" con il percorso assoluto mostrato da login.

Google Classroom

Se hai saltato il link .ics durante il login:

# Se usi uvx (senza installazione permanente)
uvx --from git+https://github.com/NihaoBoo/classeviva-mcp@stable classeviva-mcp set-classroom-url

# Se hai installato stabilmente con uv tool install
classeviva-mcp set-classroom-url

Il link viene chiesto con input nascosto. Evita di passarlo come argomento: resterebbe nella cronologia del terminale.

Computer di scuola o condivisi

Il server è pensato per un solo account su un dispositivo personale. Su un PC con account condiviso chiunque usi quell'account può aprire il Keyring, e due studenti che fanno login si sovrascrivono a vicenda.

Prima di lasciare un computer non tuo:

# Se usi uvx
uvx --from git+https://github.com/NihaoBoo/classeviva-mcp@stable classeviva-mcp logout --purge

# Se hai installato con uv tool install
classeviva-mcp logout --purge

Non servono privilegi di amministratore. Cancellare a mano solo le voci del Keyring non basta: session_cache.json contiene il token di sessione e resta fino a logout. Dettagli in SECURITY.md.

Documentazione

• README — guida passo-passo
• CHANGELOG — tutte le modifiche
• SECURITY — policy di sicurezza
• PRIVACY — informativa privacy
• NOTICE — disclaimer

v1.1.1 Stable — Migliorie di Sicurezza e Privacy

Output di login più chiaro, canale @stable per installare sempre l'ultima versione stabile e istruzioni aggiornate per Classroom. Tutte le modifiche sono nel CHANGELOG.

Installazione rapida

Serve solo uv. Apri il terminale ed esegui:

uvx --from git+https://github.com/NihaoBoo/classeviva-mcp@stable classeviva-mcp login

Il comando salva le credenziali sul tuo computer e stampa un blocco JSON già pronto per il client MCP.

Vuoi bloccare questa versione esatta? Sostituisci @stable con @v1.1.1.

Collega il server

Copia il JSON stampato da login e incollalo in uno dei due modi:

• nella configurazione MCP del tuo client (Claude, Cursor, Codex, Antigravity, Opencode, ...);
• oppure nella chat del tuo agente AI, chiedendogli di configurarlo per te.

Il JSON contiene il percorso assoluto dell'installazione su quel computer, quindi cambia da macchina a macchina. Ecco la struttura di riferimento:

{
  "mcpServers": {
    "classeviva": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/NihaoBoo/classeviva-mcp@stable",
        "classeviva-mcp"
      ]
    }
  }
}

Se il client non riesce a trovare uvx, sostituisci "command" con il percorso assoluto mostrato da login.

Google Classroom

Se hai saltato il link .ics durante il login:

# Se usi uvx (senza installazione permanente)
uvx --from git+https://github.com/NihaoBoo/classeviva-mcp@stable classeviva-mcp set-classroom-url

# Se hai installato stabilmente con uv tool install
classeviva-mcp set-classroom-url

Documentazione

• README — guida passo-passo
• CHANGELOG — tutte le modifiche
• SECURITY — policy di sicurezza
• PRIVACY — informativa privacy