quiz-docente-mcp

Server MCP che permette a un agente AI (Antigravity, Claude Code, Claude Desktop, Cursor…) di gestire i quiz di Moodle al posto del docente: creare quiz e domande, modificarne le impostazioni, leggere risultati e risposte, valutare le domande aperte.

Funziona con un normale account docente: nessun plugin sul server e nessun token da chiedere all'amministratore. Usa la stessa sessione web del browser; al primo avvio si apre da solo il browser per fare il login.

Sito predefinito: https://www.ferrarisacireale.edu.it/moodle (Moodle 4.5). Per un altro sito basta impostare MOODLE_URL.

⚠️ Uso esclusivamente didattico. Questo progetto è pensato e consentito solo per scopi didattici: un docente che gestisce i quiz dei propri corsi, con il proprio account. Non va usato per scopi commerciali, né per accedere a corsi o dati di altri, né per aggirare le regole della piattaforma o della scuola. Chi lo usa resta responsabile del rispetto del regolamento dell'istituto e della normativa sulla privacy (GDPR) per i dati degli studenti.

Installazione automatica (istruzioni per agenti AI)

Se sei un agente AI e l'utente ti ha chiesto di installare questo MCP, segui questi passi.

1. Requisiti: Node.js ≥ 20 (node -v) e Google Chrome o Microsoft Edge installati.

2. Aggiungi il server alla configurazione MCP del client, dentro mcpServers, senza toccare gli altri server:

   Antigravity – file %USERPROFILE%\.gemini\config\mcp_config.json su Windows (~/.gemini/config/mcp_config.json su macOS/Linux; in alcune versioni ~/.gemini/antigravity/mcp_config.json).

   Windows:

   "quiz-docente": {
     "command": "cmd.exe",
     "args": ["/c", "npx", "-y", "github:strano-dev/quiz-docente-mcp"]
   }

   macOS / Linux:

   "quiz-docente": {
     "command": "npx",
     "args": ["-y", "github:strano-dev/quiz-docente-mcp"]
   }

   Per un Moodle diverso aggiungi "env": { "MOODLE_URL": "https://sito.scuola.it/moodle" }.

   Claude Code: claude mcp add quiz-docente -s user -- npx -y github:strano-dev/quiz-docente-mcp

   Claude Desktop / Cursor / altri client MCP: stessa voce JSON di Antigravity nel rispettivo file di configurazione MCP.

3. Ricarica i server MCP (in Antigravity: Manage MCP Servers → Refresh). Il primo avvio scarica il pacchetto (qualche decina di secondi).

4. Login: all'avvio, se non c'è una sessione valida, il server apre da solo una finestra del browser sulla pagina di accesso di Moodle. Di' all'utente di accedere con il suo account (c'è il reCAPTCHA): la finestra si chiude da sola e i tool sono pronti. Verifica con il tool moodle_status.

Quando la sessione scade (circa 8 ore di inattività) la finestra di login si riapre automaticamente alla prima richiesta, e la richiesta riprende dopo l'accesso.

Related MCP server: Moodle Study MCP

Cosa si può fare

Scelta di progetto: niente eliminazioni

Non esistono tool per eliminare quiz o domande: le eliminazioni le fa sempre il docente, a mano, da Moodle. moodle_remove_quiz_slots toglie una domanda da un quiz ma la lascia nella banca domande. Un quiz che ha già tentativi degli studenti non permette di aggiungere o togliere domande (vincolo di Moodle).

Identificativi

• courseid: id del corso (course/view.php?id=…)

• cmid: id del quiz come modulo del corso (mod/quiz/view.php?id=…)

• slot_id: posizione di una domanda nel quiz, da moodle_get_quiz

• category_id, question_id: dai tool della banca domande, che accettano courseid (banca del corso) oppure cmid (banca propria del quiz)

Configurazione

La sessione è salvata in ~/.moodle-mcp/session.json e contiene il cookie di accesso: non condividerla. Login manuale da terminale: npx -y -p github:strano-dev/quiz-docente-mcp quiz-docente-mcp-login.

Sviluppo

git clone https://github.com/strano-dev/quiz-docente-mcp
cd quiz-docente-mcp
npm install
npm test           # test unitari (Vitest)
npm run check      # typecheck + test con copertura + build: da eseguire prima di ogni commit
npm run build      # compila src/ in dist/ (dist/ è versionata: serve a npx per avviare senza build)
npm run login      # login manuale
npm start          # avvia il server MCP su stdio

Regola: si procede sempre in TDD

Ogni modifica al codice segue il ciclo Test-Driven Development, senza eccezioni:

1. Red – scrivi prima un test in test/ che descrive il comportamento voluto e verifica che fallisca.

2. Green – scrivi in src/ il codice minimo che lo fa passare.

3. Refactor – migliora il codice tenendo tutti i test verdi.

Regole pratiche:

• ogni bug si corregge partendo da un test che lo riproduce;

• nessuna nuova funzione o nuovo tool MCP senza i relativi test;

• i test unitari non chiamano mai il Moodle reale: test/helpers/fake-moodle.ts simula il sito intercettando fetch, test/helpers/moodle-html.ts genera pagine sintetiche con la stessa struttura di Moodle 4.5 (nessun dato reale), Playwright viene sostituito con un mock;

• prima di ogni commit npm run check deve passare; le soglie minime di copertura (righe 90%, rami 80%) sono configurate in vitest.config.ts e fanno fallire la suite se non rispettate;

• dopo aver modificato src/ ricompila (npm run build) e versiona anche dist/.

Come funziona

Moodle non espone ai docenti API per creare quiz e domande, quindi il server usa gli stessi endpoint dell'interfaccia web, ricavati analizzando il traffico del browser:

Testato su Moodle 4.5.11. I report voti/risposte sono stati verificati solo su quiz senza tentativi di studenti (le anteprime del docente non compaiono nei report).

Licenza

MIT (vedi LICENSE). Resta valida l'indicazione d'uso esclusivamente didattico riportata all'inizio.