🧠 MCP Quiz Server

🚀 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)

# 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

npm install -g mcp-quiz-server
mcp-quiz-server start

🔧 Integration Setup

VS Code MCP Extension

Add to your VS Code settings (settings.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):

{
  "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:

{
  "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:

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:

// 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

export QUIZ_DB_PATH="/path/to/custom/quiz.db"
npx mcp-quiz-server start

Debug Mode

export LOG_LEVEL="debug"
npx mcp-quiz-server mcp

🛠️ Development

Prerequisites

• Node.js v16 or higher
• npm or yarn

Setup

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

Development Commands

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

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 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
• 🤖 Claude Desktop Setup Guide
• 🏗️ Architecture Overview
• 📖 API Documentation
• 🧪 Testing Guide

🔒 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: [email protected]

📈 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 file for details.

🙏 Acknowledgments

• Built with the Model Context Protocol (MCP)
• Inspired by modern educational technology needs
• Thanks to all contributors and the open-source community

📞 Support

• 🐛 Report Issues
• 💬 Discussions
• 📧 Email Support
• 📚 Documentation

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

⭐ Star this project • 🔄 Fork it • 📢 Share it