utn-mcp 0.8.2 → 0.8.3

package/README.md

@@ -19,6 +19,7 @@ El agente recorre el aula como lo harías vos: entra al curso, mira los foros y
 | `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_study_pack` | Une en un solo PDF con índice los apuntes que elijas de una materia (un 'machacado'), guardado en tu compu. Solo en modo local. |
 | `aula_get_site_info` | Datos de tu usuario y de tu regional en el aula virtual. |
 | `aula_forum_post` | Abre un hilo en un foro o responde en una discusión. |
 | `aula_forum_edit_post` | Edita una publicación tuya. |
@@ -160,9 +161,10 @@ La configuración va en variables de entorno o en un `.env` en la carpeta desde
 | `UTN_MCP_ACCESS_URL`, `UTN_MCP_ACCESS_SECRET` | Servicio que decide quién puede entrar. | — |
 | `UTN_MCP_ALLOWED_EMAILS` | Emails o dominios (`@frba.utn.edu.ar`) habilitados, separados por coma, si no hay `UTN_MCP_ACCESS_URL`. | Entra cualquiera con usuario de la UTN |
 | `UTN_MCP_REDIRECT_ALLOW` | Hosts (`app.ejemplo.com`) o esquemas (`miapp:`) extra, separados por coma, a los que puede volver el login de OAuth. Loopback, Claude, ChatGPT, VS Code y Cursor pasan siempre. Cualquier otro host HTTPS (un agente propio, por ejemplo) se acepta, pero el login avisa a dónde vuelve y el alumno tiene que marcar que lo conecta bajo su responsabilidad: es la defensa contra alguien que use tu página de login para quedarse con su sesión. Los hosts de esta lista pasan sin aviso. | — |
-| `UTN_MCP_ADMIN_SECRET` | Habilita la API de `/admin` para un panel de cuentas tuyo: `POST /admin/usuarios` (todos los usuarios con sus apps), `/admin/clientes` y `/admin/clientes/revocar` (las apps de un usuario, por email), `/admin/regionales` (las regionales con su soporte) y `/admin/verificar` (entra al aula con usuario y contraseña, como el login de OAuth, y le guarda la sesión). | — |
+| `UTN_MCP_ADMIN_SECRET` | Habilita la API de `/admin` para un panel de cuentas tuyo: `POST /admin/usuarios` (todos los usuarios con sus apps), `/admin/clientes` y `/admin/clientes/revocar` (las apps de un usuario, por email), `/admin/regionales` (las regionales con su soporte) y `/admin/verificar` (entra al aula con usuario y contraseña, como el login de OAuth, y le guarda la sesión; si Microsoft pide segundo factor, devuelve el paso y se sigue con `/admin/segundo-factor`). | — |
 | `UTN_MCP_LOGIN_URL` | Página donde el usuario renueva su sesión del aula; el agente se la pasa. | `<UTN_MCP_PUBLIC_URL>/login` |
 | `UTN_MCP_DB`, `UTN_MCP_KEY` | Base de sesiones y su clave de cifrado (32 bytes en base64). | En la carpeta de config |
+| `UTN_MCP_PACK_MAX_FILES`, `UTN_MCP_PACK_MAX_MB`, `UTN_MCP_PACK_MAX_FINAL_MB` | Topes del compilado de estudio (`aula_study_pack`, solo modo local): archivos por pack, MB de descarga total y MB del PDF final, que se arma entero en memoria. | 150, 300 y 30 |
 
 Con Docker, detrás de un reverse proxy con HTTPS en la misma máquina (red host, para que el rate limit del login vea la IP real):
 ```bash

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

@@ -27,6 +27,27 @@ export function getCourseSections(session, courseId, cmid) {
     }
     return callWs(session, "core_course_get_contents", params);
 }
+/**
+ * Los archivos de las secciones y módulos visibles del curso, en el orden en que aparecen en el aula.
+ * Los mismos filtros de visibilidad que el mapa del curso de format/navigate.
+ */
+export async function getCourseFiles(session, courseId) {
+    const sections = await getCourseSections(session, courseId);
+    const entries = [];
+    for (const section of sections) {
+        if (section.uservisible === false)
+            continue;
+        for (const module of section.modules) {
+            if (!module.uservisible)
+                continue;
+            for (const content of module.contents ?? []) {
+                if (content.type === "file")
+                    entries.push({ section: section.name, module: module.name, file: content });
+            }
+        }
+    }
+    return entries;
+}
 // --- Foros ---
 /** Cuántas discusiones trae una página del índice de un foro. */
 export const PAGE_SIZE = 50;

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

@@ -34,23 +34,47 @@ export async function callWs(session, wsfunction, params = {}) {
 /**
  * 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.
+ * Los redirects se siguen a mano y SOLO al propio aula y a rutas de archivos (pluginfile):
+ * un pluginfile legítimo no redirige afuera, así que cualquier otro destino se rechaza.
  */
 export async function fetchFile(session, url, maxBytes) {
     let token = await session.getToken();
-    for (let attempt = 0;; attempt++) {
-        const withToken = new URL(url);
+    const { baseUrl } = await session.getRegional();
+    const aulaOrigin = new URL(baseUrl).origin;
+    let current = url;
+    let redirects = 0;
+    // Aparte de los redirects: uno antes del token vencido no tiene que gastar la renovación.
+    let refreshed = false;
+    for (;;) {
+        const withToken = new URL(current);
         withToken.searchParams.set("token", token);
         let res;
         try {
-            res = await fetch(withToken, { signal: AbortSignal.timeout(60_000) });
+            res = await fetch(withToken, { signal: AbortSignal.timeout(60_000), redirect: "manual" });
         }
         catch (e) {
             throw new MoodleError(`No se pudo bajar el archivo: ${e.message}`);
         }
+        if (res.status >= 300 && res.status < 400) {
+            const location = res.headers.get("location");
+            const next = location ? new URL(location, current) : null;
+            redirects++;
+            if (redirects > 3 ||
+                !next ||
+                next.username ||
+                next.password ||
+                next.origin !== aulaOrigin ||
+                !next.pathname.includes("pluginfile.php")) {
+                throw new MoodleError(`El aula redirigió la descarga a una dirección no permitida (${location ?? "sin destino"})`);
+            }
+            current = next;
+            continue;
+        }
         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)) {
+            if (!refreshed && data.errorcode && TOKEN_ERRORS.has(data.errorcode)) {
+                refreshed = true;
                 token = await session.refreshToken();
                 continue;
             }

package/build/aula-virtual/format/address.js

@@ -1,3 +1,14 @@
+/**
+ * Direcciones de navegación del aula: un path que el modelo recibe en una respuesta
+ * y devuelve tal cual para entrar ahí. No hay estado en el servidor; la dirección
+ * dice todo lo necesario, y el padre se deduce del texto (eso es el "volver").
+ */
+export const AddressLevel = {
+    Root: "root",
+    Course: "course",
+    Module: "module",
+    Discussion: "discussion",
+};
 export const ROOT = "/";
 export const courseAddr = (courseId) => `/curso/${courseId}`;
 export const moduleAddr = (courseId, cmid) => `/curso/${courseId}/mod/${cmid}`;

package/build/aula-virtual/format/files.js

@@ -7,7 +7,7 @@ const BUDGET_CHARS = 30_000;
 /** Lo que cuesta una página como imagen (~1.600 tokens), medido en caracteres de texto. */
 const IMAGE_COST_CHARS = 6_000;
 /** El más grande que hay hoy en los cursos pesa 12 MB. */
-const MAX_BYTES = 30 * 1024 * 1024;
+export 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
@@ -32,7 +32,7 @@ export function userFacingUrl(fileurl) {
  * Acepta cualquiera de las dos formas y devuelve la del web service. Solo archivos del aula del
  * usuario (`baseUrl`): con cualquier otra URL estaríamos mandando su token a donde diga el modelo.
  */
-function downloadUrl(baseUrl, url) {
+export function downloadUrl(baseUrl, url) {
     let u;
     try {
         u = new URL(url);

package/build/aula-virtual/format/study-pack.js

@@ -0,0 +1,199 @@
+import { createHash } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { mergePdfs } from "../../shared/documents/merge.js";
+import { exportsDir } from "../../shared/paths.js";
+import { getCourseFiles, getUserCourses } from "../client/client.js";
+import { parseAddress } from "./address.js";
+import { downloadUrl, MAX_BYTES } from "./files.js";
+import { fetchFile } from "../client/moodle-api.js";
+/**
+ * Topes de tamaño por pack: pdf-lib junta todo el resultado en memoria, así que sin tope total un
+ * curso enorme podría colgar la compu donde corre el servidor. Lo que queda afuera por un tope se
+ * lista en `omitidos` con el motivo, para pedir el resto en otro pack.
+ * Una variable de entorno con basura NO puede desactivar el tope: si no es un número válido,
+ * vuelve al default.
+ */
+const capFromEnv = (raw, fallback) => {
+    const n = Number(raw ?? fallback);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+};
+const MAX_PACK_FILES = capFromEnv(process.env.UTN_MCP_PACK_MAX_FILES, 150);
+const MAX_PACK_BYTES = capFromEnv(process.env.UTN_MCP_PACK_MAX_MB, 300) * 1024 * 1024;
+/** Máximo del PDF final: se estima con los tamaños de entrada para cortar antes de bajar todo. */
+const MAX_FINAL_MB = capFromEnv(process.env.UTN_MCP_PACK_MAX_FINAL_MB, 30);
+const MAX_FINAL_BYTES = MAX_FINAL_MB * 1024 * 1024;
+const isPdf = (e) => e.file.mimetype === "application/pdf" || e.file.filename.toLowerCase().endsWith(".pdf");
+/** Los caracteres que no sirven para un nombre de archivo se cambian por "-". */
+const safeFileName = (name) => name.replace(/[^\p{L}\p{N}._-]+/gu, "-").replace(/^-+|-+$/g, "");
+/**
+ * Escribe el pack sin pisar packs anteriores: nombre con fecha-hora y, si ya existe (dos packs
+ * en el mismo segundo), un sufijo -2, -3... La escritura es atómica por nombre (bandera "wx").
+ */
+export async function writePackFile(dir, courseName, bytes) {
+    const now = new Date();
+    const pad = (n) => String(n).padStart(2, "0");
+    const stamp = `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+    const base = join(dir, `${safeFileName(courseName)}-apuntes-${stamp}`);
+    for (let n = 1; n <= 100; n++) {
+        const candidate = n === 1 ? `${base}.pdf` : `${base}-${n}.pdf`;
+        try {
+            await writeFile(candidate, bytes, { flag: "wx" });
+            return candidate;
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+        }
+    }
+    throw new Error(`No se pudo guardar el pack: ya existen 100 archivos para "${base}".`);
+}
+/**
+ * Baja PDF de un curso y los une en un solo archivo con índice, guardado en exportsDir().
+ * Con `archivos` une solo las URL pedidas (tal como las devuelve aula_open, validadas con
+ * `downloadUrl` como en aula_read_file); sin `archivos`, todos los PDF del curso. El pack sigue
+ * el orden del aula, no el de la lista, para que el índice acompañe las unidades. Los duplicados
+ * exactos se descartan al armar, porque ahí se bajan igual. Todo lo omitido queda listado en
+ * `omitidos` con el motivo; en el atajo sin `archivos`, los archivos que no son PDF solo se
+ * cuentan en `archivosNoPdf` en vez de listarse uno por uno.
+ */
+export async function buildStudyPack(session, rawAddress, archivos) {
+    const address = parseAddress(rawAddress);
+    if (address.level !== "course") {
+        throw new Error(`Para armar el pack pasá la dirección de un curso entero ("/curso/{courseId}", de aula_list_courses), no "${rawAddress}".`);
+    }
+    const { baseUrl } = await session.getRegional();
+    const course = (await getUserCourses(session)).find((c) => c.id === address.courseId);
+    const entries = await getCourseFiles(session, address.courseId);
+    let selected;
+    const omitted = [];
+    if (archivos) {
+        // Cada URL pedida se valida igual que en aula_read_file: solo archivos del aula del usuario.
+        const requested = new Set(archivos.map((u) => downloadUrl(baseUrl, u).href));
+        const byUrl = new Map(entries.map((e) => [downloadUrl(baseUrl, e.file.fileurl).href, e]));
+        const unknown = [...requested].filter((u) => !byUrl.has(u));
+        if (unknown.length) {
+            throw new Error(`Estas URL no son de archivos del curso (salen de aula_open sobre "${rawAddress}"):\n` +
+                unknown.map((u) => `- ${u}`).join("\n"));
+        }
+        // El orden lo manda el aula, no la lista: el índice sigue las unidades.
+        selected = entries.filter((e) => requested.has(downloadUrl(baseUrl, e.file.fileurl).href));
+        for (const e of selected.filter((x) => !isPdf(x))) {
+            omitted.push({ nombre: e.file.filename, seccion: e.section, motivo: "no es un PDF" });
+        }
+    }
+    else {
+        selected = entries;
+    }
+    const pdfs = selected.filter(isPdf);
+    const archivosNoPdf = archivos ? 0 : selected.length - pdfs.length;
+    if (!pdfs.length) {
+        throw new Error(archivos
+            ? "Ninguna de las URL pedidas es un PDF: la tool une únicamente PDF."
+            : "El curso no tiene ningún PDF en sus secciones visibles.");
+    }
+    const capMotivo = `se alcanzó el tope del pack (${MAX_PACK_FILES} archivos / ${MAX_PACK_BYTES / 1024 / 1024} MB)`;
+    const inputs = [];
+    const kept = [];
+    const seen = new Map(); // hash -> nombre del primero con ese contenido
+    let totalBytes = 0;
+    let finalLleno = false;
+    for (const entry of pdfs) {
+        const name = entry.file.filename;
+        if (finalLleno) {
+            omitted.push({
+                nombre: name,
+                seccion: entry.section,
+                motivo: `el PDF final llegó al tope de ${MAX_FINAL_MB} MB (estimado con los tamaños de entrada)`,
+            });
+            continue;
+        }
+        if (inputs.length >= MAX_PACK_FILES || totalBytes + (entry.file.filesize ?? 0) > MAX_PACK_BYTES) {
+            omitted.push({ nombre: name, seccion: entry.section, motivo: capMotivo });
+            continue;
+        }
+        let bytes;
+        try {
+            bytes = (await fetchFile(session, downloadUrl(baseUrl, entry.file.fileurl), MAX_BYTES)).bytes;
+        }
+        catch (e) {
+            omitted.push({ nombre: name, seccion: entry.section, motivo: e.message });
+            continue;
+        }
+        const hash = createHash("sha256").update(bytes).digest("hex");
+        const original = seen.get(hash);
+        if (original) {
+            omitted.push({ nombre: name, seccion: entry.section, motivo: `es idéntico a "${original}"` });
+            continue;
+        }
+        // El tamaño real se conoce recién ahora (Moodle a veces no lo anuncia): tope post-descarga.
+        if (totalBytes + bytes.length > MAX_PACK_BYTES) {
+            omitted.push({ nombre: name, seccion: entry.section, motivo: capMotivo });
+            continue;
+        }
+        // Corte temprano del tope del PDF final, estimado con los tamaños de entrada: lo que ya
+        // no puede entrar no se baja de más ni tira abajo el pack entero al final.
+        if (totalBytes + bytes.length > MAX_FINAL_BYTES) {
+            finalLleno = true;
+            omitted.push({
+                nombre: name,
+                seccion: entry.section,
+                motivo: `el PDF final llegó al tope de ${MAX_FINAL_MB} MB (estimado con los tamaños de entrada)`,
+            });
+            continue;
+        }
+        seen.set(hash, name);
+        inputs.push({ title: name, bytes });
+        kept.push(entry);
+        totalBytes += bytes.length;
+    }
+    // En el índice va el módulo, que se lee mejor que el archivo; si el módulo aporta más de un
+    // archivo, también el archivo, para que las entradas no queden repetidas.
+    const perModule = new Map();
+    const moduleKey = (e) => `${e.section}\n${e.module}`;
+    for (const e of kept)
+        perModule.set(moduleKey(e), (perModule.get(moduleKey(e)) ?? 0) + 1);
+    kept.forEach((e, i) => {
+        inputs[i].title = perModule.get(moduleKey(e)) > 1 ? `${e.module}: ${e.file.filename}` : e.module;
+    });
+    const courseName = course?.shortname ?? `curso-${address.courseId}`;
+    const dir = exportsDir();
+    // La estimación puede quedar corta (el índice y los enlaces agregan páginas): si el unido
+    // supera el tope igual, salen los últimos materiales hasta que entre, en vez de tirar todo
+    // el trabajo de descarga.
+    let pack = await mergePdfs(inputs, `Apuntes de ${course?.fullname ?? courseName}`);
+    while (pack.bytes.length > MAX_FINAL_BYTES && inputs.length > 1) {
+        inputs.pop();
+        const entry = kept.pop();
+        omitted.push({
+            nombre: entry.file.filename,
+            seccion: entry.section,
+            motivo: `el PDF final superó el tope de ${MAX_FINAL_MB} MB al unir`,
+        });
+        pack = await mergePdfs(inputs, `Apuntes de ${course?.fullname ?? courseName}`);
+    }
+    if (pack.bytes.length > MAX_FINAL_BYTES) {
+        const mb = Math.round((pack.bytes.length / 1024 / 1024) * 10) / 10;
+        throw new Error(`El PDF final pesa ${mb} MB, más del máximo (${MAX_FINAL_MB} MB): no se guardó. ` +
+            "Pedí el pack con `archivos`, eligiendo solo los PDF que necesitás.");
+    }
+    for (const s of pack.skipped) {
+        omitted.push({ nombre: kept[s.index].file.filename, seccion: kept[s.index].section, motivo: s.reason });
+    }
+    await mkdir(dir, { recursive: true });
+    const path = await writePackFile(dir, courseName, pack.bytes);
+    return {
+        archivo: path,
+        curso: course?.fullname ?? courseName,
+        paginas: pack.pages,
+        materiales: pack.merged.map((m) => ({
+            nombre: kept[m.index].file.filename,
+            seccion: kept[m.index].section,
+            modulo: kept[m.index].module,
+            paginas: m.pages,
+            empiezaEn: m.startPage,
+        })),
+        omitidos: omitted.length ? omitted : undefined,
+        archivosNoPdf: archivosNoPdf || undefined,
+    };
+}

package/build/aula-virtual/tools.js

@@ -3,6 +3,7 @@ import { getSiteInfo } from "./client/client.js";
 import { addCalendarEvent, answerChoice, deleteForumPost, editForumPost, postToForum, sendMessage, } from "./format/actions.js";
 import { ROOT } from "./format/address.js";
 import { readAulaFile } from "./format/files.js";
+import { buildStudyPack } from "./format/study-pack.js";
 import { open } from "./format/navigate.js";
 import { createUploadLink, submitAssignment } from "./format/submission.js";
 // JSON compacto: indentar estas respuestas cuesta ~25% más de contexto y no se lee mejor.
@@ -125,6 +126,45 @@ export function registerAulaVirtualTools(server, session, files) {
             return failure(e);
         }
     });
+    // El pack se guarda en el disco: solo en STDIO, donde el servidor corre en la compu del usuario.
+    if (files.local) {
+        server.registerTool("aula_study_pack", {
+            description: "Une PDF del aula en un solo compilado de estudio con índice clickeable (cada " +
+                "entrada abre la página donde empieza ese material, y cada página tiene arriba " +
+                "un enlace para volver), guardado en la compu del usuario. Une ÚNICAMENTE PDF; " +
+                "si una URL pedida no es PDF, queda en `omitidos` con el motivo.\n\n" +
+                "Conviene llamar antes a aula_open del curso: devuelve cada módulo con sus " +
+                "archivos (nombre, url, sección y tipo) y permite elegir los apuntes sin bajar " +
+                "nada. Es un compilado íntegro, no un resumen.\n\n" +
+                "Hay topes por memoria: 150 archivos, 300 MB de descarga total y 30 MB el PDF " +
+                "final (estimado con los tamaños de entrada, para no bajar archivos de más). Lo " +
+                "que no entra queda en `omitidos` con el motivo: se pide el resto en otro pack. " +
+                "La respuesta trae la ruta en `archivo` y `materiales` con sección, módulo, " +
+                "páginas y página de inicio de cada uno.\n\n" +
+                "La `direccion` del curso sale de aula_list_courses. Para leer o pasarle al " +
+                "usuario archivos que no son PDF, usá aula_open y aula_read_file.",
+            inputSchema: z.object({
+                direccion: z
+                    .string()
+                    .describe('Dirección del curso, de aula_list_courses. Ej: "/curso/691".'),
+                archivos: z
+                    .array(z.string())
+                    .optional()
+                    .describe("URL de los PDF a unir, tal como las devuelve aula_open del curso (conviene " +
+                    "llamarlo antes y elegir: cada archivo trae nombre, sección y tipo). El pack " +
+                    "sigue el orden del aula, no el de esta lista. Sin `archivos`, une todos los " +
+                    "PDF del curso."),
+            }),
+            annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+        }, async ({ direccion, archivos }) => {
+            try {
+                return json(await buildStudyPack(session, direccion, archivos));
+            }
+            catch (e) {
+                return failure(e);
+            }
+        });
+    }
     // --- Escritura: lo que sigue cambia algo en el aula, y casi todo queda a la vista de otras personas. ---
     const CONFIRM_FIRST = "\n\nAntes de llamarla, mostrale al usuario exactamente lo que se va a hacer y esperá que confirme.";
     server.registerTool("aula_forum_post", {

package/build/oauth/admin.js

@@ -2,13 +2,16 @@ import { timingSafeEqual } from "node:crypto";
 import express from "express";
 import { linkAulaAccount } from "../aula-virtual/client/link.js";
 import { availableRegionals } from "../aula-virtual/client/regionals.js";
-import { InvalidCredentialsError, MfaError, MfaRequiredError } from "../aula-virtual/client/sso-login.js";
+import { InvalidCredentialsError, MfaError } from "../aula-virtual/client/sso-login.js";
 import { AULA_PLATFORM } from "../aula-virtual/client/stored-session.js";
 import { logger } from "../shared/logger.js";
-import { RateLimiter } from "./expiring.js";
+import { Expiring, RateLimiter } from "./expiring.js";
+import { PendingLogin } from "./pending-login.js";
 /** Intentos de `/admin/verificar` por cuenta del aula cada 15 minutos: que no sirva para probar contraseñas. */
 const VERIFY_ATTEMPTS = 5;
 const VERIFY_WINDOW_MS = 15 * 60_000;
+/** Cuánto tiene el usuario para completar el segundo factor, en milisegundos: lo mismo que en el login de OAuth. */
+const SECOND_FACTOR_TTL_MS = 10 * 60_000;
 const SUPPORT = { verified: "verificada", candidate: "candidata", unsupported: "sin_soporte" };
 /** Segundos desde epoch, como los guarda el store, a ISO. */
 const isoDate = (seconds) => new Date(seconds * 1000).toISOString();
@@ -20,6 +23,7 @@ const isoDate = (seconds) => new Date(seconds * 1000).toISOString();
 export function mountAdmin(app, store, secret) {
     const json = express.json({ limit: "4kb" });
     const verifyLimiter = new RateLimiter(VERIFY_ATTEMPTS, VERIFY_WINDOW_MS);
+    const secondFactors = new Expiring(SECOND_FACTOR_TTL_MS);
     const requireSecret = (req, res, next) => {
         const got = Buffer.from(req.headers.authorization ?? "");
         const want = Buffer.from(`Bearer ${secret}`);
@@ -79,6 +83,7 @@ export function mountAdmin(app, store, secret) {
      * `{ regional, usuario, contrasena }` → entra al aula como el login de OAuth: crea el usuario si no
      * existe y le guarda la sesión, así ya puede usar las tools. Devuelve `{ usuario, nombre, email,
      * primero? }`, con `primero` si fue el primero en verificar la regional; si no entra, `{ error, motivo }`.
+     * Si Microsoft pide MFA, devuelve `{ segundoFactor }` y el login sigue con `/admin/segundo-factor`.
      */
     app.post("/admin/verificar", requireSecret, json, async (req, res) => {
         const id = typeof req.body?.regional === "string" ? req.body.regional : "";
@@ -94,8 +99,33 @@ export function mountAdmin(app, store, secret) {
         if (!verifyLimiter.allow(`${regional.id}:${username.toLowerCase()}`)) {
             return void res.status(429).json({ error: "intentos", motivo: "Demasiados intentos. Esperá unos minutos." });
         }
+        const flow = new PendingLogin((secondFactor) => linkAulaAccount(store, regional, { username, password }, secondFactor));
+        await advance(res, { flow, regional, username });
+    });
+    /**
+     * `{ login, respuesta }` → contesta lo que pidió el segundo factor: el `id` del método, el código o
+     * cualquier cosa cuando el usuario ya aprobó. Devuelve lo mismo que `/admin/verificar`.
+     */
+    app.post("/admin/segundo-factor", requireSecret, json, async (req, res) => {
+        const id = typeof req.body?.login === "string" ? req.body.login : "";
+        const verification = id ? secondFactors.get(id) : undefined;
+        if (!verification) {
+            return void res.status(410).json({ error: "vencido", motivo: "Pasó demasiado tiempo. Volvé a iniciar sesión." });
+        }
+        verification.flow.answer(typeof req.body?.respuesta === "string" ? req.body.respuesta : "");
+        await advance(res, verification, id);
+    });
+    /** Sigue el login hasta que termina o pide el segundo factor; `id` es el de uno que ya estaba esperando. */
+    async function advance(res, verification, id) {
+        const { flow, regional, username } = verification;
         try {
-            const account = await linkAulaAccount(store, regional, { username, password });
+            const step = await flow.next();
+            if ("prompt" in step) {
+                return void res.json({ segundoFactor: secondFactorJson(id ?? secondFactors.add(verification), step.prompt) });
+            }
+            if (id)
+                secondFactors.take(id);
+            const account = step.done;
             logger.info(`Admin: ${account.username} (${regional.id}) vinculó su aula.`);
             res.json({
                 usuario: account.username,
@@ -105,17 +135,28 @@ export function mountAdmin(app, store, secret) {
             });
         }
         catch (e) {
+            if (id)
+                secondFactors.take(id);
             if (e instanceof InvalidCredentialsError) {
                 return void res.status(401).json({ error: "credenciales", motivo: "El aula rechazó el usuario o la contraseña." });
             }
-            if (e instanceof MfaRequiredError || e instanceof MfaError) {
-                return void res.status(422).json({
-                    error: "mfa",
-                    motivo: "La cuenta de Microsoft pide un segundo factor (MFA): que entre por la página de login.",
-                });
-            }
+            if (e instanceof MfaError)
+                return void res.status(422).json({ error: "mfa", motivo: e.message });
             logger.warn(`Verificación de ${username} (${regional.id}): ${e.message}`);
             res.status(502).json({ error: "aula", motivo: `No pudimos entrar al aula de ${regional.name}.` });
         }
-    });
+    }
+}
+/**
+ * Lo que pide el segundo factor, para que el panel se lo muestre al usuario. `login` es el id con el que
+ * se contesta; `paso` es "elegir" (con `metodos`), "codigo" (con `reintento` si el anterior estaba mal)
+ * o "aprobar" (con `numero` si Authenticator pide tipearlo).
+ */
+function secondFactorJson(login, prompt) {
+    if (prompt.step === "choose") {
+        return { login, paso: "elegir", metodos: prompt.methods.map((m) => ({ id: m.id, nombre: m.label })) };
+    }
+    if (prompt.step === "code")
+        return { login, paso: "codigo", metodo: prompt.method.label, reintento: prompt.retry || undefined };
+    return { login, paso: "aprobar", metodo: prompt.method.label, numero: prompt.number };
 }

package/build/server.js

@@ -7,7 +7,7 @@ import { registerAulaVirtualTools } from "./aula-virtual/tools.js";
 export function createServer(aula, files) {
     const server = new McpServer({
         name: "UTN-MCP",
-        version: "0.8.2",
+        version: "0.8.3",
     });
     registerAulaVirtualTools(server, aula, files);
     return server;

package/build/shared/documents/merge.js

@@ -0,0 +1,197 @@
+import { PDFArray, PDFDocument, PDFName, StandardFonts, degrees, rgb } from "pdf-lib";
+/** Filas del índice que entran en una página A4 con letra de 11pt. */
+const INDEX_ROWS_PER_PAGE = 40;
+/**
+ * Alto de la franja que se AGREGA arriba de cada página de contenido para el enlace de
+ * vuelta al índice: la página queda un poco más alta, así el enlace nunca tapa el material.
+ */
+const BACK_STRIP = 18;
+const BACK_LABEL = "Volver al índice";
+/**
+ * Agrega a `page` un enlace rectangular (anotación Link sin borde) que muestra `dest` entera.
+ */
+function addPageLink(out, page, rect, dest) {
+    const link = out.context.register(out.context.obj({
+        Type: "Annot",
+        Subtype: "Link",
+        Rect: rect,
+        Border: [0, 0, 0],
+        Dest: [dest.ref, "Fit"],
+    }));
+    let annots = page.node.lookupMaybe(PDFName.of("Annots"), PDFArray);
+    if (!annots) {
+        annots = out.context.obj([]);
+        page.node.set(PDFName.of("Annots"), annots);
+    }
+    annots.push(link);
+}
+/**
+ * Une PDFs en uno solo, con un índice clickeable al principio: cada entrada abre la página
+ * donde empieza ese material, y cada página de contenido tiene arriba un enlace "Volver al
+ * índice" (en una franja agregada, sin tapar nada). El que no se puede abrir (roto o con
+ * clave) se salta y queda en `skipped`: pdf-lib no desencripta, así que un PDF con clave
+ * entraría con páginas rotas. El índice se arma al final, cuando se sabe qué archivos
+ * entraron, y se inserta al frente.
+ */
+export async function mergePdfs(files, documentTitle) {
+    const out = await PDFDocument.create();
+    if (documentTitle)
+        out.setTitle(documentTitle);
+    const merged = [];
+    /** En qué página empieza cada uno sin contar el índice, que todavía no se sabe cuánto ocupa. */
+    const contentStarts = [];
+    const skipped = [];
+    for (let index = 0; index < files.length; index++) {
+        const file = files[index];
+        let src;
+        try {
+            // ignoreEncryption solo para que `load` no rechace el archivo: así lo listamos
+            // en `skipped` con el motivo en vez de romper todo el pack.
+            src = await PDFDocument.load(file.bytes, { ignoreEncryption: true });
+        }
+        catch {
+            skipped.push({ index, title: file.title, reason: "no se pudo abrir (está roto)" });
+            continue;
+        }
+        if (src.isEncrypted) {
+            skipped.push({ index, title: file.title, reason: "tiene clave" });
+            continue;
+        }
+        let pages;
+        try {
+            pages = await out.copyPages(src, src.getPageIndices());
+        }
+        catch {
+            // Abre bien pero tiene objetos que no se pueden copiar: se salta como los rotos.
+            skipped.push({ index, title: file.title, reason: "no se pudieron copiar sus páginas" });
+            continue;
+        }
+        if (!pages.length) {
+            skipped.push({ index, title: file.title, reason: "no tiene páginas" });
+            continue;
+        }
+        contentStarts.push(out.getPageCount() + 1);
+        for (const page of pages)
+            out.addPage(page);
+        merged.push({ index, title: file.title, pages: pages.length });
+    }
+    if (!merged.length)
+        throw new Error("No se pudo unir ninguno de los PDF.");
+    const indexPages = Math.ceil(merged.length / INDEX_ROWS_PER_PAGE);
+    const withStart = merged.map((m, i) => ({ ...m, startPage: contentStarts[i] + indexPages }));
+    const font = await out.embedFont(StandardFonts.Helvetica);
+    await writeIndex(out, withStart, indexPages, font);
+    addBackLinks(out, indexPages, font);
+    const bytes = await out.save();
+    return { bytes, pages: out.getPageCount(), merged: withStart, skipped };
+}
+/** Escribe las páginas del índice y las inserta al frente, con cada renglón enlazado a su material. */
+async function writeIndex(out, merged, indexPages, font) {
+    const bold = await out.embedFont(StandardFonts.HelveticaBold);
+    const pageSize = [595, 842]; // A4
+    const margin = 50;
+    const lineHeight = 16;
+    const pages = [];
+    for (let n = 0; n < indexPages; n++) {
+        const page = out.insertPage(n, pageSize);
+        page.drawText(winAnsi("Índice"), { x: margin, y: pageSize[1] - margin, size: 16, font: bold });
+        pages.push(page);
+    }
+    merged.forEach((row, i) => {
+        const page = pages[Math.floor(i / INDEX_ROWS_PER_PAGE)];
+        const y = pageSize[1] - margin - lineHeight * (2 + (i % INDEX_ROWS_PER_PAGE));
+        const pageNo = String(row.startPage);
+        page.drawText(pageNo, { x: margin + 30 - font.widthOfTextAtSize(pageNo, 11), y, size: 11, font });
+        page.drawText(truncate(winAnsi(row.title), font, 11, pageSize[0] - margin * 2 - 40), {
+            x: margin + 40,
+            y,
+            size: 11,
+            font,
+        });
+        addPageLink(out, page, [margin, y - 4, pageSize[0] - margin, y + 11], out.getPage(row.startPage - 1));
+    });
+}
+/**
+ * Agrega a cada página de contenido una franja vacía con "Volver al índice" enlazado a la
+ * primera página del índice. La franja AGRANDA la página por el borde que queda arriba al
+ * leerla (arriba sin rotación; a la izquierda, abajo o a la derecha según la rotación de la
+ * página) y el texto se dibuja ya rotado: se lee horizontal en cualquier orientación y, al
+ * ser espacio agregado, nunca tapa el material. Toda la franja es clickeable.
+ */
+function addBackLinks(out, indexPages, font) {
+    const firstIndexPage = out.getPage(0);
+    const size = 9;
+    const color = rgb(0.1, 0.3, 0.7);
+    const textWidth = font.widthOfTextAtSize(BACK_LABEL, size);
+    const total = out.getPageCount();
+    for (let i = indexPages; i < total; i++) {
+        const page = out.getPage(i);
+        // Los dos box se leen ANTES de escribir: sin CropBox propio, getCropBox devuelve el
+        // MediaBox, y leerlo después de agrandarlo agrandaría el CropBox dos veces.
+        const media = page.getMediaBox();
+        const crop = page.getCropBox();
+        const { x: X, y: Y, width: w, height: h } = media;
+        const rotation = (((page.getRotation().angle % 360) + 360) % 360);
+        // Posición del texto y dirección del subrayado según el borde por donde crece la página.
+        let textX, textY, lineStart, lineEnd;
+        let strip;
+        let rotate;
+        switch (rotation) {
+            case 90:
+                // Al leerla rotada 90° el borde izquierdo queda arriba: la franja crece a la izquierda.
+                page.setMediaBox(X - BACK_STRIP, Y, w + BACK_STRIP, h);
+                page.setCropBox(crop.x - BACK_STRIP, crop.y, crop.width + BACK_STRIP, crop.height);
+                strip = [X - BACK_STRIP, Y, X, Y + h];
+                rotate = degrees(90);
+                textX = X - BACK_STRIP + 5 + size;
+                textY = Y + h - 30 - textWidth;
+                lineStart = { x: textX + 1.5, y: textY };
+                lineEnd = { x: textX + 1.5, y: textY + textWidth };
+                break;
+            case 180:
+                page.setMediaBox(X, Y - BACK_STRIP, w, h + BACK_STRIP);
+                page.setCropBox(crop.x, crop.y - BACK_STRIP, crop.width, crop.height + BACK_STRIP);
+                strip = [X, Y - BACK_STRIP, X + w, Y];
+                rotate = degrees(180);
+                textX = X + 30 + textWidth;
+                textY = Y - BACK_STRIP + 5 + size;
+                lineStart = { x: textX, y: textY + 1.5 };
+                lineEnd = { x: textX - textWidth, y: textY + 1.5 };
+                break;
+            case 270:
+                page.setMediaBox(X, Y, w + BACK_STRIP, h);
+                page.setCropBox(crop.x, crop.y, crop.width + BACK_STRIP, crop.height);
+                strip = [X + w, Y, X + w + BACK_STRIP, Y + h];
+                rotate = degrees(270);
+                textX = X + w + BACK_STRIP - 5 - size;
+                textY = Y + 30 + textWidth;
+                lineStart = { x: textX - 1.5, y: textY };
+                lineEnd = { x: textX - 1.5, y: textY - textWidth };
+                break;
+            default:
+                page.setMediaBox(X, Y, w, h + BACK_STRIP);
+                page.setCropBox(crop.x, crop.y, crop.width, crop.height + BACK_STRIP);
+                strip = [X, Y + h, X + w, Y + h + BACK_STRIP];
+                rotate = degrees(0);
+                textX = X + w - 30 - textWidth;
+                textY = Y + h + 5;
+                lineStart = { x: textX, y: textY - 1.5 };
+                lineEnd = { x: textX + textWidth, y: textY - 1.5 };
+                break;
+        }
+        page.drawText(BACK_LABEL, { x: textX, y: textY, size, font, color, rotate });
+        page.drawLine({ start: lineStart, end: lineEnd, thickness: 0.5, color });
+        addPageLink(out, page, strip, firstIndexPage);
+    }
+}
+/** Lo que la letra base del PDF sabe dibujar (WinAnsi); lo demás se cambia por "?". */
+const winAnsi = (text) => text.replace(/[^\x20-\x7E\xA0-\xFF\u2013\u2014\u2018\u2019\u201C\u201D\u2022\u2026]/g, "?");
+/** Recorta el título para que entre en el renglón, con "…" si se cortó. */
+function truncate(text, font, size, maxWidth) {
+    if (font.widthOfTextAtSize(text, size) <= maxWidth)
+        return text;
+    let cut = text;
+    while (cut && font.widthOfTextAtSize(cut + "…", size) > maxWidth)
+        cut = cut.slice(0, -1);
+    return cut + "…";
+}

package/build/shared/paths.js

@@ -15,3 +15,7 @@ export const sessionFile = () => join(configDir(), "session.json");
 export const storeFile = () => process.env.UTN_MCP_DB ?? join(configDir(), "utn-mcp.db");
 /** Clave con la que se cifran las sesiones en la base, si no viene en UTN_MCP_KEY. */
 export const storeKeyFile = () => join(configDir(), "store.key");
+/** Dónde quedan los archivos que arma el servidor (packs de estudio): UTN_MCP_EXPORTS o exports/ en la configuración. */
+export function exportsDir() {
+    return process.env.UTN_MCP_EXPORTS ?? join(configDir(), "exports");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "utn-mcp",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Este es el Model Context Protocol server NO OFICIAL de la UTN para buscar informacion o archivos en el aula virtual.",
   "main": "build/index.js",
   "bin": {
@@ -42,6 +42,7 @@
     "@modelcontextprotocol/server": "^2.3.0",
     "@napi-rs/keyring": "^2.1.0",
     "express": "^5.2.1",
+    "pdf-lib": "^1.17.1",
     "tough-cookie": "^6.0.2",
     "zod": "^4.6.5"
   },