Learning Hub

Assistente de aprendizado de IA que gerencia recompensas de tempo de jogo com base em notas escolares, tarefas de casa e tarefas bônus

GitHub

Experimente este MCPPatrocinado

Documentação

Learning Hub MCP

learninghub.cc

Beta — totalmente funcional, testado com uma família. Feedback e relatórios de bugs são bem-vindos via GitHub Issues.

Servidor MCP para o fluxo de aprendizado do estudante com banco de dados SQLite. Cada instância atende um estudante — implante uma instância separada por criança para tutoria de IA isolada e focada.

Recursos

Disciplinas — disciplinas escolares com suporte a múltiplos países (UA, CZ, DE, etc.)
Notas — acompanhamento de notas com escala europeia de 5 pontos (1=melhor, 5=pior)
Tópicos — tópicos de disciplinas para acompanhamento de melhoria
Tarefas de Casa — acompanhamento de tarefas com prazos
Tarefas Bônus — tarefas motivacionais que recompensam minutos de jogo
Minutos de Jogo — livro-razão imutável de transações para acompanhar tempo de jogo ganho/gasto
Livros — biblioteca de livros didáticos com resumos em markdown e indexação de conteúdo
Revisões de Tópicos — acompanhamento de reforço para tópicos fracos
Escalonamento — notificações de notas ruins para os pais
Ferramentas de Instrução — algoritmos em markdown que guiam agentes de IA por fluxos de trabalho
Provedores de Sincronização — estrutura de sincronização plugável (EduPage, PRONOTE)
Segredos — armazenamento seguro de credenciais para provedores de sincronização

Instalação

# Install dependencies
poetry install

# Initialize database
poetry run alembic upgrade head

Configuração

O banco de dados usa como padrão ./data/learning_hub.db. Substitua via variável de ambiente:

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

As credenciais dos provedores de sincronização (EduPage, PRONOTE, etc.) são armazenadas na tabela secrets e gerenciadas por meio das ferramentas MCP (set_secret, list_secrets).

Sistema de Configuração (SQLite)

A configuração em tempo de execução é armazenada na tabela configs. Gerenciada por meio das ferramentas MCP (get_config, set_config, list_configs). Use check_system_readiness para verificar se todas as configurações obrigatórias estão definidas.

Entradas com padrões (semeadas por migração)

Chave	Padrão	Descrição
`GRADE_MINUTES_MAP`	`{"1":15,"2":10,"3":0,"4":-20,"5":-25}`	Conversão de nota → minutos de jogo
`TOPIC_REVIEW_THRESHOLDS`	`{"2":1,"3":2,"4":3,"5":3}`	Repetições necessárias por nota antes de fechar a Revisão de Tópico
`HOMEWORK_BONUS_MINUTES_ONTIME`	`10`	Minutos bônus para tarefa de casa no prazo
`HOMEWORK_BONUS_MINUTES_OVERDUE`	`-10`	Minutos de penalidade para tarefa de casa atrasada
`MAX_PENDING_BONUS_TASKS`	`4`	Máximo de tarefas bônus pendentes simultâneas
`MAX_COMPLETED_BONUS_TASKS_PER_WEEK`	`15`	Máximo de tarefas bônus concluídas em 7 dias corridos
`DEFAULT_DEADLINE_TIME`	`20:00`	Horário padrão quando o prazo tem apenas uma data
`SETUP_COMPLETED`	`false`	Se a configuração inicial foi concluída
`BASE_CRONS_INSTALLED`	`false`	Se os jobs base do cron foram criados
`SYNC_CRON_CONFIGURED`	`false`	Se um job de sincronização do cron foi criado após a primeira sincronização bem-sucedida

Entradas obrigatórias (devem ser definidas antes do uso)

Chave	Descrição
`TEMP_BOOK_DIR`	Pasta onde os usuários colocam arquivos de livros para processamento
`BOOKS_STORAGE_DIR`	Pasta base para armazenar livros processados
`ISSUES_LOG`	Caminho para o arquivo de registro de problemas
`FAMILY_LANGUAGE`	Idioma para comunicação com a família

Uso

Executar o Servidor MCP

poetry run learning-hub-mcp

Configuração MCP

Adicione à configuração do seu cliente MCP:

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

Ferramentas MCP (78 no total)

Disciplinas

create_subject — criar uma nova disciplina escolar
list_subjects — listar disciplinas (filtro: escola, is_active)
update_subject — atualizar detalhes da disciplina

Tópicos

create_topic — criar um tópico para uma disciplina
list_topics — listar tópicos (filtro: subject_id, is_open)
close_topic — fechar tópico (motivo: resolvido/pulado/não_relevante)

Notas

add_grade — adicionar uma nota (escala 1-5, 1=melhor), cria automaticamente transação de minutos
list_grades — listar notas (filtro: disciplina, intervalo de datas, escola)

Tarefas Bônus

create_bonus_task — criar uma tarefa bônus vinculada a um tópico (valida limites)
list_bonus_tasks — listar tarefas (filtro: status, tópico)
get_bonus_task — obter uma tarefa bônus por ID
get_latest_bonus_task — obter a tarefa bônus mais recente
apply_bonus_task_result — concluir tarefa, registrar nota e atualizar revisões de tópicos
cancel_bonus_task — cancelar uma tarefa
check_pending_bonus_task — verificar se há uma tarefa pendente para reutilizar

Transações de Minutos

get_balance — obter saldo atual de minutos de jogo
add_played_minutes — registrar tempo de jogo jogado (deduz do saldo)
create_ad_hoc_transaction — criar bônus ou penalidade manual
list_transactions — listar transações (filtro: intervalo de datas, tipo)

Tarefas de Casa

create_homework — criar tarefa de casa
list_homeworks — listar tarefas de casa (filtro: status, disciplina)
complete_homework — marcar tarefa de casa como concluída
update_homework — atualizar detalhes da tarefa de casa
close_overdue_homeworks — fechar tarefa de casa atrasada, cria automaticamente transação de penalidade
get_pending_homework_reminders — obter lembretes devidos (D-1, D-2)
mark_homework_reminders_sent — marcar lembretes como enviados

Livros

add_book — adicionar um livro à biblioteca
list_books — listar livros (filtro: disciplina, has_summary)
get_book — obter um livro por ID
update_book — atualizar detalhes do livro
delete_book — excluir um livro

Revisões de Tópicos

list_topic_reviews — listar revisões de tópicos (filtro: disciplina, status)
get_pending_reviews_for_topic — obter revisões pendentes para um tópico
mark_topic_reinforced — marcar revisão como reforçada
increment_topic_repeat_count — incrementar contagem de repetições para uma revisão
get_priority_topic_for_review — escolher um tópico prioritário do top-4

Membros da Família

create_family_member — adicionar um membro da família (estudante/pai/tutor/admin)
list_family_members — listar membros (filtro: função)
update_family_member — atualizar detalhes do membro
delete_family_member — excluir um membro
get_student — obter o registro do estudante

Gateways

create_gateway — registrar um canal de mensagens (Telegram, etc.)
list_gateways — listar gateways (filtro: family_member, canal)
update_gateway — atualizar detalhes do gateway
delete_gateway — excluir um gateway
lookup_gateway — encontrar gateway por plataforma + ID externo

Configurações

get_config — obter um valor de configuração por chave
set_config — definir um valor de configuração (somente chaves existentes)
list_configs — listar todas as entradas de configuração

Segredos

set_secret — definir um valor secreto (credenciais, chaves de API)
list_secrets — listar segredos (somente chaves, valores nunca expostos)

Provedores de Sincronização

list_sync_providers — listar todos os provedores de sincronização com status
update_sync_provider — ativar/desativar, vincular à escola
run_sync — executar sincronização para todos os provedores ativos (ou um específico)
find_edupage_subdomain — detectar subdomínio da escola EduPage a partir das credenciais armazenadas

Prontidão

check_system_readiness — verificar se o sistema está configurado corretamente (escolas ativas, configurações obrigatórias)

Escalonamento

get_grades_pending_escalation — obter notas que precisam de notificação aos pais
mark_grades_escalated — marcar notas como escalonadas (pais foram notificados)

Ferramentas de Instrução

get_grade_escalation_instructions — escalonar notas ruins para tutor/admin
get_learning_system_instructions — instrução mestre: regras completas do sistema
get_student_request_router_instructions — classificar solicitação do estudante (cenários A/B/C)
get_bonus_task_assignment_instructions — atribuir uma nova tarefa bônus
get_submission_routing_instructions — encaminhar trabalho enviado para o avaliador
get_bonus_task_evaluation_instructions — avaliar tarefa bônus concluída
get_homework_evaluation_instructions — avaliar envio de tarefa de casa
get_book_lookup_instructions — encontrar e entregar páginas do livro didático
get_books_workflow_instructions — processar e registrar novos livros
get_homework_manual_instructions — adicionar tarefa de casa manualmente (somente pais)
get_grade_manual_instructions — adicionar nota manualmente (somente adultos)
get_student_content_policy_instructions — filtragem de segurança de conteúdo para conteúdo externo do estudante
get_topic_review_curation_instructions — selecionar e fechar revisões de tópicos desatualizadas
get_base_crons_setup_instructions — instruções para configurar jobs base do cron

Plugin de Ponte OpenClaw

O diretório learning-hub-bridge/ contém um plugin TypeScript que disponibiliza todas as ferramentas MCP como ferramentas nativas do agente OpenClaw.

Por quê

O OpenClaw não suporta servidores MCP nativamente. Sem a ponte, o agente precisaria de exec + mcporter — lento (~3s por chamada), com bugs (problemas de serialização do mcporter com listas) e invisível para o modelo (ferramentas não aparecem na lista de ferramentas).

Como funciona

Na inicialização do gateway, a ponte inicia o servidor MCP Python como processo filho (STDIO)
Descobre todas as ferramentas via client.listTools() (protocolo MCP)
Registra cada uma como ferramenta nativa do OpenClaw via api.registerTool() com prefixo learning_hub_
Faz proxy de execute() → client.callTool(), mesclando múltiplos blocos TextContent em um único array JSON
Reconecta automaticamente se o processo Python morrer

Depois disso, o modelo vê learning_hub_list_subjects, learning_hub_add_grade, etc. diretamente na sua lista de ferramentas.

Implantação

A ponte deve ser instalada como uma extensão do OpenClaw. O código-fonte está em learning-hub-bridge/ dentro deste repositório, mas o OpenClaw carrega plugins de ~/.openclaw/extensions/<pluginId>/.

Passo 1. Copie a ponte para as extensões:

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

Passo 2. Instale as dependências:

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

Passo 3. Adicione a configuração do plugin ao 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"
        }
      }
    }
  }
}

Passo 4. Permita ferramentas para o agente em openclaw.json:

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

Passo 5. Reinicie o gateway:

openclaw gateway restart

Opções de configuração

Opção	Descrição	Padrão
`command`	Comando para iniciar o servidor MCP	(obrigatório)
`args`	Argumentos para o comando	(obrigatório)
`cwd`	Diretório de trabalho para o processo do servidor MCP	—
`toolPrefix`	Prefixo para nomes de ferramentas registrados	`learning_hub`

Atualização após mudanças no MCP

Quando novas ferramentas são adicionadas ao servidor MCP, a ponte as detecta automaticamente na reinicialização do gateway — nenhuma mudança no código da ponte é necessária. Basta reiniciar:

openclaw gateway restart

Desenvolvimento

# 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 .

Limitações Conhecidas

Testado com uma única família (um estudante, duas escolas: EduPage CZ + UA)
Sincronização PRONOTE implementada, mas minimamente testada
Somente SQLite — projetado para uso self-hosted de família única
Requer OpenClaw como runtime do agente de IA
Casos extremos com configurações escolares diversas provavelmente ainda não cobertos

Licença

PolyForm Noncommercial 1.0.0