🧠 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

Open Command Palette (Ctrl+Shift+P)
Type "MCP: Execute Tool"
Select create_quiz
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

Fork the repository
Create a feature branch
Make your changes
Add tests
Run the test suite
Submit a pull request

Code Style

TypeScript with strict mode
ESLint + Prettier for formatting
Clean Architecture principles
Comprehensive test coverage

📚 Documentation

🔒 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

📈 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

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

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

mcp-quiz-server