educa-navarra-mcp 1.0.0 → 1.1.1

package/README.md

@@ -1,62 +1,82 @@
 <div align="center">
 
-<img src="https://raw.githubusercontent.com/vTanco/educa-navarra-mcp/main/assets/icon.png" width="112" alt="">
+<img src="https://raw.githubusercontent.com/vTanco/educa-navarra-mcp/main/assets/icon.png" width="104" alt="">
 
 # Educa Navarra · notas con IA
 
-**Pásale tu Excel de notas a Claude y él las mete en Educa por ti.**
-Tú revisas y decides cuándo se guardan.
+**Pásale tu Excel de notas a Claude y él las mete en Educa por ti.**<br>
+Tú revisas la pantalla y decides cuándo se guardan.
 
 [![npm](https://img.shields.io/npm/v/educa-navarra-mcp?color=B5121B&label=npm)](https://www.npmjs.com/package/educa-navarra-mcp)
-[![Licencia MIT](https://img.shields.io/badge/licencia-MIT-1E8E3E)](LICENSE)
+[![Licencia MIT](https://img.shields.io/badge/licencia-MIT-1E8E3E)](https://github.com/vTanco/educa-navarra-mcp/blob/main/LICENSE)
 [![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)** ·
+[Instalación](#instalación) ·
+[Primeros pasos](#primeros-pasos) ·
+[Preparar el Excel](https://github.com/vTanco/educa-navarra-mcp/blob/main/docs/BUENAS-PRACTICAS.md) ·
+[Qué se ha probado](#qué-se-ha-probado) ·
+[Preguntas](#preguntas-frecuentes)
 
 </div>
 
-> [!IMPORTANT]
-> **Herramienta no oficial.** No está hecha ni respaldada por el Gobierno de Navarra ni por el Departamento de Educación. Usas tu propia cuenta de Educa y eres responsable de las notas que guardes. Lee el [aviso legal](AVISO-LEGAL.md) antes de usarla.
+> **Herramienta no oficial.** No está hecha ni respaldada por el Gobierno de Navarra ni por el Departamento de Educación. Usas tu propia cuenta de Educa y eres responsable de las notas que guardes. Lee el [aviso legal](https://github.com/vTanco/educa-navarra-mcp/blob/main/AVISO-LEGAL.md) antes de usarla.
 
----
+<p align="center">
+  <img src="https://raw.githubusercontent.com/vTanco/educa-navarra-mcp/main/assets/flujo.svg" width="100%" alt="Cinco pasos: tu Excel, vista previa, escribe en pantalla sin guardar, tú revisas y pulsa Aceptar solo si lo confirmas.">
+</p>
 
-## ✨ Qué hace
+## Qué hace
 
 | | |
 |---|---|
-| 📄 **Lee tu fichero** | Excel (`.xlsx`) o CSV, con las columnas que tengas. Basta con *alumno* y *nota*. |
-| 🔎 **Cruza nombres** | Empareja tu lista con la de Educa aunque cambien tildes, mayúsculas o el orden de nombre y apellidos. |
-| 👀 **Te enseña una vista previa** | Nota actual, nota nueva y avisos (alumnos que faltan, nombres dudosos, notas fuera de rango) **antes de tocar nada**. |
-| ✍️ **Escribe en pantalla** | Rellena las notas en la ventana de Educa, sin guardar, para que las revises con tus ojos. |
-| ✅ **Guarda solo si tú lo dices** | Pulsa *Aceptar* únicamente cuando lo confirmas en el chat. |
-| 🔒 **Nunca cierra ni firma** | Se niega a pulsar botones de cerrar, firmar, bloquear, borrar o publicar una evaluación. |
+| **Conoce tus grupos** | Lee de Educa tus grupos, agrupamientos, asignaturas y evaluaciones. No hay que escribirlos en ningún ajuste. |
+| **Va directo a la pantalla** | *"Abre 1ºCD, 2ª evaluación"* y abre Calificaciones con el grupo, la materia y la evaluación elegidos. Basta con parte del nombre. |
+| **Encuentra tu fichero** | Busca el Excel o CSV en tu carpeta de notas por evaluación, grupo y materia. También vale adjuntarlo en el chat. |
+| **Cruza los nombres** | Empareja tu lista con la de Educa aunque cambien tildes, mayúsculas o el orden de nombre y apellidos. |
+| **Enseña una vista previa** | Nota actual, nota nueva y avisos, antes de tocar nada. |
+| **Escribe sin guardar** | Rellena las notas en la ventana de Educa para que las revises. |
+| **Guarda solo si lo dices** | Pulsa *Aceptar* únicamente cuando lo confirmas en el chat. |
+
+Sirve para **ESO** (IN, SU, BI, NT, SB), **Bachillerato** (nota sobre 10) y **FP de Grado Medio y Superior**: lee la escala de cada pantalla en vez de suponerla.
+
+## Instalación
 
-Pensado para **ESO** (IN · SU · BI · NT · SB), **Bachillerato** (nota sobre 10) y **FP de Grado Medio y Superior**, según la LOMLOE.
+Elige una opción. Las tres instalan lo mismo.
 
-## 🚀 Instalación
+| | Para quién | Qué necesitas |
+|---|---|---|
+| **A · Claude Desktop** | La mayoría de docentes | Claude Desktop. Doble clic y listo |
+| **B · Claude Code** | Si ya usas la terminal | Node.js 20 o superior |
+| **C · Otras aplicaciones** | Cursor, VS Code, Windsurf, LM Studio… | Node.js 20 o superior |
 
-### Opción A · Claude Desktop (recomendada, sin saber informática)
+### A · Claude Desktop (recomendada)
 
 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.
+3. Haz **doble clic** en el fichero. Claude Desktop se abre y pregunta si quieres instalarlo: pulsa **Instalar**.
+4. Rellena los ajustes. Todos son opcionales:
+
+   | Ajuste | Para qué |
+   |---|---|
+   | Usuario y contraseña de Educa | Para que Claude entre solo. Si los dejas vacíos, entras tú en la ventana que se abre. La contraseña se guarda cifrada en tu ordenador. |
+   | Grupos en los que no pongo notas | Por ejemplo, si compartes docencia: `ESO 2º D, ESO 2º E`. Podrás consultarlos, pero el conector se negará a escribir en ellos. |
+   | Carpeta de notas | Donde guardas tus Excel. Deja la que sale (*Documentos/Notas Educa*) y créala si no existe. |
 
-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).
+No hace falta instalar nada más: usa el **Google Chrome** o **Microsoft Edge** que ya tienes. Si no hay ninguno, descarga un navegador la primera vez (un par de minutos).
 
-> [!TIP]
-> Si el doble clic no funciona: en Claude Desktop ve a **Ajustes → Extensiones → Instalar extensión…** y elige el fichero.
+Si el doble clic no funciona, en Claude Desktop ve a **Ajustes → Extensiones → Instalar extensión…** y elige el fichero. Para actualizar a una versión nueva, descarga el fichero otra vez y repite el doble clic.
 
-### Opción B · Claude Code (una línea)
+### B · Claude Code
 
 ```bash
 claude mcp add educa -- npx -y educa-navarra-mcp
 ```
 
-### Opción C · Otras aplicaciones de IA (Cursor, VS Code, Windsurf, LM Studio…)
+### C · Otras aplicaciones compatibles con MCP
 
-Necesitas [Node.js 20 o superior](https://nodejs.org). Añade esto a la configuración de servidores MCP de tu aplicación:
+Añade esto a la configuración de servidores MCP de tu aplicación:
 
 ```json
 {
@@ -70,57 +90,132 @@ Necesitas [Node.js 20 o superior](https://nodejs.org). Añade esto a la configur
 ```
 
 <details>
-<summary>¿Quieres que entre solo en Educa con las opciones B o C?</summary>
+<summary>Entrar solo en Educa con las opciones B o C</summary>
 
-Crea el fichero `credenciales.json` en la carpeta `.educa-mcp` de tu usuario (en Mac: `/Users/tu_usuario/.educa-mcp/`; en Windows: `C:\Users\tu_usuario\.educa-mcp\`):
+Crea el fichero `credenciales.json` en la carpeta `.educa-mcp` de tu usuario (Mac: `/Users/tu_usuario/.educa-mcp/`; Windows: `C:\Users\tu_usuario\.educa-mcp\`):
 
 ```json
 { "usuario": "tu_usuario_de_educa", "clave": "tu_contraseña" }
 ```
 
-No compartas ese fichero ni lo subas a ningún sitio. También vale poner las variables `EDUCA_USER` y `EDUCA_PASSWORD` en el bloque `env` de la configuración.
+No compartas ese fichero ni lo subas a ningún sitio. También valen las variables `EDUCA_USER` y `EDUCA_PASSWORD` en el bloque `env` de la configuración. El resto de ajustes, en [CONFIGURACION.md](https://github.com/vTanco/educa-navarra-mcp/blob/main/docs/CONFIGURACION.md).
 </details>
 
-## 💬 Cómo se usa
+## Primeros pasos
 
-Escríbele a Claude con tus palabras. Por ejemplo:
+Escríbele a Claude con tus palabras. La primera vez:
 
-> *Mete las notas de la 1ª evaluación de 1º de Bachillerato A, TIC, desde el Excel `notas_1BA.xlsx` de mi Escritorio.*
+1. **"Actualiza mis grupos."** Entra en Educa, lee tus grupos y asignaturas y los guarda en tu ordenador. Tarda unos segundos por grupo. Repítelo cuando cambien (curso nuevo, sustitución).
+2. **"Mete las notas de la 1ª evaluación de BTO N 1ºA, TIC."** Busca el fichero, abre la pantalla y te enseña la vista previa.
+3. **"Vale, escríbelas."** Rellena la pantalla de Educa sin guardar. Mira la ventana del navegador.
+4. **"Guarda."** Pulsa *Aceptar*. Si algo no te cuadra, no lo digas: pulsa tú *Cancelar* en la ventana de Educa y no se guarda nada.
 
-```mermaid
-flowchart LR
-    A["📄 Tu Excel"] --> B["🔐 Entra en Educa"]
-    B --> C["🧭 Va a Calificaciones<br/>grupo · materia · evaluación"]
-    C --> D["👀 Vista previa<br/>no cambia nada"]
-    D --> E["✍️ Escribe en pantalla<br/>sin guardar"]
-    E --> F{"¿Confirmas?"}
-    F -- "Sí" --> G["✅ Pulsa Aceptar"]
-    F -- "No" --> H["↩️ Cancelar"]
-```
+El cierre y la firma de la evaluación los sigues haciendo tú a mano, como siempre.
 
-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.
+### Qué puedes pedirle
 
-### Tu fichero de notas
+| Quieres… | Dile… |
+|---|---|
+| Ir directo a un grupo | *"Abre las notas de 1ºAB de Tecnología, 2ª evaluación."* |
+| Consultar sin tocar | *"Enséñame las notas de ESO 3ºDEFH, Matemáticas. No cambies nada."* |
+| Ver qué ficheros tienes | *"¿Qué ficheros de notas tengo?"* |
+| Usar otra columna | *"La nota está en la columna Media T1."* |
+| Aceptar un nombre dudoso | *"Sí, Maite Etxeberria es la misma."* |
+| Ver la pantalla | *"Haz una captura de la pantalla."* |
+| Aprender a preparar el Excel | *"¿Cómo preparo mi Excel de notas?"* |
+
+En Claude Desktop tienes además tres atajos en el menú **+** del chat: **Meter notas en Educa**, **Revisar mis notas en Educa** y **Cómo preparo mi Excel de notas**.
+
+### Nombres de grupo a medias
 
-Vale casi cualquier Excel o CSV con una fila por alumno. Por ejemplo:
+No hace falta escribir el nombre exacto de Educa. Si lo que dices encaja con un solo grupo, lo abre; si encaja con varios, te pregunta cuál.
+
+| Tus grupos en Educa | Le dices | Abre |
+|---|---|---|
+| ESO 1ºAB plu, ESO 1ºCD plu, ESO 1ºEF plu | *"1ºCD"* | ESO 1ºCD plu |
+| BTO N 1ºA, BTO N 2ºA | *"BTO N 1"* | BTO N 1ºA |
+| ESO 1ºAB plu, ESO 1ºCD plu, ESO 1ºEF plu | *"ESO 1"* | Te pregunta cuál de los tres |
+
+Lo mismo con la asignatura (*"Tecnología"*) y la evaluación (*"2"*, *"2a"*, *"Final"*). Si el grupo solo tiene una asignatura, no hace falta decirla.
+
+## Tu fichero de notas
+
+Vale casi cualquier Excel (`.xlsx`) o CSV con una fila por alumno y una columna de nota. Para que Claude lo encuentre solo:
+
+| | Recomendación | Ejemplo |
+|---|---|---|
+| **Carpeta** | Una para todo, con subcarpeta por curso | `Documentos/Notas Educa/2026-27/` |
+| **Nombre** | `EVALUACIÓN_GRUPO_MATERIA` | `1EV_BTO-1A_TIC.xlsx` |
+| **Contenido** | Cabeceras en la primera fila, una fila por alumno | *Apellidos · Nombre · Nota* |
 
 | Apellidos | Nombre | Nota |
 |---|---|---|
 | García López | Ana | 7 |
 | Pérez Martínez | Iñigo | 9 |
+| Etxeberria Goñi | Maite | |
 
-- Si tus columnas se llaman de otra forma, díselo a Claude: *"la nota está en la columna Media T1"*.
+- Si tus columnas se llaman de otra forma, díselo: *"la nota está en la columna Media T1"*.
 - Los alumnos con la nota en blanco se saltan.
-- **No redondea por ti**: si una nota no es válida para esa enseñanza, te avisa y no la escribe.
+- **No redondea por ti**: si una nota no vale para esa enseñanza, avisa y no la escribe.
+
+Todos los consejos, con ejemplos para interinos que cambian de centro, en la **[guía para preparar los Excel](https://github.com/vTanco/educa-navarra-mcp/blob/main/docs/BUENAS-PRACTICAS.md)**.
+
+### Así es la vista previa
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/vTanco/educa-navarra-mcp/main/assets/vista-previa.svg" width="100%" alt="Ejemplo de vista previa con datos inventados: tabla con alumno en el fichero, alumno en Educa, nota actual, nota nueva y estado.">
+</p>
+
+Los nombres que solo coinciden en parte se marcan como *aproximados* y no se escriben salvo que lo confirmes. También avisa de alumnos del fichero que no están en Educa y de alumnos de Educa que no tienen nota en el fichero.
+
+## Cualquier etapa
 
-## 🛡️ Privacidad y seguridad
+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): IN, SU, BI, NT, SB | El término (*NT*, *Notable*) o un número entero: 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 (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. Normativa de referencia (LOMLOE y órdenes forales de Navarra) en [normativa-evaluacion.md](https://github.com/vTanco/educa-navarra-mcp/blob/main/docs/normativa-evaluacion.md).
+
+## Qué hace solo y qué necesita tu permiso
+
+| Lo hace solo | Necesita que lo confirmes | No lo hace nunca |
+|---|---|---|
+| Entrar en Educa | Escribir notas en pantalla (tras la vista previa) | Cerrar o firmar una evaluación |
+| Leer grupos, alumnos y notas | Escribir un nombre aproximado | Bloquear, borrar o publicar |
+| Abrir la pantalla de Calificaciones | Pulsar *Aceptar* para guardar | Escribir en tus grupos sin notas |
+| Leer tu Excel | | Visitar webs que no sean de Educa |
+| Hacer capturas de pantalla | | Redondear una nota |
+
+Antes de escribir comprueba que la tabla no ha cambiado (mismo grupo y mismos alumnos) y, después, vuelve a leer cada campo. No toca campos bloqueados, como los de una evaluación ya cerrada.
+
+## Qué se ha probado
+
+Cada cambio pasa pruebas automáticas contra un **Educa simulado** (ESO, Bachillerato, FP y Apto / No apto), con todo el recorrido: entrar, abrir el grupo, vista previa, escribir y guardar. Además, se ha probado en el **Educa real** de un instituto de Navarra con una cuenta de profesor, sin guardar nada:
+
+| | ESO | Bachillerato | FP |
+|---|---|---|---|
+| Entrar y leer la tabla de notas | Probado en Educa real | Probado en Educa real | Solo simulador |
+| Actualizar grupos y abrir un grupo por nombre parcial | Probado en Educa real | Probado en Educa real | Solo simulador |
+| Detectar la escala | Probado en Educa real (términos) | Probado en Educa real (0 a 10) | Solo simulador |
+| Escribir en pantalla, sin guardar | Probado en Educa real | Probado en Educa real | Solo simulador |
+| Pulsar *Aceptar* para guardar | Solo simulador | Solo simulador | Solo simulador |
+
+En el Educa real se ha comprobado que, al escribir una nota, Educa muestra *Aceptar* y *Cancelar* y no guarda hasta pulsar uno de los dos; el guardado definitivo se ha dejado para cuando un docente lo haga con sus propias notas. ¿Lo has usado en tu enseñanza? Cuéntalo en [Issues](https://github.com/vTanco/educa-navarra-mcp/issues).
+
+## Privacidad
 
 - **Se ejecuta en tu ordenador.** No hay ningún servidor intermedio: el conector maneja un navegador en tu equipo, como harías tú.
 - **Tu contraseña no pasa por el chat.** Se guarda en tu ordenador y solo se escribe en el formulario de acceso de Educa.
 - **Solo visita Educa** (`*.navarra.es`). Cualquier otra dirección se bloquea.
-- **Ojo:** los nombres y notas que aparecen en la vista previa sí pasan por la conversación con la IA. Consulta la política de tu centro sobre el uso de IA con datos del alumnado. Más detalle en el [aviso legal](AVISO-LEGAL.md).
+- **Ojo:** los nombres y notas que aparecen en la vista previa sí pasan por la conversación con la IA. Consulta la política de tu centro sobre el uso de IA con datos del alumnado. Más detalle en el [aviso legal](https://github.com/vTanco/educa-navarra-mcp/blob/main/AVISO-LEGAL.md).
 
-## ❓ Preguntas frecuentes
+## Preguntas frecuentes
 
 <details>
 <summary><b>¿Puede guardar algo sin que yo me entere?</b></summary>
@@ -137,32 +232,28 @@ Sí. Deja usuario y contraseña vacíos y haz tú ese paso en la ventana que se
 <details>
 <summary><b>Me cambio de centro o de etapa el curso que viene.</b></summary>
 
-No tienes que hacer nada: el conector trabaja con los grupos y materias que tengas asignados en Educa en cada momento.
+Di *"actualiza mis grupos"* al empezar el curso y listo. La escala de notas la detecta en cada pantalla, así que no hay que configurar nada para pasar de ESO a Bachillerato o a FP.
 </details>
 
 <details>
-<summary><b>Me dice que no encuentra la tabla de notas.</b></summary>
+<summary><b>No encuentra mi grupo.</b></summary>
 
-Educa cambia a veces su diseño. Pide a Claude *"haz una captura de la pantalla"* y abre un aviso en [Issues](https://github.com/vTanco/educa-navarra-mcp/issues) **sin datos de alumnos** (tapa los nombres). Los ajustes avanzados están en [docs/CONFIGURACION.md](docs/CONFIGURACION.md).
+Pídele *"actualiza mis grupos"* y vuelve a intentarlo. Si tu nombre encaja con varios grupos, te dirá cuáles y te pedirá el nombre completo.
 </details>
 
 <details>
-<summary><b>¿Cómo lo desinstalo?</b></summary>
+<summary><b>Me dice que no encuentra la tabla de notas.</b></summary>
 
-En Claude Desktop: **Ajustes → Extensiones → Educa Navarra → Desinstalar**. Si quieres borrar también la sesión guardada del navegador, elimina la carpeta `.educa-mcp` de tu usuario.
+Educa cambia a veces su diseño. Pide a Claude *"haz una captura de la pantalla"* y abre un aviso en [Issues](https://github.com/vTanco/educa-navarra-mcp/issues) **sin datos de alumnos** (tapa los nombres). Los ajustes avanzados están en [CONFIGURACION.md](https://github.com/vTanco/educa-navarra-mcp/blob/main/docs/CONFIGURACION.md).
 </details>
 
-## 📍 Estado
-
-| Enseñanza | Leer notas | Escribir notas |
-|---|---|---|
-| ESO | ✅ probado en Educa real | ✅ probado en Educa real |
-| Bachillerato | ✅ probado en Educa real | 🧪 en pruebas |
-| FP Grado Medio y Superior | 🧪 en pruebas | 🧪 en pruebas |
+<details>
+<summary><b>¿Cómo lo desinstalo?</b></summary>
 
-¿Lo has probado en tu enseñanza? Cuéntalo en [Issues](https://github.com/vTanco/educa-navarra-mcp/issues).
+En Claude Desktop: **Ajustes → Extensiones → Educa Navarra → Desinstalar**. Si quieres borrar también la sesión guardada del navegador y la lista de grupos, elimina la carpeta `.educa-mcp` de tu usuario.
+</details>
 
-## 🧑‍💻 Para desarrolladores
+## Para desarrolladores
 
 ```bash
 git clone https://github.com/vTanco/educa-navarra-mcp.git
@@ -170,12 +261,18 @@ cd educa-navarra-mcp
 npm install
 npm run build
 npm test          # ficheros, conversión de notas y emparejamiento de nombres
-npm run smoke     # prueba completa contra un Educa simulado
+npm run smoke     # recorrido completo contra un Educa simulado
 npm run pack:mcpb # genera build/educa-navarra-mcp.mcpb para Claude Desktop
 ```
 
-Configuración avanzada, variables de entorno y herramientas: [docs/CONFIGURACION.md](docs/CONFIGURACION.md). Cómo publicar una versión: [docs/PUBLICAR.md](docs/PUBLICAR.md).
+| Documento | Contenido |
+|---|---|
+| [CONFIGURACION.md](https://github.com/vTanco/educa-navarra-mcp/blob/main/docs/CONFIGURACION.md) | Herramientas, variables de entorno, fichero de configuración y Educa simulado |
+| [BUENAS-PRACTICAS.md](https://github.com/vTanco/educa-navarra-mcp/blob/main/docs/BUENAS-PRACTICAS.md) | Guía para docentes sobre cómo preparar los Excel |
+| [normativa-evaluacion.md](https://github.com/vTanco/educa-navarra-mcp/blob/main/docs/normativa-evaluacion.md) | Resumen de la normativa de evaluación por etapa |
+| [PUBLICAR.md](https://github.com/vTanco/educa-navarra-mcp/blob/main/docs/PUBLICAR.md) | Cómo sacar una versión (GitHub y npm) |
+| [CHANGELOG.md](https://github.com/vTanco/educa-navarra-mcp/blob/main/CHANGELOG.md) | Cambios de cada versión |
 
 ---
 
-<sub>Licencia [MIT](LICENSE). Proyecto independiente y sin ánimo de lucro, sin relación con el Gobierno de Navarra. "Educa" es el nombre del portal educativo del Gobierno de Navarra y se usa solo para describir con qué funciona esta herramienta.</sub>
+<sub>Licencia [MIT](https://github.com/vTanco/educa-navarra-mcp/blob/main/LICENSE). Proyecto independiente y sin ánimo de lucro, sin relación con el Gobierno de Navarra. "Educa" es el nombre del portal educativo del Gobierno de Navarra y se usa solo para describir con qué funciona esta herramienta.</sub>

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.1",
   "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",