Moodle Student Bridge
# Moodle Student Bridge
**Conecta a Claude con tu Moodle como estudiante**: entregas, cuestionarios, enunciados, rúbricas,
archivos, anuncios, notificaciones y calificaciones. Y recordatorios en tu celular.
Está pensado para estudiantes cuya universidad **no les da un token de API**: usa el mismo token que
la **app móvil oficial de Moodle** (servicio `moodle_mobile_app`), que cualquier alumno puede obtener
con su propia cuenta. Funciona con cualquier Moodle que tenga la app móvil habilitada.
> Proyecto independiente; no está afiliado a Moodle Pty Ltd. **Solo lee**: nunca entrega tareas ni
> modifica nada en tu Moodle.
## Herramientas MCP
| Herramienta | Qué hace |
|---|---|
| `resumen_semanal` | Todo lo pendiente y lo nuevo en una sola llamada |
| `proximos_vencimientos` | Línea de tiempo: lo que vence en los próximos N días (y lo vencido) |
| `listar_cursos` | Cursos en los que estás matriculado |
| `listar_tareas` | Tareas por curso con fechas |
| `ver_tarea` | Enunciado, rúbricas, adjuntos, estado de tu entrega y retroalimentación |
| `cuestionarios` | Cuándo abren/cierran, tiempo límite, intentos usados y mejor nota |
| `ver_curso` | Secciones, recursos, archivos y enlaces de un curso |
| `leer_archivo` | Extrae el texto de PDF, Word (.docx), PowerPoint (.pptx) y HTML; devuelve imágenes |
| `anuncios` / `ver_discusion` | Avisos de profesores y foros |
| `notificaciones` | La campana: notas publicadas, retroalimentación, cambios (no las marca como leídas) |
| `mensajes` | Conversaciones de mensajería |
| `calificaciones` | Tu libro de calificaciones por curso |
| `quien_soy` | Comprueba con qué cuenta estás conectado |
Cursos y tareas se pueden indicar por id o por parte del nombre (`"fisica"`, `"segundo parcial"`).
Ejemplos: *"¿Qué tengo pendiente esta semana?"*, *"Revisa la tarea del proyecto de Física y hazme
un plan según la rúbrica"*, *"Lee el PDF de Leyes de Kepler y resúmelo"*, *"¿Cómo voy en Física?"*.
## 1. Obtener tu token
```bash
npx moodle-student-bridge-token
```
El asistente te pregunta cómo inicias sesión:
- **Usuario y contraseña de Moodle** → obtiene el token directamente.
- **Microsoft / Google / SSO** → te da un enlace `launch.php`. Ábrelo con tu sesión iniciada y las
DevTools abiertas (F12 → Network), copia la redirección `moodlemobile://token=...` y pégala.
Comprueba el token y lo guarda en `.env`:
```
MOODLE_URL=https://moodle.tu-universidad.edu
MOODLE_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
MOODLE_TZ=America/Guayaquil # opcional
```
## 2. Conectarlo a Claude
**Claude Desktop (lo más fácil):** descarga `moodle-student-bridge.mcpb` de los Releases, ábrelo con
doble clic y pega tu URL y token en el formulario.
**Claude Code:**
```bash
claude mcp add moodle-student --scope user \
-e MOODLE_URL=https://moodle.tu-universidad.edu -e MOODLE_TOKEN=tu_token \
-- npx -y moodle-student-bridge
```
**Desde el código fuente:**
```bash
git clone <repo> && cd moodle-student-bridge && npm install
npm run token # crea el .env
npm run probar # prueba: tu usuario y lo que vence esta semana
claude mcp add moodle-student --scope user -- node /ruta/a/moodle-student-bridge/src/index.js
```
## 3. Recordatorios en el celular (opcional)
Usa [ntfy](https://ntfy.sh): gratis y sin cuenta.
1. Instala la app **ntfy** (Android/iOS) y suscríbete a un tema con un nombre **largo y difícil de
adivinar** (ej. `moodle-ana-8f3k2q9z`). Cualquiera que conozca el nombre puede leer los avisos.
2. Elige dónde se ejecuta:
- **En la nube con GitHub Actions** (funciona con la PC apagada): haz un fork de este repo y
añade en *Settings → Secrets and variables → Actions* los secretos `MOODLE_URL`,
`MOODLE_TOKEN` y `NTFY_TOPIC`. Luego activa los workflows en la pestaña *Actions* (en los
forks vienen desactivados). `recordatorios.yml` corre cada hora y manda el resumen del día a
las 07:00 (hora de Ecuador; cámbialo en el `cron`). Los secretos van cifrados y los
registros solo muestran cuántos avisos se enviaron, nunca su contenido, así que el fork
puede ser público.
- **En tu PC**: programa `node src/recordar.js` cada hora y `node src/recordar.js --resumen` una
vez al día (Programador de tareas de Windows o `cron`).
3. Prueba sin enviar nada: `npm run recordar -- --prueba`.
Qué recibes:
- ⏰ Un aviso **24 h** y otro **3 h** antes de cada entrega pendiente (`RECORDAR_HORAS=24,3`).
- 📝 Aviso cuando publican una **calificación o retroalimentación**.
- 📚 Un **resumen diario** con lo que vence en la semana.
Ya entregaste algo → deja de avisarte (Moodle ya no lo marca como pendiente).
Privacidad: los avisos (nombre de la tarea y curso) pasan por el servidor de ntfy. Si prefieres,
usa tu propio servidor con `NTFY_SERVER` y `NTFY_TOKEN`.
## Variables de entorno
| Variable | Uso |
|---|---|
| `MOODLE_URL`, `MOODLE_TOKEN` | Obligatorias |
| `MOODLE_TZ` | Zona horaria para fechas (por defecto la del sistema) |
| `MOODLE_DESCARGAS` | Carpeta para archivos descargados (por defecto `~/Downloads/moodle-student-bridge`) |
| `NTFY_TOPIC`, `NTFY_SERVER`, `NTFY_TOKEN` | Recordatorios |
| `RECORDAR_HORAS`, `INTERVALO_MIN` | Cuándo avisar (por defecto `24,3` y `60`) |
Las variables de entorno tienen prioridad sobre el `.env`.
## Seguridad
- El token da acceso a tu cuenta casi como tu contraseña. **No subas el `.env`** (está en
`.gitignore` y `.mcpbignore`) ni lo pegues en chats.
- Para revocarlo: Moodle → Preferencias → **Claves de seguridad** → restablecer la del servicio móvil.
- `leer_archivo` solo descarga archivos del Moodle configurado.
## Desarrollo
```bash
npm test # tests (sin red)
npm run probar -- ver_tarea '{"tarea":"proyecto"}' # llama una herramienta contra tu Moodle
npm run mcpb # genera moodle-student-bridge.mcpb para Claude Desktop
```
Licencia MIT.
TDQS
Scored across 14 tools
Most tools target distinct resources, but there's semantic overlap among the deadline-oriented tools: proximos_vencimientos, resumen_semanal, listar_tareas, and cuestionarios all surface upcoming dates, and an agent could hesitate over which to call. Mensajes vs notificaciones also mildly overlap since forum/message alerts appear in both. Descriptions largely clarify the intended use (resumen_semanal for 'what's pending', proximos_vencimientos for reminders), keeping it above average.
There is a partial convention (ver_* for detail views like ver_tarea/ver_curso/ver_discusion, listar_* for listings like listar_cursos/listar_tareas), but several tools are bare nouns (mensajes, anuncios, calificaciones, notificaciones, cuestionarios) and others are phrase-like (quien_soy, proximos_vencimientos, resumen_semanal). It's readable but mixes noun-only and verb_noun styles without a strict pattern.
14 tools sit comfortably in the well-scoped range for a learning-platform bridge, covering messaging, forums, courses, assignments, quizzes, grades, files, and notifications. Each tool maps to a recognizable Moodle feature, and none feels like filler.
The read surface is broad: courses, content, assignments, quizzes, forums, messages, grades, notifications, files, deadlines, and profile all have coverage, plus an aggregate summary. Gaps are mostly intentional read-only limits (no assignment submission, no posting/reply, notifications are not marked read), which agents can note but not work around.