mcp-quiz-server/README.md

🧠 AI-Powered Quiz Management via Model Context Protocol (MCP) - Create, manage, and take quizzes directly from VS Code, Claude, and other AI agents.

# 🧠 MCP Quiz Server

[![CI/CD Pipeline](https://github.com/GSejas/mcp-quiz-oss/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/GSejas/mcp-quiz-oss/actions/workflows/ci-cd.yml)
[![NPM Version](https://img.shields.io/npm/v/mcp-quiz-server.svg)](https://www.npmjs.com/package/mcp-quiz-server)
[![Node.js Version](https://img.shields.io/node/v/mcp-quiz-server.svg)](https://nodejs.org/en/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> 🚀 **AI-Powered Quiz Management via Model Context Protocol (MCP)**  
> Create, manage, and take quizzes directly from VS Code, Claude, and other AI agents.

## ✨ Features

- 🎯 **Zero-Install Setup** - Use with `npx` - no global installation required
- 🔌 **VS Code Integration** - Seamless quiz management in your favorite editor
- 🤖 **Claude Desktop Support** - AI-powered quiz creation and analysis
- 📊 **Advanced Analytics** - Track performance and learning outcomes
- 🌐 **Web Interface** - Browser-based quiz taking experience
- 🎨 **Modern UI** - Clean, responsive design with dark mode support
- 🔒 **Secure & Private** - Local database, no cloud dependencies
- 🧪 **TypeScript** - Fully typed for better development experience

## 🚀 Quick Start

### Option 1: NPX (Recommended)
```bash
# Start the quiz server
npx mcp-quiz-server start

# Start MCP server for VS Code/Claude integration
npx mcp-quiz-server mcp

# Show help
npx mcp-quiz-server help
```

### Option 2: Global Installation
```bash
npm install -g mcp-quiz-server
mcp-quiz-server start
```

## 🔧 Integration Setup

### VS Code MCP Extension

Add to your VS Code settings (`settings.json`):
```json
{
  "mcp": {
    "servers": {
      "mcp-quiz-server": {
        "command": "npx",
        "args": ["mcp-quiz-server", "mcp"]
      }
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop config (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "mcp-quiz-server": {
      "command": "npx",
      "args": ["mcp-quiz-server", "mcp"]
    }
  }
}
```

## 📋 Available Tools

| Tool | Description | Category |
|------|-------------|----------|
| `create_quiz` | Create new quizzes with questions | Quiz Management |
| `list_quizzes` | List all available quizzes | Quiz Management |
| `get_quiz` | Get specific quiz details | Quiz Management |
| `delete_quiz` | Delete existing quizzes | Quiz Management |
| `submit_quiz_result` | Submit quiz answers for scoring | Analytics |
| `get_quiz_analytics` | Get quiz performance analytics | Analytics |
| `generate_quiz_urls` | Generate shareable quiz URLs | Analytics |
| `start_web_server` | Start the web interface | Server Management |
| `stop_web_server` | Stop the web interface | Server Management |
| `server_status` | Check server status | Server Management |

## 🎯 Usage Examples

### Creating a Quiz with VS Code
1. Open Command Palette (`Ctrl+Shift+P`)
2. Type "MCP: Execute Tool"
3. Select `create_quiz`
4. Provide quiz data:
```json
{
  "title": "JavaScript Fundamentals",
  "description": "Test your JavaScript knowledge",
  "category": "programming",
  "questions": [
    {
      "question": "What is the correct way to declare a variable in JavaScript?",
      "options": ["var x = 5;", "variable x = 5;", "v x = 5;", "declare x = 5;"],
      "correctAnswer": "var x = 5;",
      "explanation": "Variables in JavaScript are declared using var, let, or const keywords."
    }
  ]
}
```

### Using with Claude Desktop
Simply ask Claude:
```
Create a 10-question quiz about Python programming covering variables, functions, loops, and data structures. Make it suitable for beginners.
```

Claude will use the MCP tools to create and manage your quiz automatically!

## 🌐 Web Interface

Start the web server:
```bash
npx mcp-quiz-server start
```

Then visit: **http://localhost:3000**

Features:
- 📱 **Responsive Design** - Works on desktop, tablet, and mobile
- 🎨 **Theme Support** - Light and dark modes
- ⏱️ **Timer Support** - Optional quiz timing
- 📊 **Real-time Feedback** - Instant question feedback
- 🔗 **Shareable Links** - Send quizzes to others
- 📈 **Progress Tracking** - Visual progress indicators

## 📊 Analytics & Reporting

Get comprehensive insights:
- **Completion Rates** - Track how many users finish quizzes
- **Average Scores** - Monitor learning effectiveness
- **Question Analysis** - Identify difficult questions
- **Time Tracking** - Understand quiz duration patterns
- **Score Distribution** - See performance patterns

Example analytics query:
```javascript
// Get analytics for a specific quiz
const analytics = await getQuizAnalytics("quiz-id", "last30days");
console.log(analytics.averageScore); // 78.5%
console.log(analytics.completionRate); // 92%
```

## 🔧 Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | Web server port | `3000` |
| `QUIZ_DB_PATH` | Database file location | `./data/quiz.db` |
| `LOG_LEVEL` | Logging level | `info` |
| `NODE_ENV` | Environment mode | `development` |

### Custom Database Location
```bash
export QUIZ_DB_PATH="/path/to/custom/quiz.db"
npx mcp-quiz-server start
```

### Debug Mode
```bash
export LOG_LEVEL="debug"
npx mcp-quiz-server mcp
```

## 🛠️ Development

### Prerequisites
- Node.js v16 or higher
- npm or yarn

### Setup
```bash
git clone https://github.com/GSejas/mcp-quiz-oss.git
cd mcp-quiz-oss
npm install
```

### Development Commands
```bash
npm run dev           # Start development server
npm run build         # Build for production
npm run test          # Run tests
npm run lint          # Run linting
npm run format        # Format code
```

### Testing
```bash
npm run test:quick    # Quick smoke tests
npm run test:mcp      # MCP integration tests
npm run test:db       # Database tests
npm run test:e2e      # End-to-end tests
```

## 📁 Project Structure

```
mcp-quiz-server/
├── src/
│   ├── application/     # Application layer (commands, queries)
│   ├── domain/         # Domain layer (entities, services)
│   ├── infrastructure/ # Infrastructure layer (database, HTTP)
│   ├── mcp/           # MCP protocol implementation
│   ├── shared/        # Shared utilities
│   ├── index.ts       # CLI entry point
│   ├── server.ts      # Web server entry point
│   └── mcp-server.ts  # MCP server entry point
├── public/            # Web interface assets
├── tests/             # Test suites
├── docs/              # Documentation
└── data/              # Database files
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Workflow
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run the test suite
6. Submit a pull request

### Code Style
- TypeScript with strict mode
- ESLint + Prettier for formatting
- Clean Architecture principles
- Comprehensive test coverage

## 📚 Documentation

- 🔧 [VS Code Setup Guide](docs/vscode-setup.md)
- 🤖 [Claude Desktop Setup Guide](docs/claude-setup.md)
- 🏗️ [Architecture Overview](docs/architecture.md)
- 📖 [API Documentation](docs/api.md)
- 🧪 [Testing Guide](docs/testing.md)

## 🔒 Security

- **Local Database** - No cloud dependencies or data transmission
- **Input Validation** - All inputs are sanitized and validated
- **Type Safety** - TypeScript provides compile-time safety
- **Secure Headers** - HTTP security headers enabled by default
- **Rate Limiting** - Protection against abuse

Report security issues to: [security@example.com](mailto:security@example.com)

## 📈 Roadmap

- [ ] **Multi-language Support** - Internationalization
- [ ] **Advanced Question Types** - Drag-drop, code snippets, multimedia
- [ ] **Team Collaboration** - Multi-user quiz editing
- [ ] **LMS Integration** - Canvas, Moodle, Blackboard connectors
- [ ] **AI Question Generation** - Automated content creation
- [ ] **Voice Interaction** - Audio-based quiz taking
- [ ] **Mobile Apps** - Native iOS and Android apps

## 🏆 Why Choose MCP Quiz Server?

| Feature | MCP Quiz Server | Traditional Quiz Tools |
|---------|-----------------|------------------------|
| **AI Integration** | ✅ Native VS Code & Claude | ❌ Limited or none |
| **Zero Install** | ✅ NPX ready | ❌ Complex setup |
| **Local First** | ✅ No cloud dependency | ❌ Cloud required |
| **Developer Friendly** | ✅ TypeScript, APIs | ❌ Limited extensibility |
| **Open Source** | ✅ MIT License | ❌ Proprietary |
| **Modern UI** | ✅ React-like experience | ❌ Outdated interfaces |

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
- Inspired by modern educational technology needs
- Thanks to all contributors and the open-source community

## 📞 Support

- 🐛 [Report Issues](https://github.com/GSejas/mcp-quiz-oss/issues)
- 💬 [Discussions](https://github.com/GSejas/mcp-quiz-oss/discussions)
- 📧 [Email Support](mailto:support@example.com)
- 📚 [Documentation](https://github.com/GSejas/mcp-quiz-oss/wiki)

---

<div align="center">

**Made with ❤️ for educators, developers, and learners worldwide**

[⭐ Star this project](https://github.com/GSejas/mcp-quiz-oss) • [🔄 Fork it](https://github.com/GSejas/mcp-quiz-oss/fork) • [📢 Share it](https://twitter.com/intent/tweet?text=Check%20out%20MCP%20Quiz%20Server%20-%20AI-powered%20quiz%20management!&url=https://github.com/GSejas/mcp-quiz-oss)

</div>