# tuaulavirtual-unam-mcp

Servidor [MCP](https://modelcontextprotocol.io) para el aula virtual Moodle de la UNAM
(`tuaulavirtual.educatic.unam.mx`). Permite que Claude Code, Claude Desktop, Cursor
o cualquier cliente MCP consulte tus cursos, tareas, fechas de entrega, descargue
materiales y, si se lo pides, entregue tareas por ti.

Usa la API REST oficial de Moodle (servicio `moodle_mobile_app`) y, como respaldo,
una sesión web para leer páginas que la API no cubre.

## Requisitos

- [uv](https://docs.astral.sh/uv/) instalado. En macOS: `brew install uv`.
  En cualquier sistema: `curl -LsSf https://astral.sh/uv/install.sh | sh`.
- Tu usuario y contraseña del aula virtual.

## Instalación en 2 pasos

**1. Guarda tus credenciales** (se piden de forma interactiva y quedan en
`~/.config/tuaulavirtual-unam-mcp/.env` con permisos solo para tu usuario):

```bash
uvx --from git+https://github.com/AlanMagno1/tuaulavirtual-unam-mcp tuaulavirtual-unam-mcp setup
```

**2. Registra el servidor en Claude Code:**

```bash
claude mcp add tuaulavirtual-unam -s user -- uvx --from git+https://github.com/AlanMagno1/tuaulavirtual-unam-mcp tuaulavirtual-unam-mcp
```

Listo. Abre Claude Code y pídele, por ejemplo:

> ¿Qué tareas tengo pendientes?

> Revisa https://tuaulavirtual.educatic.unam.mx/mod/assign/view.php?id=469144 y dime qué piden.

### Otros clientes (Claude Desktop, Cursor, etc.)

Agrega esto a la configuración JSON de servidores MCP del cliente:

```json
{
  "mcpServers": {
    "tuaulavirtual-unam": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/AlanMagno1/tuaulavirtual-unam-mcp", "tuaulavirtual-unam-mcp"]
    }
  }
}
```

### Variables de entorno (alternativa al archivo de configuración)

| Variable | Descripción |
|---|---|
| `MOODLE_URL` | URL del Moodle. Default: `https://tuaulavirtual.educatic.unam.mx` |
| `MOODLE_USERNAME` | Usuario del aula virtual |
| `MOODLE_PASSWORD` | Contraseña |
| `MOODLE_DOWNLOAD_DIR` | Carpeta de descargas. Default: `~/Downloads/tuaulavirtual-unam-mcp` |
| `TUAULAVIRTUAL_MCP_CONFIG_DIR` | Carpeta de configuración. Default: `~/.config/tuaulavirtual-unam-mcp` |

Las variables de entorno tienen prioridad sobre el archivo `.env`. Funciona con
cualquier Moodle que tenga habilitado el servicio móvil, cambiando `MOODLE_URL`.

### Otros Moodle de la UNAM (CUAED, idiomas, etc.)

El mismo servidor sirve para cualquier Moodle con el servicio móvil habilitado. Al
correr `setup`, escribe la URL del Moodle en la primera pregunta en vez de aceptar
la default. URLs verificadas:

| Aula | URL para `setup` |
|---|---|
| Tu Aula Virtual (default) | `https://tuaulavirtual.educatic.unam.mx` |
| Aulas Virtuales CUAED | `https://aulasvirtuales.cuaed.unam.mx/moodle` |
| Ambiente Virtual de Idiomas | `https://avicursos.cuaed.unam.mx/moodle` |

Ojo: `aulas-virtuales.cuaed.unam.mx` (con guion) es solo el portal informativo; el
Moodle de CUAED está en la URL de la tabla. En CUAED el login web está desactivado,
así que la herramienta `fetch_page` no funciona ahí; las demás sí.

### Dos o más aulas a la vez

Cada aula necesita su propia carpeta de configuración y su propio nombre de servidor.
`setup` avisa si vas a sobrescribir una configuración existente. Ejemplo para agregar
CUAED junto a Tu Aula Virtual:

```bash
# 1. Credenciales de CUAED en una carpeta aparte
TUAULAVIRTUAL_MCP_CONFIG_DIR=~/.config/cuaed-mcp \
  uvx --from git+https://github.com/AlanMagno1/tuaulavirtual-unam-mcp tuaulavirtual-unam-mcp setup

# 2. Segundo servidor en Claude Code
claude mcp add cuaed-unam -s user -e TUAULAVIRTUAL_MCP_CONFIG_DIR=$HOME/.config/cuaed-mcp -- \
  uvx --from git+https://github.com/AlanMagno1/tuaulavirtual-unam-mcp tuaulavirtual-unam-mcp
```

Claude verá las herramientas de ambos servidores con prefijos distintos y elegirá el
correcto según el aula o la URL que menciones.

## Herramientas

| Herramienta | Qué hace |
|---|---|
| `get_site_info` | Verifica la conexión y devuelve el usuario autenticado. |
| `list_courses` | Cursos en los que estás inscrito. |
| `get_course_contents(course_id)` | Secciones y módulos de un curso, con fechas y archivos. |
| `get_assignment(cmid_or_url)` | Detalle de una tarea: instrucciones, fechas, adjuntos y estado de tu entrega. Acepta la URL completa `.../mod/assign/view.php?id=NNN`. |
| `download_file(fileurl, filename?)` | Descarga un archivo a `~/Downloads/tuaulavirtual-unam-mcp/` y devuelve la ruta local. |
| `fetch_page(url)` | Inicia sesión por web y devuelve el texto de cualquier página del aula. |
| `upload_file(path)` | Sube un archivo local al área de borradores; devuelve `itemid`. |
| `submit_assignment(cmid_or_url, online_text?, files_itemid?, submit_for_grading?)` | Guarda una entrega (texto en línea y/o archivos) y opcionalmente la envía para calificación. |

## Comandos

```bash
tuaulavirtual-unam-mcp setup   # captura credenciales y prueba la conexión
tuaulavirtual-unam-mcp check   # imprime el usuario autenticado
tuaulavirtual-unam-mcp         # arranca el servidor MCP por stdio (lo usa el cliente)
```

## Seguridad

- Tus credenciales nunca salen de tu máquina: solo se envían a la URL del Moodle
  configurada, para obtener un token del servicio móvil.
- El token se guarda en `~/.config/tuaulavirtual-unam-mcp/token.json` (permisos 600) y se renueva
  automáticamente si Moodle lo invalida.
- `submit_assignment` entrega tareas en tu nombre. Claude solo debe usarla cuando se
  lo pidas explícitamente.

## Desarrollo

```bash
git clone https://github.com/AlanMagno1/tuaulavirtual-unam-mcp
cd tuaulavirtual-unam-mcp
uv sync
uv run tuaulavirtual-unam-mcp check
```

Para probar cambios locales en Claude Code sin publicar:

```bash
claude mcp add tuaulavirtual-unam -s user -- uv --directory /ruta/a/tuaulavirtual-unam-mcp run tuaulavirtual-unam-mcp
```

## Licencia

MIT