<div align="center">

# 🃏 Flashcard MCP

**Give any AI assistant a memory that actually lasts.**

A lightweight MCP server that adds **spaced-repetition flashcards** (the classic
SM-2 algorithm behind SuperMemo and Anki) to Claude, Cursor, VS Code, and every
other MCP-compatible assistant.

<p align="center">
  <img alt="GitHub stars" src="https://img.shields.io/github/stars/cokovali10-sketch/flashcard-mcp?style=for-the-badge&logo=github&color=7c3aed">
  <img alt="License" src="https://img.shields.io/badge/license-MIT-7c3aed?style=for-the-badge">
  <img alt="Python" src="https://img.shields.io/badge/python-3.10%2B-7c3aed?style=for-the-badge&logo=python">
  <img alt="MCP" src="https://img.shields.io/badge/built%20with-MCP-7c3aed?style=for-the-badge">
</p>

*Stop re-teaching your AI the same thing every session. Your assistant now
learns vocabulary, concepts, and facts once — then reviews them at the optimal
moment so they stick forever.*

![Flashcard MCP demo](docs/demo.png)

</div>

---

## Why?

Every AI session starts from zero. You ask your assistant to help you learn
English words, it makes a nice list — and by tomorrow both of you have
forgotten everything.

**Flashcard MCP** fixes this: it stores flashcards locally and schedules
reviews using the **SM-2 algorithm**, the scientifically-backed method that
powers SuperMemo and Anki. The AI creates the cards, you review them, and the
server decides *exactly when* to bring each card back so it moves from
short-term to long-term memory.

- 🔒 **100% local** — your data lives in a single SQLite file. No cloud, no accounts, no tracking.
- 🧠 **Real spaced repetition** — the SM-2 algorithm, not a random "quiz".
- ⚡ **Zero config** — install, add two lines to your MCP config, done.
- 🐍 **Pure Python, zero heavy dependencies** — one tiny package, nothing else.

## Installation

```bash
pip install flashcard-mcp
```

## Configuration

Add the server to your MCP client. Examples for the most common setups:

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "flashcards": {
      "command": "flashcard-mcp",
      "args": []
    }
  }
}
```

**VS Code / Cursor** (`.mcp.json`):

```json
{
  "servers": {
    "flashcards": {
      "type": "stdio",
      "command": "flashcard-mcp"
    }
  }
}
```

> **Data location:** the database is created at `./data/flashcards.db` next to
> the package. Override it with the `FLASHCARD_DB` environment variable.

## How it works

1. **You ask your AI to build a deck** — e.g. *"Create a deck 'English' and add
   cards for these phrasal verbs: look up, break down, give up."*
2. **The AI calls the tools** — the server creates the deck and cards in SQLite.
3. **When you want to review** — ask *"Let's review my due cards."* The server
   returns exactly the cards that are due today, per the SM-2 schedule.
4. **You grade each card** (0–5), the algorithm updates the easiness factor
   and picks the next review date. Perfect recalls → longer intervals.
   Misses → the card comes back tomorrow.
5. **Repeat** — over time each card is reviewed at expanding intervals and
   permanently lands in your long-term memory.

## Tools

| Tool | Description |
|------|-------------|
| `create_deck` | Create a study deck |
| `list_decks` | List all decks with card counts |
| `delete_deck` | Delete a deck and its cards |
| `add_card` | Add a flashcard (front / back) |
| `list_cards` | List flashcards, filtered by deck |
| `delete_card` | Delete a flashcard |
| `get_due_cards` | Get cards due for review today |
| `review_card` | Grade a card (quality 0–5) and reschedule it |
| `get_stats` | Total cards, due today, per-deck breakdown |
| `export_cards` | Export everything as JSON |

## The SM-2 algorithm

When you grade a card, the server updates two numbers:

- **Easiness factor (EF)** — how easy this card is for you. Starts at 2.5,
  never drops below 1.3.
- **Interval (days)** — the gap until the next review. `1 → 6 → 6×EF → 6×EF² → …`

A grade below 3 resets the card to a 1-day interval. This is exactly the
schedule that makes spaced repetition effective — it targets reviews right
before you'd forget.

## Development

```bash
pip install -e ".[dev]"
pytest
```

Regenerate the demo screenshot (Pillow required):

```bash
pip install pillow
python scripts/make_screenshot.py   # writes docs/demo.png
```

## Project structure

```
flashcard_mcp/
├── src/flashcard_mcp/
│   ├── srs.py      # SM-2 scheduling algorithm
│   ├── db.py       # SQLite storage layer
│   └── server.py   # MCP server + tool definitions
├── scripts/
│   └── make_screenshot.py  # generates the demo image
├── docs/           # demo.png and other assets
└── tests/          # unit + end-to-end stdio tests
```

## Roadmap

- [ ] Anki `.apkg` import/export
- [ ] HTML dashboard with retention graphs
- [ ] Prompt templates for vocabulary / exam / language learning
- [ ] Prebuilt study decks

## License

MIT