Quiz MCP

Servidor MCP para cuestionarios interactivos

Documentación

quiz-mcp

Permite que los modelos de IA entreguen cuestionarios interactivos a humanos a través de una interfaz de navegador real.

En lugar de generar formularios HTML como artefactos o hacer preguntas una por una en el chat, el modelo describe un cuestionario como JSON, el usuario lo completa en http://localhost:<port>, y las respuestas fluyen de vuelta al modelo como datos estructurados.

Útil para profesores que crean cuestionarios con IA, investigadores que realizan entrevistas estructuradas, o cualquier agente que necesite entrada real de un humano.

Quiz runner showing the bundled JavaScript basics demo

Inicio rápido

Prueba el cuestionario de demostración (sin instalación, sin clonar)

Ejecuta el cuestionario incluido de 7 preguntas sobre fundamentos de JavaScript directamente desde GitHub:

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

--open abre la URL en el navegador del sistema. Las respuestas se escriben en ./answers.json cuando envías el formulario.

Regístrate como servidor MCP

Una vez conectado, el modelo obtiene cuatro herramientas: start_quiz, get_answers, get_quiz_format y stop_runner.

Claude Code

Añade a .mcp.json en la raíz de tu proyecto (o ~/.claude.json para todo el usuario):

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

OpenCode

Añade a opencode.json (proyecto) o ~/.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

Abre el panel de configuración de MCP en Kilo Code (MCP Servers → Edit Global MCP) y añade:

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

El mismo par command/args funciona para cualquier cliente MCP que siga la forma estándar de mcpServers (Claude Desktop, Cursor, Windsurf, …).

Usa el servidor MCP remoto alojado

Si no quieres instalar nada localmente, hay una versión alojada y protegida con OAuth de quiz-mcp ejecutándose en Cloudflare Workers:

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

Expone las mismas herramientas que el servidor local, más get_quizzes y cleanup_quiz para gestionar el estado por usuario. Cada usuario obtiene un espacio de trabajo de cuestionario aislado; el inicio de sesión se gestiona mediante WorkOS AuthKit en la primera llamada a la herramienta.

Nota: las respuestas se persisten en Cloudflare KV, que es eventualmente consistente. Después de que un usuario envía un cuestionario, get_answers puede devolver brevemente datos vacíos o desactualizados — espera unos segundos y reintenta si el modelo reporta respuestas faltantes.

Claude Code

Registra el servidor remoto con el CLI de claude (esto lo almacena en ~/.claude.json):

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

O añádelo manualmente a .mcp.json (proyecto) / ~/.claude.json (todo el usuario):

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

En la primera llamada (por ejemplo, start_quiz) Claude Code abrirá tu navegador para el flujo OAuth; el token de acceso se almacena en caché después. Ejecuta /mcp dentro de Claude Code para inspeccionar el estado de la conexión o reautenticarte.

¿Quieres alojar tu propia instancia? Consulta apps/remote-mcp-oauth/README.md para la configuración completa (espacios de nombres de Cloudflare KV, secretos de WorkOS, wrangler deploy).

Crea y ejecuta tu propio cuestionario

# 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

El archivo generado incluye un puntero a $schema para que los editores puedan validar y autocompletar la estructura del cuestionario mientras lo completas.

Sirve un cuestionario remoto con un sumidero webhook

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

El ejecutor termina con el código 0 en caso de éxito, 1 en caso de fallo de carga/validación, 2 si un sumidero falló después de que el cuestionario se completara.

Estructura del repositorio

Ruta	Paquete / Aplicación	Descripción
`apps/cli`	`@quiz-mcp/cli`	Binario publicado (`quiz-mcp`). Servidor MCP stdio, ciclo de vida del ejecutor diferido, comando de generación de `create`.
`apps/runner`	`@quiz-mcp/runner`	CLI independiente que carga un cuestionario desde un archivo/URL/stdin, lo sirve en un navegador y escribe las respuestas en un archivo o webhook.
`apps/remote-mcp-oauth`	`@quiz-mcp/remote-mcp-oauth`	Cloudflare Worker que aloja un servidor MCP remoto protegido con OAuth (WorkOS AuthKit + Durable Objects). Impulsa `https://quiz-mcp-oauth.karerckor.workers.dev`.
`packages/core`	`@quiz-mcp/core`	Base de dominio: esquemas Zod, tipos, motor de calificación, validación de respuestas. Fuente única de verdad para el formato de cuestionario.
`packages/runner-api`	`@quiz-mcp/runner-api`	Servidor HTTP Hono y shell SSR para el tiempo de ejecución del cuestionario. Endpoints REST, temas, i18n. No se publica de forma independiente.
`packages/runner-ui`	`@quiz-mcp/runner-ui`	Paquete de cliente Vite/Hono-JSX. Hidrata el shell SSR y conecta los eventos de `<quiz-player>` a la API REST. Solo activos, no una importación de tiempo de ejecución.
`packages/web-components`	`@quiz-mcp/web-components`	Elemento personalizado `<quiz-player>` independiente del framework (Svelte 5 + Shadow DOM + DaisyUI 5).
`demo/`	—	Archivos JSON de ejemplo de cuestionarios.
`schema/`	—	JSON Schema generado para el tipo `Quiz` (`schema/quiz.schema.json`).
`scripts/`	—	Utilidades de tiempo de compilación: generación de JSON Schema y validación contra AJV.

Requisitos

Herramienta	Versión
Node.js	≥ 20
pnpm	10.8.1 (fijado mediante `packageManager`)

Desarrollo

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

Comando	Propósito
`pnpm build`	Compilar todos los paquetes (Turborepo respeta el grafo de `^build`).
`pnpm test`	Ejecutar la suite de pruebas completa.
`pnpm typecheck`	Verificación de tipos en cada paquete.
`pnpm dev`	Modo de observación, en paralelo entre paquetes.

Esquema del cuestionario

El formato Quiz se define en packages/core como un esquema Zod y se exporta como JSON Schema a schema/quiz.schema.json.

Forma de nivel superior:

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

Tipos de pregunta admitidos (_kind):

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

Regenera o verifica el esquema:

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

El esquema también está disponible en la URL canónica incrustada en el archivo: https://raw.githubusercontent.com/karerckor/quiz-mcp/main/schema/quiz.schema.json

READMEs de paquetes

apps/cli/README.md — herramientas MCP, comportamiento del ciclo de vida, comandos CLI
apps/runner/README.md — banderas CLI del ejecutor independiente, códigos de salida, arquitectura
apps/remote-mcp-oauth/README.md — servidor MCP remoto alojado, configuración OAuth, despliegue en Cloudflare
packages/core/README.md — esquemas de dominio, API de calificación, validación, adición de tipos de pregunta
packages/runner-api/README.md — endpoints REST, opciones del servidor SSR, interfaz de QuizService, temas
packages/runner-ui/README.md — internos del paquete de cliente, manifiesto de Vite, despliegues personalizados
packages/web-components/README.md — API del elemento <quiz-player>, eventos, temas, integración con frameworks