@gonzih/exam-prep-mcp 0.1.0

package/dist/fsrs.js

@@ -0,0 +1,101 @@
+// FSRS-5 Spaced Repetition Algorithm Implementation
+const FSRS_PARAMS = {
+    w: [
+        0.4072, 1.1829, 3.1262, 15.4722, 7.2102, 0.5316, 1.0651, 0.0589,
+        1.5330, 0.1544, 1.0071, 1.9299, 0.1100, 0.2900, 2.2700, 0.2500, 2.9898
+    ]
+};
+export function scheduleReview(rating, currentStability, currentDifficulty, reviewCount, lastReview) {
+    const w = FSRS_PARAMS.w;
+    let stability;
+    let difficulty;
+    let retrievability;
+    if (reviewCount === 0) {
+        // Initial scheduling for new cards
+        switch (rating) {
+            case 1:
+                stability = w[0];
+                break; // Again
+            case 2:
+                stability = w[1];
+                break; // Hard
+            case 3:
+                stability = w[2];
+                break; // Good
+            case 4:
+                stability = w[3];
+                break; // Easy
+        }
+        // Initial difficulty
+        difficulty = w[4] - Math.exp(w[5] * (rating - 1)) + 1;
+        difficulty = Math.max(1, Math.min(10, difficulty));
+        retrievability = 1.0;
+    }
+    else {
+        // Review scheduling
+        const now = new Date();
+        const elapsed = lastReview
+            ? (now.getTime() - lastReview.getTime()) / (1000 * 60 * 60 * 24)
+            : 1;
+        // R(t) = e^(-0.9 * t / S)
+        retrievability = calculateRetrievability(currentStability, elapsed);
+        // Update difficulty using mean reversion
+        const deltaDifficulty = -w[6] * (rating - 3);
+        difficulty = currentDifficulty + deltaDifficulty * (10 - currentDifficulty) / 9;
+        difficulty = Math.max(1, Math.min(10, difficulty));
+        // Calculate new stability based on rating
+        let stabilityMultiplier;
+        if (rating === 1) {
+            // Forgetting — reset stability
+            stability = w[11] * Math.pow(difficulty, -w[12]) *
+                (Math.pow(currentStability + 1, w[13]) - 1) *
+                Math.exp(w[14] * (1 - retrievability));
+        }
+        else {
+            // Recall — increase stability
+            const ratingFactor = rating === 2 ? w[15] : (rating === 4 ? w[16] : 1.0);
+            stabilityMultiplier = Math.exp(w[8]) *
+                (11 - difficulty) *
+                Math.pow(currentStability, -w[9]) *
+                (Math.exp(w[10] * (1 - retrievability)) - 1) *
+                ratingFactor;
+            stability = currentStability * (1 + stabilityMultiplier);
+        }
+        stability = Math.max(0.1, stability);
+    }
+    // Calculate next review interval
+    // For target retrievability of 0.9: interval = S * ln(0.9) / ln(R_target)
+    // Simplified: interval ≈ stability (days to reach 90% retrievability)
+    const targetRetrievability = 0.9;
+    let intervalDays = Math.round(stability * Math.log(targetRetrievability) / Math.log(0.9));
+    // Clamp interval
+    intervalDays = Math.max(1, Math.min(36500, intervalDays));
+    // For "Again" ratings, short review
+    if (rating === 1) {
+        intervalDays = 1;
+    }
+    const nextReview = new Date();
+    nextReview.setDate(nextReview.getDate() + intervalDays);
+    return {
+        stability,
+        difficulty,
+        retrievability,
+        nextReview,
+        intervalDays
+    };
+}
+// R(t) = e^(-t/S) where t = days since last review, S = stability
+export function calculateRetrievability(stability, daysSinceReview) {
+    if (daysSinceReview <= 0)
+        return 1.0;
+    const r = Math.exp(-0.9 * daysSinceReview / stability);
+    return Math.max(0, Math.min(1, r));
+}
+// Map a 0-1 accuracy to a rating
+export function accuracyToRating(correct, responseTime) {
+    if (!correct)
+        return 1; // Again
+    if (responseTime && responseTime > 60)
+        return 2; // Hard (took long)
+    return 3; // Good (default)
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema, ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import { initDb } from './db.js';
+import { setExam, getDailySession, answerQuestion, startMockExam, submitMockExam, getReadiness, getWeakAreas, } from './tools.js';
+const server = new Server({
+    name: 'exam-prep-mcp',
+    version: '0.1.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// ─── List Tools ───────────────────────────────────────────────────────────────
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: 'set_exam',
+                description: 'Configure an exam for a student profile. Seeds question cards and generates a study plan.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        profileId: {
+                            type: 'string',
+                            description: 'Unique identifier for the student (e.g., "alice", "student-001")',
+                        },
+                        examType: {
+                            type: 'string',
+                            enum: [
+                                'AP_Biology', 'AP_Chemistry', 'AP_US_History', 'AP_World_History',
+                                'AP_Physics', 'AP_Calculus', 'AP_Statistics', 'AP_English',
+                                'AP_Economics', 'SAT_Math', 'SAT_Reading', 'SAT_Writing',
+                                'MCAT', 'LSAT', 'GRE',
+                            ],
+                            description: 'Type of exam to prepare for',
+                        },
+                        examDate: {
+                            type: 'string',
+                            description: 'Exam date in YYYY-MM-DD format (e.g., "2025-05-15")',
+                        },
+                        currentLevel: {
+                            type: 'string',
+                            enum: ['beginner', 'intermediate', 'advanced'],
+                            description: 'Current knowledge level of the student',
+                        },
+                    },
+                    required: ['profileId', 'examType', 'examDate', 'currentLevel'],
+                },
+            },
+            {
+                name: 'get_daily_session',
+                description: 'Get today\'s personalized practice questions based on spaced repetition scheduling.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        profileId: {
+                            type: 'string',
+                            description: 'Student profile ID',
+                        },
+                    },
+                    required: ['profileId'],
+                },
+            },
+            {
+                name: 'answer_question',
+                description: 'Submit an answer to a practice question. Updates FSRS scheduling and topic stats.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        profileId: {
+                            type: 'string',
+                            description: 'Student profile ID',
+                        },
+                        cardId: {
+                            type: 'string',
+                            description: 'The card ID from get_daily_session or start_mock_exam',
+                        },
+                        answer: {
+                            type: 'string',
+                            description: 'The student\'s answer (for multiple choice: "A", "B", "C", or "D")',
+                        },
+                        rating: {
+                            type: 'number',
+                            enum: [1, 2, 3, 4],
+                            description: 'Optional manual difficulty rating: 1=Again, 2=Hard, 3=Good, 4=Easy',
+                        },
+                    },
+                    required: ['profileId', 'cardId', 'answer'],
+                },
+            },
+            {
+                name: 'start_mock_exam',
+                description: 'Begin a timed full-length practice exam simulating real exam conditions.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        profileId: {
+                            type: 'string',
+                            description: 'Student profile ID',
+                        },
+                    },
+                    required: ['profileId'],
+                },
+            },
+            {
+                name: 'submit_mock_exam',
+                description: 'Submit all answers for a mock exam and receive scoring and analysis.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        sessionId: {
+                            type: 'string',
+                            description: 'Session ID from start_mock_exam',
+                        },
+                        answers: {
+                            type: 'array',
+                            description: 'Array of answers for each question',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    cardId: { type: 'string', description: 'Card ID' },
+                                    answer: { type: 'string', description: 'Student\'s answer' },
+                                },
+                                required: ['cardId', 'answer'],
+                            },
+                        },
+                    },
+                    required: ['sessionId', 'answers'],
+                },
+            },
+            {
+                name: 'get_readiness',
+                description: 'Get a comprehensive readiness report with score, grade estimate, trends, and recommendations.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        profileId: {
+                            type: 'string',
+                            description: 'Student profile ID',
+                        },
+                    },
+                    required: ['profileId'],
+                },
+            },
+            {
+                name: 'get_weak_areas',
+                description: 'Identify topics with low accuracy that need focused study.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        profileId: {
+                            type: 'string',
+                            description: 'Student profile ID',
+                        },
+                    },
+                    required: ['profileId'],
+                },
+            },
+        ],
+    };
+});
+// ─── Call Tool ────────────────────────────────────────────────────────────────
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    if (!args) {
+        throw new McpError(ErrorCode.InvalidParams, 'No arguments provided');
+    }
+    try {
+        let result;
+        switch (name) {
+            case 'set_exam':
+                result = await setExam(args);
+                break;
+            case 'get_daily_session':
+                result = await getDailySession(args);
+                break;
+            case 'answer_question':
+                result = await answerQuestion(args);
+                break;
+            case 'start_mock_exam':
+                result = await startMockExam(args);
+                break;
+            case 'submit_mock_exam':
+                result = await submitMockExam(args);
+                break;
+            case 'get_readiness':
+                result = await getReadiness(args);
+                break;
+            case 'get_weak_areas':
+                result = await getWeakAreas(args);
+                break;
+            default:
+                throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        if (error instanceof McpError) {
+            throw error;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        throw new McpError(ErrorCode.InternalError, `Tool execution failed: ${message}`);
+    }
+});
+// ─── Start Server ─────────────────────────────────────────────────────────────
+async function main() {
+    // Initialize database
+    initDb();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Log to stderr so stdout remains clean for MCP protocol
+    process.stderr.write('exam-prep-mcp server started\n');
+}
+main().catch((error) => {
+    process.stderr.write(`Fatal error: ${error}\n`);
+    process.exit(1);
+});

package/dist/questions.d.ts

@@ -0,0 +1,17 @@
+export interface QuestionTemplate {
+    subject: string;
+    topic: string;
+    type: 'multiple_choice' | 'short_answer' | 'free_response' | 'problem_solving';
+    question: string;
+    answer: string;
+    explanation: string;
+    choices?: string[];
+    difficulty: 'easy' | 'medium' | 'hard';
+    examWeight: number;
+}
+export declare const QUESTION_BANK: QuestionTemplate[];
+export declare function getQuestionsBySubject(subject: string): QuestionTemplate[];
+export declare function getQuestionsByTopic(subject: string, topic: string): QuestionTemplate[];
+export declare function getRandomQuestions(subject: string, count: number): QuestionTemplate[];
+export declare function getAllSubjects(): string[];
+export declare function getTopicsForSubject(subject: string): string[];