educa-navarra-mcp 1.0.0 → 1.1.0

package/README.md

@@ -12,7 +12,7 @@ Tú revisas y decides cuándo se guardan.
 [![Pruebas](https://github.com/vTanco/educa-navarra-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/vTanco/educa-navarra-mcp/actions/workflows/ci.yml)
 ![Mac · Windows · Linux](https://img.shields.io/badge/Mac%20·%20Windows%20·%20Linux-grey)
 
-[**⬇️ Descargar para Claude Desktop**](https://github.com/vTanco/educa-navarra-mcp/releases/latest/download/educa-navarra-mcp.mcpb) · [Cómo se usa](#-cómo-se-usa) · [Preguntas frecuentes](#-preguntas-frecuentes) · [Aviso legal](AVISO-LEGAL.md)
+[**⬇️ Descargar para Claude Desktop**](https://github.com/vTanco/educa-navarra-mcp/releases/latest/download/educa-navarra-mcp.mcpb) · [Cómo se usa](#-cómo-se-usa) · [Prepara tus Excel](docs/BUENAS-PRACTICAS.md) · [Preguntas frecuentes](#-preguntas-frecuentes) · [Aviso legal](AVISO-LEGAL.md)
 
 </div>
 
@@ -41,7 +41,8 @@ Pensado para **ESO** (IN · SU · BI · NT · SB), **Bachillerato** (nota sobre
 1. Instala [Claude Desktop](https://claude.ai/download) si no lo tienes.
 2. **[Descarga `educa-navarra-mcp.mcpb`](https://github.com/vTanco/educa-navarra-mcp/releases/latest/download/educa-navarra-mcp.mcpb)**.
 3. Haz **doble clic** en el fichero descargado. Claude Desktop se abre y te pregunta si quieres instalarlo: pulsa **Instalar**.
-4. Te pedirá tu **usuario y contraseña de Educa**. Son **opcionales**: si los pones, Claude entra solo en Educa; si los dejas vacíos, entras tú en la ventana que se abre. La contraseña se guarda cifrada en tu ordenador.
+4. Te pedirá tu **usuario y contraseña de Educa**. Son **opcionales**: si los pones, Claude entra solo en Educa; si los dejas vacíos, entras tú en la ventana que se abre. La contraseña se guarda cifrada en tu ordenador. También puedes indicar los **grupos en los que no pones notas** (por ejemplo, si compartes docencia): el conector se negará a escribir en ellos.
+5. Te preguntará también por tu **carpeta de notas**. Deja la que sale (*Documentos/Notas Educa*) y créala si no la tienes: ahí guardarás tus Excel.
 
 Y ya está. No hace falta instalar nada más: usa el **Google Chrome** o **Microsoft Edge** que ya tienes. Si no tienes ninguno, descarga un navegador la primera vez (tarda un par de minutos).
 
@@ -85,7 +86,19 @@ No compartas ese fichero ni lo subas a ningún sitio. También vale poner las va
 
 Escríbele a Claude con tus palabras. Por ejemplo:
 
-> *Mete las notas de la 1ª evaluación de 1º de Bachillerato A, TIC, desde el Excel `notas_1BA.xlsx` de mi Escritorio.*
+| Quieres… | Dile… |
+|---|---|
+| Meter notas | *"Mete las notas de la 1ª evaluación de BTO N 1ºA, TIC."* |
+| Cargar tus grupos (la primera vez) | *"Actualiza mis grupos."* |
+| Ir directo a un grupo | *"Abre las notas de 1ºAB de Tecnología, 2ª evaluación."* |
+| Ver qué ficheros tienes | *"¿Qué ficheros de notas tengo?"* |
+| Consultar sin tocar | *"Enséñame las notas que hay ahora en Educa de ESO 3ºDEFH, Matemáticas. No cambies nada."* |
+| Escribir tras la vista previa | *"Vale, escríbelas."* |
+| Guardar tras revisar en pantalla | *"Guarda."* |
+| Usar otra columna | *"La nota está en la columna Media T1."* |
+| Aprender a preparar el Excel | *"¿Cómo preparo mi Excel de notas?"* |
+
+En Claude Desktop tienes además atajos en el menú **+** del chat: **Meter notas en Educa**, **Revisar mis notas en Educa** y **Cómo preparo mi Excel de notas**.
 
 ```mermaid
 flowchart LR
@@ -100,8 +113,31 @@ flowchart LR
 
 Verás una ventana del navegador donde ocurre todo: puedes mirar en cualquier momento qué está haciendo. **El cierre y la firma de la evaluación los haces tú a mano**, como siempre.
 
+### Tus grupos
+
+No hay que configurar los grupos: el conector los lee de Educa. Di *"actualiza mis grupos"* y guardará en tu ordenador la lista de grupos, agrupamientos, asignaturas y evaluaciones; a partir de ahí basta con *"abre las notas de 1ºAB de Tecnología, 2ª evaluación"*. Repítelo cuando cambien tus grupos (curso nuevo, sustitución).
+
+Si en algún grupo no pones tú las notas (docencia compartida), indícalo en el ajuste **Grupos en los que no pongo notas**: podrás consultarlo, pero el conector se negará a escribir en él.
+
+### Sirve para cualquier etapa
+
+El conector no supone cómo se califica: lee la pantalla de Educa abierta y se adapta. Vale igual si este curso das ESO y el siguiente un ciclo formativo.
+
+| Lo que ofrece Educa | Qué acepta de tu fichero |
+|---|---|
+| Desplegable con términos (ESO, Primaria): IN, SU, BI, NT, SB | El término ("NT", "Notable") o un número entero, que convierte así: 0–4 IN, 5 SU, 6 BI, 7–8 NT, 9–10 SB |
+| Nota tecleada (Bachillerato) | Entero de 0 a 10 |
+| Nota tecleada en un ciclo formativo (FP) | Entero de 1 a 10 |
+| Desplegable Apto / No apto | El término; rechaza números |
+| Otros valores (FPEX, EX, NP...) | Solo si la pantalla los ofrece |
+
+La vista previa dice siempre qué escala ha detectado y nunca redondea decimales. Las pantallas de FP solo se han probado con el simulador. Normativa de referencia en [docs/normativa-evaluacion.md](docs/normativa-evaluacion.md).
+
 ### Tu fichero de notas
 
+> [!TIP]
+> Guarda tus Excel en **Documentos/Notas Educa** con nombres como `1EV_BTO-1A_TIC.xlsx` (evaluación_grupo_materia) y Claude los encontrará solo. Todos los consejos en la **[guía de buenas prácticas](docs/BUENAS-PRACTICAS.md)**.
+
 Vale casi cualquier Excel o CSV con una fila por alumno. Por ejemplo:
 
 | Apellidos | Nombre | Nota |

package/dist/browser.js

@@ -258,12 +258,14 @@ export class EducaBrowser {
                 continue;
             await frame.locator("[data-educa-mcp-dd]").first().click();
             await page.waitForTimeout(600);
-            const searchBox = frame.locator("[data-educa-mcp-dd] input, .p-dropdown-filter, .ng-select input, input[role=searchbox], input[type=search]").filter({ visible: true }).first();
-            if ((await searchBox.count()) > 0)
-                await searchBox.fill(option).catch(() => undefined);
+            // Buscador del propio desplegable (o de su panel abierto); nunca otros buscadores de la página
+            const searchBox = frame.locator("[data-educa-mcp-dd] input, .p-select-overlay input, .p-dropdown-panel input, .ng-dropdown-panel input").filter({ visible: true }).first();
+            const typed = (await searchBox.count()) > 0 && (await searchBox.fill(option).then(() => true).catch(() => false));
             await page.waitForTimeout(600);
             const picked = await frame.evaluate(clickDropdownOption, option);
             if (!picked.ok) {
+                if (typed)
+                    await searchBox.fill("").catch(() => undefined); // no dejar el filtro escrito
                 await page.keyboard.press("Escape").catch(() => undefined);
                 throw new Error(`El desplegable "${fieldHint}" no tiene la opción "${option}". Opciones visibles: ${picked.options.join(" / ") || "(ninguna)"}`);
             }
@@ -272,8 +274,105 @@ export class EducaBrowser {
         }
         throw new Error(`No encuentro ningún desplegable cuyo nombre o etiqueta contenga "${fieldHint}". Usa educa_inspect_page para ver los campos.`);
     }
+    // ---------- Selector de grupo, asignatura y evaluación (Educa-Gestión) ----------
+    groupSelect(page, kind) {
+        return page.locator(`[role=dialog] p-select[placeholder="Seleccione un ${kind}"]`).first();
+    }
+    /** Abre el diálogo de Educa-Gestión que pide grupo o agrupamiento y asignatura. */
+    async openGroupSelector() {
+        let page = await this.page();
+        page = await this.goto(new URL(this.config.gradesScreen.path, page.url()).toString());
+        await settle(page);
+        const selector = this.groupSelect(page, "grupo");
+        if (!(await selector.isVisible().catch(() => false))) {
+            // Aviso de "Última conexión" que tapa el menú al entrar
+            const notice = page.locator("[role=dialog] button[data-pc-name=pcclosebutton]").filter({ visible: true }).first();
+            if ((await notice.count()) > 0)
+                await notice.click().catch(() => undefined);
+            for (const entry of this.config.gradesScreen.menu)
+                await this.click({ text: entry });
+        }
+        await selector.waitFor({ state: "visible", timeout: 10_000 }).catch(() => {
+            throw new Error(`No se ha abierto el selector de grupo de Educa tras pulsar ${this.config.gradesScreen.menu.join(" → ")}. Usa educa_inspect_page para ver dónde está el navegador; si el menú de tu centro es distinto, ajusta gradesScreen.menu en la configuración.`);
+        });
+    }
+    /** Abre un desplegable PrimeNG, lee sus opciones y lo vuelve a cerrar sin elegir nada. */
+    async overlayOptions(page, trigger) {
+        await trigger.click();
+        const items = page.locator(".p-select-overlay li[role=option]").filter({ visible: true });
+        await items.first().waitFor({ state: "visible", timeout: 3000 }).catch(() => undefined);
+        const texts = (await items.allInnerTexts().catch(() => [])).map(t => t.replace(/\s+/g, " ").trim()).filter(Boolean);
+        if ((await items.count()) > 0)
+            await trigger.click().catch(() => undefined); // se cierra con su propio botón (Escape cerraría el diálogo)
+        await page.waitForTimeout(250);
+        return [...new Set(texts)];
+    }
+    async pickOverlayOption(page, trigger, option) {
+        await trigger.click();
+        const item = page.locator(".p-select-overlay li[role=option]").filter({ visible: true }).filter({ hasText: new RegExp(`^\\s*${option.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*$`) }).first();
+        try {
+            await item.click({ timeout: 5000 });
+        }
+        catch {
+            await trigger.click().catch(() => undefined);
+            throw new Error(`El desplegable de Educa no ofrece la opción "${option}".`);
+        }
+        await settle(page, 500);
+    }
+    /** Con el selector abierto: nombres de los grupos y agrupamientos del docente. */
+    async listGroupNames() {
+        const page = await this.page();
+        const out = { grupo: [], agrupamiento: [] };
+        for (const kind of ["grupo", "agrupamiento"]) {
+            const select = this.groupSelect(page, kind);
+            if ((await select.count()) > 0 && (await select.isVisible().catch(() => false)))
+                out[kind] = await this.overlayOptions(page, select);
+        }
+        return out;
+    }
+    /** Con el selector abierto: elige el grupo y devuelve las asignaturas que lista Educa para él. */
+    async subjectsOfGroup(kind, name) {
+        const page = await this.page();
+        await this.pickOverlayOption(page, this.groupSelect(page, kind), name);
+        const items = page.locator("[role=dialog] p-listbox li[role=option]").filter({ visible: true });
+        await items.first().waitFor({ state: "visible", timeout: 4000 }).catch(() => undefined);
+        return [...new Set((await items.allInnerTexts().catch(() => [])).map(t => t.replace(/\s+/g, " ").trim()).filter(Boolean))];
+    }
+    /** Abre la pantalla de notas de un grupo y asignatura (nombres exactos, tal como los da Educa). */
+    async openSubject(kind, group, subject) {
+        await this.openGroupSelector();
+        const page = await this.page();
+        const subjects = await this.subjectsOfGroup(kind, group);
+        if (!subjects.includes(subject))
+            throw new Error(`Educa no lista la asignatura "${subject}" en ${group}. Asignaturas: ${subjects.join(" / ") || "(ninguna)"}`);
+        await page.locator("[role=dialog] p-listbox li[role=option]").filter({ visible: true }).filter({ hasText: new RegExp(`^\\s*${subject.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*$`) }).first().click();
+        await settle(page);
+        await page.locator(".listadoCalificaciones .elementoLista").first().waitFor({ state: "visible", timeout: 10_000 }).catch(() => undefined);
+    }
+    evaluationSelect(page) {
+        return page.locator('p-select[placeholder="evl"]').first();
+    }
+    /** Evaluación elegida y evaluaciones disponibles en la pantalla de notas abierta. */
+    async evaluations() {
+        const page = await this.page();
+        const select = this.evaluationSelect(page);
+        if ((await select.count()) === 0 || !(await select.isVisible().catch(() => false)))
+            return { current: "", options: [] };
+        const options = await this.overlayOptions(page, select);
+        const current = ((await select.locator("[role=combobox]").first().innerText().catch(() => "")) || "").replace(/\s+/g, " ").trim();
+        return { current, options };
+    }
+    async selectEvaluation(option) {
+        const page = await this.page();
+        await this.pickOverlayOption(page, this.evaluationSelect(page), option);
+        await settle(page);
+    }
     // ---------- Tabla de notas ----------
-    async readGradeSheet(column) {
+    /**
+     * Lee la tabla de notas. Con probeOptions abre (y cierra con Escape, sin elegir nada) el
+     * desplegable de la primera nota editable para conocer las opciones reales de esa pantalla.
+     */
+    async readGradeSheet(column, probeOptions = false) {
         const page = await this.page();
         let best = null;
         let bestScore = -1;
@@ -290,8 +389,36 @@ export class EducaBrowser {
         if (!best || best.rows.length === 0) {
             throw new Error("No encuentro una tabla de notas con campos editables en la página actual. Navega en Educa hasta la pantalla de calificaciones del grupo, materia y evaluación (puedes usar educa_click / educa_select_filter) y vuelve a intentarlo.");
         }
+        if (probeOptions)
+            await this.probeOptions(best).catch(() => undefined);
         return best;
     }
+    async probeOptions(sheet) {
+        const fields = sheet.rows.map(r => r.field).filter((f) => f !== null && !f.disabled);
+        const first = fields.find(f => f.type === "p-select" || f.type === "p-select-editable");
+        if (!first)
+            return;
+        const page = await this.page();
+        const loc = await this.locateField(first.key);
+        if (!loc)
+            return;
+        const opener = first.type === "p-select" ? loc : loc.locator("xpath=ancestor::p-select[1]").locator(".p-select-dropdown, [data-pc-section=dropdown]").first();
+        if ((await opener.count()) === 0)
+            return;
+        await opener.scrollIntoViewIfNeeded().catch(() => undefined);
+        await opener.click({ timeout: 3000 });
+        const items = page.locator(".p-select-overlay li[role=option]").filter({ visible: true });
+        await items.first().waitFor({ state: "visible", timeout: 2500 }).catch(() => undefined);
+        const texts = (await items.allInnerTexts().catch(() => [])).map(t => t.replace(/\s+/g, " ").trim()).filter(Boolean);
+        await page.keyboard.press("Escape").catch(() => undefined);
+        await page.waitForTimeout(200);
+        if (!texts.length)
+            return; // no se han podido leer: se mantiene lo deducido de la leyenda
+        const options = [...new Set(texts)].map(t => ({ value: t, text: t }));
+        for (const f of fields)
+            if (f.type === first.type)
+                f.options = options;
+    }
     async locateField(key) {
         const page = await this.page();
         for (const frame of page.frames()) {
@@ -655,7 +782,9 @@ function extractGradeSheet({ sel, column }) {
             return { index, name, ...(studentId ? { studentId } : {}), field };
         });
         // Verificado en el Educa real: al cambiar una nota la celda queda "modificado" y aparecen Aceptar/Cancelar; no se guarda sola
-        return { headers: allHeaders, column: target, rows: rowsOut, editableColumns, autoSaves: false };
+        const ctx = [...document.querySelectorAll("app-selector-grupo-asignatura-anidado p-select [role=combobox]:not(.p-placeholder), app-selector-grupo-asignatura-anidado li[role=option][aria-selected=true], h1, h2, h3")]
+            .map(e => clean(e.textContent)).filter((t, i, a) => t && a.indexOf(t) === i).join(" · ").slice(0, 300);
+        return { headers: allHeaders, column: target, rows: rowsOut, editableColumns, autoSaves: false, context: ctx };
     }
     // 1. Filas candidatas
     let rows;
@@ -759,6 +888,8 @@ function extractGradeSheet({ sel, column }) {
                 value: el.value,
                 valueText: isSelect ? clean(el.selectedOptions[0]?.textContent) : el.value,
                 disabled: el.disabled || el.readOnly === true,
+                ...(el instanceof HTMLInputElement && el.min !== "" && !isNaN(Number(el.min)) ? { min: Number(el.min) } : {}),
+                ...(el instanceof HTMLInputElement && el.max !== "" && !isNaN(Number(el.max)) ? { max: Number(el.max) } : {}),
                 ...(isSelect ? { options: [...el.options].map(o => ({ value: o.value, text: clean(o.textContent) })) } : {})
             };
         }
@@ -766,6 +897,11 @@ function extractGradeSheet({ sel, column }) {
             out.push({ index, name, ...(studentId ? { studentId } : {}), field });
     });
     const column_ = sel.gradeFieldSelector ? out.find(r => r.field)?.field?.header ?? null : targetPos !== null ? headers[targetPos] || `columna ${targetPos + 1}` : null;
-    return { headers: headers.map((h, i) => h || `columna ${i + 1}`), column: column_, rows: out, editableColumns };
+    // Contexto: títulos y filtros elegidos (grupo, materia, evaluación) fuera de las filas de notas
+    const context = [
+        ...[...document.querySelectorAll("h1, h2, h3")].map(e => clean(e.textContent)),
+        ...[...document.querySelectorAll("select")].filter(s2 => !rows.some(r => r.contains(s2))).map(s2 => clean(s2.selectedOptions[0]?.textContent))
+    ].filter((t2, i, a) => t2 && a.indexOf(t2) === i).join(" · ").slice(0, 300);
+    return { headers: headers.map((h, i) => h || `columna ${i + 1}`), column: column_, rows: out, editableColumns, context };
 }
 //# sourceMappingURL=browser.js.map

package/dist/config.js

@@ -84,6 +84,21 @@ const ConfigSchema = z.object({
         successPattern: "(correctamente|guardad[oa]s?|grabad[oa]s?|se han actualizado)",
         errorPattern: "(error|no se ha podido|incorrect[oa]|obligatori[oa])"
     }),
+    /** Cómo llegar en Educa-Gestión a la pantalla de calificaciones de evaluación por asignatura. */
+    gradesScreen: z
+        .object({
+        /** Ruta de Educa-Gestión dentro del dominio de Educa. */
+        path: z.string().default("/Educa/es/"),
+        /** Entradas de menú que se pulsan por orden hasta que se abre el selector de grupo. */
+        menu: z.array(z.string()).default(["CUADERNO DE AULA", "CALIFICACIONES", "DE EVALUACIÓN: ASIGNATURA"])
+    })
+        .default({ path: "/Educa/es/", menu: ["CUADERNO DE AULA", "CALIFICACIONES", "DE EVALUACIÓN: ASIGNATURA"] }),
+    /**
+     * Grupos o agrupamientos en los que este docente no pone notas (p. ej. docencia compartida).
+     * El servidor se niega a escribir o guardar notas si la pantalla abierta es de uno de ellos.
+     * Basta el principio del nombre: "ESO 2" cubre "ESO 2º D" y "ESO 2º E".
+     */
+    noGradeGroups: z.array(z.string()).default([]),
     /** El servidor nunca pulsa elementos cuyo texto encaje con esto. */
     forbiddenClickPattern: z
         .string()
@@ -149,6 +164,11 @@ function applyEnv(config) {
         config.browserExecutablePath = process.env.EDUCA_BROWSER_PATH;
     if (process.env.EDUCA_HEADLESS)
         config.headless = process.env.EDUCA_HEADLESS === "1";
+    // Claude Desktop deja "${user_config.x}" sin sustituir cuando el campo opcional se queda vacío
+    const noGrade = process.env.EDUCA_NO_GRADE_GROUPS?.trim();
+    if (noGrade && !noGrade.startsWith("${")) {
+        config.noGradeGroups = [...config.noGradeGroups, ...noGrade.split(/[,;\n]+/).map(g => g.trim()).filter(Boolean)];
+    }
     if (process.env.EDUCA_ALLOWED_HOSTS)
         config.allowedHosts = process.env.EDUCA_ALLOWED_HOSTS.split(",");
     return config;

package/dist/grades.js

@@ -195,6 +195,100 @@ export function parseCsv(text) {
     }
     return rows;
 }
+export function detectStage(context) {
+    const t = ` ${normalize(context ?? "")} `;
+    if (/ (bto|bach|bachiller|bachillerato) /.test(t))
+        return "bachillerato";
+    if (/ (cfgm|cfgs|cfgb|fpb|fpgb|gm|gs|fp|ciclo formativo|ciclos formativos|grado medio|grado superior|grado basico|curso de especializacion) /.test(t))
+        return "fp";
+    if (/ (eso|secundaria obligatoria) /.test(t))
+        return "eso";
+    if (/ (ep|primaria) /.test(t))
+        return "primaria";
+    return "desconocida";
+}
+/**
+ * Devuelve el grupo de la lista "no pongo notas" al que pertenece la pantalla, o null.
+ * Compara palabras completas sin tildes ni mayúsculas; basta el principio del nombre del grupo.
+ */
+export function blockedGroup(context, noGradeGroups) {
+    const text = ` ${normalize(context ?? "")} `;
+    for (const group of noGradeGroups) {
+        const wanted = normalize(group);
+        if (wanted && text.includes(` ${wanted} `))
+            return group;
+    }
+    return null;
+}
+/** Términos de calificación con sus formas habituales (código y palabra completa). */
+const TERMS = {
+    IN: ["in", "insuficiente"],
+    SU: ["su", "sf", "suficiente"],
+    BI: ["bi", "bien"],
+    NT: ["nt", "notable"],
+    SB: ["sb", "sobresaliente"],
+    AP: ["ap", "apto", "apta", "superado", "superada"],
+    NA: ["na", "no apto", "no apta", "no superado", "no superada"],
+    NP: ["np", "no presentado", "no presentada"],
+    EX: ["ex", "exento", "exenta"],
+    CV: ["cv", "convalidado", "convalidada"]
+};
+const ESO_TERMS = ["IN", "SU", "BI", "NT", "SB"];
+/** Código canónico de un término ("Sobresaliente", "SB", "Sobresaliente (SB)" -> "SB"), o null. */
+export function termCode(text) {
+    const candidates = [text, text.replace(/\s*\([^)]*\)\s*$/, ""), /\(([^)]*)\)\s*$/.exec(text)?.[1] ?? ""].map(normalize).filter(Boolean);
+    for (const [code, forms] of Object.entries(TERMS))
+        if (candidates.some(c => forms.includes(c)))
+            return code;
+    return null;
+}
+const STAGE_LABEL = { primaria: "Primaria", eso: "ESO", bachillerato: "Bachillerato", fp: "Formación Profesional", desconocida: "etapa no identificada" };
+const ESO_CONVERSION = "0–4 → IN · 5 → SU · 6 → BI · 7–8 → NT · 9–10 → SB";
+function numericRange(field, cfg, stage) {
+    // RD 659/2023: los módulos de FP se califican de 1 a 10; en Bachillerato (RD 243/2022) de 0 a 10
+    const lo = field.min ?? (stage === "fp" ? Math.max(cfg.min, 1) : cfg.min);
+    return { lo, hi: field.max ?? cfg.max };
+}
+function realOptions(field) {
+    return (field.options ?? []).filter(o => o.value.trim() !== "" || o.text.trim() !== "");
+}
+function findTerm(options, code) {
+    const hits = options.filter(o => termCode(o.text) === code || termCode(o.value) === code);
+    return hits.length === 1 ? hits[0] : null;
+}
+/** Describe la escala que pide la pantalla abierta, a partir de sus campos de nota. */
+export function describeScale(sheet, cfg, stageOverride) {
+    const stage = stageOverride ?? detectStage(sheet.context);
+    const fields = sheet.rows.map(r => r.field).filter((f) => f !== null);
+    const field = fields.find(f => !f.disabled) ?? fields[0];
+    const where = STAGE_LABEL[stage];
+    if (!field)
+        return { kind: "sin_campos", stage, description: `No hay campos de nota en la columna elegida (${where}).` };
+    if (field.tag === "select" || field.tag === "pselect") {
+        const options = realOptions(field);
+        const values = options.map(o => o.text || o.value);
+        if (!options.length)
+            return { kind: "otra", stage, values, description: `Desplegable sin opciones legibles (${where}); puede que la evaluación esté cerrada.` };
+        if (ESO_TERMS.every(c => findTerm(options, c))) {
+            return { kind: "terminos", stage, values, conversion: ESO_CONVERSION, description: `Términos (${where}): ${values.join(", ")}. Si el fichero trae números se convierten así: ${ESO_CONVERSION}.` };
+        }
+        if (findTerm(options, "AP") && findTerm(options, "NA")) {
+            return { kind: "apto", stage, values, description: `Apto / No apto (${where}): ${values.join(", ")}. El fichero debe traer el término, no un número.` };
+        }
+        const nums = options.map(o => { const n = numbersIn(o.text); return n.length === 1 ? n[0] : parseNumber(o.value); }).filter((n) => n !== null);
+        if (nums.length >= options.length / 2 && nums.length >= 5) {
+            return { kind: "numerica", stage, values, min: Math.min(...nums), max: Math.max(...nums), description: `Nota numérica elegida en un desplegable, de ${Math.min(...nums)} a ${Math.max(...nums)} (${where}). Opciones: ${values.join(", ")}.` };
+        }
+        return { kind: "otra", stage, values, description: `Desplegable con estas opciones (${where}): ${values.join(", ")}. El fichero debe traer exactamente uno de esos valores.` };
+    }
+    const { lo, hi } = numericRange(field, cfg, stage);
+    const extras = field.options ? realOptions(field).map(o => o.text || o.value) : ["FPEX"];
+    const all = [...new Set([...extras, ...cfg.extraValues])];
+    return {
+        kind: "numerica", stage, min: lo, max: hi, values: all,
+        description: `Nota numérica tecleada de ${lo} a ${hi}${cfg.integerOnly ? ", sin decimales" : ""} (${where})${all.length ? `. También admite: ${all.join(", ")}` : ""}.`
+    };
+}
 function parseNumber(text) {
     const t = text.trim().replace(",", ".");
     return /^-?\d+(\.\d+)?$/.test(t) ? Number(t) : null;
@@ -202,17 +296,19 @@ function parseNumber(text) {
 function numbersIn(text) {
     return (text.match(/\d+(?:[.,]\d+)?/g) ?? []).map(n => Number(n.replace(",", ".")));
 }
-export function resolveGrade(field, grade, cfg) {
+export function resolveGrade(field, grade, cfg, stage = "desconocida") {
     const raw = grade.trim();
     const n = parseNumber(raw);
+    const isChoice = field.tag === "select" || field.tag === "pselect";
+    const { lo, hi } = isChoice ? { lo: Math.min(cfg.min, 0), hi: cfg.max } : numericRange(field, cfg, stage);
     if (n !== null) {
-        if (n < cfg.min || n > cfg.max)
-            return { ok: false, reason: `la nota ${raw} está fuera del rango ${cfg.min}–${cfg.max}` };
+        if (n < lo || n > hi)
+            return { ok: false, reason: `la nota ${raw} está fuera del rango ${lo}–${hi}${stage === "fp" && n === 0 ? " (en FP los módulos se califican de 1 a 10)" : ""}` };
         if (cfg.integerOnly && !Number.isInteger(n))
             return { ok: false, reason: `la nota ${raw} tiene decimales y Educa espera una nota entera; redondéala tú en el fichero` };
     }
-    if (field.tag === "select" || field.tag === "pselect") {
-        const options = (field.options ?? []).filter(o => o.value.trim() !== "" || o.text.trim() !== "");
+    if (isChoice) {
+        const options = realOptions(field);
         const byValue = options.filter(o => o.value.trim() === raw);
         if (byValue.length === 1)
             return { ok: true, value: byValue[0].value, display: byValue[0].text };
@@ -229,35 +325,45 @@ export function resolveGrade(field, grade, cfg) {
                 return { ok: true, value: byNumber[0].value, display: byNumber[0].text };
             if (byNumber.length > 1)
                 return { ok: false, reason: `la nota ${raw} encaja con varias opciones (${byNumber.map(o => o.text).join(" / ")})` };
+            // El fichero trae un número y Educa pide términos (ESO, Primaria, ámbitos): equivalencia habitual
+            if (ESO_TERMS.every(c => findTerm(options, c))) {
+                if (!Number.isInteger(n))
+                    return { ok: false, reason: `la nota ${raw} tiene decimales; redondéala tú en el fichero o pon directamente IN/SU/BI/NT/SB` };
+                const o = findTerm(options, n <= 4 ? "IN" : n === 5 ? "SU" : n === 6 ? "BI" : n <= 8 ? "NT" : "SB");
+                return { ok: true, value: o.value, display: `${o.text} (${raw})` };
+            }
+            if (findTerm(options, "AP") && findTerm(options, "NA")) {
+                return { ok: false, reason: `esta pantalla califica con ${options.map(o => o.text).join(" / ")}, no con números; pon el término en el fichero` };
+            }
         }
         else {
+            // "Sobresaliente" -> SB, "Apto" -> AP...
+            const code = termCode(raw);
+            const byTerm = code ? findTerm(options, code) : null;
+            if (byTerm)
+                return { ok: true, value: byTerm.value, display: byTerm.text };
             const byPrefix = options.filter(o => normalize(o.text).startsWith(normalize(raw)));
             if (byPrefix.length === 1)
                 return { ok: true, value: byPrefix[0].value, display: byPrefix[0].text };
         }
-        // Calificaciones cualitativas (ESO LOMLOE): IN / SU / BI / NT / SB
-        if (n !== null) {
-            const has = (code) => options.find(o => normalize(o.text) === code.toLowerCase());
-            if (has("IN") && has("SU") && has("BI") && has("NT") && has("SB")) {
-                if (!Number.isInteger(n))
-                    return { ok: false, reason: `la nota ${raw} tiene decimales; redondéala tú en el fichero o pon directamente IN/SU/BI/NT/SB` };
-                const code = n <= 4 ? "IN" : n === 5 ? "SU" : n === 6 ? "BI" : n <= 8 ? "NT" : "SB";
-                const o = has(code);
-                return { ok: true, value: o.value, display: `${o.text} (${raw})` };
-            }
-        }
         return { ok: false, reason: `"${raw}" no corresponde a ninguna opción del desplegable (${options.map(o => o.text).slice(0, 15).join(" / ")})` };
     }
     if (n !== null) {
         const text = String(n).replace(".", cfg.decimalSeparator);
         return { ok: true, value: text, display: text };
     }
-    const extra = [...cfg.extraValues, "FPEX"].find(v => normalize(v) === normalize(raw));
+    // Campo tecleado con un valor no numérico: solo los que ofrece el propio campo o la configuración
+    const offered = field.options ? realOptions(field).map(o => o.text || o.value) : ["FPEX"];
+    const extra = [...offered, ...cfg.extraValues].find(v => normalize(v) === normalize(raw) || (termCode(v) !== null && termCode(v) === termCode(raw)));
     if (extra)
         return { ok: true, value: extra, display: extra };
-    return { ok: false, reason: `"${raw}" no es una nota numérica ni está en grades.extraValues` };
+    if (termCode(raw) && ESO_TERMS.includes(termCode(raw))) {
+        return { ok: false, reason: `esta pantalla pide una nota numérica de ${lo} a ${hi}, no un término como "${raw}"; pon el número en el fichero` };
+    }
+    return { ok: false, reason: `"${raw}" no es una nota numérica de ${lo} a ${hi}${offered.length ? ` ni uno de los valores que admite el campo (${[...offered, ...cfg.extraValues].join(", ")})` : ""}` };
 }
-export function buildPlan(sheet, inputs, cfg) {
+export function buildPlan(sheet, inputs, cfg, stageOverride) {
+    const stage = stageOverride ?? detectStage(sheet.context);
     const rows = sheet.rows.filter(r => r.field);
     const used = new Map(); // rowIndex -> item index
     const items = [];
@@ -312,7 +418,7 @@ export function buildPlan(sheet, inputs, cfg) {
             }
             else {
                 used.set(match.index, items.length);
-                const res = resolveGrade(match.field, input.grade, cfg);
+                const res = resolveGrade(match.field, input.grade, cfg, stage);
                 if (!res.ok) {
                     item.status = "nota_no_valida";
                     item.note = res.reason;

package/dist/groups.js

@@ -0,0 +1,39 @@
+/**
+ * Catálogo local de los grupos del docente (grupos, agrupamientos, asignaturas y evaluaciones),
+ * leído de los desplegables de Educa con educa_refresh_groups y guardado en el ordenador
+ * para que educa_open_group llegue directo a la pantalla de notas.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { DATA_DIR } from "./config.js";
+import { normalize } from "./grades.js";
+export const CATALOG_FILE = join(DATA_DIR, "grupos.json");
+export function loadCatalog(file = CATALOG_FILE) {
+    if (!existsSync(file))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(file, "utf8"));
+        return Array.isArray(raw.groups) ? { updatedAt: raw.updatedAt ?? "", groups: raw.groups, evaluations: raw.evaluations ?? [] } : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveCatalog(catalog, file = CATALOG_FILE) {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(catalog, null, 2), "utf8");
+}
+/** Busca por nombre sin tildes ni mayúsculas: exacto y, si no, el único que lo contiene. */
+export function findByName(items, wanted, nameOf) {
+    const w = normalize(wanted);
+    const exact = items.filter(i => normalize(nameOf(i)) === w);
+    if (exact.length === 1)
+        return { ok: true, item: exact[0] };
+    if (exact.length > 1)
+        return { ok: false, reason: "varios", candidates: exact };
+    const partial = items.filter(i => ` ${normalize(nameOf(i))} `.includes(` ${w} `) || normalize(nameOf(i)).replace(/ /g, "").includes(w.replace(/ /g, "")));
+    if (partial.length === 1)
+        return { ok: true, item: partial[0] };
+    return { ok: false, reason: partial.length ? "varios" : "ninguno", candidates: partial };
+}
+//# sourceMappingURL=groups.js.map

package/dist/guide.js

@@ -0,0 +1,165 @@
+/**
+ * Ayudas para el docente que no dependen de Educa:
+ *  - instrucciones del servidor (cómo debe trabajar Claude con este conector),
+ *  - la carpeta de notas y la herramienta que lista sus ficheros,
+ *  - prompts listos para usar desde el menú de Claude.
+ *
+ * Resumen de docs/BUENAS-PRACTICAS.md: si cambias una, revisa la otra.
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, extname, join, relative } from "node:path";
+import * as z from "zod/v4";
+/** Carpeta donde el docente guarda sus Excel/CSV de notas. */
+export function notesDir() {
+    const env = process.env.EDUCA_NOTES_DIR?.trim();
+    if (env && !env.startsWith("${"))
+        return env.replace(/^~(?=$|[\\/])/, homedir());
+    return join(homedir(), "Documents", "Notas Educa");
+}
+export const SERVER_INSTRUCTIONS = `Conector no oficial para meter notas de evaluación en Educa (Gobierno de Navarra) desde el Excel o CSV del docente. Quien lo usa suele ser un docente sin conocimientos técnicos: háblale claro y en español, sin jerga.
+
+Flujo:
+1. Averigua grupo, materia y evaluación. Si falta algo, pregúntalo antes de abrir Educa.
+2. Busca el fichero con educa_list_grade_files (carpeta de notas del docente). Los ficheros suelen llamarse EVALUACIÓN_GRUPO_MATERIA, p. ej. "1EV_BTO-1A_TIC.xlsx". Si hay varios candidatos o ninguno, pregunta; no adivines. Si el docente adjunta el fichero en el chat en vez de dejarlo en la carpeta, puedes pasar las notas directamente a educa_preview_grades.
+3. educa_login y abre la pantalla de notas con educa_open_group (grupo, materia y evaluación; vale el nombre parcial). Si el grupo no aparece, educa_refresh_groups relee los grupos del docente desde Educa. Solo si eso falla, navega a mano: Educa-Gestión → Cuaderno de aula → Calificaciones (educa_inspect_page, educa_click, educa_select_filter).
+4. educa_preview_grades y enseña la tabla completa: alumnos sin emparejar, nombres aproximados, notas rechazadas y alumnos de Educa sin nota. No cambia nada.
+5. Solo si el docente da el visto bueno, educa_fill_grades (escribe en pantalla sin guardar). Pídele que lo revise en la ventana del navegador.
+6. educa_save_grades únicamente tras una confirmación expresa del docente en este momento ("sí, guarda"). Nunca la des por supuesta.
+
+Reglas:
+- No redondees ni inventes notas: si una nota no vale para la escala de la pantalla, díselo y que la corrija en su fichero.
+- Las coincidencias de nombre aproximadas no se escriben sin confirmación.
+- Nunca cierres, firmes, bloquees ni publiques una evaluación: eso lo hace el docente a mano.
+- Minimiza los datos personales en el chat: no pidas capturas ni volcados de la página si no hacen falta.
+- Los grupos de "Grupos en los que no pongo notas" se pueden consultar, pero no prepares ni escribas notas en ellos.
+- La sesión de Educa caduca a los 30-40 minutos; si caduca, vuelve a llamar a educa_login.
+- Si el docente pregunta cómo preparar sus ficheros, resume esto: una hoja por grupo y materia, la primera fila con cabeceras (Alumno o Apellidos + Nombre, y Nota), un alumno por fila con el nombre igual que en Educa, notas enteras (o IN/SU/BI/NT/SB en ESO), celdas vacías para quien no tenga nota, nombre de fichero EVALUACIÓN_GRUPO_MATERIA y todos en la carpeta de notas. Guía completa: https://github.com/vTanco/educa-navarra-mcp/blob/main/docs/BUENAS-PRACTICAS.md`;
+const GRADE_EXTENSIONS = new Set([".xlsx", ".csv"]);
+const MAX_DEPTH = 3;
+const MAX_FILES = 300;
+function listFiles(root) {
+    const out = [];
+    const walk = (dir, depth) => {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            if (out.length >= MAX_FILES)
+                return;
+            if (name.startsWith(".") || name.startsWith("~$"))
+                continue; // ocultos y temporales de Excel
+            const full = join(dir, name);
+            let st;
+            try {
+                st = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                if (depth < MAX_DEPTH)
+                    walk(full, depth + 1);
+            }
+            else if (GRADE_EXTENSIONS.has(extname(name).toLowerCase())) {
+                const parts = basename(name, extname(name)).split("_").map(p => p.trim()).filter(Boolean);
+                out.push({
+                    file: name,
+                    path: full,
+                    folder: relative(root, dir) || ".",
+                    modified: st.mtime.toISOString().slice(0, 16).replace("T", " "),
+                    ...(parts.length >= 3 ? { evaluation: parts[0], group: parts[1], subject: parts.slice(2).join(" ") } : {})
+                });
+            }
+        }
+    };
+    walk(root, 0);
+    return out.sort((a, b) => b.modified.localeCompare(a.modified));
+}
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+export function registerGuide(server) {
+    server.registerTool("educa_list_grade_files", {
+        title: "Ver mis ficheros de notas",
+        description: `Lista los Excel (.xlsx) y CSV de la carpeta de notas del docente (y sus subcarpetas), del más reciente al más antiguo, con la ruta completa para educa_load_grades_file o educa_preview_grades. Si el nombre sigue la convención EVALUACIÓN_GRUPO_MATERIA (p. ej. "1EV_BTO-1A_TIC.xlsx"), devuelve también esas tres partes para elegir el fichero que encaja con lo que pide el docente. No toca Educa.`,
+        inputSchema: z.strictObject({
+            filter: z.string().optional().describe("Texto que debe aparecer en el nombre o la carpeta (sin distinguir mayúsculas ni tildes), p. ej. '1A' o 'TIC'")
+        }),
+        annotations: { readOnlyHint: true, openWorldHint: false }
+    }, async ({ filter }) => {
+        const root = notesDir();
+        if (!existsSync(root)) {
+            return text(`La carpeta de notas no existe: ${root}\n\n` +
+                `Pide al docente que la cree y guarde ahí sus Excel, o que te diga dónde están sus ficheros. ` +
+                `En Claude Desktop se puede cambiar en Ajustes → Extensiones → Educa Navarra → Carpeta de notas; en otras aplicaciones, con la variable EDUCA_NOTES_DIR.`);
+        }
+        const norm = (s) => s.normalize("NFD").replace(/\p{Diacritic}/gu, "").toLowerCase();
+        let files = listFiles(root);
+        if (filter)
+            files = files.filter(f => norm(`${f.folder}/${f.file}`).includes(norm(filter)));
+        const lines = [`Carpeta de notas: ${root}`, ""];
+        if (!files.length) {
+            lines.push(filter ? `No hay ficheros .xlsx o .csv que contengan "${filter}".` : "No hay ficheros .xlsx o .csv.");
+            return text(lines.join("\n"));
+        }
+        lines.push("| Fichero | Carpeta | Evaluación | Grupo | Materia | Modificado |", "|---|---|---|---|---|---|");
+        for (const f of files)
+            lines.push(`| ${f.file} | ${f.folder} | ${f.evaluation ?? "—"} | ${f.group ?? "—"} | ${f.subject ?? "—"} | ${f.modified} |`);
+        lines.push("", "Rutas completas:", ...files.map(f => `- ${f.path}`));
+        if (files.length >= MAX_FILES)
+            lines.push("", `(Mostrando los ${MAX_FILES} primeros; usa filter para acotar.)`);
+        return text(lines.join("\n"));
+    });
+    server.registerPrompt("meter_notas", {
+        title: "Meter notas en Educa",
+        description: "Mete las notas de un grupo y materia desde tu Excel, con vista previa antes de guardar.",
+        argsSchema: z.object({
+            grupo: z.string().describe("Grupo, como aparece en Educa (p. ej. BTO N 1ºA, ESO 3ºDEFH cd)"),
+            materia: z.string().describe("Materia o módulo (p. ej. TIC, Matemáticas)"),
+            evaluacion: z.string().describe("Evaluación (p. ej. 1ª evaluación, final, extraordinaria)")
+        })
+    }, ({ grupo, materia, evaluacion }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Quiero meter en Educa las notas de ${evaluacion} de ${grupo}, ${materia}. Busca el fichero en mi carpeta de notas, enséñame la vista previa y no guardes nada hasta que yo te lo diga.`
+                }
+            }
+        ]
+    }));
+    server.registerPrompt("revisar_notas", {
+        title: "Revisar mis notas en Educa",
+        description: "Lee las notas que hay ahora en Educa para un grupo y materia, sin cambiar nada.",
+        argsSchema: z.object({
+            grupo: z.string().describe("Grupo, como aparece en Educa"),
+            materia: z.string().describe("Materia o módulo")
+        })
+    }, ({ grupo, materia }) => ({
+        messages: [
+            {
+                role: "user",
+                content: { type: "text", text: `Abre Educa y enséñame las notas que hay ahora en ${grupo}, ${materia}. Solo lectura: no cambies nada.` }
+            }
+        ]
+    }));
+    server.registerPrompt("preparar_excel", {
+        title: "Cómo preparo mi Excel de notas",
+        description: "Consejos para preparar el fichero de notas y dónde guardarlo."
+    }, () => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Explícame en pocos pasos cómo debo preparar y guardar mis Excel de notas para que el conector de Educa los encuentre y los entienda sin problemas. Mi carpeta de notas es: ${notesDir()}`
+                }
+            }
+        ]
+    }));
+}
+//# sourceMappingURL=guide.js.map

package/dist/index.js

@@ -19,9 +19,11 @@ import { join } from "node:path";
 import { McpServer } from "@modelcontextprotocol/server";
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import * as z from "zod/v4";
+import { CATALOG_FILE, findByName, loadCatalog, saveCatalog } from "./groups.js";
 import { EducaBrowser, FieldGone } from "./browser.js";
 import { loadConfig, PROJECT_DIR } from "./config.js";
-import { buildPlan, parseGradesFile, summarizePlan } from "./grades.js";
+import { registerGuide, SERVER_INSTRUCTIONS } from "./guide.js";
+import { blockedGroup, buildPlan, describeScale, normalize as normalizeName, parseGradesFile, summarizePlan } from "./grades.js";
 const CHARACTER_LIMIT = 25_000;
 const PACKAGE_VERSION = JSON.parse(readFileSync(join(PROJECT_DIR, "package.json"), "utf8")).version;
 if (process.argv.includes("--version") || process.argv.includes("-v")) {
@@ -36,6 +38,22 @@ if (process.stdin.isTTY) {
 }
 const { config, path: configPath } = loadConfig();
 const browser = new EducaBrowser(config);
+/** Lanza un error si la pantalla abierta es de un grupo en el que el docente ha dicho que no pone notas. */
+function assertGroupAllowed(sheet, action) {
+    if (!config.noGradeGroups.length)
+        return;
+    const blocked = blockedGroup(sheet.context, config.noGradeGroups);
+    if (blocked) {
+        throw new Error(`No puedo ${action}: la pantalla abierta es de "${sheet.context}" y en los ajustes del conector figura "${blocked}" como grupo en el que no pones notas. Si es un error, quítalo de "Grupos en los que no pongo notas" en los ajustes y reinicia la aplicación.`);
+    }
+    if (!sheet.context?.trim()) {
+        throw new Error(`No puedo ${action}: no consigo identificar el grupo de la pantalla abierta y hay grupos marcados como "no pongo notas" (${config.noGradeGroups.join(", ")}). Abre el grupo desde el selector de Educa y vuelve a intentarlo.`);
+    }
+}
+function blockedNote(sheet) {
+    const blocked = blockedGroup(sheet.context, config.noGradeGroups);
+    return blocked ? `⛔ Este grupo está en tu lista "Grupos en los que no pongo notas" (${blocked}): se puede consultar, pero el conector no escribirá ni guardará notas aquí.` : null;
+}
 const plans = new Map();
 let lastFilledPlan = null;
 function text(t) {
@@ -60,7 +78,7 @@ const STATUS_LABEL = {
     campo_bloqueado: "🔒 campo bloqueado",
     duplicada: "⚠️ fila duplicada"
 };
-function planMarkdown(stored, sheet) {
+function planMarkdown(stored, sheet, scale) {
     const { plan } = stored;
     const counts = summarizePlan(plan);
     const fuzzy = plan.items.filter(i => i.fuzzyMatch && i.status === "cambia").length;
@@ -68,6 +86,8 @@ function planMarkdown(stored, sheet) {
         `# Vista previa de notas (plan ${stored.id})`,
         "",
         `Columna de Educa: **${stored.column ?? "(única)"}** · ${sheet.rows.filter(r => r.field).length} alumnos en la tabla`,
+        ...(sheet.context ? [`Pantalla: ${sheet.context}`] : []),
+        `Escala detectada: ${scale.description}`,
         "",
         `- Se escribirán: **${counts.cambia}**${fuzzy ? ` (de ellas ${fuzzy} por coincidencia aproximada de nombre, revísalas)` : ""}`,
         `- Ya estaban igual: ${counts.igual}`,
@@ -90,7 +110,8 @@ function planMarkdown(stored, sheet) {
 }
 // ---------- Servidor ----------
 function createServer() {
-    const server = new McpServer({ name: "educa-mcp", version: PACKAGE_VERSION });
+    const server = new McpServer({ name: "educa-mcp", version: PACKAGE_VERSION }, { instructions: SERVER_INSTRUCTIONS });
+    registerGuide(server);
     server.registerTool("educa_login", {
         title: "Iniciar sesión en Educa",
         description: `Abre Educa en una ventana de navegador del ordenador del profesor e inicia sesión. Si el profesor ha guardado sus credenciales en el fichero local de credenciales, el formulario se rellena solo (un único intento); si no, espera a que inicie sesión él mismo (usuario de Educa, Cl@ve o certificado). La contraseña nunca pasa por el modelo. Si ya hay sesión (el perfil del navegador la recuerda), vuelve enseguida.
@@ -225,7 +246,7 @@ Llámala antes que cualquier otra herramienta. Avisa al profesor de que debe ini
     });
     server.registerTool("educa_read_grade_sheet", {
         title: "Leer la tabla de notas",
-        description: `Lee la tabla de calificaciones abierta en Educa: alumnos y nota actual de cada uno. No cambia nada. Si la tabla tiene varias columnas editables (p. ej. nota y observaciones, o varias evaluaciones), indica cuál con column; la respuesta lista las columnas editables.`,
+        description: `Lee la tabla de calificaciones abierta en Educa: alumnos y nota actual de cada uno, y la escala de calificación que pide esa pantalla (términos IN/SU/BI/NT/SB en ESO, número de 0 a 10 en Bachillerato, de 1 a 10 en FP, Apto/No apto...). La escala se deduce de la propia pantalla, no del nombre del grupo. No cambia nada. Si la tabla tiene varias columnas editables (p. ej. nota y observaciones, o varias evaluaciones), indica cuál con column; la respuesta lista las columnas editables.`,
         inputSchema: z.strictObject({
             column: z.string().optional().describe("Parte del texto de la cabecera de la columna de nota, p. ej. 'Final' o '1ª Ev'"),
             response_format: ResponseFormat
@@ -233,8 +254,14 @@ Llámala antes que cualquier otra herramienta. Avisa al profesor de que debe ini
         annotations: { readOnlyHint: true, openWorldHint: true }
     }, async ({ column, response_format }) => {
         await requireLogin();
-        const sheet = await browser.readGradeSheet(column);
+        const sheet = await browser.readGradeSheet(column, true);
+        const scale = describeScale(sheet, config.grades);
+        const blocked = blockedNote(sheet);
         const data = {
+            no_grades_group: blocked !== null,
+            context: sheet.context ?? null,
+            stage: scale.stage,
+            scale,
             column: sheet.column,
             editable_columns: sheet.editableColumns,
             students: sheet.rows.map(r => ({ name: r.name, ...(r.studentId ? { id: r.studentId } : {}), grade: r.field ? r.field.valueText || r.field.value : null, editable: r.field ? !r.field.disabled : false }))
@@ -244,10 +271,118 @@ Llámala antes que cualquier otra herramienta. Avisa al profesor de que debe ini
         if (!sheet.column) {
             return text(`La tabla tiene varias columnas editables y no sé cuál es la nota: ${sheet.editableColumns.join(" | ")}. Vuelve a llamar con column.`);
         }
-        const lines = [`# Tabla de notas · columna "${sheet.column}" · ${data.students.length} alumnos`, "", "| # | Alumno | Nota actual |", "|---|---|---|"];
+        const lines = [`# Tabla de notas · columna "${sheet.column}" · ${data.students.length} alumnos`, ...(sheet.context ? [`Pantalla: ${sheet.context}`] : []), `Escala detectada: ${scale.description}`, ...(blocked ? [blocked] : []), "", "| # | Alumno | Nota actual |", "|---|---|---|"];
         data.students.forEach((s, i) => lines.push(`| ${i + 1} | ${s.name} | ${s.grade || "(vacía)"}${s.editable ? "" : " 🔒"} |`));
         return text(lines.join("\n"));
     });
+    // Recorre el selector de Educa y guarda en local grupos, agrupamientos, asignaturas y evaluaciones
+    async function refreshCatalog() {
+        await browser.openGroupSelector();
+        const names = await browser.listGroupNames();
+        const groups = [];
+        for (const kind of ["grupo", "agrupamiento"]) {
+            for (const name of names[kind])
+                groups.push({ name, kind, subjects: await browser.subjectsOfGroup(kind, name) });
+        }
+        if (!groups.length)
+            throw new Error("Educa no lista ningún grupo ni agrupamiento en el selector de calificaciones. Comprueba en la ventana del navegador que tu usuario tiene grupos asignados este curso.");
+        // Las evaluaciones solo se ven con una pantalla de notas abierta: se abre la primera asignatura (solo lectura)
+        let evaluations = [];
+        const first = groups.find(g => g.subjects.length);
+        if (first) {
+            await browser.openSubject(first.kind, first.name, first.subjects[0]);
+            evaluations = (await browser.evaluations()).options;
+        }
+        const catalog = { updatedAt: new Date().toISOString(), groups, evaluations };
+        saveCatalog(catalog);
+        return catalog;
+    }
+    function catalogMarkdown(catalog) {
+        const lines = [`# Tus grupos en Educa (${catalog.groups.length})`, ""];
+        for (const g of catalog.groups) {
+            const blocked = blockedGroup(g.name, config.noGradeGroups);
+            lines.push(`- **${g.name}** (${g.kind})${blocked ? " ⛔ no pones notas" : ""}: ${g.subjects.join(" · ") || "(sin asignaturas)"}`);
+        }
+        if (catalog.evaluations.length)
+            lines.push("", `Evaluaciones: ${catalog.evaluations.join(" · ")}`);
+        lines.push("", `Lista guardada en ${CATALOG_FILE} (${catalog.updatedAt.slice(0, 16).replace("T", " ")} UTC). Para abrir uno: educa_open_group.`);
+        return lines.join("\n");
+    }
+    server.registerTool("educa_refresh_groups", {
+        title: "Actualizar mis grupos",
+        description: `Lee de Educa los grupos y agrupamientos del docente, con las asignaturas de cada uno y las evaluaciones disponibles, y guarda la lista en su ordenador. No escribe nada en Educa. Tarda unos segundos por grupo.
+
+Úsala la primera vez, cuando el profesor diga que han cambiado sus grupos (curso nuevo, sustitución) o cuando educa_open_group no encuentre un grupo. Marca con ⛔ los grupos que el profesor ha indicado en los ajustes como "no pongo notas".`,
+        inputSchema: z.strictObject({ response_format: ResponseFormat }),
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true }
+    }, async ({ response_format }) => {
+        await requireLogin();
+        const catalog = await refreshCatalog();
+        if (response_format === "json")
+            return json({ ...catalog, no_grade_groups: catalog.groups.filter(g => blockedGroup(g.name, config.noGradeGroups)).map(g => g.name) });
+        return text(catalogMarkdown(catalog));
+    });
+    server.registerTool("educa_open_group", {
+        title: "Abrir las notas de un grupo",
+        description: `Abre directamente la pantalla de calificaciones de evaluación de un grupo o agrupamiento y asignatura, y opcionalmente cambia de evaluación. Usa la lista guardada por educa_refresh_groups (la actualiza sola si no existe o si el grupo no aparece). No escribe ninguna nota.
+
+Basta parte del nombre si no es ambiguo: group="1ºAB", subject="Tecnología", evaluation="2". Si el grupo solo tiene una asignatura, subject es opcional. Devuelve el grupo abierto, la escala detectada y el número de alumnos; después usa educa_read_grade_sheet o educa_preview_grades.`,
+        inputSchema: z.strictObject({
+            group: z.string().min(1).describe("Grupo o agrupamiento, p. ej. 'ESO 1ºAB plu' o 'BTO N 1ºA'"),
+            subject: z.string().min(1).optional().describe("Asignatura; opcional si el grupo solo tiene una"),
+            evaluation: z.string().min(1).optional().describe("Evaluación, p. ej. '1a Evaluación', '2' o 'Final'; por defecto la que Educa abre")
+        }),
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true }
+    }, async ({ group, subject, evaluation }) => {
+        await requireLogin();
+        let catalog = loadCatalog();
+        let refreshed = false;
+        let found = catalog ? findByName(catalog.groups, group, g => g.name) : null;
+        if (!found || !found.ok) {
+            catalog = await refreshCatalog();
+            refreshed = true;
+            found = findByName(catalog.groups, group, g => g.name);
+        }
+        if (!found.ok) {
+            const list = (found.candidates.length ? found.candidates : catalog.groups).map(g => g.name).join(" / ");
+            throw new Error(found.reason === "varios" ? `"${group}" encaja con varios grupos: ${list}. Indica el nombre completo.` : `No tienes ningún grupo que encaje con "${group}" en Educa. Tus grupos: ${list}`);
+        }
+        const entry = found.item;
+        let subjectName;
+        if (subject) {
+            const s = findByName(entry.subjects, subject, x => x);
+            if (!s.ok)
+                throw new Error(`${entry.name} no tiene ${s.reason === "varios" ? "una única" : "ninguna"} asignatura que encaje con "${subject}". Asignaturas: ${entry.subjects.join(" / ") || "(ninguna; prueba educa_refresh_groups)"}`);
+            subjectName = s.item;
+        }
+        else if (entry.subjects.length === 1)
+            subjectName = entry.subjects[0];
+        else
+            throw new Error(`${entry.name} tiene varias asignaturas: ${entry.subjects.join(" / ")}. Indica subject.`);
+        await browser.openSubject(entry.kind, entry.name, subjectName);
+        const evs = await browser.evaluations();
+        let current = evs.current;
+        if (evaluation) {
+            const e = findByName(evs.options, evaluation, x => x);
+            if (!e.ok)
+                throw new Error(`Esta pantalla no tiene ${e.reason === "varios" ? "una única" : "ninguna"} evaluación que encaje con "${evaluation}". Evaluaciones: ${evs.options.join(" / ") || "(no se ha encontrado el selector de evaluación)"}`);
+            if (normalizeName(e.item) !== normalizeName(current))
+                await browser.selectEvaluation(e.item);
+            current = e.item;
+        }
+        const sheet = await browser.readGradeSheet(undefined, true).catch(() => null);
+        const lines = [`Abierto: **${entry.name}** · ${subjectName}${current ? ` · ${current}` : ""}${refreshed ? " (he actualizado antes tu lista de grupos)" : ""}`];
+        if (sheet) {
+            lines.push(`Alumnos: ${sheet.rows.length}${sheet.column ? ` · columna editable: ${sheet.column}` : sheet.editableColumns.length ? ` · columnas editables: ${sheet.editableColumns.join(" | ")}` : " · ninguna columna editable (¿evaluación cerrada?)"}`);
+            lines.push(`Escala detectada: ${describeScale(sheet, config.grades).description}`);
+            const blocked = blockedNote(sheet) ?? (blockedGroup(entry.name, config.noGradeGroups) ? blockedNote({ ...sheet, context: entry.name }) : null);
+            if (blocked)
+                lines.push(blocked);
+        }
+        else
+            lines.push("No veo alumnos en la pantalla; puede que el grupo esté vacío o que Educa siga cargando (educa_inspect_page).");
+        return text(lines.join("\n"));
+    });
     server.registerTool("educa_load_grades_file", {
         title: "Leer el fichero de notas",
         description: `Lee un Excel (.xlsx) o CSV del ordenador del profesor y devuelve la lista alumno → nota que se ha entendido. No toca Educa. Detecta solas las columnas tipo "Alumno"/"Apellidos"+"Nombre" y "Nota"/"Nota final"/"Calificación"; si no, indícalas.`,
@@ -265,7 +400,7 @@ Llámala antes que cualquier otra herramienta. Avisa al profesor de que debe ini
     });
     server.registerTool("educa_preview_grades", {
         title: "Vista previa: cruzar notas con Educa",
-        description: `Cruza las notas (de un fichero o pasadas directamente) con la tabla de calificaciones abierta en Educa y devuelve, sin cambiar nada, qué se escribiría: alumno del fichero, alumno de Educa, nota actual, nota nueva y avisos (alumno no encontrado, nombre dudoso, nota fuera de rango o que no existe en el desplegable, campo bloqueado). Devuelve un plan_id para educa_fill_grades.
+        description: `Cruza las notas (de un fichero o pasadas directamente) con la tabla de calificaciones abierta en Educa y devuelve, sin cambiar nada, qué se escribiría: alumno del fichero, alumno de Educa, nota actual, nota nueva y avisos (alumno no encontrado, nombre dudoso, nota fuera de rango o que no existe en el desplegable, campo bloqueado). Indica también la escala detectada en la pantalla y convierte cada nota a ella: si Educa pide términos (ESO) y el fichero trae números, aplica 0–4 IN, 5 SU, 6 BI, 7–8 NT, 9–10 SB; si pide número (Bachillerato, FP) rechaza los términos y los decimales. Devuelve un plan_id para educa_fill_grades.
 
 Los nombres se emparejan sin importar mayúsculas, tildes ni el orden "Apellidos, Nombre" / "Nombre Apellidos". Las coincidencias aproximadas se marcan y no se escriben salvo que se pida.
 
@@ -281,6 +416,7 @@ Enseña siempre el resultado al profesor antes de rellenar.`,
             grade_column: z.string().optional(),
             id_column: z.string().optional(),
             column: z.string().optional().describe("Columna de Educa donde va la nota, si hay varias editables"),
+            stage: z.enum(["primaria", "eso", "bachillerato", "fp"]).optional().describe("Etapa del grupo, solo si la detección automática falla (afecta al rango numérico: en FP 1–10, en Bachillerato 0–10)"),
             response_format: ResponseFormat
         }),
         annotations: { readOnlyHint: true, openWorldHint: true }
@@ -294,27 +430,29 @@ Enseña siempre el resultado al profesor antes de rellenar.`,
         }
         if (!inputs.length)
             throw new Error("El fichero no contiene ninguna nota.");
-        const sheet = await browser.readGradeSheet(args.column);
+        const sheet = await browser.readGradeSheet(args.column, true);
         if (!sheet.column && !config.gradeSheet.gradeFieldSelector) {
             throw new Error(`La tabla de Educa tiene varias columnas editables: ${sheet.editableColumns.join(" | ")}. Indica en column cuál es la de la nota.`);
         }
-        const plan = buildPlan(sheet, inputs, config.grades);
+        assertGroupAllowed(sheet, "preparar notas para este grupo");
+        const plan = buildPlan(sheet, inputs, config.grades, args.stage);
+        const scale = describeScale(sheet, config.grades, args.stage);
         const stored = { id: randomUUID().slice(0, 8), column: args.column ?? null, createdAt: Date.now(), plan, filled: false };
         plans.set(stored.id, stored);
         if (args.response_format === "json") {
-            return json({ plan_id: stored.id, column: sheet.column, summary: summarizePlan(plan), items: plan.items, rows_without_grade: plan.rowsWithoutGrade });
+            return json({ plan_id: stored.id, column: sheet.column, context: sheet.context ?? null, scale, summary: summarizePlan(plan), items: plan.items, rows_without_grade: plan.rowsWithoutGrade });
         }
-        return text(planMarkdown({ ...stored, column: sheet.column }, sheet));
+        return text(planMarkdown({ ...stored, column: sheet.column }, sheet, scale));
     });
     server.registerTool("educa_fill_grades", {
         title: "Escribir las notas (sin guardar)",
-        description: `Escribe en los campos de Educa las notas de un plan de educa_preview_grades, solo las marcadas "se escribirá". En pantallas con botón Guardar NO lo pulsa: los cambios quedan en pantalla para que el profesor los revise. En el Cuaderno de aula de Educa-Gestión no hay botón Guardar (cada nota se guarda al elegirla), así que ahí exige confirm_autosave=true. Comprueba antes que la tabla sigue siendo la misma (mismos alumnos) y después relee cada campo.
+        description: `Escribe en los campos de Educa las notas de un plan de educa_preview_grades, solo las marcadas "se escribirá". NO guarda: los cambios quedan en pantalla para que el profesor los revise (en el Cuaderno de aula de Educa-Gestión aparecen los botones Aceptar/Cancelar; se guarda después con educa_save_grades). Comprueba antes que la tabla sigue siendo la misma (mismos alumnos) y después relee cada campo.
 
 Úsala solo después de que el profesor haya visto la vista previa y dado el visto bueno.`,
         inputSchema: z.strictObject({
             plan_id: z.string().describe("plan_id devuelto por educa_preview_grades"),
             include_fuzzy: z.boolean().default(false).describe("Escribir también las filas emparejadas por nombre aproximado (solo si el profesor las ha confirmado)"),
-            confirm_autosave: z.boolean().default(false).describe("Obligatorio (true) cuando la pantalla guarda cada nota al elegirla, como el Cuaderno de aula de Educa-Gestión: confirma que el profesor ha autorizado que las notas queden guardadas")
+            confirm_autosave: z.boolean().default(false).describe("Solo hace falta (true) en pantallas que guardan cada nota al elegirla, si alguna lo hiciera: confirma que el profesor ha autorizado que las notas queden guardadas")
         }),
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true }
     }, async ({ plan_id, include_fuzzy, confirm_autosave }) => {
@@ -328,6 +466,7 @@ Enseña siempre el resultado al profesor antes de rellenar.`,
         if (sheet.autoSaves && !confirm_autosave) {
             throw new Error("En esta pantalla de Educa no hay botón Guardar: cada nota queda guardada en cuanto se elige. Enseña la vista previa al profesor y, solo si autoriza expresamente guardar, vuelve a llamar con confirm_autosave=true.");
         }
+        assertGroupAllowed(sheet, "escribir notas en este grupo");
         const todo = stored.plan.items.filter(i => i.status === "cambia" && (include_fuzzy || !i.fuzzyMatch));
         // La tabla debe seguir teniendo a los mismos alumnos en las mismas filas
         for (const item of todo) {
@@ -393,6 +532,8 @@ IMPORTANTE: llama solo cuando el profesor haya dicho expresamente que guarde, y
         await requireLogin();
         if (!lastFilledPlan)
             throw new Error("No se ha rellenado ninguna nota en esta sesión. Usa educa_preview_grades y educa_fill_grades primero.");
+        if (config.noGradeGroups.length)
+            assertGroupAllowed(await browser.readGradeSheet(lastFilledPlan.column ?? undefined), "guardar notas de este grupo");
         const before = await browser.screenshot("antes-de-guardar");
         const res = await browser.save();
         const after = await browser.screenshot("despues-de-guardar");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "educa-navarra-mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Conector MCP no oficial para que Claude (u otra IA) meta las notas de evaluación en Educa (Gobierno de Navarra) desde tu Excel o CSV.",
   "keywords": [
     "mcp",