# Quiz MCP Server

An interactive programming quiz server built with the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) and [MCP Apps SDK](https://github.com/nicholasgasior/modelcontextprotocol-ext-apps). Features 10 quiz questions across multiple categories (Web Fundamentals, JavaScript, Git, Networking, Algorithms, TypeScript, CSS, Databases, Security, Systems) with three difficulty levels.

## Features

- **start-quiz** — Launches an interactive quiz UI with 10 questions
- **submit-answer** — Server-side grading with explanations
- **get-hint** — Provides hints for each question

## Requirements

- **Node.js** >= 20.0.0
- **npm** >= 9

## Quick Start

```bash
# Install dependencies
npm install

# Build the UI (bundles mcp-app.html into dist/)
npm run build

# Start the server
npm run serve
```

The server starts at `http://localhost:3001/mcp`.

## Development

```bash
npm run dev
```

This runs both the Vite UI watcher and the server with auto-reload concurrently.

## Scripts

| Script | Description |
|--------|-------------|
| `npm run build` | Build the bundled UI (`dist/mcp-app.html`) |
| `npm run serve` | Start the MCP server (tsx) |
| `npm run dev` | Watch mode — rebuilds UI & restarts server on changes |
| `npm start` | Production start (`node --import tsx main.ts`) |

## Testing

```bash
# Initialize
curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

# List tools
curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":2}'
```

## Project Structure

```
├── main.ts              # Entry point — HTTP & stdio transport setup
├── server.ts            # MCP server — tools, resources, quiz logic
├── mcp-app.html         # UI entry point (built by Vite into dist/)
├── src/
│   ├── mcp-app.tsx      # React quiz UI component
│   ├── mcp-app.module.css
│   └── global.css
├── vite.config.ts       # Vite config (single-file bundle)
├── tsconfig.json        # TypeScript config (UI + server)
└── package.json
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `3001` | HTTP server port |

## License

MIT