Quiz MCP

Servidor MCP para quizzes interativos

Documentação

quiz-mcp

Permita que modelos de IA entreguem quizzes interativos a humanos por meio de uma interface de navegador real.

Em vez de gerar formulários HTML como artefatos ou fazer perguntas uma a uma no chat, o modelo descreve um quiz como JSON, o usuário o preenche em http://localhost:<port>, e as respostas voltam para o modelo como dados estruturados.

Útil para professores que criam quizzes com IA, pesquisadores que conduzem entrevistas estruturadas, ou qualquer agente que precise de entrada real de um humano.

Quiz runner showing the bundled JavaScript basics demo

Início rápido

Experimente o quiz de demonstração (sem instalar, sem clonar)

Execute o quiz de fundamentos de JavaScript com 7 perguntas diretamente do GitHub:

npx @quiz-mcp/runner \
  --url https://raw.githubusercontent.com/karerckor/quiz-mcp/main/demo/js-quiz.json \
  --output ./answers.json \
  --open

--open abre a URL no navegador do sistema. As respostas são gravadas em ./answers.json quando você envia.

Registrar como servidor MCP

Uma vez conectado, o modelo ganha quatro ferramentas: start_quiz, get_answers, get_quiz_format e stop_runner.

Claude Code

Adicione em .mcp.json na raiz do seu projeto (ou ~/.claude.json para todo o usuário):

{
  "mcpServers": {
    "quiz-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@quiz-mcp/cli", "mcp"]
    }
  }
}

OpenCode

Adicione em opencode.json (projeto) ou ~/.config/opencode/opencode.json (global):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "quiz-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@quiz-mcp/cli", "mcp"],
      "enabled": true
    }
  }
}

Kilo Code

Abra o painel de configurações do MCP no Kilo Code (MCP Servers → Edit Global MCP) e adicione:

{
  "mcpServers": {
    "quiz-mcp": {
      "command": "npx",
      "args": ["-y", "@quiz-mcp/cli", "mcp"]
    }
  }
}

O mesmo par command/args funciona para qualquer cliente MCP que siga o formato padrão mcpServers (Claude Desktop, Cursor, Windsurf, …).

Usar o servidor MCP remoto hospedado

Se você não quiser instalar nada localmente, existe uma versão hospedada e protegida por OAuth do quiz-mcp rodando no Cloudflare Workers:

https://quiz-mcp-oauth.karerckor.workers.dev/mcp

Ela expõe as mesmas ferramentas do servidor local, além de get_quizzes e cleanup_quiz para gerenciar o estado por usuário. Cada usuário recebe um espaço de trabalho de quiz isolado; o login é feito via WorkOS AuthKit na primeira chamada de ferramenta.

Nota: as respostas são persistidas no Cloudflare KV, que é eventualmente consistente. Depois que um usuário envia um quiz, get_answers pode retornar brevemente dados vazios ou desatualizados — aguarde alguns segundos e tente novamente se o modelo relatar respostas ausentes.

Claude Code

Registre o servidor remoto com a CLI claude (isso o armazena em ~/.claude.json):

claude mcp add --transport http quiz-mcp-remote https://quiz-mcp-oauth.karerckor.workers.dev/mcp

Ou adicione manualmente em .mcp.json (projeto) / ~/.claude.json (todo o usuário):

{
  "mcpServers": {
    "quiz-mcp-remote": {
      "type": "http",
      "url": "https://quiz-mcp-oauth.karerckor.workers.dev/mcp"
    }
  }
}

Na primeira chamada (por exemplo, start_quiz), o Claude Code abrirá seu navegador para o fluxo OAuth; o token de acesso fica em cache depois disso. Execute /mcp dentro do Claude Code para inspecionar o estado da conexão ou reautenticar.

Quer hospedar sua própria instância? Veja apps/remote-mcp-oauth/README.md para a configuração completa (namespaces do Cloudflare KV, segredos do WorkOS, wrangler deploy).

Criar e executar seu próprio quiz

# scaffold a new quiz skeleton → ./javascript-basics.quiz.json
npx @quiz-mcp/cli create "JavaScript basics"

# serve it in a browser and write answers to a file
npx @quiz-mcp/runner --file ./javascript-basics.quiz.json --output ./answers.json --open

O arquivo gerado inclui um ponteiro $schema para que os editores possam validar e autocompletar a estrutura do quiz enquanto você o preenche.

Servir um quiz remoto com um sink de webhook

npx @quiz-mcp/runner \
  --url https://example.com/quiz.json \
  --on-complete https://example.com/hooks/quiz \
  --output ./answers.json

O runner termina com o código 0 em caso de sucesso, 1 em caso de falha de carregamento/validação, 2 se um sink falhou após o quiz ser concluído.

Estrutura do repositório

Caminho	Pacote / Aplicativo	Descrição
`apps/cli`	`@quiz-mcp/cli`	Binário publicado (`quiz-mcp`). Servidor MCP stdio, ciclo de vida do runner preguiçoso, comando de scaffolding `create`.
`apps/runner`	`@quiz-mcp/runner`	CLI autônoma que carrega um quiz de um arquivo/URL/stdin, o serve em um navegador e grava as respostas em um arquivo ou webhook.
`apps/remote-mcp-oauth`	`@quiz-mcp/remote-mcp-oauth`	Cloudflare Worker hospedando um servidor MCP remoto protegido por OAuth (WorkOS AuthKit + Durable Objects). Alimenta o `https://quiz-mcp-oauth.karerckor.workers.dev`.
`packages/core`	`@quiz-mcp/core`	Fundação de domínio: schemas Zod, tipos, mecanismo de correção, validação de respostas. Fonte única de verdade para o formato de quiz.
`packages/runner-api`	`@quiz-mcp/runner-api`	Servidor HTTP Hono e shell SSR para o runtime do quiz. Endpoints REST, temas, i18n. Não publicado de forma autônoma.
`packages/runner-ui`	`@quiz-mcp/runner-ui`	Pacote cliente Vite/Hono-JSX. Hidrata o shell SSR e conecta eventos `<quiz-player>` à API REST. Apenas assets, não um import de runtime.
`packages/web-components`	`@quiz-mcp/web-components`	Elemento customizado `<quiz-player>` independente de framework (Svelte 5 + Shadow DOM + DaisyUI 5).
`demo/`	—	Arquivos JSON de quiz de exemplo.
`schema/`	—	JSON Schema gerado para o tipo `Quiz` (`schema/quiz.schema.json`).
`scripts/`	—	Utilitários de tempo de build: geração de JSON Schema e validação contra AJV.

Requisitos

Ferramenta	Versão
Node.js	≥ 20
pnpm	10.8.1 (fixado via `packageManager`)

Desenvolvimento

git clone https://github.com/karerckor/quiz-mcp.git
cd quiz-mcp
pnpm install

Comando	Propósito
`pnpm build`	Compilar todos os pacotes (o Turborepo respeita o grafo `^build`).
`pnpm test`	Executar a suíte de testes completa.
`pnpm typecheck`	Verificar tipos em todos os pacotes.
`pnpm dev`	Modo de observação, em paralelo entre os pacotes.

Schema do quiz

O formato Quiz é definido em packages/core como um schema Zod e exportado como JSON Schema para schema/quiz.schema.json.

Forma de nível superior:

{
  "id": "my-quiz-1",
  "title": "Quiz title",
  "description": "Optional description",
  "questions": [ /* Question[] */ ]
}

Tipos de pergunta suportados (_kind):

single_choice, multiple_choice, short_text, long_text, dropdown, fill_gaps, match, scale, sorting, upload

Regenerar ou verificar o schema:

pnpm schema:gen    # writes schema/quiz.schema.json
pnpm schema:check  # validates the generated schema with AJV

O schema também está disponível na URL canônica embutida no arquivo: https://raw.githubusercontent.com/karerckor/quiz-mcp/main/schema/quiz.schema.json

READMEs dos pacotes

apps/cli/README.md — ferramentas MCP, comportamento do ciclo de vida, comandos CLI
apps/runner/README.md — flags da CLI do runner autônomo, códigos de saída, arquitetura
apps/remote-mcp-oauth/README.md — servidor MCP remoto hospedado, configuração OAuth, implantação no Cloudflare
packages/core/README.md — schemas de domínio, API de correção, validação, adição de tipos de pergunta
packages/runner-api/README.md — endpoints REST, opções do servidor SSR, interface QuizService, temas
packages/runner-ui/README.md — internals do pacote cliente, manifest Vite, implantações personalizadas
packages/web-components/README.md — API do elemento <quiz-player>, eventos, temas, integração com frameworks