Jaipuria Moodle Reports MCP

Ein fakultätsorientierter, schreibgeschützter Model Context Protocol (MCP)-Server, der die Jaipuria-student-report-system-Daten in natürlicher Sprache abfragbar macht. Verbinden Sie ihn mit einem beliebigen MCP-Host (einem Dashboard, Claude.ai, ChatGPT, Claude CLI) und fragen Sie nach Studentennoten, Anwesenheit, Fächern, Kohortenanalysen, Längsschnitt-Trends, gefährdeten Studenten und Berichtsgenauigkeit – für jeden erfassten Studenten, begrenzt auf die Campus des Aufrufers.

Live: https://moodle-mcp-f6do.onrender.com/mcp · Health: /health · Tools: 27 Repo: github.com/mansigambhir-1313/Moodle-MCP · Owner: Jaipuria AI Labs

Überblick

Die Pipeline in moodle-agent erfasst Moodle-Daten, berechnet Analysen und generiert validierte Studentenberichte in ein Supabase-Projekt. Dieser MCP ist die Leseseite dieses Projekts für Fakultät und Studienprogrammbüro: Er stellt die Rohdaten und die Ausgaben der Pipeline als ~27 strukturierte, automatisch genehmigbare Tools bereit, die ein Host-LLM weiterleitet.

Es ist datenorientiert – die primäre Oberfläche ist das rohe Notenbuch und die Anwesenheit (abfragbar für jeden Studenten, ob Bericht oder nicht); die generierten Berichte und ihre Genauigkeitswerte aus zwei Schemata sind eine sekundäre Ebene. Es ist dauerhaft schreibgeschützt: Kein Tool schreibt, erfasst oder sendet E-Mails.

Design-Abstammung: Die Muster des Rehearsal MCP (begrenzte Caches, Routing-Vertrag-Docstrings, Antwortbudgets, Geheimnis-Entfernung, elegante Degradierung), angepasst von dessen pro-Studenten-RLS-Modell auf ein rollenbasiertes, campusbezogenes Fakultätsmodell.

Wo es passt

• Upstream: Das gemeinsame Supabase-Projekt student-report-system (Tabellen students, courses, enrolments, marks, attendance_sessions, student_reports, report_accuracy), geschrieben von moodle-agent.

• Downstream: Jeder MCP-Host – ein Fakultäts-Dashboard, Claude.ai / ChatGPT-Konnektoren, Claude CLI.

Related MCP server: VortexIQ MCP Connector

Was es exklusiv macht

• Längsschnitt, nicht nur Momentaufnahme – ein Lauf enthält jedes Trimester (T1–T6). Tools wie student_trajectory und declining_students erkennen einen Studenten, der Semester für Semester abrutscht, was eine punktuelle Abfrage nie zeigt.

• Einzelansichten – student_360 und cohort_pulse geben einen ganzen Studenten / eine ganze Kohorte in einem Aufruf zurück, bereit für eine Dashboard-Schublade oder einen Startbildschirm.

• Genauigkeit als erstklassige Daten – jeder generierte Bericht trägt einen Validierungswert aus zwei Schemata (Treue-Panel + Zwei-Runden-LLM-Judge). Fragen Sie „welche Berichte sind markiert und warum?"

• Lehr- und Curriculumsignale – section_compare (A-vs-B-Fairness), assessment_breakdown (Quiz vs. Aufgabe vs. Projekt), subject_difficulty (Curriculums-Druckpunkte).

Tools (27)

Jedes Tool ist nur SELECT, auf den Campus des Aufrufers beschränkt, begrenzt und trägt eine Routing-Docstring mit WAS / WANN VERWENDEN / NICHT VERWENDEN / GIBT ZURÜCK.

Studenten – Rohdaten (primär)

Fächer – Rohdaten (primär)

Einblicke – Längsschnitt & Einzelansichten (Hero)

Analytik & gefährdete Studenten (primär)

Berichte & Genauigkeit (sekundär)

Siehe docs/INNOVATION_ROADMAP.md für Phase-3-Ideen (attendance_eligibility, attendance_marks_link, anomalies, roster_health).

Schnellstart

Host verbinden (bereitgestellter Server)

claude mcp add moodle --transport http https://moodle-mcp-f6do.onrender.com/mcp \
  --header "Authorization: Bearer <your MCP_TOKENS value>"

Dann fragen Sie in natürlicher Sprache:

„Kohorten-Puls für Jaipur 2024-26" · „wer fällt ab" · „erstellen Sie meine Watchlist" · „zeigen Sie JJ24PG001s vollständigen Datensatz" · „schwierigste Fächer" · „vergleichen Sie Sektionen von Wealth Management"

Lokal ausführen

cd moodle-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env            # fill in the vars below
uvicorn server:app --port 8899
curl localhost:8899/health      # {"status":"ok",...}

Smoke-Test (echter MCP-Handshake + Live-Abfragen)

MCP_URL="http://localhost:8899/mcp" MCP_TOKEN="<a token>" python test_client.py

Konfiguration

config.py (pydantic-settings, liest .env + Umgebungsvariablen). validate_config() ist ein Fail-Closed-Boot-Check für die Supabase-Variablen.

Die gesamte Protokollierung erfolgt auf stderr; Protokollzeilen enthalten niemals Token-Inhalte oder personenbezogene Daten.

Zugriffsmodell (rollenbasiert, campusbezogen)

Im Gegensatz zum Studenten-MCP (pro-Benutzer-RLS) dient dies Fakultätsmitgliedern, die institutionelle Daten für ihre Campus sehen. Ein Bearer-Token ordnet einem Prinzipal eine erlaubte Campus-Menge zu; jedes Tool überschneidet den angeforderten Campus mit dieser Menge. Ein Campus außerhalb der Gewährung gibt {"found": false} zurück – keine Datenleckage.

Generieren Sie einen Token-Block pro Campus:

python3 -c "import secrets; print('mcp_'+secrets.token_urlsafe(24))"   # one per faculty

// MCP_TOKENS (single-line JSON in the env var)
{
  "mcp_...indore": {"name": "Indore TNP",       "campuses": ["indore"]},
  "mcp_...office": {"name": "Programme Office",  "campuses": null}      // null = all campuses
}

Der Supabase-Service-Rollen-Schlüssel bleibt serverseitig und wird niemals an den Host weitergegeben. Es gibt keinen Schreibpfad im Code.

Architektur

MCP host (dashboard / Claude / ChatGPT)
        │  MCP over HTTP + Bearer <faculty token>
        ▼
server.py (FastMCP /mcp, /health)
  get_authenticated_service()  → verify token → MoodleService(allowed_campuses)
        │
  tools/* (6 modules, 27 tools) — each: Params model + _impl(svc,…) + register()
        │  every query .in_("campus", allowed) ; strip_secrets ; response budgets
        ▼
Supabase (read service role) — students · courses · enrolments · marks ·
                               attendance_sessions · student_reports · report_accuracy

Vollständiges Design: docs/ARCHITECTURE.md.

Schlüsseldateien

Caches (OOM-sicher – nur begrenzter TTLCache)

_run_cache (letzter endgültiger Lauf pro Bereich), _rollup_cache / _marks_cache (Kohorten-Rohdaten-Rollups). Kohorten-Tools paginieren über PostgRESTs 1000-Zeilen-Grenze und cachen das Ergebnis für 5 Minuten.

Bereitstellung

• Render (render.yaml-Blueprint oder Docker): Python 3.12 / Docker, uvicorn server:app, Health-Check /health. Setzen Sie SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, MCP_TOKENS im Dashboard.

• Docker: docker build -t moodle-mcp . && docker run -p 8000:8000 --env-file .env moodle-mcp

• Die aktuelle Produktion läuft auf der Free-Instanz (fährt nach ~15 Minuten Leerlauf herunter → ~50s Kaltstart). Upgrade auf Starter für Dauerbetrieb.

Vollständige Test-/Bereitstellungsschritte: DEPLOY.md.

Runbooks

Zugriffstokens rotieren – MCP_TOKENS neu generieren (gleicher Generator), die Render-Umgebungsvariable aktualisieren; der Dienst startet neu und alte Tokens funktionieren nicht mehr. Stellen Sie die neuen Tokens erneut an die Fakultät aus.

Fakultät pro Campus hinzufügen — einen Eintrag "mcp_...": {"name": "...", "campuses": ["<campus>"]} zu MCP_TOKENS hinzufügen, neu bereitstellen und ihnen ihr Token aushändigen.

Neues Tool hinzufügen — docs/ARCHITECTURE.md §11 folgen: ein Params-Modell + _impl(svc,…) + register() hinzufügen, jede Abfrage auf Campus-Bereich beschränken, strip_secrets, den Routing-Docstring schreiben, in server.py registrieren. Die Rohdaten-Helfer in tools/common.py wiederverwenden.

Kaltstart / erste Anfrage langsam — Free-Instanz ist aus dem Leerlauf aufgewacht (~50s). Wärme sie mit curl <url>/health, oder aktualisiere die Instanz.

Deployment verifizieren — curl <url>/health, dann MCP_URL="<url>/mcp" MCP_TOKEN="<token>" python test_client.py.

Sicherheitsinvarianten

Nur-Lese-Zugriff für immer · jede Abfrage auf Campus-Bereich beschränken · einheitliche {"found": false} Fehlschläge (kein Existenz-Orakel) · Geheimnis-Entfernung (Run-IDs / Speicherschlüssel / Hashes / E-Mails verlassen nie den Server) · Service-Rollen-Schlüssel nur serverseitig · Antwortbudgets + Paging · Graceful Degradation (niemals 500 für die Runde) · nur begrenzte Caches (OOM-sicher). Details in docs/ARCHITECTURE.md §3, §11.