@gonzih/exam-prep-mcp 0.1.0

package/src/db.ts

@@ -0,0 +1,257 @@
+import Database from 'better-sqlite3';
+import { homedir } from 'os';
+import { join } from 'path';
+import { mkdirSync } from 'fs';
+
+export interface Card {
+  id: string;
+  profile_id: string;
+  subject: string;
+  topic: string;
+  question: string;
+  answer: string;
+  difficulty: number;
+  stability: number;
+  retrievability: number;
+  next_review: string | null;
+  review_count: number;
+  last_rating: number | null;
+  created_at: string;
+}
+
+export interface Session {
+  id: string;
+  profile_id: string;
+  exam_type: string;
+  started_at: string;
+  ended_at: string | null;
+  questions_answered: number;
+  correct: number;
+  readiness_score: number | null;
+}
+
+export interface ExamConfig {
+  profile_id: string;
+  exam_type: string;
+  exam_date: string;
+  current_level: string;
+  created_at: string;
+}
+
+export interface TopicStats {
+  profile_id: string;
+  topic: string;
+  subject: string;
+  total_attempts: number;
+  correct_attempts: number;
+  last_attempt: string | null;
+}
+
+let db: Database.Database | null = null;
+
+export function getDb(): Database.Database {
+  if (!db) {
+    db = initDb();
+  }
+  return db;
+}
+
+export function initDb(): Database.Database {
+  const dbPath = process.env.EXAM_PREP_DB || join(homedir(), '.exam-prep', 'study.sqlite');
+  const dir = dbPath.substring(0, dbPath.lastIndexOf('/'));
+  mkdirSync(dir, { recursive: true });
+
+  const database = new Database(dbPath);
+  database.pragma('journal_mode = WAL');
+
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS cards (
+      id TEXT PRIMARY KEY,
+      profile_id TEXT NOT NULL,
+      subject TEXT NOT NULL,
+      topic TEXT NOT NULL,
+      question TEXT NOT NULL,
+      answer TEXT NOT NULL,
+      difficulty REAL DEFAULT 0.3,
+      stability REAL DEFAULT 1.0,
+      retrievability REAL DEFAULT 1.0,
+      next_review TEXT,
+      review_count INTEGER DEFAULT 0,
+      last_rating INTEGER,
+      created_at TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS sessions (
+      id TEXT PRIMARY KEY,
+      profile_id TEXT NOT NULL,
+      exam_type TEXT NOT NULL,
+      started_at TEXT NOT NULL,
+      ended_at TEXT,
+      questions_answered INTEGER DEFAULT 0,
+      correct INTEGER DEFAULT 0,
+      readiness_score REAL
+    );
+
+    CREATE TABLE IF NOT EXISTS exam_config (
+      profile_id TEXT PRIMARY KEY,
+      exam_type TEXT NOT NULL,
+      exam_date TEXT NOT NULL,
+      current_level TEXT NOT NULL,
+      created_at TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS topic_stats (
+      profile_id TEXT NOT NULL,
+      topic TEXT NOT NULL,
+      subject TEXT NOT NULL,
+      total_attempts INTEGER DEFAULT 0,
+      correct_attempts INTEGER DEFAULT 0,
+      last_attempt TEXT,
+      PRIMARY KEY (profile_id, topic)
+    );
+  `);
+
+  db = database;
+  return database;
+}
+
+// Card CRUD
+export function insertCard(card: Card): void {
+  const database = getDb();
+  database.prepare(`
+    INSERT OR IGNORE INTO cards
+      (id, profile_id, subject, topic, question, answer, difficulty, stability, retrievability, next_review, review_count, last_rating, created_at)
+    VALUES
+      (@id, @profile_id, @subject, @topic, @question, @answer, @difficulty, @stability, @retrievability, @next_review, @review_count, @last_rating, @created_at)
+  `).run(card);
+}
+
+export function getCard(id: string): Card | undefined {
+  return getDb().prepare('SELECT * FROM cards WHERE id = ?').get(id) as Card | undefined;
+}
+
+export function updateCard(card: Partial<Card> & { id: string }): void {
+  const database = getDb();
+  database.prepare(`
+    UPDATE cards SET
+      difficulty = @difficulty,
+      stability = @stability,
+      retrievability = @retrievability,
+      next_review = @next_review,
+      review_count = @review_count,
+      last_rating = @last_rating
+    WHERE id = @id
+  `).run(card);
+}
+
+export function getDueCards(profileId: string, now: string, limit: number): Card[] {
+  return getDb().prepare(`
+    SELECT * FROM cards
+    WHERE profile_id = ? AND (next_review IS NULL OR next_review <= ?)
+    ORDER BY next_review ASC NULLS FIRST
+    LIMIT ?
+  `).all(profileId, now, limit) as Card[];
+}
+
+export function getNewCards(profileId: string, limit: number): Card[] {
+  return getDb().prepare(`
+    SELECT * FROM cards
+    WHERE profile_id = ? AND review_count = 0
+    ORDER BY created_at ASC
+    LIMIT ?
+  `).all(profileId, limit) as Card[];
+}
+
+export function getCardsByProfile(profileId: string): Card[] {
+  return getDb().prepare('SELECT * FROM cards WHERE profile_id = ?').all(profileId) as Card[];
+}
+
+export function countCardsByQuestion(profileId: string, question: string): number {
+  const row = getDb().prepare('SELECT COUNT(*) as cnt FROM cards WHERE profile_id = ? AND question = ?').get(profileId, question) as { cnt: number };
+  return row.cnt;
+}
+
+export function getCardsByTopic(profileId: string, topic: string, limit: number): Card[] {
+  return getDb().prepare(`
+    SELECT * FROM cards WHERE profile_id = ? AND topic = ?
+    ORDER BY RANDOM() LIMIT ?
+  `).all(profileId, topic, limit) as Card[];
+}
+
+export function getAllCardsForExam(profileId: string, subject: string, limit: number): Card[] {
+  return getDb().prepare(`
+    SELECT * FROM cards WHERE profile_id = ? AND subject = ?
+    ORDER BY RANDOM() LIMIT ?
+  `).all(profileId, subject, limit) as Card[];
+}
+
+// Session CRUD
+export function insertSession(session: Session): void {
+  getDb().prepare(`
+    INSERT INTO sessions (id, profile_id, exam_type, started_at, ended_at, questions_answered, correct, readiness_score)
+    VALUES (@id, @profile_id, @exam_type, @started_at, @ended_at, @questions_answered, @correct, @readiness_score)
+  `).run(session);
+}
+
+export function updateSession(session: Partial<Session> & { id: string }): void {
+  getDb().prepare(`
+    UPDATE sessions SET
+      ended_at = @ended_at,
+      questions_answered = @questions_answered,
+      correct = @correct,
+      readiness_score = @readiness_score
+    WHERE id = @id
+  `).run(session);
+}
+
+export function getSession(id: string): Session | undefined {
+  return getDb().prepare('SELECT * FROM sessions WHERE id = ?').get(id) as Session | undefined;
+}
+
+export function getRecentSessions(profileId: string, limit: number): Session[] {
+  return getDb().prepare(`
+    SELECT * FROM sessions WHERE profile_id = ? ORDER BY started_at DESC LIMIT ?
+  `).all(profileId, limit) as Session[];
+}
+
+// Exam Config CRUD
+export function upsertExamConfig(config: ExamConfig): void {
+  getDb().prepare(`
+    INSERT OR REPLACE INTO exam_config (profile_id, exam_type, exam_date, current_level, created_at)
+    VALUES (@profile_id, @exam_type, @exam_date, @current_level, @created_at)
+  `).run(config);
+}
+
+export function getExamConfig(profileId: string): ExamConfig | undefined {
+  return getDb().prepare('SELECT * FROM exam_config WHERE profile_id = ?').get(profileId) as ExamConfig | undefined;
+}
+
+// Topic Stats CRUD
+export function upsertTopicStats(stats: TopicStats): void {
+  getDb().prepare(`
+    INSERT INTO topic_stats (profile_id, topic, subject, total_attempts, correct_attempts, last_attempt)
+    VALUES (@profile_id, @topic, @subject, @total_attempts, @correct_attempts, @last_attempt)
+    ON CONFLICT(profile_id, topic) DO UPDATE SET
+      total_attempts = topic_stats.total_attempts + @total_attempts,
+      correct_attempts = topic_stats.correct_attempts + @correct_attempts,
+      last_attempt = @last_attempt,
+      subject = @subject
+  `).run(stats);
+}
+
+export function getTopicStats(profileId: string): TopicStats[] {
+  return getDb().prepare('SELECT * FROM topic_stats WHERE profile_id = ?').all(profileId) as TopicStats[];
+}
+
+export function getTopicStat(profileId: string, topic: string): TopicStats | undefined {
+  return getDb().prepare('SELECT * FROM topic_stats WHERE profile_id = ? AND topic = ?').get(profileId, topic) as TopicStats | undefined;
+}
+
+export function getWeakTopics(profileId: string, threshold: number): TopicStats[] {
+  return getDb().prepare(`
+    SELECT * FROM topic_stats
+    WHERE profile_id = ? AND total_attempts >= 3
+      AND CAST(correct_attempts AS REAL) / total_attempts < ?
+    ORDER BY CAST(correct_attempts AS REAL) / total_attempts ASC
+  `).all(profileId, threshold) as TopicStats[];
+}

package/src/fsrs.ts

@@ -0,0 +1,118 @@
+// 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
+  ]
+};
+
+// Rating: 1=Again, 2=Hard, 3=Good, 4=Easy
+export interface FSRSResult {
+  stability: number;
+  difficulty: number;
+  retrievability: number;
+  nextReview: Date;
+  intervalDays: number;
+}
+
+export function scheduleReview(
+  rating: 1 | 2 | 3 | 4,
+  currentStability: number,
+  currentDifficulty: number,
+  reviewCount: number,
+  lastReview?: Date
+): FSRSResult {
+  const w = FSRS_PARAMS.w;
+  let stability: number;
+  let difficulty: number;
+  let retrievability: number;
+
+  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: number;
+    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: number, daysSinceReview: number): number {
+  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: boolean, responseTime?: number): 1 | 2 | 3 | 4 {
+  if (!correct) return 1; // Again
+  if (responseTime && responseTime > 60) return 2; // Hard (took long)
+  return 3; // Good (default)
+}

package/src/index.ts

@@ -0,0 +1,262 @@
+#!/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: unknown;
+
+    switch (name) {
+      case 'set_exam':
+        result = await setExam(args as unknown as Parameters<typeof setExam>[0]);
+        break;
+
+      case 'get_daily_session':
+        result = await getDailySession(args as unknown as Parameters<typeof getDailySession>[0]);
+        break;
+
+      case 'answer_question':
+        result = await answerQuestion(args as unknown as Parameters<typeof answerQuestion>[0]);
+        break;
+
+      case 'start_mock_exam':
+        result = await startMockExam(args as unknown as Parameters<typeof startMockExam>[0]);
+        break;
+
+      case 'submit_mock_exam':
+        result = await submitMockExam(args as unknown as Parameters<typeof submitMockExam>[0]);
+        break;
+
+      case 'get_readiness':
+        result = await getReadiness(args as unknown as Parameters<typeof getReadiness>[0]);
+        break;
+
+      case 'get_weak_areas':
+        result = await getWeakAreas(args as unknown as Parameters<typeof getWeakAreas>[0]);
+        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);
+});