@gonzih/exam-prep-mcp 0.1.0

package/src/tools.ts

@@ -0,0 +1,557 @@
+import { v4 as uuidv4 } from 'uuid';
+import {
+  insertCard,
+  insertSession,
+  updateSession,
+  getSession,
+  getCard,
+  updateCard,
+  getDueCards,
+  getNewCards,
+  getAllCardsForExam,
+  getWeakTopics,
+  upsertExamConfig,
+  getExamConfig,
+  upsertTopicStats,
+  getTopicStats,
+  countCardsByQuestion,
+  Card,
+} from './db.js';
+import { scheduleReview } from './fsrs.js';
+import { QUESTION_BANK, QuestionTemplate } from './questions.js';
+import { generateStudyPlan, MOCK_EXAM_QUESTIONS, EXAM_TIME_LIMITS } from './study-plan.js';
+import { calculateReadiness } from './readiness.js';
+
+// ─── Tool Input Types ─────────────────────────────────────────────────────────
+
+export interface SetExamInput {
+  profileId: string;
+  examType: string;
+  examDate: string;
+  currentLevel: 'beginner' | 'intermediate' | 'advanced';
+}
+
+export interface GetDailySessionInput {
+  profileId: string;
+}
+
+export interface AnswerQuestionInput {
+  profileId: string;
+  cardId: string;
+  answer: string;
+  rating?: 1 | 2 | 3 | 4;
+}
+
+export interface StartMockExamInput {
+  profileId: string;
+}
+
+export interface SubmitMockExamInput {
+  sessionId: string;
+  answers: Array<{ cardId: string; answer: string }>;
+}
+
+export interface GetReadinessInput {
+  profileId: string;
+}
+
+export interface GetWeakAreasInput {
+  profileId: string;
+}
+
+// ─── Helper Functions ─────────────────────────────────────────────────────────
+
+function questionTemplateToCard(template: QuestionTemplate, profileId: string): Card {
+  return {
+    id: uuidv4(),
+    profile_id: profileId,
+    subject: template.subject,
+    topic: template.topic,
+    question: formatQuestion(template),
+    answer: template.answer,
+    difficulty: template.difficulty === 'easy' ? 0.2 : template.difficulty === 'medium' ? 0.4 : 0.7,
+    stability: 1.0,
+    retrievability: 1.0,
+    next_review: new Date().toISOString(),
+    review_count: 0,
+    last_rating: null,
+    created_at: new Date().toISOString(),
+  };
+}
+
+function formatQuestion(template: QuestionTemplate): string {
+  if (template.type === 'multiple_choice' && template.choices) {
+    return `${template.question}\n\n${template.choices.join('\n')}`;
+  }
+  return template.question;
+}
+
+function evaluateAnswer(
+  card: Card,
+  studentAnswer: string,
+  template?: QuestionTemplate
+): { correct: boolean; explanation: string } {
+  const correctAnswer = card.answer.trim().toLowerCase();
+  const studentAnswerNorm = studentAnswer.trim().toLowerCase();
+
+  // Multiple choice — exact match (single letter)
+  if (template?.type === 'multiple_choice') {
+    const correct = correctAnswer === studentAnswerNorm ||
+      correctAnswer.startsWith(studentAnswerNorm) ||
+      studentAnswerNorm === correctAnswer[0];
+    return {
+      correct,
+      explanation: template.explanation
+    };
+  }
+
+  // Problem solving — check numeric answer
+  if (template?.type === 'problem_solving') {
+    // Extract numbers from both answers
+    const correctNum = extractNumber(correctAnswer);
+    const studentNum = extractNumber(studentAnswerNorm);
+    if (correctNum !== null && studentNum !== null) {
+      const tolerance = Math.abs(correctNum) * 0.05 || 0.01;
+      const correct = Math.abs(correctNum - studentNum) <= tolerance;
+      return { correct, explanation: template?.explanation || '' };
+    }
+    // Fallback to keyword matching
+    return keywordMatch(correctAnswer, studentAnswerNorm, template?.explanation || '');
+  }
+
+  // Short answer / free response — keyword matching
+  return keywordMatch(correctAnswer, studentAnswerNorm, template?.explanation || '');
+}
+
+function extractNumber(text: string): number | null {
+  const match = text.match(/-?\d+\.?\d*/);
+  if (match) return parseFloat(match[0]);
+  return null;
+}
+
+function keywordMatch(correctAnswer: string, studentAnswer: string, explanation: string): { correct: boolean; explanation: string } {
+  // Check if student answer contains key terms from correct answer
+  const keyTerms = correctAnswer
+    .split(/[\s,;.]+/)
+    .filter(w => w.length > 3)
+    .map(w => w.toLowerCase());
+
+  if (keyTerms.length === 0) {
+    const correct = correctAnswer === studentAnswer;
+    return { correct, explanation };
+  }
+
+  let matched = 0;
+  for (const term of keyTerms) {
+    if (studentAnswer.includes(term)) matched++;
+  }
+
+  const matchRatio = matched / keyTerms.length;
+  const correct = matchRatio >= 0.5;
+  return { correct, explanation };
+}
+
+function findTemplate(question: string): QuestionTemplate | undefined {
+  // Strip choices if present
+  const questionText = question.split('\n\n')[0];
+  return QUESTION_BANK.find(t => t.question === questionText);
+}
+
+// ─── Tool Implementations ─────────────────────────────────────────────────────
+
+export async function setExam(input: SetExamInput) {
+  const { profileId, examType, examDate, currentLevel } = input;
+
+  // Store exam config
+  upsertExamConfig({
+    profile_id: profileId,
+    exam_type: examType,
+    exam_date: examDate,
+    current_level: currentLevel,
+    created_at: new Date().toISOString(),
+  });
+
+  // Seed cards from question bank
+  const questions = QUESTION_BANK.filter(q => q.subject === examType);
+  let seeded = 0;
+
+  for (const template of questions) {
+    const formattedQuestion = formatQuestion(template);
+    const existing = countCardsByQuestion(profileId, formattedQuestion);
+    if (existing === 0) {
+      const card = questionTemplateToCard(template, profileId);
+      card.question = formattedQuestion;
+      insertCard(card);
+      seeded++;
+    }
+  }
+
+  // Generate study plan
+  const studyPlan = generateStudyPlan(examType, examDate, currentLevel);
+  const now = new Date();
+  const examDateObj = new Date(examDate);
+  const daysRemaining = Math.ceil((examDateObj.getTime() - now.getTime()) / (1000 * 60 * 60 * 24));
+
+  return {
+    success: true,
+    message: `Exam configured: ${examType} on ${examDate}`,
+    seededCards: seeded,
+    daysRemaining,
+    topicsIdentified: studyPlan.topicsIdentified,
+    studyPlan: {
+      examType: studyPlan.examType,
+      examDate: studyPlan.examDate,
+      daysRemaining: studyPlan.daysRemaining,
+      weeklyGoals: studyPlan.weeklyGoals,
+      first7Days: studyPlan.dailySchedule.slice(0, 7),
+    }
+  };
+}
+
+export async function getDailySession(input: GetDailySessionInput) {
+  const { profileId } = input;
+
+  const config = getExamConfig(profileId);
+  if (!config) {
+    throw new Error('No exam configured. Use set_exam first.');
+  }
+
+  const now = new Date().toISOString();
+  const TARGET_QUESTIONS = 12;
+
+  // Get due cards
+  let dueCards = getDueCards(profileId, now, TARGET_QUESTIONS);
+
+  // Top up with new cards if needed
+  if (dueCards.length < 5) {
+    const newCards = getNewCards(profileId, TARGET_QUESTIONS - dueCards.length);
+    const existingIds = new Set(dueCards.map(c => c.id));
+    const uniqueNew = newCards.filter(c => !existingIds.has(c.id));
+    dueCards = [...dueCards, ...uniqueNew].slice(0, TARGET_QUESTIONS);
+  }
+
+  // Identify focus areas
+  const topicCounts: Record<string, number> = {};
+  for (const card of dueCards) {
+    topicCounts[card.topic] = (topicCounts[card.topic] || 0) + 1;
+  }
+
+  const focusAreas = Object.entries(topicCounts)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 3)
+    .map(([topic]) => topic);
+
+  const questions = dueCards.map(card => ({
+    cardId: card.id,
+    subject: card.subject,
+    topic: card.topic,
+    question: card.question,
+    type: findTemplate(card.question)?.type || 'short_answer',
+    choices: findTemplate(card.question)?.choices,
+    difficulty: card.difficulty < 0.35 ? 'easy' : card.difficulty < 0.55 ? 'medium' : 'hard',
+    reviewCount: card.review_count,
+  }));
+
+  return {
+    questions,
+    estimatedMinutes: Math.ceil(dueCards.length * 2.5),
+    focusAreas,
+    totalDue: dueCards.length,
+    examType: config.exam_type,
+    examDate: config.exam_date,
+  };
+}
+
+export async function answerQuestion(input: AnswerQuestionInput) {
+  const { profileId, cardId, answer, rating } = input;
+
+  const card = getCard(cardId);
+  if (!card) {
+    throw new Error(`Card ${cardId} not found`);
+  }
+
+  if (card.profile_id !== profileId) {
+    throw new Error('Card does not belong to this profile');
+  }
+
+  const template = findTemplate(card.question);
+  const { correct, explanation } = evaluateAnswer(card, answer, template);
+
+  // Determine FSRS rating
+  let fsrsRating: 1 | 2 | 3 | 4 = rating || (correct ? 3 : 1);
+  if (!rating) {
+    fsrsRating = correct ? 3 : 1;
+  }
+
+  // Apply FSRS scheduling
+  const lastReview = card.next_review ? new Date(card.next_review) : undefined;
+  const fsrsResult = scheduleReview(
+    fsrsRating,
+    card.stability,
+    card.difficulty,
+    card.review_count,
+    lastReview
+  );
+
+  // Update card
+  updateCard({
+    id: card.id,
+    difficulty: fsrsResult.difficulty,
+    stability: fsrsResult.stability,
+    retrievability: fsrsResult.retrievability,
+    next_review: fsrsResult.nextReview.toISOString(),
+    review_count: card.review_count + 1,
+    last_rating: fsrsRating,
+  });
+
+  // Update topic stats
+  upsertTopicStats({
+    profile_id: profileId,
+    topic: card.topic,
+    subject: card.subject,
+    total_attempts: 1,
+    correct_attempts: correct ? 1 : 0,
+    last_attempt: new Date().toISOString(),
+  });
+
+  // Check for weak area
+  let weakAreaAlert: string | undefined;
+  const topicStats = getTopicStats(profileId).find(s => s.topic === card.topic);
+  if (topicStats && topicStats.total_attempts >= 5) {
+    const accuracy = topicStats.correct_attempts / topicStats.total_attempts;
+    if (accuracy < 0.6) {
+      weakAreaAlert = `Weak area detected: ${card.topic} (${Math.round(accuracy * 100)}% accuracy over ${topicStats.total_attempts} attempts). Consider extra focus on this topic.`;
+    }
+  }
+
+  return {
+    correct,
+    correctAnswer: card.answer,
+    explanation,
+    nextReview: fsrsResult.nextReview.toISOString(),
+    intervalDays: fsrsResult.intervalDays,
+    rating: fsrsRating,
+    weakAreaAlert,
+    topic: card.topic,
+    subject: card.subject,
+  };
+}
+
+export async function startMockExam(input: StartMockExamInput) {
+  const { profileId } = input;
+
+  const config = getExamConfig(profileId);
+  if (!config) {
+    throw new Error('No exam configured. Use set_exam first.');
+  }
+
+  const examType = config.exam_type;
+  const questionCount = MOCK_EXAM_QUESTIONS[examType] || 60;
+  const timeLimitMins = EXAM_TIME_LIMITS[examType] || 120;
+
+  // Select balanced questions across topics
+  const cards = getAllCardsForExam(profileId, examType, questionCount * 2);
+  const shuffled = [...cards].sort(() => Math.random() - 0.5);
+  const selected = shuffled.slice(0, questionCount);
+
+  // Create session
+  const sessionId = uuidv4();
+  insertSession({
+    id: sessionId,
+    profile_id: profileId,
+    exam_type: examType,
+    started_at: new Date().toISOString(),
+    ended_at: null,
+    questions_answered: 0,
+    correct: 0,
+    readiness_score: null,
+  });
+
+  const questions = selected.map(card => ({
+    cardId: card.id,
+    subject: card.subject,
+    topic: card.topic,
+    question: card.question,
+    type: findTemplate(card.question)?.type || 'short_answer',
+    choices: findTemplate(card.question)?.choices,
+  }));
+
+  return {
+    sessionId,
+    questions,
+    timeLimitMins,
+    totalQuestions: questions.length,
+    examType,
+    instructions: `You have ${timeLimitMins} minutes to complete ${questions.length} questions. This simulates the actual ${examType} exam. Answer each question and submit when done.`,
+  };
+}
+
+export async function submitMockExam(input: SubmitMockExamInput) {
+  const { sessionId, answers } = input;
+
+  const session = getSession(sessionId);
+  if (!session) {
+    throw new Error(`Session ${sessionId} not found`);
+  }
+
+  const profileId = session.profile_id;
+  const config = getExamConfig(profileId);
+
+  // Grade all answers
+  let correct = 0;
+  const topicBreakdown: Record<string, { correct: number; total: number }> = {};
+  const gradedAnswers: Array<{
+    cardId: string;
+    correct: boolean;
+    topic: string;
+  }> = [];
+
+  for (const submission of answers) {
+    const card = getCard(submission.cardId);
+    if (!card) continue;
+
+    const template = findTemplate(card.question);
+    const result = evaluateAnswer(card, submission.answer, template);
+
+    if (result.correct) correct++;
+
+    // Update topic stats
+    upsertTopicStats({
+      profile_id: profileId,
+      topic: card.topic,
+      subject: card.subject,
+      total_attempts: 1,
+      correct_attempts: result.correct ? 1 : 0,
+      last_attempt: new Date().toISOString(),
+    });
+
+    // Topic breakdown
+    if (!topicBreakdown[card.topic]) {
+      topicBreakdown[card.topic] = { correct: 0, total: 0 };
+    }
+    topicBreakdown[card.topic].total++;
+    if (result.correct) topicBreakdown[card.topic].correct++;
+
+    gradedAnswers.push({
+      cardId: submission.cardId,
+      correct: result.correct,
+      topic: card.topic,
+    });
+  }
+
+  const total = answers.length;
+  const score = total > 0 ? Math.round((correct / total) * 100) : 0;
+
+  // Calculate readiness
+  let readinessReport = null;
+  if (config) {
+    readinessReport = calculateReadiness(profileId, config.exam_type, config.exam_date);
+  }
+
+  // Update session
+  updateSession({
+    id: sessionId,
+    ended_at: new Date().toISOString(),
+    questions_answered: total,
+    correct,
+    readiness_score: readinessReport?.score ?? null,
+  });
+
+  // Format topic breakdown
+  const topicResults = Object.entries(topicBreakdown).map(([topic, stats]) => ({
+    topic,
+    correct: stats.correct,
+    total: stats.total,
+    accuracy: Math.round((stats.correct / stats.total) * 100),
+  })).sort((a, b) => a.accuracy - b.accuracy);
+
+  // Determine passing threshold
+  const examType = session.exam_type;
+  let passingThreshold = 60;
+  let estimatedGrade = `${score}%`;
+
+  if (examType.startsWith('AP_')) {
+    passingThreshold = 55;
+    if (score >= 85) estimatedGrade = 'AP Score: 5/5';
+    else if (score >= 70) estimatedGrade = 'AP Score: 4/5';
+    else if (score >= 55) estimatedGrade = 'AP Score: 3/5';
+    else if (score >= 40) estimatedGrade = 'AP Score: 2/5';
+    else estimatedGrade = 'AP Score: 1/5';
+  } else if (examType === 'SAT_Math') {
+    passingThreshold = 60;
+    if (score >= 90) estimatedGrade = 'SAT Math: ~760-800';
+    else if (score >= 80) estimatedGrade = 'SAT Math: ~700-750';
+    else if (score >= 70) estimatedGrade = 'SAT Math: ~630-690';
+    else estimatedGrade = 'SAT Math: below 630';
+  }
+
+  return {
+    score,
+    correct,
+    total,
+    passingThreshold,
+    passed: score >= passingThreshold,
+    estimatedGrade,
+    readinessScore: readinessReport?.score,
+    topicBreakdown: topicResults,
+    strongestTopics: topicResults.filter(t => t.accuracy >= 80).map(t => t.topic),
+    weakestTopics: topicResults.filter(t => t.accuracy < 60).map(t => t.topic),
+    recommendation: readinessReport?.recommendation,
+  };
+}
+
+export async function getReadiness(input: GetReadinessInput) {
+  const { profileId } = input;
+
+  const config = getExamConfig(profileId);
+  if (!config) {
+    throw new Error('No exam configured. Use set_exam first.');
+  }
+
+  const report = calculateReadiness(profileId, config.exam_type, config.exam_date);
+
+  return {
+    profileId,
+    examType: config.exam_type,
+    examDate: config.exam_date,
+    ...report,
+  };
+}
+
+export interface WeakArea {
+  topic: string;
+  subject: string;
+  accuracy: number;
+  attempts: number;
+  correctAttempts: number;
+}
+
+export async function getWeakAreas(input: GetWeakAreasInput) {
+  const { profileId } = input;
+
+  const config = getExamConfig(profileId);
+  const weakTopicStats = getWeakTopics(profileId, 0.6);
+
+  const topics: WeakArea[] = weakTopicStats.map(stats => ({
+    topic: stats.topic,
+    subject: stats.subject,
+    accuracy: Math.round((stats.correct_attempts / stats.total_attempts) * 100),
+    attempts: stats.total_attempts,
+    correctAttempts: stats.correct_attempts,
+  }));
+
+  // Suggest focus
+  let suggestedFocus = 'No weak areas identified yet — keep practicing!';
+  if (topics.length > 0) {
+    const top3 = topics.slice(0, 3).map(t => t.topic).join(', ');
+    suggestedFocus = `Focus intensively on: ${top3}. Aim for at least 10 practice questions per topic before your exam.`;
+  }
+
+  return {
+    profileId,
+    examType: config?.exam_type,
+    topics,
+    suggestedFocus,
+    totalWeakTopics: topics.length,
+  };
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}