Jaipuria Moodle Reports MCP

Un servidor de Model Context Protocol (MCP) de solo lectura orientado al profesorado que hace que los datos de student-report-system de Jaipuria sean consultables en lenguaje natural. Conéctalo a cualquier host MCP (un panel, Claude.ai, ChatGPT, Claude CLI) y pregunta sobre calificaciones de estudiantes, asistencia, asignaturas, analíticas de cohorte, tendencias longitudinales, estudiantes en riesgo y precisión de informes: cada estudiante ingerido, limitado a los campus del llamante.

En vivo: https://moodle-mcp-f6do.onrender.com/mcp · Salud: /health · Herramientas: 27 Repositorio: github.com/mansigambhir-1313/Moodle-MCP · Propietario: Jaipuria AI Labs

Resumen

El pipeline en moodle-agent ingiere datos de Moodle, calcula analíticas y genera informes de estudiantes validados en un proyecto de Supabase. Este MCP es el lado de lectura de ese proyecto para el profesorado y la oficina de programas: expone los datos brutos y las salidas del pipeline como ~27 herramientas estructuradas y autoaprobables que un LLM host enruta.

Es primero los datos: la superficie principal es el libro de calificaciones y la asistencia brutos (consultables para cada estudiante, tenga informe o no); los informes generados y sus puntuaciones de precisión de dos esquemas son una capa secundaria. Es de solo lectura para siempre: ninguna herramienta escribe, ingiere o envía correos.

Linaje de diseño: los patrones del Rehearsal MCP (cachés acotadas, docstrings de contrato de enrutamiento, presupuestos de respuesta, eliminación de secretos, degradación elegante), adaptados del modelo RLS por estudiante de ese servidor a un modelo de profesorado basado en roles y limitado por campus.

Dónde encaja

• Aguas arriba: el proyecto compartido de Supabase student-report-system (tablas students, courses, enrolments, marks, attendance_sessions, student_reports, report_accuracy), escrito por moodle-agent.

• Aguas abajo: cualquier host MCP: un panel para profesorado, conectores de Claude.ai / ChatGPT, Claude CLI.

Related MCP server: VortexIQ MCP Connector

Qué lo hace exclusivo

• Longitudinal, no solo instantánea — una ejecución contiene cada trimestre (T1–T6). Herramientas como student_trajectory y declining_students detectan a un estudiante que baja trimestre a trimestre, algo que una consulta puntual nunca muestra.

• Vistas de panel único — student_360 y cohort_pulse devuelven un estudiante completo / una cohorte completa en una sola llamada, listas para un cajón de panel o una pantalla de inicio.

• Precisión como dato de primera clase — cada informe generado lleva una puntuación de validación de dos esquemas (panel de fidelidad + juez LLM de dos turnos). Pregunta "¿qué informes están marcados y por qué?"

• Señales de enseñanza y currículo — section_compare (equidad A-vs-B), assessment_breakdown (cuestionario vs tarea vs proyecto), subject_difficulty (puntos de presión del currículo).

Herramientas (27)

Cada herramienta es solo SELECT, limitada al campus del token del llamante, acotada y lleva un docstring de enrutamiento QUÉ / CUÁNDO USAR / NO USAR / DEVUELVE.

Estudiantes — datos brutos (primario)

Asignaturas — datos brutos (primario)

Información — longitudinal y de panel único (héroe)

Analíticas y en riesgo (primario)

Informes y precisión (secundario)

Consulta docs/INNOVATION_ROADMAP.md para ideas de la Fase 3 (attendance_eligibility, attendance_marks_link, anomalies, roster_health).

Inicio rápido

Conectar un host (servidor desplegado)

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

Luego pregunta, en lenguaje natural:

"pulso de cohorte para jaipur 2024-26" · "quién está bajando" · "construye mi watchlist" · "muestra el registro completo de JJ24PG001" · "asignaturas más difíciles" · "compara secciones de Wealth Management"

Ejecutar localmente

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",...}

Prueba de humo (handshake MCP real + consultas en vivo)

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

Configuración

config.py (pydantic-settings, lee .env + variables de entorno). validate_config() es una comprobación de arranque de cierre ante fallos en las variables de Supabase.

Todo el registro va a stderr; las líneas de registro nunca contienen contenidos de tokens ni PII.

Modelo de acceso (basado en roles, limitado por campus)

A diferencia del MCP de estudiantes (RLS por usuario), este sirve al profesorado que ve datos institucionales de sus campus. Un token de portador se asigna a un principal con un conjunto de campus permitidos; cada herramienta interseca el campus solicitado con ese conjunto. Un campus fuera de la concesión devuelve {"found": false} — no hay fugas de datos.

Genera un bloque de token por 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
}

La clave de rol de servicio de Supabase permanece en el servidor y nunca se entrega al host. No hay ruta de escritura en el código.

Arquitectura

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

Diseño completo: docs/ARCHITECTURE.md.

Archivos clave

Cachés (seguras contra OOM — solo TTLCache acotada)

_run_cache (última ejecución final por ámbito), _rollup_cache / _marks_cache (resúmenes de datos brutos de cohorte). Las herramientas de cohorte paginan más allá del límite de 1000 filas de PostgREST y almacenan en caché el resultado durante 5 minutos.

Despliegue

• Render (blueprint render.yaml o Docker): Python 3.12 / Docker, uvicorn server:app, comprobación de salud /health. Configura SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, MCP_TOKENS en el panel.

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

• La producción actual está en la instancia Free (se apaga después de ~15 min de inactividad → ~50s de arranque en frío). Actualiza a Starter para que esté siempre activa.

Pasos completos de prueba/despliegue: DEPLOY.md.

Runbooks

Rotar tokens de acceso — regenera MCP_TOKENS (mismo generador), actualiza la variable de entorno de Render; el servicio se reinicia y los tokens antiguos dejan de funcionar. Reemite los nuevos tokens al profesorado.

Añadir un profesor por campus — añade una entrada "mcp_...": {"name": "...", "campuses": ["<campus>"]} a MCP_TOKENS, vuelve a desplegar, entrégales su token.

Añadir una nueva herramienta — sigue docs/ARCHITECTURE.md §11: añade un modelo Params + _impl(svc,…) + register(), limita cada consulta al campus, strip_secrets, escribe el docstring de enrutamiento, registra en server.py. Reutiliza los ayudantes de datos brutos en tools/common.py.

Arranque en frío / primera solicitud lenta — la instancia gratuita se despertó de inactividad (~50s). Caliéntala con curl <url>/health, o mejora la instancia.

Verificar un despliegue — curl <url>/health, luego MCP_URL="<url>/mcp" MCP_TOKEN="<token>" python test_client.py.

Invariantes de seguridad

Solo lectura para siempre · limita cada consulta al campus · fallos uniformes {"found": false} (sin oráculo de existencia) · eliminación de secretos (los ids de ejecución / claves de almacenamiento / hashes / correos nunca salen del servidor) · clave de rol de servicio solo en el servidor · presupuestos de respuesta + paginación · degradación elegante (nunca 500 en el turno) · solo cachés acotadas (seguro contra OOM). Detalle en docs/ARCHITECTURE.md §3, §11.