mcp-quiz-server
Version:
🧠AI-Powered Quiz Management via Model Context Protocol (MCP) - Create, manage, and take quizzes directly from VS Code, Claude, and other AI agents.
232 lines (231 loc) • 8.77 kB
JavaScript
;
/**
* OpenAPI Specification Generator for MCP Quiz Server
*
* @description Generates OpenAPI 3.0 specification from route definitions
* @version 1.0.0
* @since 2025-08-01
*/
var __importDefault = (this && this.__importDefault) || function (mod) {
return (mod && mod.__esModule) ? mod : { "default": mod };
};
Object.defineProperty(exports, "__esModule", { value: true });
exports.generateOpenAPISpec = generateOpenAPISpec;
exports.setupSwaggerUI = setupSwaggerUI;
exports.exportOpenAPISpec = exportOpenAPISpec;
const swagger_jsdoc_1 = __importDefault(require("swagger-jsdoc"));
/**
* OpenAPI specification configuration
*/
const swaggerOptions = {
definition: {
openapi: '3.0.0',
info: {
title: 'MCP Quiz Server API',
version: '0.0.1',
description: 'TypeScript quiz platform showcasing Model Context Protocol integration',
contact: {
name: 'MCP Quiz Server Team',
url: 'https://github.com/GSejas/mcp-quiz-server',
email: 'support@mcp-quiz-server.com',
},
license: {
name: 'MIT',
url: 'https://opensource.org/licenses/MIT',
},
},
servers: [
{
url: 'http://localhost:3000',
description: 'Development server',
},
{
url: 'https://api.mcp-quiz-server.com',
description: 'Production server',
},
],
components: {
securitySchemes: {
bearerAuth: {
type: 'http',
scheme: 'bearer',
bearerFormat: 'JWT',
},
},
schemas: {
Quiz: {
type: 'object',
required: ['id', 'title', 'questions'],
properties: {
id: {
type: 'string',
description: 'Unique quiz identifier',
},
title: {
type: 'string',
description: 'Quiz title',
},
description: {
type: 'string',
description: 'Quiz description',
},
questions: {
type: 'array',
items: { $ref: '#/components/schemas/Question' },
},
timeLimit: {
type: 'number',
description: 'Time limit in seconds',
},
difficulty: {
type: 'string',
enum: ['easy', 'medium', 'hard'],
},
},
},
Question: {
type: 'object',
required: ['id', 'text', 'type', 'options'],
properties: {
id: {
type: 'string',
description: 'Unique question identifier',
},
text: {
type: 'string',
description: 'Question text',
},
type: {
type: 'string',
enum: ['multiple-choice', 'true-false', 'text'],
description: 'Question type',
},
options: {
type: 'array',
items: {
type: 'object',
properties: {
id: { type: 'string' },
text: { type: 'string' },
correct: { type: 'boolean' },
},
},
},
explanation: {
type: 'string',
description: 'Explanation for the correct answer',
},
},
},
QuizResult: {
type: 'object',
properties: {
quizId: { type: 'string' },
userId: { type: 'string' },
score: { type: 'number' },
totalQuestions: { type: 'number' },
correctAnswers: { type: 'number' },
completedAt: { type: 'string', format: 'date-time' },
timeSpent: { type: 'number', description: 'Time spent in seconds' },
},
},
Error: {
type: 'object',
required: ['type', 'title', 'status'],
properties: {
type: {
type: 'string',
description: 'A URI reference that identifies the problem type',
},
title: {
type: 'string',
description: 'A short, human-readable summary of the problem',
},
status: {
type: 'number',
description: 'The HTTP status code',
},
detail: {
type: 'string',
description: 'A human-readable explanation specific to this occurrence',
},
instance: {
type: 'string',
description: 'A URI reference that identifies the specific occurrence',
},
},
},
HealthCheck: {
type: 'object',
properties: {
status: {
type: 'string',
enum: ['healthy', 'degraded', 'unhealthy'],
},
timestamp: {
type: 'string',
format: 'date-time',
},
uptime: {
type: 'number',
description: 'Server uptime in seconds',
},
database: {
type: 'object',
properties: {
connected: { type: 'boolean' },
responseTime: { type: 'number' },
},
},
mcp: {
type: 'object',
properties: {
status: { type: 'string' },
toolsCount: { type: 'number' },
},
},
},
},
},
},
security: [
{
bearerAuth: [],
},
],
},
apis: ['./src/infrastructure/http/routes/*.ts', './src/controllers/*.ts', './src/server.ts'],
};
/**
* Generate OpenAPI specification
*/
function generateOpenAPISpec() {
return (0, swagger_jsdoc_1.default)(swaggerOptions);
}
/**
* Setup Swagger UI middleware for Express app
*/
function setupSwaggerUI(app) {
const swaggerUi = require('swagger-ui-express');
const specs = generateOpenAPISpec();
// Serve swagger-ui at /api-docs
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs, {
explorer: true,
customCss: '.swagger-ui .topbar { display: none }',
customSiteTitle: 'MCP Quiz Server API Documentation',
}));
// Serve raw JSON at /api-docs.json
app.get('/api-docs.json', (req, res) => {
res.setHeader('Content-Type', 'application/json');
res.send(specs);
});
}
/**
* Export OpenAPI spec to file
*/
function exportOpenAPISpec(outputPath = './openapi.json') {
const fs = require('fs');
const specs = generateOpenAPISpec();
fs.writeFileSync(outputPath, JSON.stringify(specs, null, 2));
console.log(`OpenAPI specification exported to ${outputPath}`);
}