Moodle ITESCAM MCP
README.md
# Moodle ITESCAM MCP
Servidor [MCP](https://modelcontextprotocol.io/) que permite a un asistente de IA (Claude Code,
Claude Desktop, Codex u otro cliente MCP) consultar tu cuenta de estudiante en
[Moodle ITESCAM](https://moodle.itescam.edu.mx/moodle4/): cursos, contenidos, tareas, fechas
límite, calificaciones, calendario y avisos.
Usa la API oficial de Moodle (Web Services, el mismo servicio de la app móvil). No lee HTML, no
guarda tu contraseña. Las consultas son de lectura; la entrega de archivos requiere confirmación
explícita en un cliente MCP compatible con elicitation.
## Requisitos
- Node.js **24** o superior y npm
- Una cuenta de estudiante de Moodle ITESCAM
## Instalación
```bash
git clone https://github.com/Jack-SparrowQ/Mod-MCP.git moodle-itescam-mcp
cd moodle-itescam-mcp
npm install
npm run build
```
> En PowerShell de Windows, si `npm` falla con "running scripts is disabled", usa `npm.cmd`.
## Obtener tu token
El servidor se autentica con un **token** de Moodle, nunca con tu contraseña.
```bash
npm run token
```
Te pide usuario y contraseña (la contraseña no se muestra al escribirla), obtiene el token y lo
guarda en `.env` como `MOODLE_TOKEN`. El token no se imprime en pantalla y la contraseña no se
guarda en ningún sitio.
- `.env` está en `.gitignore`: nunca lo subas al repositorio.
- El token aparece en Moodle en **Preferencias → Claves de seguridad** (servicio
`moodle_mobile_app`). Desde ahí puedes revocarlo en cualquier momento.
- Para "cerrar sesión": revoca la clave en Moodle y borra la línea `MOODLE_TOKEN` de `.env`.
Variables de `.env` (plantilla en `.env.example`):
| Variable | Obligatoria | Valor por defecto |
| ----------------- | ----------- | ----------------------------------------------------- |
| `MOODLE_TOKEN` | sí | — (lo escribe `npm run token`) |
| `MOODLE_BASE_URL` | no | `https://moodle.itescam.edu.mx/moodle4/` (solo HTTPS) |
| `LOG_LEVEL` | no | `info` (`silent`, `error`, `warn`, `debug`…) |
| `MAX_DOWNLOAD_MB` | no | `50` (entero de 1 a 500; límite por archivo) |
El servidor carga el `.env` de la carpeta del proyecto aunque el cliente MCP lo lance desde otra
carpeta.
## Conectar un cliente MCP
Usa la ruta absoluta a `dist/index.js` de tu copia del proyecto.
**Claude Code**
```bash
claude mcp add --transport stdio moodle-itescam -- node /ruta/a/moodle-itescam-mcp/dist/index.js
```
**Codex**
```bash
codex mcp add moodle-itescam -- node /ruta/a/moodle-itescam-mcp/dist/index.js
```
**Claude Desktop** — en `claude_desktop_config.json`:
```json
{
"mcpServers": {
"moodle-itescam": {
"command": "node",
"args": ["/ruta/a/moodle-itescam-mcp/dist/index.js"]
}
}
}
```
Reinicia el cliente y pídele: _"Comprueba mi conexión con Moodle"_ (usa `moodle_auth_status`).
## Herramientas
Las herramientas actúan únicamente sobre tu cuenta: ninguna acepta un id de usuario.
`moodle_submit_assignment` es la única que escribe en Moodle y siempre requiere confirmación.
Las fechas se devuelven en ISO 8601 (UTC).
| Herramienta | Entradas | Devuelve |
| ------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------- |
| `moodle_auth_status` | — | si el token es válido y la versión del sitio |
| `moodle_get_profile` | — | tu nombre, usuario, correo y URL de perfil |
| `moodle_get_courses` | `query?`, `courseId?` | tus cursos; `query` ignora mayúsculas y acentos |
| `moodle_get_course_contents` | `courseId` | secciones y actividades (archivos: solo metadatos) |
| `moodle_get_assignments` | `courseId?`, `dueAfter?`, `dueBefore?`, `limit?` (50, máx. 200) | tareas; primero las próximas |
| `moodle_get_assignment` | `assignmentId` | instrucciones, estado de tu entrega, si está vencida y su nota |
| `moodle_get_upcoming_deadlines` | `days?` (14, máx. 60), `includeOverdue?` (sí) | lo que aún tienes pendiente, incluidas las vencidas |
| `moodle_get_calendar_events` | `from?`, `to?` (7 días, máx. 92), `courseId?` | eventos del calendario |
| `moodle_get_grades` | `courseId?` | resumen por curso, o elementos y total de un curso |
| `moodle_get_announcements` | `courseId?`, `limit?` (10, máx. 50) | avisos de los foros de noticias |
| `moodle_download_resource` | `courseId`, `moduleId`, `filename?`, `filepath?` | ruta local y metadatos de un archivo del curso |
| `moodle_submit_assignment` | `assignmentId`, `files` (1–20 nombres relativos) | entrega verificada, tras confirmación en el cliente |
Las descargas se guardan en `downloads/<courseId>/` dentro del proyecto, con un límite de 50 MB
por archivo (configurable con `MAX_DOWNLOAD_MB`). Los archivos existentes nunca se sobrescriben;
se añade un sufijo al nombre. En carpetas se descarga un archivo por petición.
### Entregar una tarea
Coloca los archivos en `submissions/` dentro del proyecto (carpeta ignorada por Git), por ejemplo
`submissions/practica/informe.pdf`. Pasa `practica/informe.pdf` en `files`, junto al `assignmentId`
obtenido con `moodle_get_assignments`. No se aceptan rutas absolutas ni archivos fuera de esa
carpeta, enlaces simbólicos, archivos vacíos o duplicados.
El cliente mostrará un formulario de confirmación con curso, tarea, archivos y tamaños, fecha
límite y avisos de entrega tardía o reemplazo de borradores. Debes confirmar y, si corresponde,
aceptar la declaración de autoría. La IA no puede responder ese formulario. Sin un cliente con
elicitation de formularios (Claude Code; Codex también la declara), no se sube ni entrega nada.
Codex en modo no interactivo (`codex exec`) rechaza la confirmación automáticamente y además
bloquea las herramientas que no son de solo lectura, así que nunca puede entregar sin ti. Solo se informa éxito
cuando Moodle devuelve el estado `submitted`; las escrituras no se reintentan automáticamente. Si
los archivos llegaron a guardarse como borrador pero la entrega no se confirmó, el error lo indica
(`draftSaved: true`): revisa la tarea en Moodle antes de reintentar.
Ejemplos de peticiones: _"¿Qué tareas tengo pendientes esta semana?"_, _"Muéstrame mis
calificaciones de Redes"_, _"¿Qué hay en la sección 3 de Sistemas Operativos?"_.
### Errores
Las herramientas devuelven `{ error: { code, message, suggestion } }` con estos códigos:
| Código | Qué hacer |
| ----------------------------------- | ------------------------------------------------------ |
| `AUTH_REQUIRED` / `SESSION_EXPIRED` | falta el token o fue revocado: ejecuta `npm run token` |
| `RESOURCE_NOT_FOUND` | no estás inscrito en ese curso o no existe esa tarea |
| `PERMISSION_DENIED` | Moodle no te permite ver eso |
| `MOODLE_UNAVAILABLE` | Moodle no responde; inténtalo más tarde |
| `VALIDATION_ERROR` | parámetros inválidos (p. ej. `from` posterior a `to`) |
| `INTEGRATION_UNSUPPORTED` | el servicio web de Moodle no está disponible |
| `OPERATION_FAILED` | Moodle devolvió algo inesperado |
## Privacidad y seguridad
- La IA nunca ve tu contraseña ni el token. Sí ve los datos académicos que le pidas (nombre,
correo, notas…), porque ese es el propósito de la herramienta.
- Los logs van a stderr y solo registran la función de Moodle llamada, la duración y el resultado:
sin parámetros, datos personales ni token.
- Solo se pueden llamar 12 funciones de lectura de Moodle (lista explícita en
`src/infrastructure/moodle/rest-client.ts`). Las dos funciones de entrega tienen una vía de
escritura separada, usada únicamente después de la confirmación. No hay funciones de profesor.
- No se devuelven enlaces de descarga de archivos.
- **Efecto de Moodle al consultar el estado de una tarea:** la primera vez que se consulta una tarea
abierta (`moodle_get_assignment`, o las comprobaciones previas de `moodle_submit_assignment`),
Moodle crea un registro de entrega vacío con estado `new`, igual que al abrir la tarea en el
navegador. No contiene archivos, no es una entrega y no afecta a la calificación.
## Limitaciones actuales
- Entregas: solo archivos, sin texto en línea, reenvíos ni entregas de grupo. Requiere un cliente
con elicitation de formularios; una tarea ya entregada se rechaza.
- Avisos: solo la primera página de cada foro de noticias.
- Fechas límite y calendario: como máximo 200 elementos por consulta (`truncated: true` si hay más).
- Probado contra Moodle ITESCAM 4.1.1+. Otras instalaciones de Moodle pueden funcionar si
tienen habilitado el servicio móvil, pero no están verificadas.
## Desarrollo
```bash
npm run typecheck # tsc --noEmit
npm test # Vitest; la red real está bloqueada en los tests
npm run dev # servidor con tsx (sin compilar)
```
Arquitectura: `docs/architecture.md`. Requisitos: `docs/requirements.md`. Hallazgos sobre Moodle
ITESCAM: `docs/moodle-investigation.md`. Decisiones: `docs/decisions/`.
## Licencia
ISC — ver [`LICENSE`](LICENSE).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues