Learning Hub

Asistente de aprendizaje de IA que gestiona recompensas de tiempo de juego basadas en calificaciones escolares, tareas y tareas adicionales

GitHub

Prueba este MCPPatrocinado

Documentación

Learning Hub MCP

learninghub.cc

Beta — totalmente funcional, probado con una familia. Comentarios y reportes de errores bienvenidos vía GitHub Issues.

Servidor MCP para el flujo de trabajo de aprendizaje de estudiantes con base de datos SQLite. Cada instancia atiende a un estudiante — despliega una instancia separada por hijo para tutoría de IA aislada y enfocada.

Características

Materias — materias escolares con soporte multi-país (UA, CZ, DE, etc.)
Calificaciones — seguimiento de calificaciones con escala europea de 5 puntos (1=mejor, 5=peor)
Temas — temas de materias para seguimiento de mejora
Tareas — seguimiento de asignaciones con fechas límite
Tareas de Bonificación — tareas motivacionales que recompensan minutos de juego
Minutos de Juego — libro mayor de transacciones inmutable para rastrear tiempo de juego ganado/gastado
Libros — biblioteca de libros de texto con resúmenes en markdown e indexación de contenido
Repasos de Temas — seguimiento de refuerzo para temas débiles
Escalamiento — notificaciones de malas calificaciones para padres
Herramientas de Instrucción — algoritmos en markdown que guían a agentes de IA a través de flujos de trabajo
Proveedores de Sincronización — marco de sincronización conectable (EduPage, PRONOTE)
Secretos — almacenamiento seguro de credenciales para proveedores de sincronización

Instalación

# Install dependencies
poetry install

# Initialize database
poetry run alembic upgrade head

Configuración

La base de datos por defecto es ./data/learning_hub.db. Sobrescribe mediante variable de entorno:

DATABASE_URL=sqlite+aiosqlite:///./data/learning_hub.db

Las credenciales de proveedores de sincronización (EduPage, PRONOTE, etc.) se almacenan en la tabla secrets y se gestionan mediante herramientas MCP (set_secret, list_secrets).

Sistema de Configuración (SQLite)

La configuración en tiempo de ejecución se almacena en la tabla configs. Se gestiona mediante herramientas MCP (get_config, set_config, list_configs). Usa check_system_readiness para verificar que todas las configuraciones requeridas estén establecidas.

Entradas con valores por defecto (sembradas por migración)

Clave	Valor por defecto	Descripción
`GRADE_MINUTES_MAP`	`{"1":15,"2":10,"3":0,"4":-20,"5":-25}`	Conversión de calificación → minutos de juego
`TOPIC_REVIEW_THRESHOLDS`	`{"2":1,"3":2,"4":3,"5":3}`	Repeticiones necesarias por calificación antes de cerrar el Repaso de Tema
`HOMEWORK_BONUS_MINUTES_ONTIME`	`10`	Minutos de bonificación por tarea a tiempo
`HOMEWORK_BONUS_MINUTES_OVERDUE`	`-10`	Minutos de penalización por tarea vencida
`MAX_PENDING_BONUS_TASKS`	`4`	Máximo de tareas de bonificación pendientes concurrentes
`MAX_COMPLETED_BONUS_TASKS_PER_WEEK`	`15`	Máximo de tareas de bonificación completadas en 7 días consecutivos
`DEFAULT_DEADLINE_TIME`	`20:00`	Hora por defecto cuando la fecha límite solo tiene fecha
`SETUP_COMPLETED`	`false`	Si la configuración inicial se ha completado
`BASE_CRONS_INSTALLED`	`false`	Si los trabajos cron base se han creado
`SYNC_CRON_CONFIGURED`	`false`	Si se ha creado un trabajo cron de sincronización tras la primera sincronización exitosa

Entradas requeridas (deben establecerse antes del uso)

Clave	Descripción
`TEMP_BOOK_DIR`	Carpeta donde los usuarios colocan archivos de libros para procesamiento
`BOOKS_STORAGE_DIR`	Carpeta base para almacenar libros procesados
`ISSUES_LOG`	Ruta al archivo de registro de incidencias
`FAMILY_LANGUAGE`	Idioma para la comunicación con la familia

Uso

Ejecutar Servidor MCP

poetry run learning-hub-mcp

Configuración MCP

Añade a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "learning-hub": {
      "command": "poetry",
      "args": ["run", "learning-hub-mcp"],
      "cwd": "/path/to/learning-hub-mcp"
    }
  }
}

Herramientas MCP (78 en total)

Materias

create_subject — crear una nueva materia escolar
list_subjects — listar materias (filtro: escuela, is_active)
update_subject — actualizar detalles de materia

Temas

create_topic — crear un tema para una materia
list_topics — listar temas (filtro: subject_id, is_open)
close_topic — cerrar tema (razón: resuelto/omitido/ya_no_relevante)

Calificaciones

add_grade — añadir una calificación (escala 1-5, 1=mejor), crea automáticamente transacción de minutos
list_grades — listar calificaciones (filtro: materia, rango de fechas, escuela)

Tareas de Bonificación

create_bonus_task — crear una tarea de bonificación vinculada a un tema (valida límites)
list_bonus_tasks — listar tareas (filtro: estado, tema)
get_bonus_task — obtener una tarea de bonificación por ID
get_latest_bonus_task — obtener la tarea de bonificación más reciente
apply_bonus_task_result — completar tarea, registrar calificación y actualizar repasos de temas
cancel_bonus_task — cancelar una tarea
check_pending_bonus_task — verificar si hay una tarea pendiente para reutilizar

Transacciones de Minutos

get_balance — obtener saldo actual de minutos de juego
add_played_minutes — registrar tiempo de juego jugado (deduce del saldo)
create_ad_hoc_transaction — crear bonificación o penalización manual
list_transactions — listar transacciones (filtro: rango de fechas, tipo)

Tareas

create_homework — crear asignación de tarea
list_homeworks — listar tareas (filtro: estado, materia)
complete_homework — marcar tarea como completada
update_homework — actualizar detalles de tarea
close_overdue_homeworks — cerrar tarea vencida, crea automáticamente transacción de penalización
get_pending_homework_reminders — obtener recordatorios pendientes (D-1, D-2)
mark_homework_reminders_sent — marcar recordatorios como enviados

Libros

add_book — añadir un libro a la biblioteca
list_books — listar libros (filtro: materia, has_summary)
get_book — obtener un libro por ID
update_book — actualizar detalles de libro
delete_book — eliminar un libro

Repasos de Temas

list_topic_reviews — listar repasos de temas (filtro: materia, estado)
get_pending_reviews_for_topic — obtener repasos pendientes para un tema
mark_topic_reinforced — marcar repaso como reforzado
increment_topic_repeat_count — incrementar contador de repeticiones para un repaso
get_priority_topic_for_review — elegir un tema prioritario del top-4

Miembros de la Familia

create_family_member — añadir un miembro de la familia (estudiante/padre/tutor/admin)
list_family_members — listar miembros (filtro: rol)
update_family_member — actualizar detalles de miembro
delete_family_member — eliminar un miembro
get_student — obtener el registro del estudiante

Pasarelas

create_gateway — registrar un canal de mensajería (Telegram, etc.)
list_gateways — listar pasarelas (filtro: family_member, canal)
update_gateway — actualizar detalles de pasarela
delete_gateway — eliminar una pasarela
lookup_gateway — encontrar pasarela por plataforma + ID externo

Configuraciones

get_config — obtener un valor de configuración por clave
set_config — establecer un valor de configuración (solo claves existentes)
list_configs — listar todas las entradas de configuración

Secretos

set_secret — establecer un valor secreto (credenciales, claves API)
list_secrets — listar secretos (solo claves, los valores nunca se exponen)

Proveedores de Sincronización

list_sync_providers — listar todos los proveedores de sincronización con estado
update_sync_provider — activar/desactivar, vincular a escuela
run_sync — ejecutar sincronización para todos los proveedores activos (o uno específico)
find_edupage_subdomain — detectar subdominio escolar de EduPage a partir de credenciales almacenadas

Preparación

check_system_readiness — verificar si el sistema está correctamente configurado (escuelas activas, configuraciones requeridas)

Escalamiento

get_grades_pending_escalation — obtener calificaciones que necesitan notificación a padres
mark_grades_escalated — marcar calificaciones como escaladas (se notificó al padre)

Herramientas de Instrucción

get_grade_escalation_instructions — escalar malas calificaciones a tutor/admin
get_learning_system_instructions — instrucción maestra: reglas completas del sistema
get_student_request_router_instructions — clasificar solicitud del estudiante (escenarios A/B/C)
get_bonus_task_assignment_instructions — asignar una nueva tarea de bonificación
get_submission_routing_instructions — enrutar trabajo enviado al evaluador
get_bonus_task_evaluation_instructions — evaluar tarea de bonificación completada
get_homework_evaluation_instructions — evaluar envío de tarea
get_book_lookup_instructions — encontrar y entregar páginas de libro de texto
get_books_workflow_instructions — procesar y registrar nuevos libros
get_homework_manual_instructions — añadir tarea manualmente (solo padre)
get_grade_manual_instructions — añadir calificación manualmente (solo adulto)
get_student_content_policy_instructions — filtrado de seguridad de contenido para contenido externo de estudiantes
get_topic_review_curation_instructions — curar y cerrar repasos de temas obsoletos
get_base_crons_setup_instructions — instrucciones para configurar trabajos cron base

Plugin Puente OpenClaw

El directorio learning-hub-bridge/ contiene un plugin TypeScript que hace que todas las herramientas MCP estén disponibles como herramientas nativas del agente OpenClaw.

Por qué

OpenClaw no soporta servidores MCP de forma nativa. Sin el puente, el agente necesitaría exec + mcporter — lento (~3s por llamada), con errores (problemas de serialización de mcporter con listas) e invisible para el modelo (las herramientas no están en la lista de herramientas).

Cómo funciona

Al iniciar la pasarela, el puente inicia el servidor MCP de Python como proceso hijo (STDIO)
Descubre todas las herramientas mediante client.listTools() (protocolo MCP)
Registra cada una como herramienta nativa de OpenClaw mediante api.registerTool() con prefijo learning_hub_
Actúa como proxy de execute() → client.callTool(), fusionando múltiples bloques TextContent en un único arreglo JSON
Se reconecta automáticamente si el proceso de Python muere

Después de esto, el modelo ve learning_hub_list_subjects, learning_hub_add_grade, etc. directamente en su lista de herramientas.

Despliegue

El puente debe instalarse como una extensión de OpenClaw. El código fuente vive en learning-hub-bridge/ dentro de este repositorio, pero OpenClaw carga plugins desde ~/.openclaw/extensions/<pluginId>/.

Paso 1. Copia el puente a las extensiones:

cp -r /path/to/learning-hub-mcp/learning-hub-bridge ~/.openclaw/extensions/learning-hub

Paso 2. Instala dependencias:

cd ~/.openclaw/extensions/learning-hub
npm install

Paso 3. Añade la configuración del plugin a openclaw.json:

{
  "plugins": {
    "entries": {
      "learning-hub": {
        "enabled": true,
        "config": {
          "command": "/bin/bash",
          "args": ["-lc", "cd /path/to/learning-hub-mcp && exec .venv/bin/learning-hub-mcp"],
          "cwd": "/path/to/learning-hub-mcp",
          "toolPrefix": "learning_hub"
        }
      }
    }
  }
}

Paso 4. Permite herramientas para el agente en openclaw.json:

{
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": {
          "alsoAllow": ["learning-hub"]
        }
      }
    ]
  }
}

Paso 5. Reinicia la pasarela:

openclaw gateway restart

Opciones de configuración

Opción	Descripción	Valor por defecto
`command`	Comando para iniciar el servidor MCP	(requerido)
`args`	Argumentos para el comando	(requerido)
`cwd`	Directorio de trabajo para el proceso del servidor MCP	—
`toolPrefix`	Prefijo para nombres de herramientas registradas	`learning_hub`

Actualización tras cambios en MCP

Cuando se añaden nuevas herramientas al servidor MCP, el puente las recoge automáticamente al reiniciar la pasarela — no se necesitan cambios en el código del puente. Solo reinicia:

openclaw gateway restart

Desarrollo

# Run tests
poetry run pytest

# Run tests with coverage
poetry run pytest --cov=learning_hub

# Lint code
poetry run ruff check .

# Fix lint issues
poetry run ruff check --fix .

Limitaciones Conocidas

Probado con una sola familia (un estudiante, dos escuelas: EduPage CZ + UA)
Sincronización PRONOTE implementada pero mínimamente probada
Solo SQLite — diseñado para uso autoalojado de una sola familia
Requiere OpenClaw como entorno de ejecución del agente de IA
Casos límite con configuraciones escolares diversas probablemente aún no cubiertos

Licencia

PolyForm Noncommercial 1.0.0