npm package: @gonzih/exam-prep-mcp
Description: AI-powered exam preparation MCP server with FSRS spaced repetition
Author: Gonzih
Latest version: 0.1.0

# exam-prep-mcp

> AI-powered exam preparation MCP server with FSRS-5 spaced repetition

[![npm version](https://badge.fury.io/js/@gonzih%2Fexam-prep-mcp.svg)](https://www.npmjs.com/package/@gonzih/exam-prep-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Overview

`exam-prep-mcp` is a Model Context Protocol (MCP) server that brings adaptive, science-backed exam preparation into your AI assistant workflow. It uses the **FSRS-5 spaced repetition algorithm** to schedule reviews at optimal intervals — you study smarter, not harder.

### Features

- **FSRS-5 Spaced Repetition** — Cards are scheduled based on your performance and forgetting curves
- **50+ Real Practice Questions** — Accurate questions with detailed explanations across AP and SAT subjects
- **Study Plan Generator** — Personalized day-by-day schedule based on your exam date and level
- **Mock Exams** — Full-length timed practice exams with grade estimates
- **Readiness Score** — Track your preparation progress with a 0-100 readiness score
- **Weak Area Detection** — Automatically identifies topics that need more focus
- **Multiple Exam Types** — AP Biology, AP Chemistry, AP US History, SAT Math, MCAT, LSAT, GRE, and more

## Installation

### Global install (recommended)

```bash
npm install -g @gonzih/exam-prep-mcp
```

### Run without installing

```bash
npx @gonzih/exam-prep-mcp
```

## MCP Configuration

### Claude Desktop

Add to your `claude_desktop_config.json`:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "exam-prep": {
      "command": "exam-prep-mcp"
    }
  }
}
```

Or with npx:

```json
{
  "mcpServers": {
    "exam-prep": {
      "command": "npx",
      "args": ["-y", "@gonzih/exam-prep-mcp"]
    }
  }
}
```

### Custom database path

```json
{
  "mcpServers": {
    "exam-prep": {
      "command": "exam-prep-mcp",
      "env": {
        "EXAM_PREP_DB": "/path/to/your/study.sqlite"
      }
    }
  }
}
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `EXAM_PREP_DB` | `~/.exam-prep/study.sqlite` | Path to SQLite database file |

## Tools

### 1. `set_exam`

Configure an exam for a student profile. Seeds question cards and generates a personalized study plan.

**Parameters:**
- `profileId` (string, required) — Unique student identifier (e.g., `"alice"`, `"student-001"`)
- `examType` (string, required) — Exam to prepare for (see Supported Exams below)
- `examDate` (string, required) — Exam date in `YYYY-MM-DD` format
- `currentLevel` (string, required) — `"beginner"`, `"intermediate"`, or `"advanced"`

**Returns:** Study plan, topics identified, days remaining, seeded card count

---

### 2. `get_daily_session`

Get today's personalized practice questions based on FSRS spaced repetition scheduling.

**Parameters:**
- `profileId` (string, required) — Student profile ID

**Returns:** 10-15 questions with card IDs, topics, question text, choices (for MC), estimated time, focus areas

---

### 3. `answer_question`

Submit an answer to a practice question. Evaluates correctness, applies FSRS scheduling, and detects weak areas.

**Parameters:**
- `profileId` (string, required) — Student profile ID
- `cardId` (string, required) — Card ID from `get_daily_session` or `start_mock_exam`
- `answer` (string, required) — Student's answer (`"A"`, `"B"`, `"C"`, `"D"` for multiple choice; text for others)
- `rating` (1-4, optional) — Manual difficulty rating: 1=Again, 2=Hard, 3=Good, 4=Easy

**Returns:** Correct/incorrect, correct answer, explanation, next review date, weak area alert if applicable

---

### 4. `start_mock_exam`

Begin a timed full-length practice exam simulating real exam conditions.

**Parameters:**
- `profileId` (string, required) — Student profile ID

**Returns:** Session ID, all exam questions, time limit in minutes, instructions

---

### 5. `submit_mock_exam`

Submit all answers for a completed mock exam and receive detailed scoring and analysis.

**Parameters:**
- `sessionId` (string, required) — Session ID from `start_mock_exam`
- `answers` (array, required) — Array of `{ cardId, answer }` objects

**Returns:** Score, grade estimate, topic breakdown, weak/strong topics, readiness score update, recommendation

---

### 6. `get_readiness`

Get a comprehensive readiness report with your current score, grade estimate, performance trend, and recommendation.

**Parameters:**
- `profileId` (string, required) — Student profile ID

**Returns:** 0-100 readiness score, strong/weak topics, coverage percent, trend (improving/declining/stable), grade estimate, recommendation

---

### 7. `get_weak_areas`

Identify topics with accuracy below 60% that need focused study.

**Parameters:**
- `profileId` (string, required) — Student profile ID

**Returns:** Ranked list of weak topics with accuracy and attempt counts, suggested focus plan

## Supported Exam Types

| Exam Type | Description | Questions | Time Limit |
|-----------|-------------|-----------|------------|
| `AP_Biology` | AP Biology | 60 | 170 min |
| `AP_Chemistry` | AP Chemistry | 60 | 190 min |
| `AP_US_History` | AP US History | 55 | 205 min |
| `AP_World_History` | AP World History | 55 | 205 min |
| `AP_Physics` | AP Physics | 50 | 180 min |
| `AP_Calculus` | AP Calculus AB/BC | 45 | 195 min |
| `AP_Statistics` | AP Statistics | 40 | 180 min |
| `AP_English` | AP English Language | 45 | 215 min |
| `AP_Economics` | AP Micro/Macro Economics | 60 | 130 min |
| `SAT_Math` | SAT Math section | 44 | 70 min |
| `SAT_Reading` | SAT Reading section | 52 | 65 min |
| `SAT_Writing` | SAT Writing section | 44 | 35 min |
| `MCAT` | Medical College Admissions | 230 | 375 min |
| `LSAT` | Law School Admissions | 100 | 175 min |
| `GRE` | Graduate Record Examination | 80 | 225 min |

## Example Conversation

**Scenario:** Student has AP Chemistry exam in 3 weeks

---

**Student:** I have my AP Chemistry exam on May 15th. I'm currently at an intermediate level. Can you set me up?

**Claude:** I'll set up your AP Chemistry exam prep right away!

*[calls `set_exam` with profileId="student", examType="AP_Chemistry", examDate="2025-05-15", currentLevel="intermediate"]*

Great! I've configured your AP Chemistry prep:
- **21 days** until your exam
- **10 topics** identified: Atomic Structure, Chemical Bonding, Stoichiometry, Gas Laws, Thermodynamics, Chemical Equilibrium, Acids and Bases, Electrochemistry, Kinetics, Nuclear Chemistry
- **48 practice cards** seeded into your study queue
- Weekly goal: Master 3-4 topics per week

---

**Student:** What should I study today?

**Claude:** *[calls `get_daily_session`]*

Today's session (12 questions, ~30 min):

**Focus areas:** Stoichiometry, Gas Laws, Acids and Bases

1. **[Stoichiometry]** How many grams of H₂O are produced when 4.0g of H₂ reacts completely with excess O₂?
2. **[Gas Laws]** A gas occupies 2.0 L at 300K and 1.0 atm. What volume at 600K and 2.0 atm?
...

---

**Student:** For question 1, I think it's 36 grams.

**Claude:** *[calls `answer_question` with answer="36 g"]*

**Correct!** Well done.

36 g is right. 2H₂ + O₂ → 2H₂O. Moles H₂ = 4.0g / 2.0g/mol = 2.0 mol. From stoichiometry, 2.0 mol H₂O × 18 g/mol = **36 g**.

Next review: in 3 days

---

**Student:** Let's do a mock exam!

**Claude:** *[calls `start_mock_exam`]*

Starting your AP Chemistry mock exam:
- **60 questions**
- **190 minutes** time limit
- Answer all questions, then use `submit_mock_exam` when done.

---

**Student:** How ready am I overall?

**Claude:** *[calls `get_readiness`]*

**Readiness Score: 67/100**

- Estimated AP Score: **4/5** (Well Qualified)
- Topics mastered: Chemical Bonding, Atomic Structure
- Weak areas: Electrochemistry (40%), Thermodynamics (50%)
- Trend: **Improving**
- 21 days remaining — excellent time to close the gaps!

**Recommendation:** Focus on Electrochemistry and Thermodynamics this week. You're on track for a 4!

## How FSRS Works

FSRS-5 (Free Spaced Repetition Scheduler) is a state-of-the-art algorithm that models human memory:

- **Stability (S):** How long you'll remember something (in days)
- **Difficulty (D):** How hard the material is for you (1-10 scale)
- **Retrievability (R):** Probability you can recall it right now (0-1)

After each answer, the algorithm calculates your next optimal review date. Cards you find easy get longer intervals; cards you struggle with come back sooner. This minimizes total study time while maximizing retention.

## Development

```bash
git clone https://github.com/gonzih/exam-prep-mcp
cd exam-prep-mcp
npm install
npm run dev     # Run with tsx (no build needed)
npm run build   # Compile TypeScript
npm start       # Run compiled version
```

## License

MIT © Gonzih