VibeQuiz

AI-powered quiz generator and interactive learning tool with MCP server support.

Dual mode: Standalone JSON import for quick quizzes, or MCP mode for AI-driven quiz sessions.

Features

• Dual mode — standalone (paste JSON) or MCP (AI creates quiz via create_quiz tool)
• Interactive quiz — single/multi-select, shuffle questions & options, progress tracking
• AI error analysis — generates batch prompt for incorrect questions
• MCP protocol — stdio (local) and Streamable HTTP (remote/Docker) transports
• Session persistence — quiz state saved to disk with 1-hour TTL
• Modern stack — Svelte 5 + TypeScript + Tailwind CSS v4 + Vite

Quick Start

# Install
pnpm install

# Terminal 1: Frontend dev server (port 5173)
pnpm dev

# Terminal 2: MCP + Express server (port 3001)
pnpm dev:server

For MCP mode (so create_quiz returns the Vite URL):

$env:BASE_URL="http://localhost:5173"; pnpm dev:server

Production

pnpm build
pnpm start                          # stdio transport (default)
$env:MCP_TRANSPORT="sse"; pnpm start  # Streamable HTTP

Project Structure

F:\projects\VibeQuiz/
├── index.html               # Single entry point (import/quiz/report views)
├── src/
│   └── [App.svelte, main.ts, types.ts, style.css, ...]
├── server/
│   ├── index.ts             # MCP server + Express HTTP server
│   ├── session.ts           # Session store with JSON persistence + TTL
│   ├── api.ts               # REST API routes
│   └── format.ts            # Result formatting (English output)
├── public/
│   ├── favicon.ico
│   └── robots.txt
├── .sessions.json           # Persisted sessions (auto-generated)
├── CHANGELOG.md
├── vite.config.ts
├── tsconfig.json / tsconfig.server.json
├── package.json
└── Dockerfile / docker-compose.yml

Data Flow

MCP Mode

1. AI model calls create_quiz(questions) → gets { sessionId, url }
2. User opens the URL in browser, takes the quiz
3. Results POSTed to server automatically on completion
4. AI model calls check_results(sessionId) → gets score & answer details
5. Model analyzes results and provides feedback

Standalone Mode

1. User pastes JSON directly → quiz → report → copies AI prompt for manual analysis

MCP Client Configuration

Local (stdio)

{
  "mcpServers": {
    "vibe-quiz": {
      "command": "node",
      "args": ["--import", "tsx/esm", "server/index.ts"],
      "cwd": "F:\\projects\\VibeQuiz"
    }
  }
}

Remote (Streamable HTTP)

{
  "mcpServers": {
    "vibe-quiz": {
      "url": "http://your-domain.com:3001/mcp"
    }
  }
}

Docker

docker compose up -d

Environment variables: MCP_TRANSPORT (default sse), BASE_URL.

Tech Stack

Layer	Technology
Frontend	Svelte 5, TypeScript, Tailwind CSS v4
Build	Vite 7, @tailwindcss/vite
Server	Express 5, @modelcontextprotocol/sdk
Runtime	Node.js 24, pnpm, ESM

License

MIT