Estúdio de Aprendizagem

Projeto pessoal de um aplicativo educacional interativo que funciona no ChatGPT por meio da arquitetura oficial de ChatGPT Apps, Apps SDK e MCP.

Estado atual

O MVP está implementado e implantado. Ele inclui:

• servidor HTTP local;

• rota de saúde GET /health;

• testes automatizados da rota;

• serviço em memória para criar sessões dinâmicas com uma a cinco questões;

• validação, correção e idempotência por submissionId;

• testes automatizados da lógica do exercício;

• endpoint MCP local em http://127.0.0.1:8787/mcp;

• três ferramentas MCP para preparar uma sessão, iniciar a demonstração fixa e enviar respostas;

• recurso MCP Apps ui://widget/exercicio.html com o MIME oficial;

• widget acessível e responsivo em HTML, CSS e JavaScript simples;

• host local de desenvolvimento em http://127.0.0.1:8787/local;

• testes automatizados pelo cliente oficial do SDK MCP.

O servidor está implantado no Railway em https://inspiring-spirit-production-429d.up.railway.app/mcp. A versão publicada continua sendo um MVP sem banco de dados, login ou geração de questões por IA.

Related MCP server: OLCP

Prova de conceito local

A lógica atual recebe uma definição de sessão com título, matéria ou tema e uma a cinco questões. Cada questão contém enunciado, quatro ou cinco alternativas, alternativa correta e uma explicação interna opcional. O aluno continua informando justificativa obrigatória e confiança de 1 a 5.

Cada sessão recebe um sessionId próprio e permanece somente na memória do processo. O servidor entrega uma questão por vez, sem gabarito ou explicação interna, e só avança depois de validar e corrigir a resposta atual. Depois da última resposta, devolve um resumo com acertos, erros, respostas, gabaritos, explicações disponíveis, justificativas e níveis de confiança.

Quando um submissionId é repetido com os mesmos dados validados, o serviço devolve o resultado já armazenado sem corrigir novamente. Se o identificador for reutilizado com conteúdo diferente, o serviço rejeita a tentativa e preserva o resultado original.

Servidor MCP local

O endpoint /mcp usa o transporte Streamable HTTP sem sessão. Ele expõe somente estas ferramentas:

• preparar_sessao_exercicios: valida a definição recebida, cria a sessão em memória e devolve somente a primeira questão pública;

• iniciar_exercicio_fixo: mantém a sessão fixa anterior apenas como demonstração compatível;

• enviar_resposta_exercicio: valida e corrige a questão atual, devolvendo a próxima questão pública ou o resumo final.

As ferramentas que preparam sessões referenciam o recurso visual ui://widget/exercicio.html. A ferramenta enviar_resposta_exercicio permanece sem metadados de UI, para que o envio atualize o widget existente sem solicitar uma nova montagem. O recurso usa text/html;profile=mcp-app, conforme o guia oficial da OpenAI.

O widget recebe a primeira questão pública pelo resultado da ferramenta inicial e chama somente enviar_resposta_exercicio pela ponte MCP Apps. Após cada envio ele avança para a próxima questão e, ao final, mostra o resumo completo. Ele impede o envio incompleto no cliente, mas toda validação, ordem das questões e correção continuam no servidor. O estado visual pode usar window.openai.widgetState quando o host oferecer essa extensão; esse recurso é opcional e não substitui o estado em memória do servidor.

Resultados bem-sucedidos seguem o outputSchema declarado e usam structuredContent. Erros conhecidos usam isError: true e mantêm código, mensagem e detalhes no bloco textual de content, sem devolver um structuredContent incompatível. Falhas internas do transporte recebem uma resposta de erro JSON-RPC 2.0.

Host local de desenvolvimento

Para testar o MVP sem publicar o plugin nem conectar ao ChatGPT, o servidor expõe GET /local. Essa página carrega o mesmo widget do MCP Apps em um iframe e simula a ponte ui/* localmente. As chamadas do widget passam pelo servidor em POST /local/api/tools/call, usando os mesmos nomes e formatos das ferramentas MCP.

Esse host local existe somente para validação de desenvolvimento. O fluxo MCP real continua em /mcp, verificado por pnpm test:mcp:local.

Requisitos

• Node.js 20 ou superior;

• pnpm.

Comandos locais

• pnpm start: inicia o servidor em http://127.0.0.1:8787.

• pnpm test: executa os testes automatizados.

• pnpm test:mcp:local: com o servidor já iniciado, executa uma verificação local pelo cliente oficial MCP.

• Abra http://127.0.0.1:8787/local para testar a interação completa no navegador.

A porta pode ser alterada pela variável de ambiente PORT. Por padrão, o servidor aceita conexões somente da própria máquina. O endpoint MCP fica disponível em /mcp e a rota de saúde permanece em /health. Para testar outra porta, defina MCP_SERVER_URL antes de executar pnpm test:mcp:local.

Configuração de produção

Toda configuração operacional é recebida por variáveis de ambiente. O projeto não carrega arquivos .env automaticamente; configure os valores no ambiente da hospedagem ou no gerenciador de segredos da plataforma. O arquivo .env.example contém apenas exemplos sem credenciais.

Com NODE_ENV=production, as rotas locais de demonstração ficam desativadas. As rotas públicas são GET /, /suporte, /privacidade, /termos, /site.css, /health, /mcp e, somente quando houver um token configurado, GET /.well-known/openai-apps-challenge. A última devolve o token exato como texto puro, sem JSON e sem gravá-lo no código ou nos logs.

O site público e as páginas de suporte e políticas ficam no mesmo domínio do MCP:

• site: https://inspiring-spirit-production-429d.up.railway.app/;

• suporte: https://inspiring-spirit-production-429d.up.railway.app/suporte;

• privacidade: https://inspiring-spirit-production-429d.up.railway.app/privacidade;

• termos: https://inspiring-spirit-production-429d.up.railway.app/termos.

O CORS de /mcp permite os cabeçalhos usados pelo transporte Streamable HTTP e pode refletir somente as origens configuradas. O valor * é compatível com este MVP público sem credenciais, mas não funciona como controle de acesso. Quando a origem real de um cliente de navegador for conhecida, prefira uma lista explícita.

O widget é autocontido. Sua política MCP Apps declara listas vazias para conexões, recursos externos, frames aninhados e URI-base. Se futuramente algum domínio for necessário, ele deve ser adicionado explicitamente à política e revisado antes da publicação.

As três ferramentas alteram apenas o estado efêmero da sessão no processo, não acessam a internet e não apagam ou sobrescrevem dados externos. Por isso todas declaram readOnlyHint: false, openWorldHint: false e destructiveHint: false. Todas declaram autenticação noauth. A ferramenta de envio também declara idempotentHint: true, de acordo com seu comportamento por submissionId.

Execução atrás de HTTPS

O processo Node recebe HTTP interno. Em produção, um balanceador ou proxy reverso deve encerrar TLS e encaminhar as requisições para HOST e PORT, preservando os métodos POST, GET, DELETE e OPTIONS, além dos cabeçalhos MCP. O endereço externo precisa ser HTTPS, estável e terminar normalmente em /mcp. Não faça redirecionamento de /mcp para outra origem e não armazene respostas MCP em cache.

A infraestrutura deve oferecer:

• Node.js 20 ou uma plataforma compatível com contêiner OCI;

• domínio público estável com certificado HTTPS válido;

• encaminhamento HTTP sem alterar corpo, métodos ou cabeçalhos MCP;

• verificação de saúde por GET /health;

• variáveis de ambiente e armazenamento seguro do token de verificação;

• logs operacionais que não registrem corpos de submissões, gabaritos ou tokens.

O Dockerfile fornece uma imagem mínima, executada como usuário sem privilégios, com dependências travadas pelo pnpm-lock.yaml e verificação de saúde integrada:

docker build -t estudio-aprendizagem .
docker run --rm -p 8787:8787 --env-file .env estudio-aprendizagem

Esses comandos servem apenas para validação local da imagem. Nenhuma imagem ou serviço é publicado automaticamente.

As decisões seguem a documentação oficial atual da OpenAI para servidores MCP públicos, UI e CSP do MCP Apps e verificação de domínio.

Estado e documentação

O app foi enviado para revisão da OpenAI em 21/09/2026. Isso não significa aprovação. A conexão de teste funcionou no ChatGPT. O projeto está sendo preparado para publicação open source; consulte SECURITY.md antes de hospedar para terceiros.

• Instalação e deploy

• Arquitetura, ferramentas MCP e widget

• Exemplos

• Contribuição

• Segurança

• Roadmap

• Changelog

Licença MIT: veja LICENSE. Não há vínculo oficial com a OpenAI. O software é experimental e não substitui avaliação pedagógica profissional.

Limites desta etapa

• nenhum banco de dados;

• nenhum login;

• as sessões precisam ser fornecidas por um chamador; não há geração por IA;

• nenhuma chamada à API da OpenAI;

• nenhum ativo, script ou serviço externo no widget;

• nenhum ngrok ou outro túnel;

• publicação do repositório público ainda pendente.

Consulte também as regras permanentes em AGENTS.md antes de realizar mudanças.