Tutor de Polaco con Modelo Local y MCP

Este manual explica cómo configurar y utilizar el sistema de tutoría de polaco con un modelo de lenguaje grande (LLM) ejecutándose localmente en tu máquina, integrado con VS Code a través del protocolo MCP (Model Context Protocol).

1. ¿Qué es esto?

Este proyecto implementa un tutor de polaco que utiliza un servidor MCP para comunicarse con un modelo de IA. El objetivo es proporcionar una experiencia de aprendizaje interactiva y personalizada sin depender de servicios en la nube, ahorrando tokens y garantizando la privacidad.

• MCP (Model Context Protocol): Un estándar abierto para que los modelos de IA interactúen con herramientas externas. Aquí, el servidor MCP (mcp/server.py) expone las herramientas pedagógicas del tutor (buscar conceptos, corregir respuestas, etc.).

• Modelo Local (Ollama): Ejecutamos un LLM directamente en tu máquina (ej. qwen3:8b) para procesar las solicitudes y usar las herramientas MCP.

• Continue (Extensión VS Code): Actúa como el cliente que conecta VS Code con el modelo local y el servidor MCP, permitiendo la interacción a través del chat.

Related MCP server: mcp-hello-world

2. Qué hay dentro

3. Requisitos Previos

Antes de empezar, asegúrate de tener lo siguiente instalado:

• VS Code: El editor de código.

• Python 3.10+: Para ejecutar el servidor MCP. Se recomienda usar el entorno virtual del proyecto (.venv).

• Homebrew: Gestor de paquetes para macOS (si no lo tienes, instálalo desde brew.sh).

• Git: Para clonar el repositorio.

4. Instalación

Sigue estos pasos para configurar el entorno:

4.1. Clonar el Repositorio

git clone https://github.com/tu_usuario/polski-tutor.git
cd polski-tutor

4.2. Entorno Python

Configura el entorno virtual del proyecto:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt # Si existe requirements.txt, o usa pyproject.toml

4.3. Instalar Ollama

Ollama es el motor que ejecuta modelos de lenguaje localmente.

# Instalar Ollama vía Homebrew
brew install ollama

# Iniciar el servicio de Ollama (se ejecutará en segundo plano)
brew services start ollama

# Verificar que Ollama está corriendo
ollama --version

4.4. Instalar la Extensión Continue

Busca e instala la extensión "Continue - open-source AI code agent" desde el Marketplace de VS Code.

5. Configuración

Ahora, configuraremos Continue para que use tu modelo local y el servidor MCP del tutor.

5.1. Descargar un Modelo Local

Necesitas un modelo que soporte tool-calling. qwen3:8b es una buena opción para tu hardware (Mac M4, 16 GB RAM).

# Descargar el modelo (puede tardar varios minutos)
ollama pull qwen3:8b

5.2. Configurar Continue

Crea la siguiente estructura de directorios y archivos dentro de la raíz de tu proyecto (polski-tutor/):

.continue/
├── mcpServers/
│   └── polski-tutor.yaml
├── models/
│   └── qwen3-local.yaml
└── rules/
    └── tutor-de-polaco.yaml

Contenido de los archivos:

.continue/models/qwen3-local.yaml

Este archivo define el modelo local que usaremos.

name: qwen3-local
model: qwen3:8b
provider: ollama
roles:
  - chat
  - edit
capabilities:
  - tool_use

.continue/mcpServers/polski-tutor.yaml

Este archivo configura el servidor MCP del tutor.

name: polski-tutor
type: stdio
# Rutas ABSOLUTAS a propósito. Continue no garantiza lanzar el proceso desde la
# raíz del repositorio, y con rutas relativas el servidor no arranca sin decir
# por qué: el modelo se queda sin herramientas y empieza a improvisar
# contenido, que es justo lo que este proyecto evita.
command: /Users/mauricioonoro/polski-tutor/.venv/bin/python
args:
  - /Users/mauricioonoro/polski-tutor/mcp/server.py
env:
  PYTHONUNBUFFERED: "1"

Comprueba que arranca desde otro directorio, que es como lo lanzará Continue:

cd /tmp && echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  | /Users/mauricioonoro/polski-tutor/.venv/bin/python \
    /Users/mauricioonoro/polski-tutor/mcp/server.py

Debe listar 12 herramientas.

.continue/rules/tutor-de-polaco.yaml

Este archivo define el comportamiento del asistente (el rol del tutor).

name: tutor-de-polaco
alwaysApply: true
rule: |
  (contenido completo en .continue/rules/tutor-de-polaco.yaml)

  Doce herramientas, en tres grupos:
    consulta      buscar_concepto, explicar_concepto, obtener_ejercicios,
                  cobertura_concepto
    progreso      corregir_respuesta, puntos_debiles, estado_alumno
    pronunciación escuchar, comprobar_escucha, ejercicio_pronunciacion,
                  comprobar_pronunciacion, audio_de

5.3. Qué modelos locales sirven

El tutor depende de que el modelo sepa invocar herramientas. Sin eso no consulta el grafo y se pone a inventar polaco, que es exactamente el fallo que todo este proyecto trata de impedir.

Hay una configuración lista por modelo en .continue/models/:

Para cambiar de modelo basta seleccionar otro en el desplegable de Continue. Descarga solo el que vayas a usar: ollama pull qwen3:14b.

Todas llevan contextLength: 16384, y no es un capricho. Ollama usa 4.096 por defecto aunque el modelo declare 40.960, y solo las definiciones de las 12 herramientas más las reglas ocupan ~1.450 tokens; una respuesta de obtener_ejercicios o explicar_concepto añade otros ~1.500. Al desbordar, lo primero que se trunca son las herramientas: el modelo olvida que las tiene y empieza a inventar gramática polaca a media sesión, sin dar ningún aviso.

Con 12 herramientas y un rol largo, un 8B va justo: tiende a responder de memoria en vez de llamar. Si lo notas, sube a 14B o pídeselo explícitamente.

5.4. Configuración de VS Code para MCP (Opcional, para Copilot)

Si también quieres que Copilot (u otros agentes que usen MCP) pueda acceder al servidor, crea el archivo .vscode/mcp.json en la raíz del proyecto:

{
  "servers": {
    "polski-tutor": {
      "type": "stdio",
      "command": "/Users/mauricioonoro/polski-tutor/.venv/bin/python",
      "args": ["/Users/mauricioonoro/polski-tutor/mcp/server.py"]
    }
  }
}

6. Uso en VS Code

Una vez configurado todo, puedes empezar a usar el tutor local:

1. Reinicia VS Code: Ejecuta Developer: Reload Window desde la paleta de comandos (Cmd+Shift+P).

2. Selecciona el modelo local: Abre el panel de Continue (icono en la barra lateral izquierda de VS Code). En la parte superior, selecciona el modelo qwen3-local.

3. Chatea con el tutor: Escribe tus preguntas o peticiones en la ventana de chat de Continue. El asistente usará el modelo local y las herramientas MCP automáticamente.

Los ejemplos de qué pedirle están en la sección siguiente.

El modelo local invocará las herramientas del MCP (buscar_concepto, obtener_ejercicios, corregir_respuesta, etc.) para responderte. Tu progreso se guardará en la base de datos polski.db (capa L3).

7. Qué decirle a la IA

Todos estos prompts están probados contra qwen3:8b en local y disparan la herramienta indicada. No hace falta nombrar las herramientas: basta pedir la cosa en lenguaje normal.

La primera sesión

Tú:  Veamos qué sé de polaco
IA:  [diagnostico_inicial] → ejercicios repartidos por nivel, de A1 a B1,
     de uno en uno. Cuando falles dos seguidos de un nivel, para: ya
     sabe dónde estás. Termina diciéndote qué reforzar.

Esto sitúa, no certifica: sale del pool de práctica. Los tests auténticos son finitos y de un solo uso limpio, así que gastarlos en el primer contacto tiraría la única medida fiable de nivel que existe.

Sesión típica

Tú:  ¿Qué tal voy y qué debería practicar hoy?
IA:  [estado_alumno + puntos_debiles] → te dice el concepto más flojo
     y sus prerrequisitos, por si el problema real está más abajo

Tú:  Vale, dame 10 ejercicios de eso
IA:  [obtener_ejercicios] → ítems reales, citando libro, lekcja y página

Tú:  1. kawę  2. mleka  3. chleb
IA:  [corregir_respuesta ×3] → corrige contra la clave DEL LIBRO y
     registra el avance; te dice en qué peldaño aceptó cada una

Tú:  Ahora pronunciación de las nasales
IA:  [ejercicio_pronunciacion] → «di kąt (ángulo), se confunde con kat
     (verdugo); graba las dos y pásame las rutas»

No hace falta el identificador exacto

El servidor resuelve el concepto por nombre, en español o en polaco:

• «locativo», «miejscownik» y gram.case.loc llevan al mismo sitio.

• Si pides un prefijo (gram.case.acc) te da el concepto más general.

• Si pides pronunciación de algo que no es un contraste fonético, te devuelve la lista de los que hay en vez de un error seco.

Esto está en el servidor a propósito: los modelos locales pequeños mandan el nombre en vez del id, y exigir el formato exacto los dejaba sin datos — momento en el que se ponen a improvisar gramática polaca, que es justo lo que este proyecto existe para impedir.

Cómo saber si de verdad está usando el MCP

Es el fallo más importante de todos, porque no da ningún error: si el servidor no está conectado, el modelo responde igual — leyendo los ficheros del repositorio que Continue indexa— y produce informes que suenan perfectamente creíbles y son falsos por completo.

Un caso real, en la primera sesión de un alumno que no había respondido nada:

«Basado en tu progreso actual (45% de ejercicios completados)… Has dominado el 78% de los conceptos básicos… Tu desempeño en tests de pronunciación alcanza el 82%… Usa el modo "contraste auditivo"…»

Todo inventado. Los números salían del README —donde describen el corpus, no al alumno— y el «modo contraste auditivo» no existe.

Tres señales de que NO está consultando:

1. Da porcentajes de progreso sin que hayas hecho ningún ejercicio.

2. No cita libro, lekcja y página. La cita es la prueba de que los datos son reales.

3. Menciona «modos» o funciones que no están entre las doce herramientas.

Comprobación en 10 segundos. Pregúntale «¿qué tal voy?» en una sesión nueva. La respuesta correcta es que es tu primera sesión y no hay progreso. Cualquier porcentaje es invención.

Si está inventando:

# 1. ¿arranca el servidor?  Debe listar 12 herramientas
cd /tmp && echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  | /Users/mauricioonoro/polski-tutor/.venv/bin/python \
    /Users/mauricioonoro/polski-tutor/mcp/server.py

# 2. recarga VS Code tras cualquier cambio en .continue/
#    Cmd+Shift+P -> Developer: Reload Window

En el panel de Continue, el servidor polski-tutor debe aparecer conectado y con sus herramientas listadas. Si no está, el tutor no consulta nada.

Si el modelo responde sin usar las herramientas

Le pasa a los modelos de 8B con un rol largo. Tres remedios, de menor a mayor:

1. Pídeselo explícito: «usa obtener_ejercicios para el acusativo».

2. Empieza la sesión con «¿qué tal voy?»: una llamada exitosa lo encarrila.

3. Sube a qwen3:14b, que obedece mejor instrucciones largas.

Si responde en polaco inventado y sin citar libro ni página, no está usando el MCP. La cita es la señal de que los datos son reales.

8. Uso desde la terminal (sin IA)

polski estado                     # resumen y nivel estimado
polski explicar gram.case.loc     # qué es, de qué depende, dónde estudiarlo
polski practicar --concepto ...   # sesión de práctica con corrección
polski debiles                    # qué reforzar, con sus prerrequisitos
polski test-autentico             # examen del pool reservado

Como MCP: apunta tu cliente a mcp/server.py. Doce herramientas, sin dependencias externas.

9. Decisiones que conviene conocer antes de tocar nada

Tres capas separadas por ciclo de vida. L1 es la ontología curada a mano; L2 el contenido extraído, que se puede borrar y regenerar entero; L3 tu progreso. Estudiar solo escribe en L3, así que reiniciarlo no deshace nada del grafo — verificado. Cada persona puede tener su propio fichero de progreso (tutor/alumno.py) compartiendo un grafo que cuesta horas construir.

La gramática la etiqueta Morfeusz, no el LLM. Si la respuesta es kawę, el analizador morfológico devuelve kawa / subst:sg:acc:f con certeza. El 54 % de las formas son ambiguas (kawy es genitivo singular y nominativo plural), así que Stanza desambigua por contexto y resuelve el 46 % de los casos; el resto queda marcado como pendiente en vez de elegirse al azar.

Las respuestas vienen del libro. Todas salen del Klucz do ćwiczeń. Las de los manuales están en su libro del profesor, no en el propio manual — se verificó por coincidencia de contenido, no por numeración. El tutor nunca inventa una respuesta: si no la tiene, lo dice.

Práctica y evaluación no se mezclan. Los testy osiągnięć están marcados held_out y las vistas los excluyen del pool de práctica. Si el tutor entrena con lo mismo con que evalúa, el nivel mide memoria y no competencia.

El nivel se ancla a evidencia. Dominar conceptos sueltos no es tener un nivel: el MCEV se define por lo que uno sabe hacer. Sin tests auténticos ni producción evaluada, nivel_reportado() devuelve "sin evidencia suficiente" — esa negativa es una funcionalidad, no una carencia.

Los agujeros se declaran. 30 conceptos no tienen material, todos temas léxicos sueltos que el índice nombra pero el texto no desarrolla. Ninguno es gramatical. v_concept_coverage los expone para que el tutor lo diga en vez de improvisar.

10. Pronunciación

Dos mitades, ambas funcionando y validadas sobre grabación humana real:

Percepción (tutor/percepcion.py) — se reproduce una palabra y se elige cuál de las dos era. Medición exacta: el sistema generó el audio, así que conoce la respuesta y no interviene ningún reconocedor que pueda dar un falso aprobado. 20 pares mínimos, todos verificados como audibles.

Producción (tutor/pronunciacion.py) — el alumno graba las DOS palabras de un par y se comprueba si las pronuncia distinto. 20/20 sobre grabación real.

Dos cosas que no funcionan y están medidas, para que nadie las reintente:

Y es además la pregunta correcta: lo que importa no es si una palabra suelta se acerca a un ideal abstracto, sino si el alumno produce el contraste. Si dice kąt y kat igual, no lo tiene, aunque ambas suenen razonables por separado.

Por qué un TTS mejor no arreglaría el 52 %

La sospecha natural es que la voz sintética no habla suficiente polaco. Medido, no es eso — distancia fonémica media sobre 10 pares:

El ruido supera a la señal. La misma palabra dicha por dos hablantes difiere más que dos palabras distintas dichas por el mismo. Y el TTS separa los pares tan bien como el humano (2,3 frente a 2,2): su pronunciación no es el problema.

El obstáculo es la variabilidad entre hablantes, no la calidad de la síntesis, así que cambiar de voz —incluso a un nativo grabado en estudio— no lo resuelve. Se arreglaría con representaciones normalizadas por hablante o alineamiento forzado con scoring GOP, pero eso es mucha complejidad para llegar donde el método de contraste ya llega.

11. Verificación

Los scripts de spike/ son la suite de comprobación; cada uno mide una parte con números reales sobre el corpus:

python3 spike/check_layout.py         # reconstrucción de layout
python3 spike/check_morph.py          # cobertura morfológica (99,3 %)
python3 spike/check_disambiguate.py   # desambiguación contextual
python3 spike/check_exercises.py      # segmentación vs. clave del libro
python3 spike/check_piloto.py         # calidad de la pasada LLM

12. Reconstruir el corpus desde cero

uv venv && source .venv/bin/activate
uv pip install morfeusz2 stanza transformers soundfile phonemizer
python3 graph/cargar_todo.py        # construye polski.db
python3 ingest/run_lote.py          # pasada LLM sobre el corpus (~2,5 h)
python3 -c "from graph import cargar_llm; cargar_llm.cargar()"

Los PDFs viven en iCloud y se tratan como solo lectura; config/books.json los referencia por ruta. El corpus extraído no se versiona: es material con copyright y se regenera desde los PDFs.

13. Mantenimiento

• Cambiar de modelo: Si deseas probar otro modelo local (ej. qwen3:14b o mistral-nemo:12b), solo necesitas descargarlo con ollama pull <nombre_modelo> y actualizar la línea model: qwen3:8b en .continue/models/qwen3-local.yaml.

• Reinicio del progreso: Si necesitas resetear tu avance en el tutor (ej. para empezar de cero), ejecuta el siguiente comando en la terminal del proyecto:

  .venv/bin/python -c "from tutor import alumno; import sqlite3; con = sqlite3.connect('polski.db'); alumno.reiniciar(con)"

  Esto borrará los datos de la capa L3 (intentos, dominio_concepto, etc.) pero conservará el grafo principal del proyecto.