Ateliê — MCP Tutor

Um MVP local de aprendizagem ativa. O tutor conversa no Codex, Claude Code ou outro cliente MCP; o aluno pratica em um painel no navegador. O tutor pode adicionar atividades durante a aula, ler as tentativas e devolver feedback.

Versão 0.5. Laboratório local, aulas de Python/Java e revisões espaçadas, integrados ao chat, editor e controle de etapas da versão anterior.

Ciclo da experiência: entender → prever → praticar → explicar → aplicar em outro contexto → revisar depois.

Experimentar

Requer Node.js 22 ou superior. Para executar programas, esta versão usa Linux, Bubblewrap, Python 3 e libseccomp. Python é necessário também para preparar o ambiente isolado. Java (JDK), GCC e G++ são opcionais; o painel detecta o que está disponível em /usr/bin, /usr/local/bin ou /bin com destino em /usr. Na pasta do projeto:

npm install
npm start

Abra o painel local e clique em Escolher exemplo para explorar HTML, Python ou Java ou em Nova conversa para iniciar uma aula com o agente. A aula “Sua primeira página” demonstra o ciclo completo com HTML. No modo exemplo não há um modelo de IA respondendo; explicações abertas ficam registradas, sem uma correção simulada.

Para uma primeira execução reproduzível, siga o guia operacional. Ele cobre pré-requisitos, conexão do cliente de IA, rotina de uma aula e recuperação de falhas. Antes de considerar uma instalação saudável, execute npm run quality e npm run doctor. Use npm run backup antes de atualizações para criar uma cópia validada e versionada do histórico local.

O painel tem editor, prévia de HTML/CSS, perguntas, dicas graduais, diagramas com elementos selecionáveis e gráficos de barras. Notas do aluno são privadas, ficam em localStorage por sessão e não são enviadas ao tutor; tentativas, atividades e feedback ficam no histórico local da sessão. Atividades e histórico ficam no painel Estudo. Os exemplos comentados de blocos lesson também aparecem no centro da aula para leitura antes da prática. A arquitetura e os limites de cada processo estão descritos em docs/architecture.md.

Em telas largas, o painel usa três superfícies: Aulas à esquerda, um chat central amplo e Estudo à direita. Estudo tem as abas Atividade, Dicas, Notas e Plano. Em telas pequenas, Estudo sai do fluxo principal e é aberto por um drawer acionado pelo botão Estudo. O chat organiza a conversa e a teoria; tentativas, dicas, notas e plano continuam nas abas do painel Estudo.

Arraste a divisória entre o chat e Estudo para aumentar o espaço de leitura ou de código. A largura é lembrada neste navegador; as setas esquerda/direita também ajustam o divisor quando ele recebe foco, e dois cliques restauram o padrão. O conteúdo do chat ocupa a largura disponível, sem o antigo limite central fixo.

Ao clicar em Começar aula, o objetivo e o nível do formulário já iniciam a conversa com Luna: o plano e a primeira mini-lição são preparados automaticamente. Não é necessário repetir o pedido no chat. O tutor deve explicar um conceito e mostrar um exemplo resolvido antes de propor uma tarefa. A primeira resposta fica reservada ao ensino; depois, você pode tirar dúvidas ou pedir para praticar. A abertura não altera aulas antigas nem inicia automaticamente aulas criadas por um cliente MCP externo.

Quando o agente estiver respondendo, o painel acompanha status e fases legíveis da operação: conexão, raciocínio, leitura da sessão, criação de atividade, revisão da tentativa, avanço da etapa, finalização, falha ou cancelamento. Uma mensagem do aluno é salva antes da resposta, portanto a sessão pode ser retomada mesmo se o agente falhar ou for cancelado.

Chat integrado

O botão Nova conversa cria uma sessão diretamente no painel. Em uma sessão conduzida pelo tutor, cada mensagem enviada em Converse com seu tutor é gravada e encaminhada ao backend do agente; a resposta volta para o histórico da conversa. O backend da v0.5 usa obrigatoriamente o modelo gpt-5.6-luna, em modo efêmero e com sandbox read-only, ignora configurações pessoais de plugins/MCPs e injeta somente o MCP Tutor. Não existe override de modelo por variável de ambiente: qualquer override deve ser ignorado. Defina TUTOR_AGENT=none para deixar apenas o modo manual MCP.

O chat automático da v0.5 é um backend específico do contrato do agente Luna. npm run setup:claude configura o Claude Code como cliente MCP externo para conduzir a aula no próprio chat, mas não promete que o executável claude funcione como backend do chat do navegador.

O chat integrado requer o backend do agente disponível localmente; npm run setup:codex é necessário quando você quer usar o MCP Tutor diretamente em uma conversa externa do Codex. O agente recebe o estado da sessão como contexto e deve tratar mensagens, respostas e código do aluno como dados não confiáveis. JavaScript com testes de expressões continua no Worker do navegador. Exercícios com entrada e saída usam um processo isolado no servidor, inclusive Node quando solicitado.

O status exibido pelo painel informa configuração e estado operacional, mas não comprova autenticação. A autenticação e a disponibilidade só podem ser confirmadas pelo resultado de uma chamada real. A v0.5 não promete streaming token-a-token: o painel mostra fases/status durante o processamento e recebe a resposta textual final.

O status por sessão é consultado em GET /api/agent?sessionId=… e retorna session com phase, active, lastError, startedAt, updatedAt e elapsedSeconds. Para cancelar, use POST /api/sessions/:id/chat/cancel com corpo {}. Para repetir a última mensagem sem criar outra cópia, use POST /api/sessions/:id/chat com { "retry": true }. Quando o agente conclui, phase: "completed" indica a conclusão do agente; a mensagem tutorMessage é salva logo depois.

No chat integrado, o envio de uma tentativa dispara uma solicitação de revisão automaticamente quando o tutor está habilitado e não há resposta ativa para a sessão. Se isso não for possível, a tentativa continua salva e o aluno pede a revisão ao terminar. Cancelar não desfaz atividades, revisões ou avanços MCP já realizados.

Laboratório e revisões

No Laboratório, escolha a linguagem, escreva um programa e informe os valores de entrada, um por linha. Use Executar código ou Ctrl/Cmd+Enter. O console apresenta saída, erros e duração; Parar cancela a execução. Java usa um arquivo Main.java com public class Main. JavaScript roda em Node, sem DOM do navegador. Cada execução começa em uma pasta temporária nova.

Nas aulas, Executar serve para experimentar; Enviar tentativa roda os casos de teste definidos pelo tutor e registra código, raciocínio e resultados. A entrada desses testes pode ser diferente da usada na sua experiência livre.

Em Revisões, responda de memória antes de revelar a referência. Depois, compare e registre sua autoavaliação. O aplicativo agenda a próxima revisão usando intervalos de 1, 3, 7, 14 ou 30 dias, como uma heurística inicial ajustável — não como um calendário cientificamente ótimo. As revisões aparecem no painel, sem notificações externas. Consulte a orientação pedagógica.

Related MCP server: vibetutor-mcp

Conectar o tutor

Com o cliente correspondente instalado e disponível no terminal:

npm run setup:codex
# Ou:
npm run setup:claude

Esses comandos registram mcp-tutor no cliente usando o caminho absoluto do Node e do servidor, inclusive quando a pasta contém espaços. O Codex usa seu cadastro de servidores; o Claude Code usa escopo local ao projeto. Reinicie a conexão MCP ou abra uma nova conversa no cliente para carregar as ferramentas. O chat integrado usa a conexão local do backend do agente; o status de configuração não substitui uma chamada bem-sucedida e não há uma chave de API própria do MCP Tutor.

Há dois modos de uso que não devem ser confundidos:

• Cliente MCP externo: Codex, Claude Code ou outro cliente conversa com o tutor e chama as ferramentas MCP. Esse é o caminho de integração documentado para Codex e Claude Code.

• Chat no navegador: o painel chama localmente o backend Luna, sempre com gpt-5.6-luna. A configuração MCP do Claude Code, por si só, não habilita esse chat automático.

Comece com esta mensagem:

Use o MCP Tutor para me ensinar a criar um site. Comece perguntando o que eu já sei, crie uma sessão e compartilhe o link do painel. Me dê uma atividade por vez. Espere minhas tentativas, ofereça dicas graduais e peça para eu explicar e depois recriar algo em um novo contexto.

O servidor MCP inicia o painel local automaticamente quando uma ferramenta é chamada, caso ele ainda não esteja rodando. Codex e Claude Code podem compartilhar o mesmo serviço e armazenamento. Para encerrar um painel iniciado manualmente, use Ctrl+C no terminal de npm start. Quando iniciado automaticamente pelo MCP, o processo continua disponível após a conversa; seu PID e a porta estão em .data/runtime.json. Encerre esse processo com SIGTERM se quiser fechá-lo.

Atenção ao fluxo da conversa: no chat integrado, enviar uma mensagem chama o backend Luna e a resposta aparece na mesma sessão; o aluno pode cancelar uma resposta em andamento e tentar novamente. O envio de uma tentativa também tenta iniciar a revisão no chat quando o tutor está habilitado e livre. Em um cliente MCP externo, enviar uma tentativa ou mensagem apenas deixa o conteúdo disponível para o tutor; nesse caso, a ferramenta tutor_get_events pode aguardar até 25 segundos e você pode voltar ao chat dizendo “Enviei minha tentativa; leia a sessão e me ajude com o próximo passo.”

Outro cliente MCP

Configure um servidor stdio, com:

{
  "mcpServers": {
    "mcp-tutor": {
      "command": "/caminho/absoluto/para/node",
      "args": ["/caminho/absoluto/para/mcp tutor/src/mcp.js"]
    }
  }
}

O formato do arquivo externo varia por cliente; command e args acima representam os mesmos parâmetros usados pelos scripts de conexão. Para conferir os caminhos no seu computador: command -v node e pwd.

Ferramentas MCP

Também são publicados o prompt active_learning_tutor e o recurso tutor://guide, com a orientação pedagógica. O servidor envia a mesma orientação na inicialização MCP. O cliente decide como disponibilizar prompts e recursos.

Estado da aula

As etapas seguem predict → practice → explain → transfer. O serviço permite apenas uma atividade respondível aberta por vez (quiz, code ou reflection). Tentativas que precisam de trabalho mantêm o aluno na mesma etapa; uma tentativa aprovada libera o estado ready_for_transition, mas o tutor ainda precisa chamar tutor_advance_stage com a tentativa mais recente e uma justificativa baseada em evidência. Teoria estruturada, mensagens, diagramas e gráficos podem apoiar a etapa atual sem abrir outra atividade respondível.

Blocos de teoria lesson podem usar stage: learn como apoio. Mensagens de revisão podem usar stage: review; o agendamento é independente e não abre uma segunda atividade respondível. As quatro etapas de progress continuam compatíveis com planos existentes.

O estado visível da sessão inclui progress.stage, progress.status, progress.activeBlockId, progress.lastAttemptId e progress.completedStages. O contrato detalhado está em docs/state-machine.md.

Exemplo do argumento de tutor_add_block:

{
  "sessionId": "UUID retornado por tutor_start_session",
  "block": {
    "type": "code",
    "stage": "practice",
    "title": "Seu primeiro título",
    "prompt": "Crie uma região main com um título h1 e explique sua escolha.",
    "language": "html",
    "starterCode": "<main>\n\n</main>",
    "checks": [
      {
        "label": "Um título com conteúdo dentro de main",
        "selector": "main h1",
        "kind": "text_nonempty"
      }
    ],
    "hints": ["Pense no elemento que expressa o título principal."]
  }
}

Quando a tentativa demonstrar o objetivo, avance uma etapa explicitamente:

{
  "sessionId": "UUID da sessão",
  "attemptId": "UUID da tentativa mais recente",
  "reason": "A tentativa contém a estrutura pedida e o raciocínio explica a escolha."
}

Esse é o argumento de tutor_advance_stage. Se a sessão ainda estiver aguardando tentativa ou revisão, o serviço rejeita a transição.

Para preservar aulas existentes, atividades code com language: "javascript" e testes booleanos mantêm o executor do navegador. HTML usa checks estruturais e aparece em uma prévia sem scripts; JavaScript usa tests com expressões booleanas e pode ser executado pelo aluno no sandbox do painel. O resultado JavaScript é salvo como evidência pending_review, para o tutor avaliar junto com o código e, quando informado, o raciocínio complementar. Exemplo:

{
  "sessionId": "UUID retornado por tutor_start_session",
  "block": {
    "type": "code",
    "stage": "practice",
    "title": "Uma função que transforma texto",
    "prompt": "Crie uma função upperCase que receba um texto e devolva sua versão em maiúsculas.",
    "language": "javascript",
    "starterCode": "function upperCase(text) {\n  // escreva sua solução\n}",
    "tests": [
      { "label": "A função existe", "expression": "typeof upperCase === 'function'" },
      { "label": "Transforma o texto", "expression": "upperCase('oi') === 'OI'" }
    ],
    "hints": ["Comece pensando em qual operação de string já faz essa transformação."]
  }
}

As expressões em tests são fornecidas pelo tutor e avaliadas no Worker dedicado /exercise-worker.js, não no servidor. A resposta desse Worker é apenas evidência do navegador e não é confiável por si só: o tutor deve revisá-la, e não há promessa de isolamento absoluto contra código hostil. Os contratos completos estão em src/schema.js. Os tipos incluem message, lesson, quiz, code, reflection, diagram e chart. Etapas possíveis: predict, practice, explain e transfer. Verificações HTML: exists, text_nonempty, text_includes, text_equals e attribute_equals. Diagramas usam nós e arestas com IDs; gráficos aceitam valores numéricos finitos e não negativos.

Para Python, Java, C ou C++, use testes de entrada e saída. Em JavaScript, escolha runtime: "local" para Node; testes de entrada e saída também selecionam esse modo. Não misture expressões booleanas e casos de entrada/saída. Exemplo, quando a sessão está em practice:

{
  "sessionId": "UUID retornado por tutor_start_session",
  "block": {
    "type": "code",
    "stage": "practice",
    "title": "Transforme uma entrada",
    "prompt": "Leia um inteiro e imprima seu triplo. Explique como o texto recebido vira um número.",
    "language": "python",
    "starterCode": "numero = int(input())\n# Complete a transformação\n",
    "stdin": "4\n",
    "tests": [
      { "name": "Inteiro positivo", "stdin": "4\n", "expectedStdout": "12\n" },
      { "name": "Inteiro negativo", "stdin": "-2\n", "expectedStdout": "-6\n" }
    ],
    "hints": ["Qual operação representa três vezes a mesma quantidade?"]
  }
}

Os contratos completos estão em src/schema.js. Tipos: message, lesson, quiz, code, reflection, diagram e chart. Etapas: learn, predict, practice, explain, transfer e review. lesson aceita texto, ideias principais e exemplo comentado. Sessões podem declarar objetivos e tempo estimado. HTML usa verificações de estrutura (checks); as outras linguagens usam casos de entrada e saída (tests). A comparação normaliza quebras de linha e ignora espaços no fim da saída; o restante precisa corresponder. Cada caso executa o código novamente em um ambiente novo. Diagramas usam nós e arestas com IDs; gráficos aceitam valores finitos e não negativos.

Como funciona

flowchart LR
  A[Codex / Claude Code] <-->|MCP stdio| B[Adaptador MCP]
  B <-->|API local autenticada| C[Serviço de aprendizagem]
  C <-->|Respostas e atualizações| D[Painel no navegador]
  C <--> E[Histórico local em JSON]

• src/mcp.js: protocolo MCP, ferramentas, prompt e inicialização do serviço.

• src/server.js: API HTTP local, autenticação, arquivos do painel e eventos SSE.

• src/store.js: atividades, tentativas, máquina de estados, avaliação objetiva, eventos e persistência.

• src/schema.js: contratos validados e orientação do tutor.

• src/demo.js: aula de exemplo, sem IA, usada para explorar a experiência.

• public/: interface em JavaScript e CSS, sem dependência de serviços externos.

• src/agent.js: ponte opcional entre o chat do painel e um agente CLI, com contexto de sessão e timeout.

• test/: testes de domínio e integração pelo SDK MCP real.

• src/runner.js e src/runner-launcher.py: descoberta de linguagens, isolamento e execução.

• src/learning.js, public/lab.js e public/reviews.js: revisões e laboratório.

• docs/pedagogy.md: base pedagógica, heurísticas e limitações.

• docs/product.md: decisões de produto e escopo da versão 0.5.

• docs/agent-bridge.md: fluxo, configuração e limites do chat integrado.

• docs/architecture.md: componentes, fluxos, dados e fronteiras de confiança.

• docs/operations.md: procedimento de instalação, uso diário, backup e troubleshooting.

• docs/release-readiness.md: crítica de maturidade, critérios de pronto e roadmap priorizado.

• docs/validation-v0.4.md: registro datado das evidências observadas e pendências da v0.5.

Há uma única instância de serviço por diretório de dados. As escritas são serializadas e salvas com substituição atômica do arquivo. Não execute serviços diferentes apontando para o mesmo diretório: o MVP não possui coordenação de armazenamento entre processos.

Limites desta versão

• Execução local em Linux. Um arquivo por programa, com entrada fornecida de uma vez. Sem terminal interativo, interfaces gráficas, rede, pacotes de projeto, ambientes virtuais ou acesso às pastas do usuário. O executor não aceita comandos de shell nem caminhos de executáveis fornecidos pelo aluno. A prévia HTML continua sem scripts.

• Limites por execução. Até 10 segundos incluindo compilação, 32 KiB de saída combinada, 1.536 MiB de memória virtual por processo, dois programas simultâneos e arquivos temporários limitados. JVM e Node recebem limites adicionais. Threads são permitidas para os runtimes; novos processos do programa são bloqueados. Os detalhes estão no código do executor.

• Execução delimitada. HTML/CSS aparece em prévia sem scripts ou rede. JavaScript roda em /exercise-worker.js, um Worker dedicado com limite de 1,5 segundo e connect-src 'none'; a CSP da página principal mantém script-src 'self' sem unsafe-eval e worker-src 'self' sem blob:. O asset do Worker tem CSP própria default-src 'none'; script-src 'unsafe-eval'; connect-src 'none'; worker-src 'none' para permitir Function somente dentro dele. Essa fronteira reduz o alcance do exercício, mas não é isolamento absoluto; checks e saída do browser continuam evidência não confiável. Python, Java, C, C++ e Node possuem um caminho separado com Bubblewrap e seccomp no Linux; veja os limites abaixo.

• Verificação não é domínio. Os testes de HTML checam a estrutura do documento e os testes de JavaScript checam apenas as expressões configuradas; nenhum deles avalia a aparência, a qualidade do raciocínio ou a aprendizagem. A avaliação do tutor é apresentada separadamente e preserva a evidência automática.

• Interface no navegador. A v0.5 define chat central amplo, Aulas à esquerda, Estudo à direita e drawer de Estudo em telas pequenas. Este MVP ainda não implementa uma extensão MCP Apps empacotada para renderizar atividades dentro de chats de terceiros; o suporte varia por cliente.

• Uso local. Sem login de usuários, sincronização na nuvem, publicação ou compartilhamento. As sessões locais ficam disponíveis para o tutor conectado; não há isolamento por cliente ou pessoa.

• A máquina não substitui o tutor. O serviço garante ordem, atividade única e evidência mínima para a transição, mas o tutor continua responsável pela qualidade pedagógica da explicação, da rubrica e da adaptação de dificuldade.

• Agente e retomada. O backend Luna expõe status da sessão, cancelamento idempotente e retomada sem duplicar mensagens. Eventos do painel não disparam conversas por conta própria em clientes MCP externos.

Prontidão de entrega

O produto está em nível de MVP utilizável para piloto local individual: o percurso de prática funciona, as sessões persistem e há integração MCP testada. Ainda não deve ser tratado como serviço público, produto multiusuário ou ambiente seguro para código não confiável em escala. Faltam, entre outros pontos, contas e isolamento de dados, backup/restore assistido, telemetria, recuperação de processos do agente, limites operacionais mais completos e uma extensão MCP Apps empacotada.

Use docs/release-readiness.md para decidir se uma mudança está pronta e docs/operations.md para colocar uma instalação local em uso. O roadmap prioriza confiabilidade e segurança operacional antes de ampliar linguagens ou interfaces.

O serviço escuta somente em 127.0.0.1, valida Host e Origin, exige um cookie local ou token de conexão e não habilita CORS. A prévia HTML usa iframe com sandbox, scripts desabilitados e política que bloqueia recursos de rede. O executor JavaScript usa um Web Worker descartável, com APIs de rede desabilitadas, política de conteúdo e timeout que consegue interromper loops infinitos; ele não tem acesso ao DOM, ao Node, ao terminal ou ao sistema de arquivos. O código dos exercícios locais é executado em processos separados, com namespaces, arquivos temporários, ambiente limpo e filtro seccomp. Se o isolamento não estiver disponível, esse caminho fica desabilitado; não há alternativa sem isolamento. O token de conexão fica em .data/runtime.json com permissão restrita. .data/ está fora do Git.

Desenvolvimento e verificação

npm run check
npm test

Os testes cobrem: percurso completo da aula, máquina de estados e transições inválidas, atividade única, retry, revisão de reflexões, comentários que não devem satisfazer verificações, respostas vazias, dicas e respostas de quiz ocultas, preservação da avaliação automática, espera de eventos, persistência, escritas concorrentes, validação de contratos, autenticação local e integração real MCP → atividade → tentativa → avaliação → avanço. O teste de integração usa uma porta temporária e um diretório em /tmp, sem tocar nas aulas do usuário.

Consulte o registro de validação da v0.5 para a evidência observada em 2026-09-10. O registro é parcial: não marca a reflection em andamento nem os demais critérios como concluídos e não promete segurança ou release público.

Para outra instância independente, configure as duas variáveis no serviço e no adaptador MCP:

TUTOR_PORT=4318 TUTOR_DATA_DIR=/tmp/meu-tutor npm start

Se a porta estiver ocupada, confira primeiro se o painel já está rodando. Não apague o histórico para resolver falhas de conexão. Um arquivo de dados ilegível causa erro explícito e é preservado.

Referências de integração

Documentação consultada em 9 de setembro de 2026:

• MCP no Codex: configuração de transportes stdio e HTTP.

• MCP no Claude Code: registro de servidores locais e escopos.

• SDK TypeScript oficial do MCP, linha v1: servidor e cliente usados nesta versão.

• MCP Apps: extensão para interfaces interativas em clientes compatíveis.

Verificação da v0.5

A suíte reúne os testes anteriores do agente, editor, Worker, layout e máquina de estados com os novos testes de execução e revisão. A suíte do executor requer Linux, isolamento funcional e Python 3; linguagens opcionais ausentes têm casos pulados explicitamente. Consulte o registro desta versão. Após atualizar, reinicie o serviço e reconecte o cliente MCP para carregar as 12 ferramentas. As aulas e revisões locais são preservadas na migração de dados.

Se o Laboratório indicar isolamento indisponível, confira os pacotes bubblewrap e libseccomp2, Python 3 e a permissão do sistema para namespaces sem privilégios. Restrições do ambiente em que o servidor foi iniciado também podem bloquear o Bubblewrap. Não desative as proteções do host para contornar o erro: use uma configuração Linux compatível. Após instalar runtimes ou atualizar este projeto, reinicie o serviço local; para carregar novas ferramentas, reconecte também o cliente MCP.