utn-mcp 0.1.0 → 0.2.1

package/README.md

@@ -1,56 +1,134 @@
-# UTN-MCP — El puente entre tu agente y los sistemas de la Universidad.
-Este es el Model Context Protocol server NO OFICIAL de la UTN. Con él podrás pedirle a tu agente de preferencia (ChatGPT, Claude, etc.) que busque informacion o archivos en el aula virtual.
-
-## Features
-Actualmente solamente tiene dos tools, aula_get_site_info() y aula_list_courses(). Ya se incorporarán más!
-
-## Cómo instalar
-Necesitás [Node.js](https://nodejs.org) 20 o superior. No hace falta clonar el repo ni instalar nada a mano: `npx` descarga el paquete solo.
-
-### 1. Iniciar sesión
-```bash
-npx -y utn-mcp login
-```
-Te pide tu usuario institucional y tu contraseña de la UTN (los mismos de "Usuarios Institucionales" en el aula virtual). Se hace una sola vez: después el servidor renueva la sesión solo.
-
-### 2. Agregarlo a tu cliente
-
-**Claude Code**
-```bash
-claude mcp add utn -- npx -y utn-mcp
-```
-
-**Claude Desktop**: en *Settings → Developer → Edit Config*, agregá dentro de `mcpServers`:
-```json
-"utn": {
-  "command": "npx",
-  "args": ["-y", "utn-mcp"]
-}
-```
-En Windows, si no arranca, usá `"command": "cmd"` y `"args": ["/c", "npx", "-y", "utn-mcp"]`. Después reiniciá Claude Desktop por completo.
-
-**Otros clientes (Cursor, VS Code, etc.)**: cualquier cliente MCP que lance servidores por STDIO sirve con el comando `npx -y utn-mcp`.
-
-### Instalación global (opcional)
-Si preferís tener el comando `utn-mcp` siempre disponible:
-```bash
-npm i -g utn-mcp
-utn-mcp login
-```
-y en la config del cliente usás `"command": "utn-mcp"` sin argumentos.
-
-### Modo HTTP (opcional)
-```bash
-npx -y utn-mcp --http --port 3000
-```
-Levanta el servidor en `http://127.0.0.1:3000/mcp`, solo accesible desde tu propia máquina. Tenés que dejar la terminal abierta mientras lo uses.
-
-## Dónde se guardan tus datos
-Todo queda en tu computadora:
-- **Usuario y contraseña**: en el gestor de credenciales del sistema (Windows Credential Manager, Keychain en macOS, Secret Service en Linux).
-- **Token del aula virtual y cookies de sesión**: en `%APPDATA%\utn-mcp\session.json` (Windows) o `~/.config/utn-mcp/session.json` (Linux y macOS).
-
-En Linux sin gestor de credenciales (servidores, Docker, WSL) podés definir las variables de entorno `UTN_USER` y `UTN_PASS` en lugar de usar `login`.
-
-## Aviso
-Este proyecto no está afiliado ni avalado por la UTN. Usalo bajo tu responsabilidad.
+# UTN-MCP — El puente entre tu agente y los sistemas de la Universidad.
+Este es el Model Context Protocol server NO OFICIAL de la UTN. Con él podrás pedirle a tu agente de preferencia (ChatGPT, Claude, etc.) que busque informacion o archivos en el aula virtual.
+
+## Qué podés pedirle
+- *"¿Cuándo es el recuperatorio del primer parcial de Álgebra?"*
+- *"¿Qué avisó la profesora de Física esta semana?"*
+- *"Resumime la guía de la unidad 3 de Sistemas Operativos."*
+- *"Pasame el link para bajar el apunte de calorimetría."*
+
+El agente recorre el aula como lo harías vos: entra al curso, mira los foros y abre los archivos que hagan falta.
+
+## Tools
+| Tool | Qué hace |
+|---|---|
+| `aula_list_courses` | Lista tus cursos. Es el punto de partida. |
+| `aula_open` | Entra a un curso, un módulo, un foro o una discusión. Cada respuesta trae las direcciones de lo que hay adentro y de un nivel más arriba, así el agente navega sin perderse. |
+| `aula_read_file` | Lee un archivo del aula, por partes cuando es largo. |
+| `aula_get_site_info` | Datos de tu usuario en el aula virtual. |
+
+### Archivos que puede leer
+- **PDF**: el texto, página por página. Los **escaneados** se mandan como imagen de cada página, y el agente los lee igual.
+- **Word (.docx), PowerPoint (.pptx) y Excel (.xlsx)**: el texto, con las tablas fila por fila.
+- **Imágenes** (PNG, JPG, GIF) y texto plano.
+
+Los formatos viejos de Office (.doc, .ppt, .pps), los comprimidos (.zip, .rar) y los videos no se leen. En ese caso el agente te pasa el link para que lo bajes.
+
+### Links de descarga
+Cada archivo viene con un link del aula virtual que podés abrir en tu navegador. Funciona con tu sesión del aula (si no estás logueado te manda al login) y **nunca incluye tu token**: ese queda siempre en tu computadora.
+
+## Cómo instalar
+Necesitás [Node.js](https://nodejs.org) 20 o superior. No hace falta clonar el repo ni instalar nada a mano: `npx` descarga el paquete solo.
+
+### 1. Iniciar sesión
+```bash
+npx -y utn-mcp login
+```
+Te pide tu usuario institucional y tu contraseña de la UTN (los mismos de "Usuarios Institucionales" en el aula virtual). Se hace una sola vez: después el servidor renueva la sesión solo.
+
+### 2. Agregarlo a tu cliente
+
+**Claude Code**
+```bash
+claude mcp add utn -- npx -y utn-mcp
+```
+
+**Claude Desktop**: en *Settings → Developer → Edit Config*, agregá dentro de `mcpServers`:
+```json
+"utn": {
+  "command": "npx",
+  "args": ["-y", "utn-mcp"]
+}
+```
+En Windows, si no arranca, usá `"command": "cmd"` y `"args": ["/c", "npx", "-y", "utn-mcp"]`. Después reiniciá Claude Desktop por completo.
+
+**Codex**
+```bash
+codex mcp add utn -- npx -y utn-mcp
+```
+
+**Gemini CLI**
+```bash
+gemini mcp add utn npx -y utn-mcp
+```
+
+**OpenClaw**
+```bash
+openclaw mcp add utn --command npx --arg -y --arg utn-mcp
+```
+
+**Hermes**: en `~/.hermes/config.yaml`:
+```yaml
+mcp_servers:
+  utn:
+    command: "npx"
+    args: ["-y", "utn-mcp"]
+```
+
+**Cursor**: en `~/.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "utn": { "command": "npx", "args": ["-y", "utn-mcp"] }
+  }
+}
+```
+
+**VS Code**: en `.vscode/mcp.json` (o con *MCP: Add Server* desde la paleta de comandos):
+```json
+{
+  "servers": {
+    "utn": { "type": "stdio", "command": "npx", "args": ["-y", "utn-mcp"] }
+  }
+}
+```
+
+**ChatGPT**: todavía no. ChatGPT sólo se conecta a servidores MCP remotos por HTTPS, y utn-mcp corre en tu computadora. Va a funcionar con la versión hosteada.
+
+**Otros clientes (Windsurf, opencode, etc.)**: cualquier cliente MCP que lance servidores por STDIO sirve con el comando `npx -y utn-mcp`.
+
+### Instalación global (opcional)
+Si preferís tener el comando `utn-mcp` siempre disponible:
+```bash
+npm i -g utn-mcp
+utn-mcp login
+```
+y en la config del cliente usás `"command": "utn-mcp"` sin argumentos.
+
+### Modo HTTP (opcional)
+```bash
+npx -y utn-mcp --http --port 3000
+```
+Levanta el servidor en `http://127.0.0.1:3000/mcp`, solo accesible desde tu propia máquina. Tenés que dejar la terminal abierta mientras lo uses.
+
+## Dónde se guardan tus datos
+Todo queda en tu computadora:
+- **Usuario y contraseña**: en el gestor de credenciales del sistema (Windows Credential Manager, Keychain en macOS, Secret Service en Linux).
+- **Token del aula virtual y cookies de sesión**: en `%APPDATA%\utn-mcp\session.json` (Windows) o `~/.config/utn-mcp/session.json` (Linux y macOS).
+
+En Linux sin gestor de credenciales (servidores, Docker, WSL) podés definir las variables de entorno `UTN_USER` y `UTN_PASS` en lugar de usar `login`.
+
+## Desarrollo
+```bash
+git clone https://github.com/nialvape/utn-mcp.git
+cd utn-mcp
+npm install
+npm run login   # una vez
+npm run dev     # servidor por STDIO desde src/, con tsx
+npm run build   # compila a build/
+```
+
+pdf.js no es una dependencia del paquete publicado. Está como `devDependency`, y `npm install` corre el script `prepare`, que copia a `vendor/pdfjs/` solo los archivos que usa el servidor (~4 MB). Así, quien instala `utn-mcp` no baja pdf.js entero ni su canvas nativo opcional (~37 MB). Si instalaste con `--ignore-scripts`, generalo a mano con `npm run prepare`.
+
+## Aviso
+Este proyecto no está afiliado ni avalado por la UTN. Usalo bajo tu responsabilidad.

package/build/aula-virtual/address.js

@@ -0,0 +1,39 @@
+export const RAIZ = "/";
+export const cursoAddr = (courseId) => `/curso/${courseId}`;
+export const moduloAddr = (courseId, cmid) => `/curso/${courseId}/mod/${cmid}`;
+export const discusionAddr = (courseId, cmid, discussionId) => `/curso/${courseId}/mod/${cmid}/disc/${discussionId}`;
+const FORMATOS = [
+    "/",
+    "/curso/{courseId}",
+    "/curso/{courseId}/mod/{cmid}",
+    "/curso/{courseId}/mod/{cmid}/disc/{discussionId}",
+].join(", ");
+const PATRON = /^\/curso\/(\d+)(?:\/mod\/(\d+)(?:\/disc\/(\d+))?)?$/;
+export function parseAddress(raw) {
+    const path = raw.trim().replace(/\/+$/, "") || "/";
+    if (path === "/")
+        return { nivel: "raiz" };
+    const m = PATRON.exec(path);
+    if (!m)
+        throw new Error(`Dirección inválida: "${raw}". Formatos válidos: ${FORMATOS}`);
+    const [, curso, cmid, disc] = m;
+    const courseId = Number(curso);
+    if (!cmid)
+        return { nivel: "curso", courseId };
+    if (!disc)
+        return { nivel: "modulo", courseId, cmid: Number(cmid) };
+    return { nivel: "discusion", courseId, cmid: Number(cmid), discussionId: Number(disc) };
+}
+/** La dirección de un nivel más arriba, o null si ya estamos en la raíz. */
+export function padre(address) {
+    switch (address.nivel) {
+        case "raiz":
+            return null;
+        case "curso":
+            return RAIZ;
+        case "modulo":
+            return cursoAddr(address.courseId);
+        case "discusion":
+            return moduloAddr(address.courseId, address.cmid);
+    }
+}

package/build/aula-virtual/client/client.js

@@ -2,15 +2,33 @@ import { callWs } from "./moodle-api.js";
 export function getSiteInfo(session) {
     return callWs(session, "core_webservice_get_site_info");
 }
-export async function listCourses(session) {
+export async function getUserCourses(session) {
     const { userid } = await getSiteInfo(session);
-    const courses = await callWs(session, "core_enrol_get_users_courses", { userid });
-    return courses.map((c) => ({
-        id: c.id,
-        nombre: c.fullname,
-        nombreCorto: c.shortname,
-        visible: c.visible === 1,
-        progreso: c.progress ?? null,
-        ultimoAcceso: c.lastaccess ? new Date(c.lastaccess * 1000).toISOString() : null,
-    }));
+    return callWs(session, "core_enrol_get_users_courses", { userid });
+}
+/**
+ * Secciones del curso con sus módulos. Con `cmid` Moodle devuelve igual todas las secciones
+ * pero solo popula el módulo pedido, así que no hay que traerse el curso entero para abrir una cosa.
+ */
+export function getCourseSections(session, courseId, cmid) {
+    const params = { courseid: courseId };
+    if (cmid !== undefined) {
+        params["options[0][name]"] = "cmid";
+        params["options[0][value]"] = cmid;
+    }
+    return callWs(session, "core_course_get_contents", params);
+}
+// --- Foros ---
+/** Cuántas discusiones trae una página del índice de un foro. */
+export const POR_PAGINA = 50;
+/**
+ * Discusiones de un foro, las más recientes primero. Moodle manda el mensaje completo de la
+ * primera publicación de cada una; el que lee decide si lo recorta.
+ */
+export function getForumDiscussions(session, forumid, page = 0) {
+    return callWs(session, "mod_forum_get_forum_discussions", { forumid, page, perpage: POR_PAGINA });
+}
+/** Publicaciones de una discusión, incluidas las respuestas. */
+export function getDiscussionPosts(session, discussionid) {
+    return callWs(session, "mod_forum_get_discussion_posts", { discussionid });
 }

package/build/aula-virtual/client/moodle-api.js

@@ -30,3 +30,56 @@ export async function callWs(session, wsfunction, params = {}) {
         throw new MoodleError(data.message ?? data.exception, data.errorcode);
     }
 }
+/**
+ * Baja un archivo de `webservice/pluginfile.php` con el token; lo renueva una vez si venció.
+ * Los errores llegan como JSON (`{ error, errorcode }`) en lugar del archivo.
+ */
+export async function fetchFile(session, url, maxBytes) {
+    let token = await session.getToken();
+    for (let attempt = 0;; attempt++) {
+        const conToken = new URL(url);
+        conToken.searchParams.set("token", token);
+        let res;
+        try {
+            res = await fetch(conToken, { signal: AbortSignal.timeout(60_000) });
+        }
+        catch (e) {
+            throw new MoodleError(`No se pudo bajar el archivo: ${e.message}`);
+        }
+        const contentType = res.headers.get("content-type");
+        if (contentType?.startsWith("application/json")) {
+            const data = (await res.json());
+            if (attempt === 0 && data.errorcode && TOKEN_ERRORS.has(data.errorcode)) {
+                token = await session.refreshToken();
+                continue;
+            }
+            throw new MoodleError(data.error ?? `HTTP ${res.status}`, data.errorcode);
+        }
+        if (!res.ok || !res.body)
+            throw new MoodleError(`HTTP ${res.status} al bajar el archivo`);
+        return { bytes: await leerConLimite(res, maxBytes), contentType };
+    }
+}
+/** Lee el cuerpo cortando apenas pasa el límite, sin esperar a bajarlo entero. */
+async function leerConLimite(res, maxBytes) {
+    const limite = `El archivo pesa más de ${Math.round(maxBytes / 1024 / 1024)} MB; es demasiado para leerlo.`;
+    if (Number(res.headers.get("content-length")) > maxBytes) {
+        await res.body?.cancel();
+        throw new MoodleError(limite);
+    }
+    const partes = [];
+    let total = 0;
+    for await (const parte of res.body) {
+        total += parte.length;
+        if (total > maxBytes)
+            throw new MoodleError(limite);
+        partes.push(parte);
+    }
+    const bytes = new Uint8Array(total);
+    let i = 0;
+    for (const p of partes) {
+        bytes.set(p, i);
+        i += p.length;
+    }
+    return bytes;
+}

package/build/aula-virtual/files.js

@@ -0,0 +1,89 @@
+import { abrirDocumento, FormatoNoSoportado } from "../shared/documents/index.js";
+import { AULA_BASE_URL } from "./client/constants.js";
+import { fetchFile } from "./client/moodle-api.js";
+const ORIGEN = new URL(AULA_BASE_URL).origin;
+const RUTA_WS = "/webservice/pluginfile.php/";
+const RUTA_WEB = "/pluginfile.php/";
+/** Cuánto se devuelve por llamada, en caracteres de texto. */
+const PRESUPUESTO = 30_000;
+/** Lo que cuesta una página como imagen (~1.600 tokens), medido en caracteres de texto. */
+const COSTO_IMAGEN = 6_000;
+/** El más grande que hay hoy en los cursos pesa 12 MB. */
+const MAX_BYTES = 30 * 1024 * 1024;
+/**
+ * Moodle devuelve las URLs del web service, que piden token. Al usuario le sirve la misma ruta sin
+ * `/webservice`, que se abre con la sesión de su navegador. Es la única que mostramos: el token no
+ * sale nunca del servidor.
+ */
+export function urlParaUsuario(fileurl) {
+    return fileurl.replace(`${ORIGEN}${RUTA_WS}`, `${ORIGEN}${RUTA_WEB}`);
+}
+/**
+ * Acepta cualquiera de las dos formas y devuelve la del web service. Solo archivos del aula: con
+ * cualquier otra URL estaríamos mandando el token del usuario a donde diga el modelo.
+ */
+function urlDeDescarga(url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        throw new Error(`URL inválida: "${url}". Usá la \`url\` de un archivo tal como la devuelve aula_open.`);
+    }
+    const ruta = u.pathname.startsWith(RUTA_WS) ? u.pathname : u.pathname.startsWith(RUTA_WEB) ? RUTA_WS + u.pathname.slice(RUTA_WEB.length) : null;
+    if (u.origin !== ORIGEN || !ruta) {
+        throw new Error(`Solo se pueden leer archivos del aula virtual (${ORIGEN}${RUTA_WEB}...).`);
+    }
+    u.pathname = ruta;
+    u.searchParams.delete("token");
+    u.searchParams.delete("wstoken");
+    return u;
+}
+/** Baja un archivo del aula y devuelve desde la parte `desde` tantas como entren en el presupuesto. */
+export async function leerArchivo(session, url, desde = 1) {
+    const descarga = urlDeDescarga(url);
+    const archivo = decodeURIComponent(descarga.pathname.split("/").pop() ?? "");
+    const paraUsuario = urlParaUsuario(descarga.href);
+    const { bytes } = await fetchFile(session, descarga, MAX_BYTES);
+    let documento;
+    try {
+        documento = await abrirDocumento(bytes, archivo);
+    }
+    catch (e) {
+        if (e instanceof FormatoNoSoportado) {
+            throw new Error(`${e.message} El usuario lo puede bajar desde ${paraUsuario}`);
+        }
+        throw e;
+    }
+    try {
+        if (desde > documento.total) {
+            throw new Error(`"${archivo}" termina en ${documento.unidad} ${documento.total}; se pidió desde ${desde}.`);
+        }
+        const partes = [];
+        let gastado = 0;
+        let n = desde;
+        for (; n <= documento.total; n++) {
+            const parte = await documento.parte(n);
+            const costo = "texto" in parte ? parte.texto.length : COSTO_IMAGEN;
+            // Siempre al menos una parte, aunque sola se pase del presupuesto.
+            if (partes.length > 0 && gastado + costo > PRESUPUESTO)
+                break;
+            partes.push({ ...parte, numero: n });
+            gastado += costo;
+        }
+        return {
+            archivo,
+            formato: documento.formato,
+            unidad: documento.unidad,
+            total: documento.total,
+            desde,
+            hasta: n - 1,
+            siguiente: n <= documento.total ? n : undefined,
+            urlParaUsuario: paraUsuario,
+            partes,
+        };
+    }
+    finally {
+        await documento.cerrar();
+    }
+}

package/build/aula-virtual/navigate.js

@@ -0,0 +1,144 @@
+import { htmlToSnippet, htmlToText } from "../shared/html.js";
+import { cursoAddr, discusionAddr, moduloAddr, padre, parseAddress, RAIZ } from "./address.js";
+import { getCourseSections, getDiscussionPosts, getForumDiscussions, getUserCourses, POR_PAGINA, } from "./client/client.js";
+import { urlParaUsuario } from "./files.js";
+const isoDate = (seconds) => (seconds ? new Date(seconds * 1000).toISOString() : null);
+/**
+ * Entra a una dirección del aula y devuelve su contenido, el padre y las direcciones de lo que hay
+ * adentro. Es el único lugar que decide qué ve el modelo y cuánto texto le cuesta.
+ */
+export async function open(session, direccion, pagina = 0) {
+    const address = parseAddress(direccion);
+    const base = { direccion: formatear(address), padre: padre(address) };
+    switch (address.nivel) {
+        case "raiz":
+            return { ...base, cursos: await verCursos(session) };
+        case "curso":
+            return { ...base, secciones: await verCurso(session, address.courseId) };
+        case "modulo":
+            return { ...base, ...(await verModulo(session, address, pagina)) };
+        case "discusion":
+            return { ...base, ...(await verDiscusion(session, address.discussionId)) };
+    }
+}
+function formatear(address) {
+    switch (address.nivel) {
+        case "raiz":
+            return RAIZ;
+        case "curso":
+            return cursoAddr(address.courseId);
+        case "modulo":
+            return moduloAddr(address.courseId, address.cmid);
+        case "discusion":
+            return discusionAddr(address.courseId, address.cmid, address.discussionId);
+    }
+}
+async function verCursos(session) {
+    const courses = await getUserCourses(session);
+    return courses.map((c) => ({
+        direccion: cursoAddr(c.id),
+        id: c.id,
+        nombre: c.fullname,
+        nombreCorto: c.shortname,
+        visible: c.visible === 1,
+        progreso: c.progress ?? null,
+        ultimoAcceso: isoDate(c.lastaccess),
+    }));
+}
+/** El mapa del curso: secciones y módulos, con las descripciones recortadas. */
+async function verCurso(session, courseId) {
+    const sections = await getCourseSections(session, courseId);
+    return sections
+        .filter((s) => s.uservisible !== false)
+        .map((s) => ({
+        nombre: s.name,
+        numero: s.section,
+        resumen: htmlToText(s.summary) || undefined,
+        modulos: s.modules.filter((m) => m.uservisible).map((m) => toModule(m, courseId, true)),
+    }))
+        .filter((s) => s.resumen || s.modulos.length > 0);
+}
+async function verModulo(session, address, pagina) {
+    const { seccion, module } = await buscarModulo(session, address.courseId, address.cmid);
+    const modulo = toModule(module, address.courseId);
+    if (module.modname !== "forum")
+        return { seccion, modulo };
+    // Un foro es un índice: asuntos y un fragmento de cada uno. El mensaje completo sale al abrir la discusión.
+    const { discussions } = await getForumDiscussions(session, module.instance, pagina);
+    return {
+        seccion,
+        modulo,
+        discusiones: discussions.map((d) => ({
+            direccion: discusionAddr(address.courseId, address.cmid, d.discussion),
+            asunto: d.subject,
+            autor: d.userfullname,
+            fecha: isoDate(d.created),
+            ultimaActividad: isoDate(d.timemodified),
+            respuestas: d.numreplies,
+            fijada: d.pinned || undefined,
+            adjuntos: d.attachment || undefined,
+            resumen: htmlToSnippet(d.message),
+        })),
+        pagina,
+        hayMasDiscusiones: discussions.length === POR_PAGINA || undefined,
+    };
+}
+async function verDiscusion(session, discussionId) {
+    const { posts } = await getDiscussionPosts(session, discussionId);
+    const visibles = posts.filter((p) => !p.isdeleted);
+    return {
+        asunto: visibles[0]?.subject,
+        publicaciones: visibles.map((p) => ({
+            autor: p.author.fullname,
+            fecha: isoDate(p.timecreated),
+            respuestaA: p.parentid ?? undefined,
+            id: p.id,
+            mensaje: htmlToText(p.message),
+            adjuntos: p.attachments.length ? p.attachments.map(toFile) : undefined,
+        })),
+    };
+}
+/** Ubica un módulo por su cmid y se queda con la sección que lo contiene. */
+async function buscarModulo(session, courseId, cmid) {
+    const sections = await getCourseSections(session, courseId, cmid);
+    for (const section of sections) {
+        const module = section.modules.find((m) => m.id === cmid);
+        if (!module)
+            continue;
+        if (!module.uservisible)
+            throw new Error(`No tenés acceso al módulo ${cmid}.`);
+        return { seccion: section.name, module };
+    }
+    throw new Error(`No existe el módulo ${cmid} en el curso ${courseId}.`);
+}
+/** `resumido` recorta la descripción: en el mapa del curso alcanza para decidir si entrar. */
+function toModule(m, courseId, resumido = false) {
+    const contents = m.contents ?? [];
+    const archivos = contents.filter((c) => c.type === "file");
+    const enlaces = contents.filter((c) => c.type === "url");
+    return {
+        direccion: moduloAddr(courseId, m.id),
+        id: m.id,
+        nombre: m.name,
+        tipo: m.modname,
+        url: m.url,
+        descripcion: (resumido ? htmlToSnippet(m.description) : htmlToText(m.description)) || undefined,
+        restriccion: htmlToText(m.availabilityinfo) || undefined,
+        fechas: m.dates?.length
+            ? m.dates.map((d) => ({ etiqueta: d.label, fecha: isoDate(d.timestamp) }))
+            : undefined,
+        archivos: archivos.length ? archivos.map(toFile) : undefined,
+        enlaces: enlaces.length ? enlaces.map((l) => l.fileurl) : undefined,
+    };
+}
+function toFile(f) {
+    return {
+        nombre: f.filename,
+        ruta: f.filepath || undefined,
+        tamanio: f.filesize,
+        mimetype: f.mimetype,
+        modificado: isoDate(f.timemodified),
+        // Sirve para pasársela al usuario y también para leerlo con aula_read_file.
+        url: urlParaUsuario(f.fileurl),
+    };
+}

package/build/aula-virtual/tools.js

@@ -1,6 +1,11 @@
-import { getSiteInfo, listCourses } from "./client/client.js";
+import * as z from "zod";
+import { getSiteInfo } from "./client/client.js";
+import { RAIZ } from "./address.js";
+import { leerArchivo } from "./files.js";
+import { open } from "./navigate.js";
+// JSON compacto: indentar estas respuestas cuesta ~25% más de contexto y no se lee mejor.
 const json = (data) => ({
-    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    content: [{ type: "text", text: JSON.stringify(data) }],
 });
 const failure = (e) => ({
     content: [{ type: "text", text: `Error: ${e.message}` }],
@@ -16,9 +21,86 @@ export function registerAulaVirtualTools(server, session) {
             return failure(e);
         }
     });
-    server.registerTool("aula_list_courses", { description: "Lista los cursos (materias) en los que está inscripto el usuario en el aula virtual." }, async () => {
+    server.registerTool("aula_list_courses", {
+        description: "Lista los cursos (materias) en los que está inscripto el usuario. Es el punto de entrada: " +
+            "cada curso viene con su `direccion`, que se le pasa a aula_open para entrar.",
+    }, async () => {
         try {
-            return json(await listCourses(session));
+            return json(await open(session, RAIZ));
+        }
+        catch (e) {
+            return failure(e);
+        }
+    });
+    server.registerTool("aula_open", {
+        description: "Entra a una dirección del aula virtual y devuelve lo que hay ahí: un curso con sus secciones " +
+            "y módulos, un módulo con sus archivos y fechas, un foro con el índice de sus discusiones, o " +
+            "una discusión con sus mensajes completos.\n\n" +
+            "No hace falta armar la dirección: cada respuesta trae las direcciones de lo que hay adentro " +
+            "(`direccion`) y la de un nivel más arriba (`padre`), así que se navega pasando de vuelta una " +
+            "de esas. Para empezar, usar aula_list_courses o la dirección \"/\".\n\n" +
+            "Buscar algo que puede estar en cualquier parte (una fecha de parcial, un aviso) se hace " +
+            "entrando al curso y abriendo lo que corresponda: el índice de un foro muestra los asuntos sin " +
+            "volcar los mensajes enteros, y archivos como un cronograma se leen con aula_read_file.\n\n" +
+            "Los archivos vienen con una `url`, que sirve para leerlos con aula_read_file y también para " +
+            "dársela al usuario si quiere bajarlo: se abre con su sesión del aula.",
+        inputSchema: z.object({
+            direccion: z
+                .string()
+                .describe('Dirección a abrir, sacada de una respuesta anterior. Ej: "/", "/curso/691", ' +
+                '"/curso/691/mod/34806", "/curso/691/mod/34806/disc/421348".'),
+            pagina: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Solo para foros: página del índice de discusiones, de 50 en 50. La respuesta avisa " +
+                "con `hayMasDiscusiones` cuando hay otra."),
+        }),
+    }, async ({ direccion, pagina }) => {
+        try {
+            return json(await open(session, direccion, pagina));
+        }
+        catch (e) {
+            return failure(e);
+        }
+    });
+    server.registerTool("aula_read_file", {
+        description: "Lee un archivo del aula virtual: PDF, Word (docx), PowerPoint (pptx), Excel (xlsx), imágenes y " +
+            "texto. Los PDF escaneados se devuelven como imagen de cada página.\n\n" +
+            "Devuelve el archivo por partes (páginas, diapositivas o fragmentos), tantas como entren en una " +
+            "respuesta. Si quedan más, `siguiente` dice desde cuál pedir; también se puede saltar directo " +
+            "a una parte con `desde`.\n\n" +
+            "Formatos que no sabe leer (.doc, .ppt viejos, .zip, .rar, videos): devuelve un error con la URL " +
+            "para que el usuario lo baje.",
+        inputSchema: z.object({
+            url: z.string().describe("La `url` del archivo tal como la devuelve aula_open."),
+            desde: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe("Número de página, diapositiva o fragmento desde el cual leer. Por defecto, 1."),
+        }),
+    }, async ({ url, desde }) => {
+        try {
+            const { partes, ...lectura } = await leerArchivo(session, url, desde);
+            const etiqueta = (n, titulo) => `--- ${lectura.unidad} ${n} de ${lectura.total}${titulo ? ` (${titulo})` : ""} ---`;
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(lectura) },
+                    ...partes.flatMap((p) => "texto" in p
+                        ? [{ type: "text", text: `${etiqueta(p.numero, p.titulo)}\n${p.texto}` }]
+                        : [
+                            { type: "text", text: etiqueta(p.numero, p.titulo) },
+                            {
+                                type: "image",
+                                data: Buffer.from(p.imagen).toString("base64"),
+                                mimeType: p.mimeType,
+                            },
+                        ]),
+                ],
+            };
         }
         catch (e) {
             return failure(e);