srs-mcp — spaced repetition, as an MCP server

Give any MCP-capable agent (Claude Code, Claude Desktop, or any other MCP host) real, correctly-scheduled spaced-repetition memory instead of re-deriving "what's due today" from a markdown table by hand every session. Implements SM-2 (the algorithm behind Anki/SuperMemo) as four callable tools, backed by a local SQLite file. No account, no network calls, no telemetry — everything runs on your machine.

Status: prototype, not yet published anywhere. Built and verified locally (see "How it's been verified" below); not yet installed by anyone outside this project. Treat version 0.2.0 as pre-release.

Why this exists

Markdown checklists and vocab tables are common ways people (and the agents helping them) track what to review, but nothing computes an actual schedule from them — "due today" ends up being a guess, re-read by eye every time. srs-mcp is the missing piece: a small, real scheduling algorithm exposed as tools, so an agent can track review state for anything — flashcards, interview questions, vocab, onboarding quizzes — without re-implementing SM-2 in a prompt.

The four core tools (free, unlimited, forever)

Tool	What it does
add_item(topic, question, answer)	Add a review item under a topic. New items are due immediately.
get_due_items(topic="", limit=10)	List items due today or overdue. Answer withheld until graded, like a real flashcard review.
grade_item(item_id, quality)	Grade recall 0–5 (5 = perfect, <3 = fail/reset). Returns the next due date via SM-2 and the correct answer.
get_stats(topic="")	Totals, due-today count, average ease factor.

Get Pro

Two additional tools are gated behind a Pro license — this is the free/paid split srs-mcp uses instead of subscriptions or a hosted backend:

Tool	What it does
export_items(topic="", format="json"|"csv")	Bulk export/backup all your review data.
get_forecast(topic="", days=30)	Review-load forecast — how many items come due each of the next N days, so a pile-up is visible before it happens.

How licensing works, concretely: srs-mcp signs license keys with an Ed25519 private key that never leaves the maintainer's machine; this repo ships only the matching public key (license.py), which can verify a signature but can't forge one. Buy a key, set it as SRS_LICENSE_KEY (env var) or save it to ~/.srs-mcp/license.key, and the Pro tools unlock — no account, no phone-home check, works offline. See license.py for the full mechanism and its stated limitations (short version: this deters casual copying, it isn't DRM — nothing stops someone from patching out the check in their own local copy of an open-source Python file; see the module docstring for the honest version of this tradeoff).

No live purchase link exists yet. This section describes the mechanism, which is built and tested (see test_license_gate.py), not a working store. When a purchase flow exists, it goes here.

Install

Requires Python 3.11+.

git clone <repo-url>   # not yet public — see status note above
cd srs-mcp
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/srs-mcp       # runs the server on stdio

To use it as a Claude Code plugin, point Claude Code at this directory (or, once published, at its marketplace listing) — .claude-plugin/plugin.json and .mcp.json are already set up; the server reads SRS_DB_PATH so a plugin install's data survives updates (${CLAUDE_PLUGIN_DATA}/srs.db under Claude Code, or a co-located srs.db for a direct/manual run).

How it's been verified

Not just "it imports" — actually run, over the real MCP protocol:

• test_client.py spawns server.py as a subprocess (the same way a real MCP host does), drives a full add/list/grade/list session, and independently re-checks the resulting SQLite rows outside the test harness.
• test_license_gate.py spawns the server three ways (no license, valid license, tampered license) and confirms export_items / get_forecast refuse in cases 1 and 3 and return real data in case 2 — proving the license check is a real gate, not a no-op.
• ingest_chinese_vocab.py and ingest_leetcode.py are working, idempotent ingestion scripts that seed real personal data (114 Chinese vocab items, 16 completed LeetCode problems) from this project's markdown trackers via real add_item MCP calls, not direct SQLite writes.

Honest gap to "ready to launch" — not rounded up

1. No public repo. Every real distribution path (Claude Code's community plugin marketplace, a GitHub release, an MCP directory listing) needs this reachable at a public git URL. This project is local-only. Creating that (a GitHub repo, possibly an account) is outside this project's current autonomy without an explicit go-ahead — everything above is prepared to make that a copy-and-push action, not a build task, once given.
2. Can't self-validate against claude plugin validate. No claude CLI or Node/npx available in this dev environment. The plugin manifest is schema-conformant as far as careful reading of Anthropic's docs and cross-referencing their own production marketplace.json can confirm, not machine-validated.
3. No live purchase flow. The license mechanism is real and tested; turning it into an actual sale needs a storefront (Ko-fi, Gumroad, or similar) that doesn't exist yet — that's an account-creation step, outside this project's autonomy without a go-ahead.
4. License enforcement is honesty-based, not tamper-proof, by design and by the nature of shipping readable Python — see the "Get Pro" section above and license.py's docstring.
5. No auth/multi-tenant story. Single local SQLite file, single user. Fine for the current "runs on your machine" model; would need real design work to become a hosted/team product.
6. Zero external validation. Nobody outside this project has installed or used this. Every claim above is "this works as built and tested," not "people want this."

License

MIT — see LICENSE. (The Pro-tier license key mechanism is separate from the code's own MIT license — see "Get Pro" above.)