utn-mcp 0.8.3 → 0.9.1

package/build/shared/logger.d.ts

@@ -0,0 +1,5 @@
+export declare const logger: {
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+};

package/build/shared/pages.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Página mínima con el estilo del sitio del proyecto: se abre desde el celu, así que nada más que lo necesario.
+ * `kicker` es la etiqueta chica arriba del título.
+ */
+export declare function page(title: string, body: string, kicker?: string): string;
+export declare const escapeHtml: (s: string) => string;

package/build/shared/paths.d.ts

@@ -0,0 +1,10 @@
+/** Carpeta de configuración: UTN_MCP_HOME, %APPDATA% en Windows, o XDG/~/.config en Linux y macOS. */
+export declare function configDir(): string;
+/** Token de Moodle del modo local. */
+export declare const sessionFile: () => string;
+/** Base de usuarios, tokens y sesiones del modo HTTP: UTN_MCP_DB o un SQLite en la carpeta de configuración. */
+export declare const storeFile: () => string;
+/** Clave con la que se cifran las sesiones en la base, si no viene en UTN_MCP_KEY. */
+export declare const storeKeyFile: () => string;
+/** Dónde quedan los archivos que arma el servidor (packs de estudio): UTN_MCP_EXPORTS o exports/ en la configuración. */
+export declare function exportsDir(): string;

package/build/shared/store/session-store.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Dónde viven los usuarios del modo HTTP, sus tokens y sus sesiones en cada plataforma. El servidor
+ * MCP lee (y guarda la sesión cuando la renueva); los usuarios y tokens los crea otro proceso: el
+ * login por OAuth de la versión hosteada o `utn-mcp login --http` en local.
+ */
+export interface SessionStore {
+    /**
+     * Id del usuario con ese nombre en esa regional; lo crea si no existe. Con `email`, se lo actualiza.
+     * Dos regionales pueden tener el mismo nombre de usuario para personas distintas.
+     */
+    findOrCreateUser(regional: string, utnUsername: string, email?: string): Promise<number>;
+    findUser(userId: number): Promise<StoredUser | null>;
+    findUserByEmail(email: string): Promise<StoredUser | null>;
+    /** Todos los usuarios, los más nuevos primero. */
+    listUsers(): Promise<ListedUser[]>;
+    /**
+     * Emite un token para el usuario y devuelve el valor en claro: se muestra una sola vez, en la base
+     * queda solo el hash. Sin `ttlSeconds` no vence (el token fijo del modo local).
+     */
+    issueToken(userId: number, options: {
+        kind: TokenKind;
+        clientId?: string;
+        ttlSeconds?: number;
+    }): Promise<string>;
+    /** El token si es de ese tipo y está vigente; si no, null. */
+    findToken(token: string, kind: TokenKind): Promise<IssuedToken | null>;
+    revokeToken(token: string): Promise<void>;
+    /** La sesión del usuario en una plataforma, tal como la guardó: cada plataforma decide su forma. */
+    loadSession(userId: number, platform: string): Promise<string | null>;
+    saveSession(userId: number, platform: string, data: string): Promise<void>;
+    /** Cuándo se guardó por última vez la sesión, en segundos desde epoch; null si no hay. */
+    sessionUpdatedAt(userId: number, platform: string): Promise<number | null>;
+    /** Las regionales que alguien ya usó en este servidor sin que estuvieran verificadas en el catálogo. */
+    listVerifiedRegionals(): Promise<string[]>;
+    /** true si esta llamada la verificó: nadie lo había hecho antes. */
+    markRegionalVerified(regional: string): Promise<boolean>;
+    /** Clientes OAuth registrados por registro dinámico (RFC 7591). */
+    saveClient(client: RegisteredClient): Promise<void>;
+    findClient(clientId: string): Promise<RegisteredClient | null>;
+    /** Los clientes que todavía tienen un token vigente del usuario: las apps que tiene conectadas. */
+    listConnectedClients(userId: number): Promise<ConnectedClient[]>;
+    /** Borra todos los tokens del usuario para ese cliente: la app queda desconectada. */
+    revokeClient(userId: number, clientId: string): Promise<void>;
+}
+export interface ConnectedClient {
+    clientId: string;
+    /** El que mandó la app al registrarse; null para el token fijo de `utn-mcp login --http`. */
+    clientName: string | null;
+    /** Cuándo se emitió su token más nuevo, en segundos desde epoch: los refresh rotan con el uso. */
+    lastTokenAt: number;
+}
+export interface StoredUser {
+    id: number;
+    /** El id de su regional (`frba`, `frt`...): su aula y, junto con el nombre, su identidad. */
+    regional: string;
+    utnUsername: string;
+    /** El institucional, el que se usa para decidir el acceso; null en usuarios de antes de guardarlo. */
+    email: string | null;
+}
+export interface ListedUser extends StoredUser {
+    /** Cuándo entró por primera vez, en segundos desde epoch. */
+    createdAt: number;
+}
+/** Un cliente público: no tiene secreto, se autentica con PKCE. */
+export interface RegisteredClient {
+    clientId: string;
+    clientName: string | null;
+    redirectUris: string[];
+}
+/** `access` va en cada request al MCP; `refresh` solo sirve para pedir un `access` nuevo. */
+export type TokenKind = "access" | "refresh";
+export interface IssuedToken {
+    userId: number;
+    clientId: string | null;
+    /** En segundos desde epoch; null si no vence. */
+    expiresAt: number | null;
+}

package/build/shared/store/sqlite-store.d.ts

@@ -0,0 +1,36 @@
+import type { ConnectedClient, IssuedToken, ListedUser, RegisteredClient, SessionStore, StoredUser, TokenKind } from "./session-store.js";
+/**
+ * El SessionStore sobre SQLite. Las sesiones van cifradas con AES-256-GCM: tienen el token de Moodle,
+ * que alcanza para entrar al aula como el usuario. Los tokens se guardan
+ * hasheados, así que una copia de la base no sirve para usar el servidor.
+ */
+export declare class SqliteStore implements SessionStore {
+    private readonly db;
+    private readonly key;
+    private constructor();
+    /** `node:sqlite` llega con Node 22.13; se importa acá para que el modo STDIO siga andando en Node 20. */
+    static open(path?: string): Promise<SqliteStore>;
+    findOrCreateUser(regional: string, utnUsername: string, email?: string): Promise<number>;
+    findUserByEmail(email: string): Promise<StoredUser | null>;
+    listUsers(): Promise<ListedUser[]>;
+    findUser(userId: number): Promise<StoredUser | null>;
+    issueToken(userId: number, options: {
+        kind: TokenKind;
+        clientId?: string;
+        ttlSeconds?: number;
+    }): Promise<string>;
+    findToken(token: string, kind: TokenKind): Promise<IssuedToken | null>;
+    revokeToken(token: string): Promise<void>;
+    loadSession(userId: number, platform: string): Promise<string | null>;
+    saveSession(userId: number, platform: string, data: string): Promise<void>;
+    listVerifiedRegionals(): Promise<string[]>;
+    markRegionalVerified(regional: string): Promise<boolean>;
+    saveClient(client: RegisteredClient): Promise<void>;
+    findClient(clientId: string): Promise<RegisteredClient | null>;
+    sessionUpdatedAt(userId: number, platform: string): Promise<number | null>;
+    listConnectedClients(userId: number): Promise<ConnectedClient[]>;
+    revokeClient(userId: number, clientId: string): Promise<void>;
+    /** iv + tag + texto cifrado, en un solo blob. */
+    private encrypt;
+    private decrypt;
+}

package/build/shared/uploads.d.ts

@@ -0,0 +1,62 @@
+export interface UploadedFile {
+    name: string;
+    bytes: Uint8Array;
+}
+/** Lo que acepta una subida; lo pone la plataforma que la abre. */
+export interface UploadLimits {
+    maxFiles?: number;
+    /** Por archivo. */
+    maxBytes: number;
+    /** En minúscula y con punto (".pdf"); sin lista, cualquiera. */
+    extensions?: string[];
+}
+/**
+ * De dónde saca el servidor los archivos que el usuario quiere subir a una plataforma: en STDIO, del
+ * disco, que es el suyo; en HTTP, de una subida, porque el servidor puede estar en otra máquina.
+ * `owner` es el usuario de la request: una subida solo la puede usar quien la abrió.
+ */
+export type FileSource = {
+    local: true;
+} | {
+    local: false;
+    inbox: UploadInbox;
+    owner: string;
+};
+interface Upload {
+    owner: string;
+    title: string;
+    limits: UploadLimits;
+    /** null mientras no se subió nada. */
+    files: UploadedFile[] | null;
+    expiresAt: number;
+}
+/** Tope de una subida entera, en bytes: los archivos quedan en memoria hasta que se entregan. */
+export declare const MAX_UPLOAD_BYTES: number;
+/**
+ * Links de un solo uso para recibir archivos por HTTP: los sube el agente con `curl` si tiene
+ * terminal, o el usuario desde el navegador. Los archivos quedan en memoria hasta que una tool los
+ * toma o el link vence; si el servidor se reinicia, se pierden y hay que pedir otro link.
+ */
+export declare class UploadInbox {
+    private readonly baseUrl;
+    private readonly uploads;
+    constructor(baseUrl: string);
+    open(owner: string, title: string, limits: UploadLimits): {
+        id: string;
+        url: string;
+        expiresAt: string;
+    };
+    /** La subida para mostrar su formulario, o undefined si no existe o venció. */
+    get(id: string): Pick<Upload, "title" | "limits" | "files"> | undefined;
+    /** Guarda los archivos de una subida; cada link acepta una sola. */
+    receive(id: string, files: UploadedFile[]): void;
+    /** Los archivos que se subieron, para entregarlos. No los borra: si la entrega falla, se reintenta. */
+    take(id: string, owner: string): UploadedFile[];
+    close(id: string): void;
+    private sweep;
+}
+/** Cantidad, tamaño, tipo y nombres repetidos, que Moodle no acepta. */
+export declare function checkFiles(files: UploadedFile[], limits: UploadLimits): void;
+/** Tamaño para personas: en KB por debajo del mega, para que un archivo chico no diga "0.0 MB". */
+export declare const formatSize: (bytes: number) => string;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "utn-mcp",
-  "version": "0.8.3",
+  "version": "0.9.1",
   "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": {
@@ -55,5 +55,12 @@
   },
   "engines": {
     "node": ">=20"
+  },
+  "exports": {
+    ".": "./build/index.js",
+    "./autogestion": {
+      "types": "./build/autogestion/client/connector.d.ts",
+      "default": "./build/autogestion/client/connector.js"
+    }
   }
 }